View a markdown version of this page

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

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

開始使用 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 關聯。此組態可讓客服人員空間跨帳戶監控資源。

  • 第 3 部分 （選用） – 將技能、自訂代理程式和排程觸發新增至代理程式空間，讓代理程式具備自訂知識，並依排程執行自訂代理程式。

第 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 部分，才能繼續。服務帳戶範本需要AgentSpaceArn來自第 1 部分堆疊輸出的 。

步驟 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>

第 3 部分：新增技能、自訂代理程式和排程觸發

此部分為選用。在本節中，您將三個資源新增至您在第 1 部分中建立的代理程式空間。第一個是客服人員在相關時載入的技能。第二個是自訂代理程式，將代理程式範圍限定在特定工作流程。第三個是自動執行自訂代理程式的排程觸發。這些資源使用 AWS::DevOpsAgent::Asset和 AWS::DevOpsAgent::Trigger 資源類型。如需以程式碼形式管理資產的詳細資訊，請參閱 管理資產。

您必須完成第 1 部分，才能繼續。此範本需要AgentSpaceId來自第 1 部分堆疊輸出的 。

步驟 1：建立範本

將下列範本儲存為 devops-agent-content.yaml。以時間為基礎的觸發動作會依資產 ID 參考自訂代理程式，格式為 custom:<assetId>。範本會自動使用 進行路由Fn::GetAtt。

AWSTemplateFormatVersion: '2010-09-09'
Description: AWS DevOps Agent - Example skill, custom agent, and scheduled trigger

Parameters:
  AgentSpaceId:
    Type: String
    Description: The agent space ID from the Part 1 stack outputs

Resources:
  # A skill the agent loads when relevant
  ExampleSkill:
    Type: AWS::DevOpsAgent::Asset
    Properties:
      AgentSpaceId: !Ref AgentSpaceId
      AssetType: skill
      Metadata:
        name: rds-performance-investigation
        description: Investigation procedures for RDS performance issues.
        agent_types:
          - GENERIC
      Files:
        - Path: SKILL.md
          ContentText: |
            # RDS Performance Investigation
            Use this skill when investigating database latency, connection
            errors, or query timeouts.

  # A custom agent that a trigger can invoke
  ExampleCustomAgent:
    Type: AWS::DevOpsAgent::Asset
    Properties:
      AgentSpaceId: !Ref AgentSpaceId
      AssetType: custom_agent
      Metadata:
        name: rds-firefighter
        skills:
          - rds-performance-investigation
      Files:
        - Path: AGENT.md
          ContentText: |
            # RDS Firefighter
            Custom agent for RDS incidents.

  # A time-based trigger that runs the custom agent on a schedule
  DailyTrigger:
    Type: AWS::DevOpsAgent::Trigger
    Properties:
      AgentSpaceId: !Ref AgentSpaceId
      Type: TIME_BASED
      Condition:
        Schedule:
          Expression: rate(1 day)
      Action:
        actionType: create:task
        task:
          agent: !Sub
            - custom:${AssetId}
            - AssetId: !GetAtt ExampleCustomAgent.AssetId
      Status: Active

Outputs:
  SkillAssetId:
    Description: The skill asset ID
    Value: !GetAtt ExampleSkill.AssetId
  CustomAgentAssetId:
    Description: The custom agent asset ID
    Value: !GetAtt ExampleCustomAgent.AssetId
  TriggerId:
    Description: The trigger ID
    Value: !GetAtt DailyTrigger.TriggerId

步驟 2：部署堆疊

使用監控帳戶登入資料，執行下列命令。<AGENT_SPACE_ID> 將 取代為來自第 1 部分輸出的值。

aws cloudformation deploy \
  --template-file devops-agent-content.yaml \
  --stack-name DevOpsAgentContentStack \
  --parameter-overrides AgentSpaceId=<AGENT_SPACE_ID> \
  --region <REGION>

AgentSpaceId、Condition、 Type和 Action 屬性僅限建立。變更其中任何一個會取代 資源。您可以更新觸發的 Status(Active 或 Inactive)，將其設定為 Inactive以暫停觸發，而不將其刪除。如需其他資產類型和完整屬性參考的詳細資訊，請參閱 管理資產。

驗證

執行下列 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 Part 3 content stack, delete it first
aws cloudformation delete-stack \
  --stack-name DevOpsAgentContentStack \
  --region <REGION>

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

# If you deployed the source association stack, delete it next
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 代理程式之後：

  • 若要連接其他整合，請參閱 設定整合和知識。

  • 如果您註冊第三方整合，請在主控台中輪換 Webhook，以取得其 Webhook URL 和秘密。 AWS CloudFormation 不會將 Webhook 秘密傳回為堆疊輸出，因為它很敏感。如需管理 Webhook 登入資料的指示，請參閱管理 Webhook 登入資料。

  • 若要了解客服人員的技能和功能，請參閱 DevOps 代理程式技能。

  • 如需將技能、自訂代理程式和其他資產作為基礎設施作為程式碼管理的詳細資訊，請參閱 管理資產。

  • 若要了解 運算子 Web 應用程式，請參閱 什麼是 DevOps Agent Web 應用程式？。

  • 如需本指南中所用 CloudFormation 資源類型的詳細屬性參考，請參閱 CloudFormation 範本AWS 參考中的 DevOps Agent 資源類型參考。 AWS CloudFormation