AWS devopsagent documentation change
Summary
Restructured documentation for CDK deployment of AWS DevOps Agent. Added cross-account monitoring instructions, clarified resource creation details, updated prerequisites, and enhanced security considerations with IAM role trust policies.
Security assessment
The changes emphasize IAM role configurations with trust policies restricted to the 'aidevops.amazonaws.com' service principal and account-specific conditions. While this improves security documentation, there's no evidence of addressing a specific vulnerability or incident.
Diff
diff --git a/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-aws-cdk.md b/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-aws-cdk.md index dacaa2c4b..080a3c805 100644 --- a//devopsagent/latest/userguide/getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-aws-cdk.md +++ b//devopsagent/latest/userguide/getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-aws-cdk.md @@ -5 +5 @@ -OverviewPrerequisitesWhat gets createdSetupDeploymentVerificationAdding additional associationsCustomizationTroubleshootingCleanupSecurity considerationsNext stepsAdditional resources +OverviewPrerequisitesWhat this guide coversResources createdSetupPart 1: Deploy the agent spacePart 2 (Optional): Add cross-account monitoringTroubleshootingCleanupSecurity considerationsNext stepsAdditional resources @@ -11 +11 @@ OverviewPrerequisitesWhat gets createdSetupDeploymentVerificationAdding addition -This guide shows you how to use AWS Cloud Development Kit (CDK) to create and deploy AWS DevOps Agent resources, including the agent space, IAM roles, and AWS account associations. Using CDK provides infrastructure as code benefits such as version control, repeatability, and automated deployment. +This guide shows you how to use the AWS Cloud Development Kit (AWS CDK) to create and deploy AWS DevOps Agent resources. The CDK application automates the creation of an agent space, IAM roles, an operator app, and AWS account associations through AWS CloudFormation. @@ -13 +13 @@ This guide shows you how to use AWS Cloud Development Kit (CDK) to create and de -The CDK approach automates the manual steps described in the [CLI onboarding guide](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html) by creating all required resources through CloudFormation. +The CDK approach automates the manual steps described in the [CLI onboarding guide](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html) by defining all required resources as infrastructure as code. @@ -20,0 +21,2 @@ The CDK approach automates the manual steps described in the [CLI onboarding gui +Before you begin, make sure you have the following: + @@ -23 +25 @@ The CDK approach automates the manual steps described in the [CLI onboarding gui - * Node.js (version 18 or later) + * Node.js version 18 or later @@ -27 +29 @@ The CDK approach automates the manual steps described in the [CLI onboarding gui - * AWS DevOps Agent is available in us-east-1 + * One AWS account for the monitoring (primary) account @@ -28,0 +31 @@ The CDK approach automates the manual steps described in the [CLI onboarding gui + * (Optional) A second AWS account if you want to set up cross-account monitoring @@ -32 +34,0 @@ The CDK approach automates the manual steps described in the [CLI onboarding gui -## What gets created @@ -34 +36 @@ The CDK approach automates the manual steps described in the [CLI onboarding gui -The CDK stack creates the following resources using CloudFormation: +###### Important @@ -36 +38 @@ The CDK stack creates the following resources using CloudFormation: -### IAM Roles + __AWS DevOps Agent is currently available in the`us-east-1` Region. @@ -38 +40 @@ The CDK stack creates the following resources using CloudFormation: - * **DevOpsAgentRole-AgentSpace** : Main role for the agent space with: +## What this guide covers @@ -40 +42 @@ The CDK stack creates the following resources using CloudFormation: - * Trust policy for `aidevops.amazonaws.com` service +This guide is divided into two parts: @@ -42 +44 @@ The CDK stack creates the following resources using CloudFormation: - * `AIOpsAssistantPolicy` managed policy + * **Part 1** — Deploy an agent space with an operator app and an AWS association in your monitoring account. After completing this part, the agent can monitor issues in that account. @@ -44 +46 @@ The CDK stack creates the following resources using CloudFormation: - * Additional inline policies for support and expanded permissions + * **Part 2 (Optional)** — Add a source AWS association for a service account and deploy a cross-account IAM role into that account. This allows the agent space to monitor resources across accounts. @@ -46 +47,0 @@ The CDK stack creates the following resources using CloudFormation: - * **DevOpsAgentRole-WebappAdmin** : Operator app role with: @@ -48 +48,0 @@ The CDK stack creates the following resources using CloudFormation: - * Trust policy for `aidevops.amazonaws.com` service @@ -50 +49,0 @@ The CDK stack creates the following resources using CloudFormation: - * Inline policies for basic operator actions and support @@ -51,0 +51 @@ The CDK stack creates the following resources using CloudFormation: +## Resources created @@ -52,0 +53 @@ The CDK stack creates the following resources using CloudFormation: +### Part 1: DevOpsAgentStack (monitoring account) @@ -53,0 +55 @@ The CDK stack creates the following resources using CloudFormation: + * **IAM role** (`DevOpsAgentRole-AgentSpace`) — Assumed by the DevOps Agent service to monitor the account. Includes the `AIOpsAssistantPolicy` managed policy and inline policies for support and expanded permissions. @@ -55 +57 @@ The CDK stack creates the following resources using CloudFormation: -### DevOps Agent Resources + * **IAM role** (`DevOpsAgentRole-WebappAdmin`) — Operator app role with inline policies for agent operations and support actions. @@ -57 +59 @@ The CDK stack creates the following resources using CloudFormation: - * **Agent Space** : Created using `AWS::DevOpsAgent::AgentSpace` CloudFormation resource + * **Agent space** (`MyCDKAgentSpace`) — The central agent space, created using the `AWS::DevOpsAgent::AgentSpace` CloudFormation resource. Includes operator app configuration. @@ -59 +61 @@ The CDK stack creates the following resources using CloudFormation: - * **AWS Association** : Created using `AWS::DevOpsAgent::Association` CloudFormation resource + * **Association** (AWS monitor) — Links the monitoring account to the agent space using the `AWS::DevOpsAgent::Association` CloudFormation resource. @@ -60,0 +63 @@ The CDK stack creates the following resources using CloudFormation: + * **Association** (AWS source) — (Optional) Links the service account to the agent space for cross-account monitoring. @@ -64 +66,0 @@ The CDK stack creates the following resources using CloudFormation: -## Setup @@ -66 +68 @@ The CDK stack creates the following resources using CloudFormation: -### 1\. Clone the sample repository +### Part 2: ServiceStack (service account, optional) @@ -67,0 +70 @@ The CDK stack creates the following resources using CloudFormation: + * **IAM role** (`DevOpsAgentRole-SecondaryAccount`) — Cross-account role with a fixed name. Trusted by the agent space in the monitoring account. Includes the `AIOpsAssistantPolicy` managed policy and expanded inline policies. @@ -69,2 +72 @@ The CDK stack creates the following resources using CloudFormation: - git clone https://github.com/aws-samples/sample-aws-devops-agent-cdk.git - cd sample-aws-devops-agent-cdk + * **Lambda function** (`echo-service`) — A simple example service that echoes back input events. @@ -73 +74,0 @@ The CDK stack creates the following resources using CloudFormation: -### 2\. Install dependencies @@ -76 +77 @@ The CDK stack creates the following resources using CloudFormation: - npm install +## Setup @@ -77,0 +79 @@ The CDK stack creates the following resources using CloudFormation: +### Step 1: Clone the sample repository @@ -79 +80,0 @@ The CDK stack creates the following resources using CloudFormation: -### 3\. Bootstrap your AWS environment @@ -81 +82,6 @@ The CDK stack creates the following resources using CloudFormation: -If you haven't bootstrapped CDK in your AWS account and region before: + git clone https://github.com/aws-samples/sample-aws-devops-agent-cdk.gitcd sample-aws-devops-agent-cdk + +### Step 2: Install dependencies + + + npm install @@ -84 +90 @@ If you haven't bootstrapped CDK in your AWS account and region before: - cdk bootstrap --region us-east-1 +## Part 1: Deploy the agent space @@ -85,0 +92 @@ If you haven't bootstrapped CDK in your AWS account and region before: +In this section, you create the agent space, IAM roles, operator app, and an AWS association in your monitoring account. @@ -87 +94 @@ If you haven't bootstrapped CDK in your AWS account and region before: -### 4\. Review the configuration +### Step 1: Configure the monitoring account ID @@ -89 +96 @@ If you haven't bootstrapped CDK in your AWS account and region before: -The CDK stack is pre-configured with sensible defaults. You can modify the following in `lib/sample-aws-devops-agent-cdk-stack.ts`: +Open `lib/constants.ts` and set your monitoring account ID: @@ -91 +97,0 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo - * Agent space name (default: "MyAgentSpace") @@ -93 +99 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo - * IAM role names + export const MONITORING_ACCOUNT_ID = "<YOUR_MONITORING_ACCOUNT_ID>"; @@ -95 +100,0 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo - * Policy configurations @@ -96,0 +102 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo +### Step 2: Bootstrap the AWS CDK environment @@ -97,0 +104 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo +If you have not bootstrapped the AWS CDK in your monitoring account, run the following command: @@ -100 +107 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo -## Deployment + cdk bootstrap aws://<MONITORING_ACCOUNT_ID>/us-east-1 --profile monitoring @@ -102 +109,3 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo -### 1\. Build the TypeScript code +### Step 3: Build and deploy + +Build the TypeScript code and deploy the stack: @@ -105,0 +115 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo + cdk deploy DevOpsAgentStack --profile monitoring @@ -106,0 +117 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo +### Step 4: Record the stack outputs @@ -108 +119 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo -### 2\. Preview the changes +After deployment completes, the AWS CDK prints the stack outputs. Record these values for later use: @@ -110 +120,0 @@ The CDK stack is pre-configured with sensible defaults. You can modify the follo -Review what resources will be created: @@ -111,0 +122,5 @@ Review what resources will be created: + Outputs: + DevOpsAgentStack.AgentSpaceArn = arn:aws:aidevops:us-east-1: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 @@ -113 +128 @@ Review what resources will be created: - cdk diff --region us-east-1 +If you plan to complete Part 2, save the `AgentSpaceArn` value. You will need it to configure the service account stack. @@ -114,0 +130 @@ Review what resources will be created: +### Step 5: Verify the deployment @@ -116 +132 @@ Review what resources will be created: -### 3\. Deploy the stack +Use the AWS CLI to verify that the agent space was created successfully: @@ -119 +135,3 @@ Review what resources will be created: - cdk deploy --region us-east-1 + aws devopsagent get-agent-space \ + --agent-space-id <AGENT_SPACE_ID> \ + --region us-east-1 @@ -120,0 +139 @@ Review what resources will be created: +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. @@ -122 +141 @@ Review what resources will be created: -The deployment will create all necessary resources and output important values: +## Part 2 (Optional): Add cross-account monitoring @@ -124 +143 @@ The deployment will create all necessary resources and output important values: - * `AgentSpaceId`: The ID of the created agent space +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: @@ -126 +145 @@ The deployment will create all necessary resources and output important values: - * `AgentSpaceRoleArn`: The ARN of the agent space role + 1. Adding a source AWS association in the DevOpsAgentStack that points to the service account. @@ -128 +147 @@ The deployment will create all necessary resources and output important values: - * `OperatorRoleArn`: The ARN of the operator role + 2. Deploying the ServiceStack into the service account with an IAM role that trusts the agent space. @@ -130 +148,0 @@ The deployment will create all necessary resources and output important values: - * `AssociationId`: The ID of the AWS association @@ -133,0 +152 @@ The deployment will create all necessary resources and output important values: +###### Important @@ -135 +154 @@ The deployment will create all necessary resources and output important values: -### 4\. Enable the operator app + __You must complete Part 1 before proceeding. The ServiceStack requires the`AgentSpaceArn` from the DevOpsAgentStack deployment output. @@ -137 +156 @@ The deployment will create all necessary resources and output important values: -After deployment, run the provided script to enable the operator app: +### Step 1: Configure the service account ID @@ -138,0 +158 @@ After deployment, run the provided script to enable the operator app: +Open `lib/constants.ts` and set your service account ID: @@ -140 +159,0 @@ After deployment, run the provided script to enable the operator app: - ./scripts/enable-operator-app.sh @@ -141,0 +161 @@ After deployment, run the provided script to enable the operator app: + export const SERVICE_ACCOUNT_ID = "<YOUR_SERVICE_ACCOUNT_ID>"; @@ -143 +162,0 @@ After deployment, run the provided script to enable the operator app: -This script uses the stack outputs to automatically configure the operator app with the correct role ARN and agent space ID. @@ -145 +164 @@ This script uses the stack outputs to automatically configure the operator app w -## Verification +The DevOpsAgentStack creates a source AWS association using this account ID. If you deployed the DevOpsAgentStack before setting this value, redeploy to create the association: @@ -147 +165,0 @@ This script uses the stack outputs to automatically configure the operator app w -Verify your setup using the AWS CLI: @@ -148,0 +167,2 @@ Verify your setup using the AWS CLI: + npm run build + cdk deploy DevOpsAgentStack --profile monitoring @@ -150,5 +170 @@ Verify your setup using the AWS CLI: - # Get details of your AgentSpace (replace <AGENT_SPACE_ID> with the output value) - aws devopsagent get-agent-space \ - --agent-space-id <AGENT_SPACE_ID> \ - --endpoint-url "https://api.prod.cp.aidevops.us-east-1.api.aws" \ - --region us-east-1 +### Step 2: Set the agent space ARN