ec2.instances.run

Launch an instance

POST /ec2/api/instancesIAM ec2:RunInstancesChanges state

Request syntax

POST /ec2/api/instances
{
  "serverType": "string",
  "sizeClass": "enum",
  "imageId": "number",
  "machineImageId": "string",
  "regionId": "string",
  "availabilityZoneId": "string",
  "vpcId": "string",
  "name": "string",
  "sshKeyPairId": "string",
  "keyPairId": "string",
  "userData": "string",
  "tags": "map of string",
  "securityGroupIds": "array of string",
  "subnetId": "string",
  "enablePublicIpv4": "boolean",
  "osPatching": "boolean",
  "connect": "boolean",
  "iamRoleName": "string",
  "volumes": "array of json",
  "publicHostname": "object",
  "idleSuspendMinutes": "number",
  "requiredHostTags": "object"
}

Request body

  • serverTypeOptional

    string

    An instance type, e.g. performance-2 (ec2 instance-types list). Give this or sizeClass. The provider’s own type names are still accepted, deprecated.

    Constraints: min 1 chars

  • sizeClassOptional

    enum

    A size class instead of a provider type: s-2 (2 vCPU / 4 GiB), s-4 (4 / 8), s-8 (8 / 16), s-16 (16 / 32), m-4 (4 / 32), d-2 (2 dedicated / 8), d-8 (8 dedicated / 32), a-2, a-4, a-8, a-16 (ARM, as s-*); it becomes the smallest type of your provider that fits

    One of: s-2, s-4, s-8, s-16, m-4, d-2, d-8, a-2, a-4, a-8, a-16

  • imageIdOptional

    number

    An OS image from the catalog. Give this or machineImageId, not both.

    Constraints: integer, min 1

  • machineImageIdOptional

    string

    One of your machine images (ewi-…), to launch a copy of a snapshot.

    Constraints: /^ewi-[0-9a-f]{6,32}$/

  • regionIdRequired

    string

    The region to launch in, e.g. de1

    Constraints: min 1 chars

  • availabilityZoneIdOptional

    string

    Zone to run in (de1a = Falkenstein, de1b = Nuremberg); default the subnet’s, else de1a

    Constraints: /^[a-z]+[0-9]+[a-z]$/

  • vpcIdOptional

    string

    The VPC to join; omitted: the region’s default VPC, created the first time it is needed

    Constraints: uuid

  • nameOptional

    string

    A display name; omitted: none

    Constraints: max 64 chars

  • sshKeyPairIdOptional

    string

    A KMS SSH key pair (kms ssh-key-pairs)

    Constraints: uuid

  • keyPairIdOptional

    string

    Instead of sshKeyPairId: a Compute key pair (ec2 key-pairs); not both

    Constraints: uuid

  • userDataOptional

    string

    A cloud-init script run at first boot, passed through unchanged

  • tagsOptional

    map of string

    Tags for the instance (and its launch volumes); your organization’s required keys must be present

    Constraints: key=value

  • securityGroupIdsOptional

    array of string

    Security groups to attach; omitted: none, so the instance is not filtered

    Constraints: uuid

  • subnetIdOptional

    string

    A subnet of the VPC: the instance gets a fixed private address in its range and runs in its zone

    Constraints: uuid

  • enablePublicIpv4Optional

    boolean

    Give the machine a public IPv4 (default true); false: IPv6 only, IPv4 out through the VPC’s NAT gateway if it has one

  • osPatchingOptional

    boolean

    Keep OS patched: install the platform patch reporter; security updates install nightly and reboots happen in the 02:00–05:00 UTC window. Ubuntu images only.

  • connectOptional

    boolean

    Deutsche Cloud Connect (default true): the machine keeps one outbound SSH connection to Deutsche Cloud so the console terminal and adding keys work with no inbound port. false: nothing is installed.

  • iamRoleNameOptional

    string

    IAM role the machine acts as (needs iam:PassRole on it): it gets 60-minute credentials for it through its instance identity (`ews-instance credentials`), with no key in user data

    Constraints: 1-64 chars, /^[\w+=,.@-]+$/

  • volumesOptional

    array of json

    Up to 4 extra volumes made with the instance in its zone, attached once it runs (needs ec2:CreateVolume and ec2:AttachVolume); encrypted and deleted with the instance unless told otherwise. CLI: --volumes '{"sizeGib":40}'

  • publicHostnameOptional

    object

    Own hosts only: a name in one of your DNS zones (and *.name) that reaches this machine through the site’s front: HTTPS by SNI, SSH through the jump on port 2222. Needs dns:ChangeRecords on that zone; removed at terminate.

    Constraints: JSON

  • idleSuspendMinutesOptional

    number

    Own hosts only: suspend the machine (memory saved) after this many idle minutes; the next HTTPS request or SSH connection through the front wakes it.

    Constraints: integer, 10-10080

  • requiredHostTagsOptional

    object

    Own hosts only: capability tags the machine’s host must carry (a name or name:value, e.g. fsync:high, cpu:a); only hosts with every one take it, else it waits saying which tag is missing. CLI: --required-host-tags fsync:high

    Constraints: JSON

Response

201: `data` is the new instance in state `pending` (id `i-…`, name, regionId, availabilityZoneId, vpcId, subnetId); with `volumes` asked for, also `volumes`: per extra volume its id and sizeGib, or the error that kept it from being made.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow ec2:RunInstances on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud ec2 instances run --region-id example

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_ec2_instances_run.