翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# AWS CloudFormation を使用した AWS DevOps エージェントの開始方法
<a name="getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-aws-cloudformation"></a>

## 概要:
<a name="overview"></a>

このガイドでは、 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)。

## 前提条件
<a name="prerequisites"></a>

作業を開始する前に、以下の準備が整っていることを確認します。
+ AWS コマンドラインインターフェイス (AWS CLI) がインストールされ、適切な認証情報で設定されている
+ IAM ロールと CloudFormation スタックを作成するアクセス許可
+ モニタリング (プライマリ) AWS アカウントの 1 つのアカウント
+ (オプション) クロス AWS アカウントモニタリングを設定する場合は 2 番目のアカウント

## このガイドの内容
<a name="what-this-guide-covers"></a>

このガイドは 2 つのパートに分かれています。
+ **パート 1** — オペレーターアプリと AWS 関連付けを使用してエージェントスペースをモニタリングアカウントにデプロイします。このパートを完了すると、エージェントはそのアカウントの問題をモニタリングできます。
+ **パート 2 (オプション)** — クロスアカウント IAM ロールをセカンダリアカウントにデプロイし、ソースの AWS 関連付けを追加します。この設定により、エージェントスペースはアカウント全体のリソースをモニタリングできます。

## パート 1: エージェントスペースをデプロイする
<a name="part-1-deploy-the-agent-space"></a>

このセクションでは、モニタリングアカウントのエージェントスペース、IAM ロール、オペレータアプリ、および AWS 関連付けをプロビジョニングする CloudFormation テンプレートを作成します。

### ステップ 1: CloudFormation テンプレートを作成する
<a name="step-1-create-the-cloudformation-template"></a>

次のテンプレートを として保存します`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: スタックをデプロイする
<a name="step-2-deploy-the-stack"></a>

次のコマンドを実行してスタックをデプロイします。を `<REGION>`に置き換えます [サポートされるリージョン](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 <REGION>
```

### ステップ 3: スタック出力を記録する
<a name="step-3-record-the-stack-outputs"></a>

デプロイが完了したら、次のコマンドを実行してスタック出力を取得します。これらの値は後で使用するために記録します。

```
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: デプロイを検証する
<a name="step-4-verify-the-deployment"></a>

エージェントスペースが正常に作成されたことを確認するには、次の AWS CLI コマンドを実行します。

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

この時点で、エージェントスペースはオペレーターアプリが有効で、モニタリングアカウントが関連付けられている状態でデプロイされます。エージェントはこのアカウントの問題をモニタリングできます。

## パート 2 (オプション): クロスアカウントモニタリングを追加する
<a name="part-2-optional-add-cross-account-monitoring"></a>

このセクションでは、エージェントスペースが 2 番目の AWS アカウント (サービスアカウント) のリソースをモニタリングできるようにセットアップを拡張します。これには、次の 2 つのアクションが含まれます。

1. エージェントスペースを信頼するサービスアカウントに IAM ロールをデプロイします。

1. サービスアカウントを指すソース AWS 関連付けをモニタリングアカウントに追加します。

**注:** 続行する前にパート 1 を完了する必要があります。サービスアカウントテンプレートには、パート 1 スタック出力`AgentSpaceArn`の が必要です。

### ステップ 1: サービスアカウントテンプレートを作成する
<a name="step-1-create-the-service-account-template"></a>

次のテンプレートを として保存します`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: サービスアカウントスタックをデプロイする
<a name="step-2-deploy-the-service-account-stack"></a>

サービスアカウントの認証情報を使用して、次のコマンドを実行します。

```
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 関連付けを追加する
<a name="step-3-add-the-source-aws-association"></a>

モニタリングアカウントに切り替えて、ソースの 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>
```

## 検証
<a name="verification"></a>

次の AWS CLI コマンドを実行して、セットアップを確認します。

```
# 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>
```

## トラブルシューティング
<a name="troubleshooting"></a>

このセクションでは、一般的な問題とその解決方法について説明します。

**CloudFormation リソースタイプが見つかりません**
+ にデプロイしていることを確認します[サポートされるリージョン](about-aws-devops-agent-supported-regions.md)。
+ CLI AWS に適切なアクセス許可が設定されていることを確認します。

**IAM ロールの作成に失敗しました**
+ デプロイ認証情報に、カスタム名 () で IAM ロールを作成するアクセス許可があることを確認します`CAPABILITY_NAMED_IAM`。
+ 信頼ポリシーの条件がアカウント ID と一致していることを確認します。

**クロスアカウントデプロイが失敗する**
+ 各スタックは、ターゲットアカウントの認証情報を使用してデプロイする必要があります。`--profile` フラグを使用して、正しい CLI AWS プロファイルを指定します。
+ `AgentSpaceArn` パラメータがパート 1 スタック出力の正確な ARN と一致することを確認します。

**IAM 伝達の遅延**
+ IAM ロールの変更が反映されるまでに数分かかる場合があります。ロールの作成直後にエージェントスペースの作成が失敗した場合、数分待ってから再デプロイします。

## クリーンアップ
<a name="cleanup"></a>

すべてのリソースを削除するには、スタックを逆の順序で削除します。

**警告:** このアクションは、エージェントスペースと関連するすべてのデータを完全に削除します。このアクションは元に戻すことができません。続行する前に、重要な情報がバックアップされていることを確認してください。

次のコマンドを実行して、スタックを削除します。

```
# 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>
```

## 次の手順
<a name="next-steps"></a>

 AWS CloudFormation を使用して AWS DevOps エージェントをデプロイした後:
+ 追加の統合を接続するには、「」を参照してください[AWS DevOps Agent の機能の設定](configuring-capabilities-for-aws-devops-agent.md)。
+ エージェントのスキルと機能の詳細については、「」を参照してください[DevOps エージェントスキル](about-aws-devops-agent-devops-agent-skills.md)。
+ オペレーターウェブアプリを理解するには、「」を参照してください[DevOps エージェントウェブアプリとは](about-aws-devops-agent-what-is-a-devops-agent-web-app.md)。