기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 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 자격 증명 및 액세스 관리(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 계정에 대한 하나의 계정
+ (선택 사항) 교차 AWS 계정 모니터링을 설정하려는 경우 두 번째 계정

## 이 가이드에서 다루는 내용
<a name="what-this-guide-covers"></a>

이 가이드는 두 부분으로 나뉩니다.
+ **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>

이 섹션에서는 에이전트 공간이 두 번째 AWS 계정(서비스 계정)의 리소스를 모니터링할 수 있도록 설정을 확장합니다. 여기에는 다음 두 가지 작업이 포함됩니다.

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

## Verification(확인)
<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).
+  AWS CLI가 적절한 권한으로 구성되어 있는지 확인합니다.

**IAM 역할 생성 실패**
+ 배포 자격 증명에 사용자 지정 이름()으로 IAM 역할을 생성할 수 있는 권한이 있는지 확인합니다`CAPABILITY_NAMED_IAM`.
+ 신뢰 정책 조건이 계정 ID와 일치하는지 확인합니다.

**교차 계정 배포 실패**
+ 각 스택은 대상 계정의 자격 증명으로 배포해야 합니다. `--profile` 플래그를 사용하여 올바른 AWS CLI 프로파일을 지정합니다.
+ `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).