Skip to main content

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.

  1. 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.

  2. Open Create this role in the account. It has three steps:

    • Download the role template: the member-account-role.yaml button.

    • The CloudFormation parameters to create a stack with in that account, each with a copy button. TrustedPrincipalArn is 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
  3. 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 role created moments ago

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​

ParameterDefaultMeaning
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.
RoleNameDelegarisRoleThe 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.
ManageEC2trueEC2 instances: list, start, stop, reboot and tag.
ManageRDStrueRDS instances, and Aurora, DocumentDB and Neptune clusters: list, start, stop, reboot instances, and tag.
ManageAutoScalingfalseAuto Scaling groups: list, scale to zero and back, and tag.
ManageECSfalseECS services: list, scale to zero and back, restart (a new deployment), and tag.
ManageEKSfalseEKS managed node groups: list, scale to zero and back, and tag.
ManageRedshiftfalseRedshift clusters: list, pause, resume, reboot and tag.
ManageSageMakerfalseSageMaker notebook instances: list, start, stop and tag.
ManageLightsailfalseLightsail instances: list, start, stop, reboot and tag.
ReadSchedulesfalseRead 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​

SwitchIAM actions
ManageEC2ec2: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
ManageRDSrds: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
ManageAutoScalingautoscaling:DescribeAutoScalingGroups, autoscaling:UpdateAutoScalingGroup, autoscaling:CreateOrUpdateTags, autoscaling:DeleteTags
ManageECSecs:ListClusters, ecs:ListServices, ecs:DescribeServices, ecs:UpdateService, ecs:TagResource, ecs:UntagResource
ManageEKSeks:ListClusters, eks:ListNodegroups, eks:DescribeNodegroup, eks:UpdateNodegroupConfig, eks:TagResource, eks:UntagResource
ManageRedshiftredshift:DescribeClusters, redshift:PauseCluster, redshift:ResumeCluster, redshift:RebootCluster, redshift:CreateTags, redshift:DeleteTags
ManageSageMakersagemaker:ListNotebookInstances, sagemaker:DescribeNotebookInstance, sagemaker:ListTags, sagemaker:StartNotebookInstance, sagemaker:StopNotebookInstance, sagemaker:AddTags, sagemaker:DeleteTags
ManageLightsaillightsail:GetInstances, lightsail:GetInstance, lightsail:StartInstance, lightsail:StopInstance, lightsail:RebootInstance, lightsail:TagResource, lightsail:UntagResource
ReadSchedulesdynamodb: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.

Encrypted EBS volumes

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).

ParameterDefaultMeaning
RoleNamedelegaris-hubThe name of the role and of its instance profile.
ManagedRoleNameDelegarisRoleThe 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).

OutputUse
RoleArnGive this as TrustedPrincipalArn when deploying member-account-role.yaml.
InstanceProfileNameAttach 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​