Member account role
In each AWS account Delegaris manages, it assumes a role, DelegarisRole, created from the CloudFormation template iam/member-account-role.yaml. The role allows listing, starting, stopping and tagging the services you switch on, and nothing else. A second template, iam/hub-role.yaml, creates the service's own role for an EC2 host.
Both templates can be downloaded from the Accounts page: the member account template from the Add an account dialog, and the hub template under What this identity needs at the top of the page.
Deploying the role from the account dialog
The easiest way is to let the Add an account dialog work out the values.
-
On Accounts, choose Add an account. Enter the name and AWS account ID, tick the services to manage under Manage, and leave Access on Assume a role in the account.
-
Open Create this role in the account. It has three steps:
-
Download the role template: the
member-account-role.yamlbutton. -
The CloudFormation parameters to create a stack with in that account, each with a copy button.
TrustedPrincipalArnis filled in with the service's own identity. Only parameters that differ from the template's defaults are listed. -
The same as one command, to run from a shell signed in to that account, in the folder with the template. For an account managing ECS services as well as EC2 and RDS, it looks like this:
aws cloudformation deploy --template-file member-account-role.yaml --stack-name delegaris-role \--capabilities CAPABILITY_NAMED_IAM \--parameter-overrides TrustedPrincipalArn=arn:aws:iam::111111111111:role/delegaris-hub ManageECS=true
-
-
Once the stack has been created, come back to the dialog and choose Test connection.
If the service has no AWS identity yet, the dialog says that the value for TrustedPrincipalArn is not known. Sort that out first; see The service's own identity.
A new role can take a few seconds before AWS lets anyone assume it. If Test connection fails on the first step straight after creating the stack, wait a moment and try again.
Parameters of member-account-role.yaml
| Parameter | Default | Meaning |
|---|---|---|
TrustedPrincipalArn | (required) | The ARN of the IAM role or user the Delegaris container runs as, for example arn:aws:iam::111111111111:role/delegaris-hub. Only this identity may assume the role. The top of the Accounts page shows it. |
RoleName | DelegarisRole | The role's name. If you change it, change the Role to assume on the account to match, and make sure the service's identity may assume the new name. |
ExternalId | (empty) | Optional. If set, the role can only be assumed with this value, which you then also enter as External ID on the account. The dialog's Generate button makes a random one. |
ManageEC2 | true | EC2 instances: list, start, stop, reboot and tag. |
ManageRDS | true | RDS instances, and Aurora, DocumentDB and Neptune clusters: list, start, stop, reboot instances, and tag. |
ManageAutoScaling | false | Auto Scaling groups: list, scale to zero and back, and tag. |
ManageECS | false | ECS services: list, scale to zero and back, restart (a new deployment), and tag. |
ManageEKS | false | EKS managed node groups: list, scale to zero and back, and tag. |
ManageRedshift | false | Redshift clusters: list, pause, resume, reboot and tag. |
ManageSageMaker | false | SageMaker notebook instances: list, start, stop and tag. |
ManageLightsail | false | Lightsail instances: list, start, stop, reboot and tag. |
ReadSchedules | false | Read schedule definitions from AWS Instance Scheduler and Systems Manager Quick Setup, if the scheduler runs in this account. Read only. See Reading from the scheduler. |
At least one of the Manage parameters must be true, or CloudFormation refuses the stack.
The template's output, RoleArn, is the value for Role to assume on the account. The dialog fills it in for you from the account ID.
What each switch allows
| Switch | IAM actions |
|---|---|
ManageEC2 | ec2:DescribeInstances, ec2:StartInstances, ec2:StopInstances, ec2:RebootInstances; ec2:CreateTags and ec2:DeleteTags on this account's instances only; kms:CreateGrant, only for grants to AWS services |
ManageRDS | rds:DescribeDBInstances, rds:DescribeDBClusters, rds:ListTagsForResource, rds:StartDBInstance, rds:StopDBInstance, rds:RebootDBInstance, rds:StartDBCluster, rds:StopDBCluster; rds:AddTagsToResource and rds:RemoveTagsFromResource on this account's databases and clusters only |
ManageAutoScaling | autoscaling:DescribeAutoScalingGroups, autoscaling:UpdateAutoScalingGroup, autoscaling:CreateOrUpdateTags, autoscaling:DeleteTags |
ManageECS | ecs:ListClusters, ecs:ListServices, ecs:DescribeServices, ecs:UpdateService, ecs:TagResource, ecs:UntagResource |
ManageEKS | eks:ListClusters, eks:ListNodegroups, eks:DescribeNodegroup, eks:UpdateNodegroupConfig, eks:TagResource, eks:UntagResource |
ManageRedshift | redshift:DescribeClusters, redshift:PauseCluster, redshift:ResumeCluster, redshift:RebootCluster, redshift:CreateTags, redshift:DeleteTags |
ManageSageMaker | sagemaker:ListNotebookInstances, sagemaker:DescribeNotebookInstance, sagemaker:ListTags, sagemaker:StartNotebookInstance, sagemaker:StopNotebookInstance, sagemaker:AddTags, sagemaker:DeleteTags |
ManageLightsail | lightsail:GetInstances, lightsail:GetInstance, lightsail:StartInstance, lightsail:StopInstance, lightsail:RebootInstance, lightsail:TagResource, lightsail:UntagResource |
ReadSchedules | dynamodb:ListTables; dynamodb:Scan on tables named like *ConfigTable* in this account; ssm:ListAssociations, ssm:DescribeAssociation |
The role's sessions last at most one hour; the service fetches new ones as they run out.
Starting an instance whose EBS volumes use a customer-managed KMS key needs a grant for EC2. The role includes kms:CreateGrant for that, but the key policy must also allow DelegarisRole. Otherwise the instance goes to pending and straight back to stopped a few seconds after starting.
Changing what the role allows
The services ticked on an account in Delegaris and the switches on the role must agree. A service ticked in Delegaris without the matching permission fails its step of Test connection (for example "List ECS clusters in eu-west-2") with AWS's access-denied message.
To switch a service on later, tick it on the account (Edit), then update the stack with the command the dialog now shows. Running aws cloudformation deploy again with the same stack name updates the existing role.
Newer versions of Delegaris sometimes need permissions the role did not have before (rebooting, for example, needs ec2:RebootInstances and rds:RebootDBInstance). Download the template again from the account dialog and update the stack.
Many accounts: a StackSet
For an organisation with many accounts, deploy the template as a CloudFormation StackSet rather than one stack at a time. Give the same TrustedPrincipalArn and switches to every account, or use separate StackSets for groups of accounts that manage different services.
IAM roles are global, so deploy each account's stack in one region only. A second region would try to create a role with the same name and fail.
Parameters of hub-role.yaml
iam/hub-role.yaml creates the service's own identity on EC2: an IAM role that EC2 can use, and an instance profile for it. Deploy it once, in the account the instance lives in, then attach the instance profile to the instance (EC2 console > Actions > Security > Modify IAM role).
| Parameter | Default | Meaning |
|---|---|---|
RoleName | delegaris-hub | The name of the role and of its instance profile. |
ManagedRoleName | DelegarisRole | The name of the role in each managed account. The hub role may assume this name in any account. Keep it in step with RoleName in member-account-role.yaml. |
BackupBucketName | (empty) | Optional. An S3 bucket the nightly database backup is uploaded to (BACKUP_S3_BUCKET). Adds s3:PutObject on that bucket. |
AuditBucketName | (empty) | Optional. An S3 bucket the activity log is copied to (Settings > Health and backups > Activity log to S3). Adds s3:PutObject on that bucket. |
The role always has sts:AssumeRole on the managed role name in any account, and pricing:GetProducts for cost estimates (read only, and not about your accounts).
| Output | Use |
|---|---|
RoleArn | Give this as TrustedPrincipalArn when deploying member-account-role.yaml. |
InstanceProfileName | Attach this to the EC2 instance that runs the container. |
aws cloudformation deploy --template-file hub-role.yaml --stack-name delegaris-hub \
--capabilities CAPABILITY_NAMED_IAM \
--parameter-overrides BackupBucketName=corp-delegaris-backups
On ECS or EKS, hub-role.yaml is not the right shape (it trusts EC2 only). Give the task role, or the IRSA or Pod Identity role, the same permissions instead; see The service's own identity.
Next steps
- Docker on EC2: letting the container use the instance profile.
- Adding accounts
- Supported services