View a markdown version of this page

開始使用 AWS CloudFormation 的 AWS DevOps 代理程式 - AWS DevOps 代理程式
概觀先決條件本指南涵蓋的內容第 1 部分：部署代理程式空間第 2 部分 （選用）：新增跨帳戶監控驗證疑難排解清除後續步驟

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

開始使用 AWS CloudFormation 的 AWS DevOps 代理程式

概觀

本指南說明如何使用 AWS CloudFormation 範本來建立和部署 AWS DevOps 代理程式資源。範本會自動建立代理程式空間、 AWS Identity and Access Management (IAM) 角色、運算子應用程式，以及 AWS 帳戶關聯做為基礎設施做為程式碼。

CloudFormation 方法會透過在宣告式 YAML 範本中定義所有必要的資源，自動執行 CLI 入門指南中所述的手動步驟。

AWS DevOps 代理程式可在多個 AWS 區域使用。如需完整清單，請參閱支援的區域。

先決條件

開始前，請確定您有下列項目：

  • AWS 命令列界面 (AWS CLI) 已安裝並使用適當的登入資料設定

  • 建立 IAM 角色和 CloudFormation 堆疊的許可

  • 一個 AWS 帳戶用於監控 （主要） 帳戶

  • （選用） 如果您想要設定跨 AWS 帳戶監控的第二個帳戶

本指南涵蓋的內容

本指南分為兩個部分：

  • 第 1 部分 — 使用 運算子應用程式和監控帳戶中的 AWS 關聯部署代理程式空間。完成此部分後，代理程式可以監控該帳戶中的問題。

  • 第 2 部分 （選用） — 將跨帳戶 IAM 角色部署到次要帳戶，並新增來源 AWS 關聯。此組態可讓客服人員空間跨帳戶監控資源。

第 1 部分：部署代理程式空間

在本節中，您會建立 CloudFormation 範本，在監控帳戶中佈建代理程式空間、IAM 角色、運算子應用程式和 AWS 關聯。

步驟 1：建立 CloudFormation 範本

將下列範本儲存為 devops-agent-stack.yaml：

AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Agent Space with IAM roles, operator app, and AWS association

Parameters:
  AgentSpaceName:
    Type: String
    Default: MyCloudFormationAgentSpace
    Description: Name for the agent space
  AgentSpaceDescription:
    Type: String
    Default: Agent space deployed with CloudFormation
    Description: Description for the agent space

