本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 開始使用 AWS CloudFormation 的 AWS DevOps 代理程式 ## 概觀 本指南說明如何使用 AWS CloudFormation 範本來建立和部署 AWS DevOps 代理程式資源。範本會自動建立代理程式空間、 AWS Identity and Access Management (IAM) 角色、運算子應用程式，以及 AWS 帳戶關聯做為基礎設施做為程式碼。 CloudFormation 方法會透過在宣告式 YAML 範本中定義所有必要資源，自動執行 [CLI 入門指南](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html)中所述的手動步驟。 AWS DevOps 代理程式可在下列 6 AWS 區域使用：美國東部 （維吉尼亞北部）、美國西部 （奧勒岡）、亞太區域 （雪梨）、亞太區域 （東京）、歐洲 （法蘭克福） 和歐洲 （愛爾蘭）。如需支援區域的詳細資訊，請參閱 [支援的區域](about-aws-devops-agent-supported-regions.md)。 ## 先決條件 開始前，請確定您有下列項目： + 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：部署堆疊 執行下列命令來部署堆疊。`` 以 取代 [支援的區域](about-aws-devops-agent-supported-regions.md)（例如，`us-east-1`)。 ``` aws cloudformation deploy \ --template-file devops-agent-stack.yaml \ --stack-name DevOpsAgentStack \ --capabilities CAPABILITY_NAMED_IAM \ --region ``` ### 步驟 3：記錄堆疊輸出 部署完成後，請執行下列命令來擷取堆疊輸出。記錄這些值以供日後使用。 ``` aws cloudformation describe-stacks \ --stack-name DevOpsAgentStack \ --query 'Stacks[0].Outputs' \ --region ``` 下列範例顯示預期的輸出： ``` [ { "OutputKey": "AgentSpaceId", "OutputValue": "abc123def456" }, { "OutputKey": "AgentSpaceArn", "OutputValue": "arn:aws:aidevops:::agentspace/abc123def456" }, { "OutputKey": "AgentSpaceRoleArn", "OutputValue": "arn:aws:iam:::role/DevOpsAgentRole-AgentSpace" }, { "OutputKey": "OperatorRoleArn", "OutputValue": "arn:aws:iam:::role/DevOpsAgentRole-WebappAdmin" } ] ``` 如果您打算完成第 2 部分，請儲存該`AgentSpaceArn`值。您需要它來設定跨帳戶角色。 ### 步驟 4：驗證部署 若要驗證已成功建立代理程式空間，請執行下列 AWS CLI 命令： ``` aws devops-agent get-agent-space \ --agent-space-id \ --region ``` 此時，您的代理程式空間會部署並啟用 運算子應用程式，並且與監控帳戶相關聯。代理程式可以監控此帳戶中的問題。 ## 第 2 部分 （選用）：新增跨帳戶監控 在本節中，您會擴展設定，讓您的客服人員空間可以監控第二個 AWS 帳戶 （服務帳戶） 中的資源。這涉及兩個動作： 1. 在信任客服人員空間的服務帳戶中部署 IAM 角色。 1. 在監控帳戶中新增指向服務帳戶的來源 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= \ AgentSpaceArn= \ --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= \ ServiceAccountId= \ ServiceAccountRoleArn=arn:aws:iam:::role/DevOpsAgentRole-SecondaryAccount \ --region ``` ## 驗證 執行下列 CLI AWS 命令來驗證您的設定： ``` # List your agent spaces aws devops-agent list-agent-spaces \ --region # Get details of a specific agent space aws devops-agent get-agent-space \ --agent-space-id \ --region # List associations for an agent space aws devops-agent list-associations \ --agent-space-id \ --region ``` ## 疑難排解 本節說明常見問題以及如何解決這些問題。 **找不到 CloudFormation 資源類型** + 確認您正在 中部署[支援的區域](about-aws-devops-agent-supported-regions.md)。 + 確認您的 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 aws cloudformation wait stack-delete-complete \ --stack-name DevOpsAgentSourceAssociationStack \ --region # If you deployed the service account stack, delete it next (using service account credentials) aws cloudformation delete-stack \ --stack-name DevOpsAgentServiceAccountStack \ --region aws cloudformation wait stack-delete-complete \ --stack-name DevOpsAgentServiceAccountStack \ --region # Delete the main stack last aws cloudformation delete-stack \ --stack-name DevOpsAgentStack \ --region ``` ## 後續步驟 使用 AWS CloudFormation 部署您的 AWS DevOps 代理程式之後： + 若要連接其他整合，請參閱 [設定適用於 AWS DevOps 代理程式的功能](configuring-capabilities-for-aws-devops-agent.md)。 + 若要了解客服人員的技能和功能，請參閱 [DevOps 代理程式技能](about-aws-devops-agent-devops-agent-skills.md)。 + 若要了解 運算子 Web 應用程式，請參閱 [什麼是 DevOps Agent Web 應用程式？](about-aws-devops-agent-what-is-a-devops-agent-web-app.md)。