Getting started with AWS DevOps Agent using AWS CDK

Overview

This guide shows you how to use the AWS Cloud Development Kit (AWS CDK) to create and deploy AWS DevOps Agent resources. The AWS CDK application automates the creation of an agent space, AWS Identity and Access Management (IAM) roles, an operator app, and AWS account associations through AWS CloudFormation.

The AWS CDK approach automates the manual steps described in the CLI onboarding guide by defining all required resources as infrastructure as code.

AWS DevOps Agent is available in the following 6 AWS Regions: US East (N. Virginia), US West (Oregon), Asia Pacific (Sydney), Asia Pacific (Tokyo), Europe (Frankfurt), and Europe (Ireland). For more information about supported Regions, see Supported Regions.

Prerequisites

Before you begin, make sure that you have the following:

npm install -g aws-cdk

What this guide covers

This guide is divided into two parts:

Resources created

Part 1: DevOpsAgentStack (monitoring account)

Part 2: ServiceStack (service account, optional)

Setup

Step 1: Clone the sample repository

Run the following commands to clone the repository and change to the project directory:

git clone https://github.com/aws-samples/sample-aws-devops-agent-cdk.git
cd sample-aws-devops-agent-cdk

Step 2: Install dependencies

Run the following command to install the project dependencies:

npm install

Part 1: Deploy the agent space

In this section, you create the agent space, IAM roles, operator app, and an AWS association in your monitoring account.

Step 1: Configure the monitoring account ID

Open lib/constants.ts and set your monitoring account ID:

The following example shows the constant to update:

export const MONITORING_ACCOUNT_ID = "<YOUR_MONITORING_ACCOUNT_ID>";

Step 2: Bootstrap the AWS CDK environment

If you haven't bootstrapped the AWS CDK in your monitoring account, run the following command:

cdk bootstrap aws://<MONITORING_ACCOUNT_ID>/<REGION> --profile monitoring

Step 3: Build and deploy

Run the following commands to build the TypeScript code and deploy the stack:

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

Step 4: Record the stack outputs

After deployment completes, the AWS CDK prints the stack outputs. Record these values for later use.

The following example shows the expected output:

Outputs:
DevOpsAgentStack.AgentSpaceArn = arn:aws:aidevops:<REGION>:123456789012:agentspace/abc123
DevOpsAgentStack.AgentSpaceRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-AgentSpace
DevOpsAgentStack.OperatorRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-WebappAdmin
DevOpsAgentStack.AssociationId = assoc-xyz

If you plan to complete Part 2, save the AgentSpaceArn value. You need it to configure the service account stack.

Step 5: Verify the deployment

To verify that the agent space was created successfully, run the following AWS CLI command:

aws devopsagent get-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

At this point, your agent space is deployed with the operator app enabled and your monitoring account associated. The agent can monitor issues in this account.

Part 2 (Optional): Add cross-account monitoring

In this section, you extend the setup so that your agent space can monitor resources in a second AWS account (the service account). This involves two actions:

Step 1: Configure the service account ID

Open lib/constants.ts and set your service account ID:

The following example shows the constant to update:

export const SERVICE_ACCOUNT_ID = "<YOUR_SERVICE_ACCOUNT_ID>";

The DevOpsAgentStack creates a source AWS association by using this account ID. If you deployed the DevOpsAgentStack before setting this value, redeploy to create the association:

Run the following commands to redeploy:

npm run build
cdk deploy DevOpsAgentStack --profile monitoring

Step 2: Set the agent space ARN

Copy the AgentSpaceArn value from the DevOpsAgentStack output (Part 1, Step 4) and set it in lib/constants.ts:

The following example shows the constant to update:

export const AGENT_SPACE_ARN = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>";

The ServiceStack uses this value to scope the trust policy on the secondary account role. The ServiceStack is only synthesized when this value is set.

Step 3: Bootstrap the service account

If you haven't bootstrapped the AWS CDK in your service account, run the following command:

cdk bootstrap aws://<SERVICE_ACCOUNT_ID>/<REGION> --profile service

Step 4: Deploy the ServiceStack

Run the following commands to build and deploy the ServiceStack by using credentials for the service account:

npm run build
cdk deploy ServiceStack --profile service

This creates the following resources in the service account:

Step 5: Verify the deployment

To confirm that the Lambda function was deployed successfully, run the following commands to test the echo service:

aws lambda invoke \
  --function-name echo-service \
  --payload '{"test": "hello world"}' \
  --profile service \
  response.json
cat response.json

Troubleshooting

This section describes common issues and how to resolve them.

CloudFormation resource type not found

IAM role creation failed

Cross-account deployment fails with "Could not assume role in target account"

IAM propagation delays

Cleanup

To remove all resources, destroy the stacks in reverse order.

Run the following commands to destroy the stacks:

# If you deployed the ServiceStack, destroy it first
cdk destroy ServiceStack --profile service
# Then destroy the DevOpsAgentStack
cdk destroy DevOpsAgentStack --profile monitoring

Warning: This action permanently deletes your agent space and all associated data. This action can't be undone. Make sure that you have backed up any important information before you proceed.

Security considerations

Next steps

After you have deployed your AWS DevOps Agent by using the AWS CDK:

Additional resources