ec2.instances.runLaunch an instance
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
serverTypeOptionalstring
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
sizeClassOptionalenum
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-16imageIdOptionalnumber
An OS image from the catalog. Give this or machineImageId, not both.
Constraints: integer, min 1
machineImageIdOptionalstring
One of your machine images (ewi-…), to launch a copy of a snapshot.
Constraints: /^ewi-[0-9a-f]{6,32}$/
regionIdRequiredstring
The region to launch in, e.g. de1
Constraints: min 1 chars
availabilityZoneIdOptionalstring
Zone to run in (de1a = Falkenstein, de1b = Nuremberg); default the subnet’s, else de1a
Constraints: /^[a-z]+[0-9]+[a-z]$/
vpcIdOptionalstring
The VPC to join; omitted: the region’s default VPC, created the first time it is needed
Constraints: uuid
nameOptionalstring
A display name; omitted: none
Constraints: max 64 chars
sshKeyPairIdOptionalstring
A KMS SSH key pair (kms ssh-key-pairs)
Constraints: uuid
keyPairIdOptionalstring
Instead of sshKeyPairId: a Compute key pair (ec2 key-pairs); not both
Constraints: uuid
userDataOptionalstring
A cloud-init script run at first boot, passed through unchanged
tagsOptionalmap of string
Tags for the instance (and its launch volumes); your organization’s required keys must be present
Constraints: key=value
securityGroupIdsOptionalarray of string
Security groups to attach; omitted: none, so the instance is not filtered
Constraints: uuid
subnetIdOptionalstring
A subnet of the VPC: the instance gets a fixed private address in its range and runs in its zone
Constraints: uuid
enablePublicIpv4Optionalboolean
Give the machine a public IPv4 (default true); false: IPv6 only, IPv4 out through the VPC’s NAT gateway if it has one
osPatchingOptionalboolean
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.
connectOptionalboolean
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.
iamRoleNameOptionalstring
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+=,.@-]+$/
volumesOptionalarray 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}'
publicHostnameOptionalobject
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
idleSuspendMinutesOptionalnumber
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
requiredHostTagsOptionalobject
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 examplecurl -X POST "https://console.platform-development.deutschecloud.app/ec2/api/instances" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"regionId":"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.