Drive instances from a script

Keep a pool of machines from a script, launching with tags and extra volumes, waiting for a state, finding machines by tag and relabelling them in one call.

Last updated 18 November 2026View as Markdown

What a script that keeps a pool of machines (preview boxes, runners) needs, without reading the console. Replace the ids and tag values with your own.

Prerequisites

  • Permission for ec2:RunInstances and ec2:DescribeInstances; with volumes, also ec2:CreateVolume and ec2:AttachVolume; with an instance role, iam:PassRole on it.
  • Relabelling needs tags:TagResource to set and tags:UntagResource to remove, on the instance.

Launch and wait

id=$(dcloud ec2 instances run --region-id de1 --availability-zone-id de1b \
  --server-type dedicated-8 --machine-image-id ewi-0a1b2c3d \
  --iam-role-name preview-box --tags pool=preview --tags slot=7 \
  --volumes '{"sizeGib":40}' --json | jq -r .data.id)
dcloud ec2 instances wait "$id"
  • volumes (up to 4, 10 to 10 000 GiB each) are made in the instance's zone and attached as soon as it runs; each is encrypted and deleted with the instance unless you say "encrypted": false or "deleteOnTermination": false. The instance's activity says when each was attached or deleted.
  • wait takes --state running|stopped|terminated (default running) and --timeout-seconds (1 to 300, default 120). running counts only once the machine exists at the provider, so its public address is known. When the time runs out it answers 408 "… is pending, not running, after 120 s; call again to keep waiting", and 409 "… terminated before it was running" at once if the instance terminated first.
  • tags must include your organization's required tag keys, if it has any; the tags also go onto the launch volumes.

Find and relabel

dcloud ec2 instances list --tag pool=preview,slot=7
dcloud ec2 instances set-tags "$id" --set owner=pr-42 --set state=busy --remove slot
  • tag takes key=value clauses separated by commas, at most 10 ("At most 10 tag clauses" otherwise), all of which must match; a bare key means the tag is present.
  • Every row of the list carries its tags. The list also filters by state and by name (a part of the name or id), and pages with limit (1 to 500, default 100) and offset, oldest first.
  • set-tags answers with the tags the instance carries afterwards. A request with nothing to set or remove is refused with 400 "Give tags to set, keys to remove, or both".

A stable public address per slot: an elastic IP moved to the slot's new machine.

Did this page help you?