Connect AWS

• You are an owner of the Groundcrew workspace.
• You can create IAM roles with CloudFormation in the AWS account you want to connect (an administrator, or a role with iam:CreateRole, iam:PutRolePolicy, and CloudFormation rights).
• You know which region your workloads run in. You can add more regions later.
• About five minutes.

Connect one AWS account per connection. For several accounts, repeat these steps in each; every connection gets its own ExternalId.

1. Open Connect AWS

   In Groundcrew, open Connections. On the AWS card, leave Observe selected (or choose Deploy to allow deploys, below) and choose Connect AWS.

2. Download the template

   Download aws-connect.yaml. Read it if you like; it is the same file as in Groundcrew's repository, and it is the only thing that defines what the role can do.

3. Keep the dialog open

   It shows the values for this workspace, each with a copy button:

   • GroundcrewPrincipalArn: Groundcrew's service role, the only identity allowed to assume your role. Use the value on your Connections page.
   • ExternalId: unique to this connection. Do not reuse it anywhere else.
   • Tier: observe (read-only) or deploy.

1. Open CloudFormation

   Sign in to the AWS account you want to connect. Use Open CloudFormation in the dialog, or open CloudFormation yourself and check the region (top right).

2. Upload the template

   Choose Create stack, then Choose an existing template and Upload a template file. Select aws-connect.yaml and choose Next.

3. Name it and paste the parameters

   Stack name: groundcrew-read-only. Paste GroundcrewPrincipalArn, ExternalId, and Tier from the dialog. Leave the other parameters as they are unless you are turning on emergency fixes.

4. Acknowledge and submit

   Choose Next twice. Tick I acknowledge that AWS CloudFormation might create IAM resources with custom names and choose Submit.

5. Copy the RoleArn

   Wait for CREATE_COMPLETE, about a minute. Open the Outputs tab and copy RoleArn.

Or with the AWS CLI

With credentials for the account you are connecting, in the folder where you saved the template. The dialog shows the same commands with your values filled in.

aws cloudformation create-stack \
  --region <your region> \
  --stack-name groundcrew-read-only \
  --template-body file://aws-connect.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters \
    ParameterKey=GroundcrewPrincipalArn,ParameterValue=<from the Connections page> \
    ParameterKey=ExternalId,ParameterValue=<from the Connections page> \
    ParameterKey=Tier,ParameterValue=observe

aws cloudformation wait stack-create-complete --region <your region> --stack-name groundcrew-read-only
aws cloudformation describe-stacks --region <your region> --stack-name groundcrew-read-only \
  --query "Stacks[0].Outputs[?OutputKey=='RoleArn'].OutputValue" --output text

Paste the RoleArn in the dialog and choose Verify. Groundcrew checks three things before it saves the connection:

• The role refuses Groundcrew without your ExternalId.
• It works with your ExternalId.
• The session belongs to the account in the ARN.

Then choose Run discovery. If you close the dialog before verifying, the connection shows as pending; choose Finish connecting on it to continue with the same ExternalId.

It reads resource configuration and tags (ECS, ECR, RDS, VPC, Lambda, load balancers, EC2, IAM, and others), CloudWatch logs and metrics, and secret metadata such as names and when a secret changed. It turns on a local Resource Explorer index in the region, so discovery is one search. AWS Config is not turned on. Set CreateResourceExplorerIndex=false if the region already has an index.

Choose Regions on the connection to pick where Groundcrew discovers resources, watches for incidents, and runs approved fixes, up to 10 regions. IAM roles are global, so no stack update is needed. Groundcrew refreshes the map after you save.

With Tier=deploy, the stack also creates an ECS cluster groundcrew-deploys (Fargate, no running cost until something is deployed), the role groundcrew-deploy, and the task execution role groundcrew-task-execution. The deploy role may only create and change ECS services in that cluster, ECR repositories named groundcrew-*, log groups under /groundcrew/, security groups tagged project=groundcrew, and secrets under groundcrew/, which it can write but never read. Every deploy still waits for your approval of its plan.

For an account that is already connected:

1. Choose Enable deploys on the connection.
2. In CloudFormation, select the groundcrew-read-only stack and choose Update, Replace existing template, Upload a template file, with the same file.
3. Set Tier to deploy, leave the rest, and submit. Wait for UPDATE_COMPLETE, then choose Verify in the dialog.

Deploys need subnets with public addresses; Groundcrew uses the region's default VPC. See Deploys.

With EnableOperate=true, the stack creates groundcrew-operate, which can roll an ECS service back or restart it, make a secret's previous version current again, point a Lambda alias at an earlier version, or reboot an EC2 instance whose status checks fail. It acts only on the resources you list:

• OperateServiceArns: ECS services, for example all services in one cluster.
• OperateSecretArns: Secrets Manager secrets, by prefix.
• OperateFunctionArns and OperateInstanceArns: Lambda functions and EC2 instances.
• OperatePassRoleArns: the task roles of services you want rolled back, if their task definitions have roles of their own.

Update the stack with these, then choose Enable emergency fixes on the connection. Groundcrew checks the role before it uses it. Each fix needs an approval, by default from an owner.

• "Usually the stack was created with a different ExternalId". The stack has an ExternalId from an earlier attempt or another workspace. Update the stack with the ExternalId shown in the dialog, or delete it and create it again. If the stack is brand new, wait a minute and choose Verify again: IAM changes take a moment to reach every region.
• "This role can be assumed without the ExternalId, which is unsafe". The role's trust policy was changed by hand or created without the template. Groundcrew refuses it. Delete the role and create the stack from the template.
• The stack fails with "groundcrew-read-only already exists". IAM role names are global in an account, so a stack in another region, or from an earlier connection, already made the role. Update that stack instead, delete it first, or set the RoleName parameter to another name that starts with groundcrew-.
• Connected, but the map is empty. The stack's region is not where your workloads run. Choose Regions on the connection and add the right ones. The role works in every region.
• Connected to the wrong account. The RoleArn came from a stack in another account. Remove the connection, delete that stack, and start again signed in to the right account.
• "Requires capabilities: [CAPABILITY_NAMED_IAM]". You did not tick the acknowledgement, or the CLI command is missing --capabilities CAPABILITY_NAMED_IAM.
• An emergency fix plan says it needs PassRole. The service's task definition uses a role that is not in OperatePassRoleArns. Add it and update the stack.

To change what the role can do, update the groundcrew-read-only stack with new parameters. Turning deploys or emergency fixes off in Groundcrew stops using those roles at once; update the stack too to delete them.

To disconnect, remove the connection on the Connections page. That deletes everything Groundcrew discovered through it. Then delete the groundcrew-read-only stack in CloudFormation. If you used deploys, delete Groundcrew's deployed services in groundcrew-deploys first, so the cluster can be removed. The full model is on the Security page.