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.
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) andiam:PassRoleon the role. Removing it needsec2:DisassociateInstanceRole. - An IAM role in your organization. An unknown role is refused with
404"There is no IAM role named …"; withoutiam:PassRoleon it, the request is refused with403. - 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-3f9a2c07PUT /ec2/api/instances/i-3f9a2c07/role
{ "iamRoleName": "ci-runner" }DELETE /ec2/api/instances/{id}/role takes it away. At launch, "iamRoleName" in the request.
Set iam_role_name on the dcloud_instance. Changing it replaces the instance; to change the role
of a running machine without replacing it, use the CLI or API.
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 onThe 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-3f9a2c07shows the role, whether the instance has an identity, when the secret was last rotated and last used, and from which address.