# 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`) 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

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

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

**API**
```http
PUT /ec2/api/instances/i-3f9a2c07/role
{ "iamRoleName": "ci-runner" }
```

`DELETE /ec2/api/instances/{id}/role` takes it away. At launch, `"iamRoleName"` in the request.

**Terraform**
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:

```sh
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:

```sh
#!/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).

```sh
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.

## Related

- [Prove an instance's identity](prove-an-instance-identity.md)
- `ec2.instances.set-role` · `dcloud ec2 instances get-identity` · `dcloud_instance`
