Deploying AWS DevOps Agent using Terraform

AWS DevOps Agent, an AI-powered operational service for investigating production incidents, can be deployed using Terraform. The service correlates telemetry and infrastructure changes to identify root causes and recommend improvements, with Agent Spaces defining access boundaries. Supported regions include us-east-1, eu-west-1, and others.

AWS DevOps Agent is an AI-powered operational service designed to investigate production incidents, correlate telemetry and infrastructure changes, identify likely root causes, and recommend preventive improvements. The service can work with AWS resources, observability platforms, code repositories, CI/CD systems, runbooks, and ticketing systems. AWS DevOps Agent acts as an operational assistant for DevOps and Site Reliability Engineering teams. It can: AWS defines an Agent Space as the logical boundary controlling what the agent can access. Each Agent Space has its own AWS account access, external integrations, operator permissions, investigation data, and chat history. An Agent Space should normally align with an application, business service, platform, or on-call ownership boundary. AWS DevOps Agent can investigate resources across Regions after an AWS account is associated with the Agent Space. You do not need to create a separate Agent Space in every workload Region. However, the Agent Space itself must be created in a supported Region. At the time of writing, supported Regions include: us-east-1 us-west-2 ca-central-1 sa-east-1 ap-south-1 ap-southeast-1 ap-southeast-2 ap-northeast-1 eu-central-1 eu-west-1 eu-west-2 Production operations are available in all supported Regions, while some preview capabilities can have more limited Regional availability. For European workloads, eu-west-1 or eu-central-1 may be appropriate depending on latency, data residency, and organizational requirements. Before starting, ensure you have: Check the installed tools : 1 terraform version terraform version Terraform v1.15.8 2 AWS CLI version aws --version aws-cli/2.24.0 Python/3.12.6 Windows/11 exe/AMD64 3 Verify AWS identity: aws sts get-caller-identity Expected output: { "UserId": "AIDAXXXXXXXXXXXXXXXX", "Account": "123456789876", "Arn": "arn:aws:iam::123456789876:user/terraform-admin" } For local testing, an AWS CLI profile can be used: aws configure --profile devops-agent-admin For production CI/CD, use temporary credentials through OpenID Connect or an AWS role instead of storing long-lived access keys. A small environment, can use the following structure: aws-devops-agent-terraform/ ├── backend.tf ├── versions.tf ├── providers.tf ├── variables.tf ├── locals.tf ├── data.tf ├── iam-agent.tf ├── iam-operator.tf ├── devops-agent.tf ├── associations.tf ├── outputs.tf ├── terraform.tfvars.example └── README.md For a larger environment, extract the deployment into a reusable module: aws-devops-agent-terraform/ ├── modules/ │ └── devops-agent/ │ ├── main.tf │ ├── iam.tf │ ├── variables.tf │ └── outputs.tf └── environments/ ├── production/ └── non-production/ Step 1: Configure the Terraform versions Create versions.tf: terraform { required version = " = 1.6.0" required providers { aws = { source = "hashicorp/aws" version = "~ 6.0" } awscc = { source = "hashicorp/awscc" version = "~ 1.0" } time = { source = "hashicorp/time" version = "~ 0.13" } } } The awscc provider is important because AWS DevOps Agent resources are exposed through AWS Cloud Control. The time provider can be used to handle IAM propagation delays before creating the Agent Space. Step 2: Configure the providers Create providers.tf: provider "aws" { region = var.aws region profile = var.aws profile default tags { tags = local.common tags } } provider "awscc" { region = var.aws region profile = var.aws profile } For local development, profile is acceptable. In CI/CD, remove the profile and let the provider obtain temporary credentials from the pipeline environment: provider "aws" { region = var.aws region default tags { tags = local.common tags } } provider "awscc" { region = var.aws region } Avoid putting access keys directly inside the provider, as shown below: provider "aws" { access key = "AKIA..." secret key = "..." } Step 3: Define variables Create variables.tf: variable "aws region" { description = "AWS Region in which the Agent Space will be created." type = string default = "eu-west-1" validation { condition = contains "us-east-1", "us-west-2", "ca-central-1", "sa-east-1", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ap-northeast-1", "eu-central-1", "eu-west-1", "eu-west-2" , var.aws region error message = "The selected Region is not currently supported by AWS DevOps Agent." } } variable "aws profile" { description = "Optional AWS CLI profile for local deployment." type = string default = null } variable "agent space name" { description = "Name of the AWS DevOps Agent Space." type = string validation { condition = length trimspace var.agent space name 2 error message = "The Agent Space name must contain at least three characters." } } variable "agent space description" { description = "Description of the Agent Space and its operational boundary." type = string } variable "environment" { description = "Deployment environment." type = string default = "production" validation { condition = contains "development", "test", "staging", "production" , var.environment error message = "Environment must be development, test, staging, or production." } } variable "application name" { description = "Application or platform monitored by the Agent Space." type = string } variable "additional tags" { description = "Additional tags applied to supported resources." type = map string default = {} } Step 4: Create common tags Create locals.tf: locals { common tags = merge { Application = var.application name Environment = var.environment ManagedBy = "Terraform" Repository = "aws-devops-agent-terraform" Service = "AWS-DevOps-Agent" }, var.additional tags } Tags help with: Step 5: Retrieve the current AWS account Create data.tf: data "aws caller identity" "current" {} data "aws partition" "current" {} data "aws region" "current" {} These data sources prevent hardcoding the AWS account ID, partition, and Region. Step 6: Create the DevOps Agent IAM role AWS DevOps Agent needs an IAM role that the service can assume. Create iam-agent.tf: data "aws iam policy document" "devops agent assume role" { statement { sid = "AllowAWSDevOpsAgent" effect = "Allow" actions = "sts:AssumeRole" principals { type = "Service" identifiers = "aidevops.amazonaws.com" } condition { test = "StringEquals" variable = "aws:SourceAccount" values = data.aws caller identity.current.account id } } } resource "aws iam role" "devops agent" { name prefix = "DevOpsAgentRole-AgentSpace-" description = "Role assumed by AWS DevOps Agent for ${var.application name}" assume role policy = data.aws iam policy document.devops agent assume role.json tags = local.common tags } Attach the AWS-managed DevOps Agent access policy resource "aws iam role policy attachment" "devops agent access" { role = aws iam role.devops agent.name policy arn = "arn:${data.aws partition.current.partition}:iam::aws:policy/AIDevOpsAgentAccessPolicy" } AWS DevOps Agent can also require permission to create or use the AWS Resource Explorer service-linked role. Create a narrowly scoped inline policy: data "aws iam policy document" "resource explorer service linked role" { statement { sid = "AllowResourceExplorerServiceLinkedRole" effect = "Allow" actions = "iam:CreateServiceLinkedRole" resources = " " condition { test = "StringEquals" variable = "iam:AWSServiceName" values = "resource-explorer-2.amazonaws.com" } } } resource "aws iam role policy" "resource explorer service linked role" { name = "AllowResourceExplorerServiceLinkedRole" role = aws iam role.devops agent.id policy = data.aws iam policy document.resource explorer service linked role.json } Check the current AWS-managed policy names in the official AWS documentation before deployment. Service policies can evolve as capabilities are added. Step 7: Create the operator web application role The operator role controls what engineers can do through the AWS DevOps Agent web application. Create iam-operator.tf: data "aws iam policy document" "operator assume role" { statement { sid = "AllowAWSDevOpsAgentOperatorApp" effect = "Allow" actions = "sts:AssumeRole" principals { type = "Service" identifiers = "aidevops.amazonaws.com" } condition { test = "StringEquals" variable = "aws:SourceAccount" values = data.aws caller identity.current.account id } } } resource "aws iam role" "operator" { name prefix = "DevOpsAgentRole-WebappAdmin-" description = "Operator web application role for ${var.application name}" assume role policy = data.aws iam policy document.operator assume role.json tags = local.common tags } resource "aws iam role policy attachment" "operator access" { role = aws iam role.operator.name policy arn = "arn:${data.aws partition.current.partition}:iam::aws:policy/AIDevOpsOperatorAppAccessPolicy" } Separating the agent role from the operator role is important: Do not combine these responsibilities into a single role. Step 8: Handle IAM propagation IAM is eventually consistent. The DevOps Agent service validates the role trust policies while the Agent Space is being created. Add a small delay: resource "time sleep" "wait for iam propagation" { create duration = "30s" depends on = aws iam role policy attachment.devops agent access, aws iam role policy attachment.operator access, aws iam role policy.resource explorer service linked role } The official AWS Terraform example also accounts for IAM propagation. If role validation still fails, waiting briefly and rerunning terraform apply can allow Terraform to continue from the existing IAM resources. Step 9: Create the Agent Space Create devops-agent.tf: resource "awscc devopsagent agent space" "this" { name = var.agent space name description = var.agent space description operator app = { enabled = true role arn = aws iam role.operator.arn } depends on = time sleep.wait for iam propagation } The exact resource schema can change as the AWS Cloud Control resource evolves. Validate the current arguments with: terraform providers schema -json You can also inspect the resource documentation: terraform init terraform providers Step 10: Associate the monitoring account The account association connects the current AWS account to the Agent Space. Create associations.tf: resource "awscc devopsagent association" "monitoring account" { agent space id = awscc devopsagent agent space.this.agent space id association type = "AWS" configuration = { account id = data.aws caller identity.current.account id role arn = aws iam role.devops agent.arn source type = "MONITOR" } depends on = awscc devopsagent agent space.this } Because AWS Cloud Control schemas can differ between provider releases, compare the property names with the current Terraform Registry schema before publishing or applying the configuration. The official AWS sample is the safest baseline for the exact awscc devopsagent association configuration. AWS confirms that this association links the monitoring account to the Agent Space. Step 11: Define outputs Create outputs.tf: output "agent space id" { description = "AWS DevOps Agent Space ID." value = awscc devopsagent agent space.this.agent space id } output "agent space arn" { description = "AWS DevOps Agent Space ARN." value = awscc devopsagent agent space.this.agent space arn } output "agent space name" { description = "AWS DevOps Agent Space name." value = var.agent space name } output "devops agent role arn" { description = "IAM role assumed by AWS DevOps Agent." value = aws iam role.devops agent.arn } output "operator role arn" { description = "Operator web application IAM role." value = aws iam role.operator.arn } output "monitoring account id" { description = "AWS monitoring account ID." value = data.aws caller identity.current.account id } Step 12: Configure the environment Create terraform.tfvars.example: aws region = "eu-west-1" aws profile = "devops-agent-admin" agent space name = "payments-production" agent space description = "AWS DevOps Agent Space for the production payments platform" application name = "payments-platform" environment = "production" additional tags = { Owner = "Platform-Engineering" CostCenter = "CC-1234" Criticality = "High" } Copy the file: cp terraform.tfvars.example terraform.tfvars Never commit terraform.tfvars when it contains account-specific or sensitive data. Add it to .gitignore : .terraform/ .tfstate .tfstate. .tfplan terraform.tfvars crash.log override.tf override.tf.json override.tf override.tf.json Commit .terraform.lock.hcl so that the same provider versions are used across development and CI/CD environments. Step 13: Deploy the Agent Space Format the code: terraform fmt -recursive Initialize Terraform: terraform init Validate the configuration: terraform validate Create a saved plan: terraform plan \ -out=tfplan Review the plan carefully and apply it: terraform apply tfplan After deployment, inspect the outputs: terraform output Example: agent space id = "abc123" agent space arn = "arn:aws:aidevops:eu-west-1:123456789876:agentspace/abc123" agent space name = "payments-production" operator role arn = "arn:aws:iam::123456789876:role/DevOpsAgentRole-WebappAdmin-. Step 14: Verify the deployment Use the AWS CLI: aws devops-agent get-agent-space \ --agent-space-id "$ terraform output -raw agent space id " \ --region "$ terraform output -raw aws region 2 /dev/null || echo eu-west-1 " Alternatively: AGENT SPACE ID=$ terraform output -raw agent space id aws devops-agent get-agent-space \ --agent-space-id "$AGENT SPACE ID" \ --region eu-west-1 You can also verify that the IAM roles exist: aws iam get-role \ --role-name "$ terraform output -raw devops agent role arn | awk -F/ '{print $NF}' " Then open the AWS DevOps Agent console and confirm: 1 Use a remote Terraform backend Do not store production Terraform state only on an engineer’s laptop. Example S3 backend: terraform { backend "s3" { bucket = "company-terraform-state-prod" key = "platform/aws-devops-agent/terraform.tfstate" region = "eu-west-1" encrypt = true use lockfile = true } } The backend bucket should have: Bootstrap the backend separately because Terraform cannot use a backend that does not yet exist. 2 Protect observability data The agent can process logs, metrics, traces, ticket metadata, resource tags, and other operational information. Do not place: inside logs, tags, or incident descriptions. AWS notes that personally identifiable information is not automatically removed when data is summarized. Sensitive information should therefore be redacted before it enters observability systems. 1 Resource type not found Example: Error: Invalid resource type The provider hashicorp/aws does not support resource type "aws devopsagent agent space". Cause: AWS DevOps Agent resources use the AWS Cloud Control provider. Solution: required providers { awscc = { source = "hashicorp/awscc" version = "~ 1.0" } } Use: awscc devopsagent agent space awscc devopsagent association The official AWS documentation requires the awscc provider for these resources. 2 IAM trust policy validation failure Example: The operator role trust policy is invalid Possible causes: Resolution: 3 Access denied while creating the Agent Space Check the caller identity: aws sts get-caller-identity Then verify the deployment principal can: Also check whether an SCP blocks: aidevops: iam:CreateServiceLinkedRole iam:PassRole Do not grant unrestricted administrator access permanently merely to bypass a policy problem. To remove the environment: terraform plan -destroy -out=destroy.tfplan terraform apply destroy.tfplan Or: terraform destroy Destroying an Agent Space can permanently remove its investigation history, recommendations, and associated data. Therefore, review retention requirements before deletion.