training/data/raw/getting-started-with-aws-devops-agent-cli-onboarding-guide.md

AWS DevOps Agent CLI onboarding guide

Overview

With AWS DevOps Agent, you can monitor and manage your AWS infrastructure. This guide walks you through setting up AWS DevOps Agent by using the AWS Command Line Interface (AWS CLI). You create IAM roles, set up an agent space, and associate your AWS account. You also enable the operator app and optionally connect third-party integrations. This guide takes approximately 20 minutes to complete.

Prerequisites

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

• AWS CLI version 2 installed and configured
• Authentication to your AWS monitoring account
• Permissions to create AWS Identity and Access Management (IAM) roles and attach policies
• An AWS account to use as the monitoring account
• Familiarity with the AWS CLI and JSON syntax

Throughout this guide, replace the following placeholder values with your own:

• <MONITORING_ACCOUNT_ID> — Your 12-digit AWS account ID for the monitoring (primary) account
• <EXTERNAL_ACCOUNT_ID> — The 12-digit AWS account ID of the secondary account to monitor
• <REGION> — The AWS Region code for your agent space (for example, us-east-1 or eu-central-1)
• <AGENT_SPACE_ID> — The agent space identifier returned by the create-agent-space command

IAM roles setup

1. Create the DevOps Agent space role

Create the IAM trust policy:

cat > devops-agentspace-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<MONITORING_ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/*"
        }
      }
    }
  ]
}
EOF

Create the IAM role:

aws iam create-role \
  --region <REGION> \
  --role-name DevOpsAgentRole-AgentSpace \
  --assume-role-policy-document file://devops-agentspace-trust-policy.json

Attach the AWS managed policy:

aws iam attach-role-policy \
  --role-name DevOpsAgentRole-AgentSpace \
  --policy-arn arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy

2. Create the operator app IAM role

Create the IAM trust policy:

cat > devops-operator-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "aidevops.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<MONITORING_ACCOUNT_ID>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/*"
        }
      }
    }
  ]
}
EOF

Create the IAM role:

aws iam create-role \
  --role-name DevOpsAgentRole-WebappAdmin \
  --assume-role-policy-document file://devops-operator-trust-policy.json \
  --region <REGION>

Attach the AWS managed operator app policy:

aws iam attach-role-policy \
  --role-name DevOpsAgentRole-WebappAdmin \
  --policy-arn arn:aws:iam::aws:policy/AIDevOpsOperatorAppAccessPolicy

Onboarding steps

1. Create an agent space

aws devops-agent create-agent-space \
  --name "MyAgentSpace" \
  --description "AgentSpace for monitoring my application" \
  --region <REGION>

2. Associate your AWS account

aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id aws \
  --configuration '{
    "aws": {
      "assumableRoleArn": "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace",
      "accountId": "<MONITORING_ACCOUNT_ID>",
      "accountType": "monitor"
    }
  }' \
  --region <REGION>

3. Enable the operator app

aws devops-agent enable-operator-app \
  --agent-space-id <AGENT_SPACE_ID> \
  --auth-flow iam \
  --operator-app-role-arn "arn:aws:iam::<MONITORING_ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin" \
  --region <REGION>

4. (Optional) Associate additional source accounts

Create a cross-account role in the external account and then associate it:

aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id aws \
  --configuration '{
    "sourceAws": {
      "accountId": "<EXTERNAL_ACCOUNT_ID>",
      "accountType": "source",
      "assumableRoleArn": "arn:aws:iam::<EXTERNAL_ACCOUNT_ID>:role/DevOpsAgentCrossAccountRole"
    }
  }' \
  --region <REGION>

5. (Optional) Associate GitHub

You must first register GitHub through the AWS DevOps Agent console using the OAuth flow before you can associate it through the CLI.

aws devops-agent associate-service \
  --agent-space-id <AGENT_SPACE_ID> \
  --service-id <SERVICE_ID> \
  --configuration '{
    "github": {
      "repoName": "<GITHUB_REPO_NAME>",
      "repoId": "<GITHUB_REPO_ID>",
      "owner": "<GITHUB_OWNER>",
      "ownerType": "organization"
    }
  }' \
  --region <REGION>

6. (Optional) Register and associate ServiceNow

aws devops-agent register-service \
  --service servicenow \
  --service-details '{
    "servicenow": {
      "instanceUrl": "<SERVICENOW_INSTANCE_URL>",
      "authorizationConfig": {
        "oAuthClientCredentials": {
            "clientName": "<SERVICENOW_CLIENT_NAME>",
            "clientId": "<SERVICENOW_CLIENT_ID>",
            "clientSecret": "<SERVICENOW_CLIENT_SECRET>"
        }
      }
    }
  }' \
  --region <REGION>

7. (Optional) Register and associate Dynatrace

aws devops-agent register-service \
  --service dynatrace \
  --service-details '{
    "dynatrace": {
      "accountUrn": "<DYNATRACE_ACCOUNT_URN>",
      "authorizationConfig": {
        "oAuthClientCredentials": {
            "clientName": "<DYNATRACE_CLIENT_NAME>",
            "clientId": "<DYNATRACE_CLIENT_ID>",
            "clientSecret": "<DYNATRACE_CLIENT_SECRET>"
        }
      }
    }
  }' \
  --region <REGION>

8. (Optional) Register and associate Splunk

aws devops-agent register-service \
  --service mcpserversplunk \
  --service-details '{
    "mcpserversplunk": {
      "name": "<SPLUNK_NAME>",
      "endpoint": "<SPLUNK_ENDPOINT>",
      "authorizationConfig": {
        "bearerToken": {
            "tokenName": "<SPLUNK_TOKEN_NAME>",
            "tokenValue": "<SPLUNK_TOKEN_VALUE>"
        }
      }
    }
  }' \
  --region <REGION>

9. (Optional) Register and associate New Relic

aws devops-agent register-service \
  --service mcpservernewrelic \
  --service-details '{
    "mcpservernewrelic": {
      "authorizationConfig": {
        "apiKey": {
          "apiKey": "<YOUR_NEW_RELIC_API_KEY>",
          "accountId": "<YOUR_ACCOUNT_ID>",
          "region": "US"
        }
      }
    }
  }' \
  --region <REGION>

10. (Optional) Register and associate Datadog

You must first register Datadog through the AWS DevOps Agent console using the OAuth flow before you can associate it through the CLI.

11. (Optional) Delete an agent space

aws devops-agent delete-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

Verification

aws devops-agent list-agent-spaces --region <REGION>
aws devops-agent get-agent-space --agent-space-id <AGENT_SPACE_ID> --region <REGION>
aws devops-agent list-associations --agent-space-id <AGENT_SPACE_ID> --region <REGION>

Next steps

• To connect additional integrations, see Configuring capabilities for AWS DevOps Agent.
• To learn about agent skills and capabilities, see DevOps Agent Skills.
• To understand the operator web app, see What is a DevOps Agent Web App?.