Give an instance a role

Let a machine call the API with short-lived credentials of an IAM role, through its own instance identity, with no keys in its user data.

Last updated 18 November 2026View as Markdown

Every instance has an instance identity: a secret of its own, written at first boot to /etc/ews/instance-identity (readable by root only). The platform stores only its hash; the API never returns it, not even with the user data. On an image with systemd, the machine replaces it a few minutes after every boot and once a day, so a copy left in a machine image stops working within a day; it also stops working when the instance terminates. Instances launched before identities existed have none; replace them to get one.

An instance role is an IAM role the machine gets short-lived credentials for, as AWS instance profiles work.

Prerequisites

  • Permission for ec2:AssociateInstanceRole (or, at launch, ec2:RunInstances) and iam:PassRole on the role. Removing it needs ec2:DisassociateInstanceRole.
  • An IAM role in your organization. An unknown role is refused with 404 "There is no IAM role named …"; without iam:PassRole on it, the request is refused with 403.
  • An instance that is not terminated: setting a role on a terminated one answers 404 "Instance not found".

Give it a role

At launch, --iam-role-name ci-runner on dcloud ec2 instances run. Later:

dcloud ec2 instances set-role i-3f9a2c07 --iam-role-name ci-runner
dcloud ec2 instances remove-role i-3f9a2c07

For machines of an auto scaling group, put the role in the launch template's spec.

Use it on the machine

The helper ews-instance is installed next to the identity:

ews-instance identity          # instance id, name, zone, type, addresses, tags, role, group (JSON)
ews-instance credentials --env # export DCLOUD_ACCESS_KEY=… and DCLOUD_API_URL for the role
ews-instance token AUDIENCE    # a signed identity token, see Prove an instance's identity
ews-instance protect on        # in an auto scaling group: protect itself from scale-in
ews-instance lifecycle         # in a group: is it leaving?
ews-instance complete          # let a termination lifecycle hook go on

The credentials are an access key of the role that expires after an hour: they work with the API, the CLI, the SDKs, and whatever else accepts an access key, and can do exactly what the role's policies allow. The helper reads the identity file, so run it as root. On an instance with no role, credentials is refused with 404 "This instance has no instance role. …". A boot script that needs a secret fetches it instead of carrying it:

#!/bin/sh
eval "$(ews-instance credentials --env)"
curl -fsS -H "Authorization: EWS-ACCESS-KEY $DCLOUD_ACCESS_KEY" \
  "$DCLOUD_API_URL/secrets/api/secrets/secret-id/value"

Result

Each issue of credentials is in the audit log (iam:AssumeRoleForInstance) and in the instance's activity. Removing the role stops new credentials; ones already issued run out within the hour (revoke the role's sessions to end them now).

dcloud ec2 instances get-identity i-3f9a2c07

shows the role, whether the instance has an identity, when the secret was last rotated and last used, and from which address.

Did this page help you?