Getting started with AWS DevOps Agent using Terraform

Overview

This guide shows you how to use Terraform to create and deploy AWS DevOps Agent resources. The Terraform configuration automates the creation of an agent space, IAM roles, an operator app, and AWS account associations.

The Terraform 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 you have the following:

What this guide covers

This guide is divided into two parts:

Resources created

Part 1: Monitoring account

Part 2: Service account (optional)

Setup

Step 1: Clone the sample repository

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

Step 2: Configure variables

Copy the example variables file and customize it for your environment:

cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars with your agent space name and description:

agent_space_name        = "MyCompanyAgentSpace"
agent_space_description = "DevOps Agent Space for monitoring production workloads"

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: Deploy with automation (recommended)

Use the provided deployment script for a streamlined setup:

./deploy.sh

This script automatically:

Alternatively, if you prefer manual control:

terraform init
terraform plan
terraform apply

Type yes when prompted to confirm the deployment.

Step 2: Record the outputs

After deployment completes, Terraform prints the outputs. Record these values for later use:

Outputs:
agent_space_id              = "abc123"
agent_space_arn             = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/abc123"
agent_space_name            = "MyCompanyAgentSpace"
devops_agentspace_role_arn  = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace-a1b2c3d4"
devops_operator_role_arn    = "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin-a1b2c3d4"
primary_account_id          = "<MONITORING_ACCOUNT_ID>"
primary_account_association_id = "assoc-xyz"

If you plan to complete Part 2, save the agent_space_arn value. You will need it to configure the service account resources.

Step 3: Verify the deployment

Run the post-deployment verification script:

./post-deploy.sh

Or use the AWS CLI to verify that the agent space was created successfully:

aws devops-agent 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 the agent space can monitor resources in a second AWS account (the service account). This involves two actions:

Step 1: Configure the service account ID

In terraform.tfvars, set your service account ID:

service_account_id = "<YOUR_SERVICE_ACCOUNT_ID>"

Step 2: Set the agent space ARN

Copy the agent_space_arn value from the Part 1 output (Step 2) and set it in terraform.tfvars:

agent_space_arn = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>"

The service account resources use this value to scope the trust policy on the secondary account role. These resources are only created when this value is set.

Step 3: Configure the `aws.service` provider

In main.tf, configure the aws.service provider alias with credentials for the service account. You can use either a named profile or an assume role:

Using a profile:

provider "aws" {
  alias   = "service"
  region  = var.aws_region
  profile = "your-service-account-profile"
}

Or using assume role:

provider "aws" {
  alias  = "service"
  region = var.aws_region
  assume_role {
    role_arn = "arn:aws:iam::<SERVICE_ACCOUNT_ID>:role/OrganizationAccountAccessRole"
  }
}

Step 4: Deploy

Apply the updated configuration:

terraform apply

This creates the following resources in the service account:

It also creates a source AWS association in the monitoring account that links the service account.

Step 5: Verify the deployment

Test the echo service to confirm the Lambda function was deployed successfully:

aws lambda invoke \
  --function-name echo-service-tf \
  --payload '{"test": "hello world"}' \
  --profile <your-service-account-profile> \
  --region <REGION> \
  response.json
cat response.json

Troubleshooting

IAM propagation delays

Permission errors

Cross-account deployment fails

Terraform resource type not found

Cleanup

To remove all resources, destroy in reverse order if you deployed Part 2:

./cleanup.sh

Or manually:

terraform destroy

Warning: This permanently deletes your agent space and all associated data. Make sure you have backed up any important information before proceeding.

Security considerations

Next steps

After you have deployed your AWS DevOps Agent using Terraform:

Additional resources