Docker on EC2
The usual home for Delegaris is Docker on an EC2 instance, with the instance's IAM role as the service's own identity. There is one catch: by default, a container on an EC2 instance cannot use the instance's role. This page explains why and how to fix it.
Set up the instance role
- Deploy
iam/hub-role.yamlwith CloudFormation in the account the instance lives in. See Member account role for its parameters. - Attach the instance profile it creates to the instance: EC2 console > Actions > Security > Modify IAM role.
- Apply one of the two fixes below.
Why the container gets no credentials
An instance role is handed out by the instance metadata service at 169.254.169.254. The reply that carries its session token is limited to a number of network hops, 1 by default on most instances. A container on Docker's bridge network is one hop further away than the host, so the reply is dropped and the container ends up with no credentials. (Where the instance still allows the older token-less requests, it gets them anyway, slowly.)
Fix 1: raise the hop limit to 2
From any shell with access to the account:
aws ec2 modify-instance-metadata-options --instance-id i-0123456789abcdef0 \
--http-put-response-hop-limit 2 --http-tokens required
In Terraform, that is:
metadata_options {
http_put_response_hop_limit = 2
}
In a CloudFormation launch template:
MetadataOptions:
HttpPutResponseHopLimit: 2
Some newer AMIs, Amazon Linux 2023 for one, launch with a limit of 2 already.
Fix 2: use the host's network
Run the container on the host's network instead of Docker's bridge. In docker-compose.yml, uncomment network_mode: host and remove the ports: section:
services:
delegaris:
image: goodhallsolutions/delegaris:${DELEGARIS_TAG:-latest}
network_mode: host
# no "ports:" section
The service then listens on the host's port 8080 directly. If nginx runs on the same host, it still reaches the container at http://127.0.0.1:8080, but the port is open on every interface, so restrict it with the instance's security group.
How to tell which situation you are in
Delegaris tells you. At startup it logs the identity it found, or why it found none:
WARNING delegaris: The service cannot sign in to AWS. This is an EC2 instance, but the container cannot collect the instance role's credentials. ... Fix: aws ec2 modify-instance-metadata-options --instance-id <instance-id> --http-put-response-hop-limit 2 --http-tokens required
The top of the Accounts page shows the same thing, with the command to copy. It tells these cases apart:
| What it says | Meaning |
|---|---|
| The container cannot collect the instance role's credentials | The hop limit. Apply fix 1 or fix 2. |
| The instance has no IAM role attached | The container reaches the metadata service fine, but there is no role. Attach the instance profile. |
| Nothing answered at the EC2 instance metadata address | The container is not on EC2, or is blocked from the metadata address. |
Neither fix needs the container restarting. Apply it, then choose Check again on the Accounts page.
A word on sharing the host
Raising the hop limit lets every container on that instance use the instance role. The role is narrow (it can only assume DelegarisRole and read list prices), but it leads to start and stop rights in your accounts. Do not run containers you do not trust on the same host.
If the instance role cannot be used at all
The service accepts an IAM user's access keys instead, entered on the Accounts page or in the environment, or an IAM Identity Center sign-in. See The service's own identity. A role is still what the service uses inside each managed account; this only changes how the service itself signs in before assuming those roles.
Other things worth knowing on EC2
- Outbound access. The instance needs to reach the AWS APIs, your domain controllers on port 636 (for Active Directory sign-in) and
slack.com(for Slack). Nothing needs to reach the instance from the internet for Slack: it connects out. - Size. The container is small; a
t3.smallort4g.smallis enough. The published image islinux/amd64; on a Graviton (t4g) instance, use the Linux package instead, which is built for arm64 too. - More than one instance. For a deployment that survives the loss of an instance, see High availability.