Resources:
  # IAM role assumed by the DevOps Agent service to monitor the account
  DevOpsAgentSpaceRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: DevOpsAgentRole-AgentSpace
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: aidevops.amazonaws.com
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                aws:SourceAccount: !Ref AWS::AccountId
              ArnLike:
                aws:SourceArn: !Sub arn:aws:aidevops:${AWS::Region}:${AWS::AccountId}:agentspace/*
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy
      Policies:
        - PolicyName: AllowCreateServiceLinkedRoles
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Sid: AllowCreateServiceLinkedRoles
                Effect: Allow
                Action:
                  - iam:CreateServiceLinkedRole
                Resource:
                  - !Sub arn:aws:iam::${AWS::AccountId}:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer

  # IAM role for the operator app interface
  DevOpsOperatorRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: DevOpsAgentRole-WebappAdmin
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: aidevops.amazonaws.com
            Action:
              - sts:AssumeRole
              - sts:TagSession
            Condition:
              StringEquals:
                aws:SourceAccount: !Ref AWS::AccountId
              ArnLike:
                aws:SourceArn: !Sub arn:aws:aidevops:${AWS::Region}:${AWS::AccountId}:agentspace/*
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AIDevOpsOperatorAppAccessPolicy

  # The agent space resource
  AgentSpace:
    Type: AWS::DevOpsAgent::AgentSpace
    DependsOn:
      - DevOpsAgentSpaceRole
      - DevOpsOperatorRole
    Properties:
      Name: !Ref AgentSpaceName
      Description: !Ref AgentSpaceDescription
      OperatorApp:
        Iam:
          OperatorAppRoleArn: !GetAtt DevOpsOperatorRole.Arn

  # Association linking the monitoring account to the agent space
  MonitorAssociation:
    Type: AWS::DevOpsAgent::Association
    Properties:
      AgentSpaceId: !GetAtt AgentSpace.AgentSpaceId
      ServiceId: aws
      Configuration:
        Aws:
          AssumableRoleArn: !GetAtt DevOpsAgentSpaceRole.Arn
          AccountId: !Ref AWS::AccountId
          AccountType: monitor

Outputs:
  AgentSpaceId:
    Description: The agent space ID
    Value: !GetAtt AgentSpace.AgentSpaceId
  AgentSpaceArn:
    Description: The agent space ARN
    Value: !GetAtt AgentSpace.Arn
  AgentSpaceRoleArn:
    Description: The agent space IAM role ARN
    Value: !GetAtt DevOpsAgentSpaceRole.Arn
  OperatorRoleArn:
    Description: The operator app IAM role ARN
    Value: !GetAtt DevOpsOperatorRole.Arn

步驟 2：部署堆疊

執行下列命令來部署堆疊。<REGION> 以 取代 支援的區域（例如，us-east-1)。

aws cloudformation deploy \
  --template-file devops-agent-stack.yaml \
  --stack-name DevOpsAgentStack \
  --capabilities CAPABILITY_NAMED_IAM \
  --region <REGION>

步驟 3：記錄堆疊輸出

部署完成後，請執行下列命令來擷取堆疊輸出。記錄這些值以供日後使用。

aws cloudformation describe-stacks \
  --stack-name DevOpsAgentStack \
  --query 'Stacks[0].Outputs' \
  --region <REGION>

下列範例顯示預期的輸出：

[
  {
    "OutputKey": "AgentSpaceId",
    "OutputValue": "abc123def456"
  },
  {
    "OutputKey": "AgentSpaceArn",
    "OutputValue": "arn:aws:aidevops:<REGION>:<ACCOUNT_ID>:agentspace/abc123def456"
  },
  {
    "OutputKey": "AgentSpaceRoleArn",
    "OutputValue": "arn:aws:iam::<ACCOUNT_ID>:role/DevOpsAgentRole-AgentSpace"
  },
  {
    "OutputKey": "OperatorRoleArn",
    "OutputValue": "arn:aws:iam::<ACCOUNT_ID>:role/DevOpsAgentRole-WebappAdmin"
  }
]

如果您打算完成第 2 部分，請儲存該AgentSpaceArn值。您需要它來設定跨帳戶角色。

步驟 4：驗證部署

若要確認已成功建立代理程式空間，請執行下列 AWS CLI 命令：

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

此時，您的代理程式空間會部署並啟用 運算子應用程式，並與您的監控帳戶相關聯。代理程式可以監控此帳戶中的問題。

第 2 部分 （選用）：新增跨帳戶監控

在本節中，您會擴展設定，讓您的客服人員空間可以監控第二個 AWS 帳戶 （服務帳戶） 中的資源。這涉及兩個動作：

  1. 在信任客服人員空間的服務帳戶中部署 IAM 角色。

  2. 在監控帳戶中新增指向服務帳戶的來源 AWS 關聯。

步驟 1：建立服務帳戶範本

將下列範本儲存為 devops-agent-service-account.yaml。此範本會在次要帳戶中建立跨帳戶 IAM 角色。

AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Cross-account IAM role for secondary account monitoring

Parameters:
  MonitoringAccountId:
    Type: String
    Description: The 12-digit AWS account ID of the monitoring account
  AgentSpaceArn:
    Type: String
    Description: The ARN of the agent space from the monitoring account

Resources:
  # Cross-account IAM role trusted by the agent space
  DevOpsSecondaryAccountRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: DevOpsAgentRole-SecondaryAccount
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: aidevops.amazonaws.com
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                aws:SourceAccount: !Ref MonitoringAccountId
              ArnLike:
                aws:SourceArn: !Ref AgentSpaceArn
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AIDevOpsAgentAccessPolicy
      Policies:
        - PolicyName: AllowCreateServiceLinkedRoles
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Sid: AllowCreateServiceLinkedRoles
                Effect: Allow
                Action:
                  - iam:CreateServiceLinkedRole
                Resource:
                  - !Sub arn:aws:iam::${AWS::AccountId}:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer

Outputs:
  SecondaryAccountRoleArn:
    Description: The cross-account IAM role ARN
    Value: !GetAtt DevOpsSecondaryAccountRole.Arn

步驟 2：部署服務帳戶堆疊

使用服務帳戶的登入資料，執行下列命令：

aws cloudformation deploy \
  --template-file devops-agent-service-account.yaml \
  --stack-name DevOpsAgentServiceAccountStack \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    MonitoringAccountId=<MONITORING_ACCOUNT_ID> \
    AgentSpaceArn=<AGENT_SPACE_ARN> \
  --region <REGION>

步驟 3：新增來源 AWS 關聯

切換回監控帳戶並建立來源 AWS 關聯。您可以透過建立個別堆疊或更新原始範本來執行此操作。下列範例使用獨立範本。

將下列範本儲存為 devops-agent-source-association.yaml：

AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Source AWS association for cross-account monitoring

Parameters:
  AgentSpaceId:
    Type: String
    Description: The agent space ID from the monitoring account stack
  ServiceAccountId:
    Type: String
    Description: The 12-digit AWS account ID of the service account
  ServiceAccountRoleArn:
    Type: String
    Description: The ARN of the DevOpsAgentRole-SecondaryAccount role in the service account

Resources:
  SourceAssociation:
    Type: AWS::DevOpsAgent::Association
    Properties:
      AgentSpaceId: !Ref AgentSpaceId
      ServiceId: aws
      Configuration:
        SourceAws:
          AccountId: !Ref ServiceAccountId
          AccountType: source
          AssumableRoleArn: !Ref ServiceAccountRoleArn

Outputs:
  SourceAssociationId:
    Description: The source association ID
    Value: !Ref SourceAssociation

使用監控帳戶登入資料部署關聯堆疊：

aws cloudformation deploy \
  --template-file devops-agent-source-association.yaml \
  --stack-name DevOpsAgentSourceAssociationStack \
  --parameter-overrides \
    AgentSpaceId=<AGENT_SPACE_ID> \
    ServiceAccountId=<SERVICE_ACCOUNT_ID> \
    ServiceAccountRoleArn=arn:aws:iam::<SERVICE_ACCOUNT_ID>:role/DevOpsAgentRole-SecondaryAccount \
  --region <REGION>

驗證

執行下列 CLI AWS 命令來驗證您的設定：

# List your agent spaces
aws devops-agent list-agent-spaces \
  --region <REGION>

# Get details of a specific agent space
aws devops-agent get-agent-space \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

# List associations for an agent space
aws devops-agent list-associations \
  --agent-space-id <AGENT_SPACE_ID> \
  --region <REGION>

疑難排解

本節說明常見問題以及如何解決這些問題。

找不到 CloudFormation 資源類型

  • 驗證您正在 中部署支援的區域。

  • 確認您的 AWS CLI 已設定適當的許可。

IAM 角色建立失敗

  • 確認您的部署登入資料具有使用自訂名稱 () 建立 IAM 角色的許可CAPABILITY_NAMED_IAM。

  • 檢查信任政策條件是否符合您的帳戶 ID。

跨帳戶部署失敗

  • 每個堆疊都必須使用目標帳戶的登入資料進行部署。使用 --profile旗標指定正確的 CLI AWS 設定檔。

  • 確認 AgentSpaceArn 參數符合來自第 1 部分堆疊輸出的確切 ARN。

IAM 傳播延遲

  • IAM 角色變更可能需要幾分鐘的時間才能傳播。如果客服人員空間建立在角色建立後立即失敗，請等待幾分鐘，然後重新部署。

清除

若要移除所有資源，請以相反順序刪除堆疊。

警告：此動作會永久刪除您的客服人員空間和所有相關資料。此動作無法復原。在繼續之前，請確定您已備份任何重要資訊。

執行下列命令來刪除堆疊：

# If you deployed the source association stack, delete it first
aws cloudformation delete-stack \
  --stack-name DevOpsAgentSourceAssociationStack \
  --region <REGION>

aws cloudformation wait stack-delete-complete \
  --stack-name DevOpsAgentSourceAssociationStack \
  --region <REGION>

# If you deployed the service account stack, delete it next (using service account credentials)
aws cloudformation delete-stack \
  --stack-name DevOpsAgentServiceAccountStack \
  --region <REGION>

aws cloudformation wait stack-delete-complete \
  --stack-name DevOpsAgentServiceAccountStack \
  --region <REGION>

# Delete the main stack last
aws cloudformation delete-stack \
  --stack-name DevOpsAgentStack \
  --region <REGION>

後續步驟

使用 AWS CloudFormation 部署您的 AWS DevOps 代理程式之後：