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

# AWS CDK를 사용하여 AWS DevOps 에이전트 시작하기
<a name="getting-started-with-aws-devops-agent-getting-started-with-aws-devops-agent-using-aws-cdk"></a>

## 개요
<a name="overview"></a>

이 가이드에서는 AWS 클라우드 개발 키트(AWS CDK)를 사용하여 AWS DevOps 에이전트 리소스를 생성하고 배포하는 방법을 보여줍니다. AWS CDK 애플리케이션은 AWS CloudFormation을 통해 에이전트 공간, AWS 자격 증명 및 액세스 관리(IAM) 역할, 운영자 앱 및 AWS 계정 연결 생성을 자동화합니다.

 AWS CDK 접근 방식은 필요한 모든 리소스를 코드형 인프라로 정의하여 [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)
+ Node.js 버전 18 이상
+ AWS CDK 명령줄 인터페이스(CLI)는 전역적으로 설치됩니다. AWS CDK CLI를 설치하려면 다음 명령을 실행합니다.

```
npm install -g aws-cdk
```
+ 모니터링(기본) AWS 계정에 대한 하나의 계정
+ (선택 사항) 교차 AWS 계정 모니터링을 설정하려는 경우 두 번째 계정

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

이 가이드는 두 부분으로 나뉩니다.
+ **1부 **- 운영자 앱과 모니터링 계정의 AWS 연결을 사용하여 에이전트 공간을 배포합니다. 이 부분을 완료하면 에이전트가 해당 계정의 문제를 모니터링할 수 있습니다.
+ **2부(선택 사항)** - 서비스 계정에 대한 소스 AWS 연결을 추가하고 해당 계정에 교차 계정 IAM 역할을 배포합니다. 이 구성을 사용하면 에이전트 공간이 계정 전체에서 리소스를 모니터링할 수 있습니다.

## 생성할 리소스
<a name="resources-created"></a>

### 1부: DevOpsAgentStack(모니터링 계정)
<a name="part-1-devopsagentstack-monitoring-account"></a>
+ **IAM 역할**(`DevOpsAgentRole-AgentSpace`) - 계정을 모니터링하기 위해 DevOps 에이전트 서비스에서 수임합니다. `AIDevOpsAgentAccessPolicy` 관리형 정책과 Resource Explorer 서비스 연결 역할 생성을 허용하는 인라인 정책을 포함합니다.
+ **IAM 역할**(`DevOpsAgentRole-WebappAdmin`) - 에이전트 작업에 대한 `AIDevOpsOperatorAppAccessPolicy` 관리형 정책이 있는 운영자 앱 역할입니다.
+ **에이전트 공간**(`MyCDKAgentSpace`) - `AWS::DevOpsAgent::AgentSpace` CloudFormation 리소스를 사용하여 생성된 중앙 에이전트 공간입니다. 운영자 앱 구성을 포함합니다.
+ **연결**(AWS 모니터) - `AWS::DevOpsAgent::Association` CloudFormation 리소스를 사용하여 모니터링 계정을 에이전트 공간에 연결합니다.
+ **연결**(AWS 소스) - (선택 사항) 교차 계정 모니터링을 위해 서비스 계정을 에이전트 스페이스에 연결합니다.

### 2부: ServiceStack(서비스 계정, 선택 사항)
<a name="part-2-servicestack-service-account-optional"></a>
+ **IAM 역할**(`DevOpsAgentRole-SecondaryAccount`) - 이름이 고정된 교차 계정 역할입니다. 모니터링 계정의 에이전트 공간에서 신뢰합니다. `AIDevOpsAgentAccessPolicy` 관리형 정책과 Resource Explorer 서비스 연결 역할 생성을 허용하는 인라인 정책을 포함합니다.
+ **Lambda 함수**(`echo-service`) - 입력 이벤트를 에코백하는 간단한 예제 서비스입니다.

## 설정
<a name="setup"></a>

### 1단계: 샘플 리포지토리 복제
<a name="step-1-clone-the-sample-repository"></a>

다음 명령을 실행하여 리포지토리를 복제하고 프로젝트 디렉터리로 변경합니다.

```
git clone https://github.com/aws-samples/sample-aws-devops-agent-cdk.git
cd sample-aws-devops-agent-cdk
```

### 2단계: 종속성 설치
<a name="step-2-install-dependencies"></a>

다음 명령을 실행하여 프로젝트 종속성을 설치합니다.

```
npm install
```

## 1부: 에이전트 공간 배포
<a name="part-1-deploy-the-agent-space"></a>

이 섹션에서는 모니터링 계정에 에이전트 공간, IAM 역할, 운영자 앱 및 AWS 연결을 생성합니다.

### 1단계: 모니터링 계정 ID 구성
<a name="step-1-configure-the-monitoring-account-id"></a>

`lib/constants.ts`를 열고 모니터링 계정 ID를 설정합니다.

다음 예제에서는 업데이트할 상수를 보여줍니다.

```
export const MONITORING_ACCOUNT_ID = "<YOUR_MONITORING_ACCOUNT_ID>";
```

### 2단계: AWS CDK 환경 부트스트랩
<a name="step-2-bootstrap-the-aws-cdk-environment"></a>

모니터링 계정에서 AWS CDK를 부트스트래핑하지 않은 경우 다음 명령을 실행합니다.

```
cdk bootstrap aws://<MONITORING_ACCOUNT_ID>/<REGION> --profile monitoring
```

### 3단계: 빌드 및 배포
<a name="step-3-build-and-deploy"></a>

다음 명령을 실행하여 TypeScript 코드를 빌드하고 스택을 배포합니다.

```
npm run build
cdk deploy DevOpsAgentStack --profile monitoring
```

### 4단계: 스택 출력 기록
<a name="step-4-record-the-stack-outputs"></a>

배포가 완료되면 AWS CDK는 스택 출력을 인쇄합니다. 나중에 사용할 수 있도록 이러한 값을 기록합니다.

다음 예제에서는 예상 출력을 보여줍니다.

```
Outputs:
DevOpsAgentStack.AgentSpaceArn = arn:aws:aidevops:<REGION>:123456789012:agentspace/abc123
DevOpsAgentStack.AgentSpaceRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-AgentSpace
DevOpsAgentStack.OperatorRoleArn = arn:aws:iam::123456789012:role/DevOpsAgentRole-WebappAdmin
DevOpsAgentStack.AssociationId = assoc-xyz
```

2부를 완료하려는 경우 `AgentSpaceArn` 값을 저장합니다. 서비스 계정 스택을 구성하는 데 필요합니다.

### 5단계: 배포 확인
<a name="step-5-verify-the-deployment"></a>

에이전트 공간이 성공적으로 생성되었는지 확인하려면 다음 AWS CLI 명령을 실행합니다.

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

이 시점에서 에이전트 공간은 운영자 앱이 활성화되고 모니터링 계정이 연결된 상태로 배포됩니다. 에이전트는이 계정의 문제를 모니터링할 수 있습니다.

## 2부(선택 사항): 교차 계정 모니터링 추가
<a name="part-2-optional-add-cross-account-monitoring"></a>

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

1. 서비스 계정을 가리키는 소스 AWS 연결을 DevOpsAgentStack에 추가합니다.

1. 에이전트 공간을 신뢰하는 IAM 역할을 사용하여 ServiceStack을 서비스 계정에 배포합니다.

**중요**  
** 계속하기 전에 1부를 완료해야 합니다. ServiceStack에는 DevOpsAgentStack 배포 출력`AgentSpaceArn`의이 필요합니다.

### 1단계: 서비스 계정 ID 구성
<a name="step-1-configure-the-service-account-id"></a>

서비스 계정 ID를 `lib/constants.ts` 열고 설정합니다.

다음 예제에서는 업데이트할 상수를 보여줍니다.

```
export const SERVICE_ACCOUNT_ID = "<YOUR_SERVICE_ACCOUNT_ID>";
```

DevOpsAgentStack은이 계정 ID를 사용하여 소스 AWS 연결을 생성합니다. 이 값을 설정하기 전에 DevOpsAgentStack을 배포한 경우 다시 배포하여 연결을 생성합니다.

다음 명령을 실행하여 재배포합니다.

```
npm run build
cdk deploy DevOpsAgentStack --profile monitoring
```

### 2단계: 에이전트 공간 ARN 설정
<a name="step-2-set-the-agent-space-arn"></a>

DevOpsAgentStack 출력(1부, 4단계)에서 `AgentSpaceArn` 값을 복사하고에서 설정합니다`lib/constants.ts`.

다음 예제에서는 업데이트할 상수를 보여줍니다.

```
export const AGENT_SPACE_ARN = "arn:aws:aidevops:<REGION>:<MONITORING_ACCOUNT_ID>:agentspace/<SPACE_ID>";
```

ServiceStack은이 값을 사용하여 보조 계정 역할에 대한 신뢰 정책의 범위를 지정합니다. ServiceStack은이 값이 설정된 경우에만 합성됩니다.

### 3단계: 서비스 계정 부트스트랩
<a name="step-3-bootstrap-the-service-account"></a>

서비스 계정에서 AWS CDK를 부트스트래핑하지 않은 경우 다음 명령을 실행합니다.

```
cdk bootstrap aws://<SERVICE_ACCOUNT_ID>/<REGION> --profile service
```

### 4단계: ServiceStack 배포
<a name="step-4-deploy-the-servicestack"></a>

다음 명령을 실행하여 서비스 계정의 자격 증명을 사용하여 ServiceStack을 빌드하고 배포합니다.

```
npm run build
cdk deploy ServiceStack --profile service
```

이렇게 하면 서비스 계정에 다음 리소스가 생성됩니다.
+ 모니터링 계정의 에이전트 공간을 신뢰하는 IAM 역할(`DevOpsAgentRole-SecondaryAccount`)
+ 예제 서비스로 사용되는 에코 Lambda 함수(`echo-service`)

### 5단계: 배포 확인
<a name="step-5-verify-the-deployment"></a>

Lambda 함수가 성공적으로 배포되었는지 확인하려면 다음 명령을 실행하여 에코 서비스를 테스트합니다.

```
aws lambda invoke \
  --function-name echo-service \
  --payload '{"test": "hello world"}' \
  --profile service \
  response.json
cat response.json
```

## 문제 해결
<a name="troubleshooting"></a>

이 섹션에서는 일반적인 문제와 해결 방법을 설명합니다.

**CloudFormation 리소스 유형을 찾을 수 없음**
+ 에 배포하고 있는지 확인합니다[지원되는 리전:](about-aws-devops-agent-supported-regions.md).
+  AWS CLI가 적절한 권한으로 구성되어 있는지 확인합니다.

**IAM 역할 생성 실패**
+ 배포 역할에 IAM 역할을 생성할 수 있는 권한이 있는지 확인합니다.
+ 신뢰 정책 조건이 계정 ID와 일치하는지 확인합니다.

**"대상 계정에서 역할을 수임할 수 없음"과 함께 교차 계정 배포가 실패합니다.**
+ 각 스택은 대상 계정의 자격 증명으로 배포해야 합니다. `--profile` 플래그를 사용하여 올바른 AWS CLI 프로파일을 지정합니다.
+ 대상 계정에서 AWS CDK가 부트스트랩되었는지 확인합니다.

**IAM 전파 지연**
+ IAM 역할 변경 사항이 전파되는 데 몇 분 정도 걸릴 수 있습니다. 역할 생성 직후 에이전트 공간 생성에 실패하면 몇 분 정도 기다렸다가 다시 배포합니다.

## 정리
<a name="cleanup"></a>

모든 리소스를 제거하려면 스택을 역순으로 삭제합니다.

다음 명령을 실행하여 스택을 삭제합니다.

```
# If you deployed the ServiceStack, destroy it first
cdk destroy ServiceStack --profile service
# Then destroy the DevOpsAgentStack
cdk destroy DevOpsAgentStack --profile monitoring
```

**경고:**이 작업은 에이전트 공간과 모든 관련 데이터를 영구적으로 삭제합니다. 이 작업은 실행 취소할 수 없습니다. 계속하기 전에 중요한 정보를 백업했는지 확인합니다.

## 보안 고려 사항
<a name="security-considerations"></a>
+  AWS CDK 애플리케이션은 `aidevops.amazonaws.com` 서비스 보안 주체만 해당 역할을 수임하도록 허용하는 신뢰 정책을 사용하여 IAM 역할을 생성합니다.
+ 신뢰 정책에는 특정 AWS 계정 및 에이전트 공간 ARN에 대한 액세스를 제한하는 조건이 포함됩니다.
+ 모든 정책은 최소 권한 원칙을 따릅니다. 조직의 보안 요구 사항에 따라 IAM 정책을 검토하고 사용자 지정합니다.
+ 교차 계정 역할(`DevOpsAgentRole-SecondaryAccount`)은 고정된 이름을 사용하며 특정 에이전트 공간 ARN으로 범위가 지정됩니다.

## 다음 단계
<a name="next-steps"></a>

 AWS CDK를 사용하여 AWS DevOps 에이전트를 배포한 후:

1. DevOps 에이전트 [AWS 사용 설명서에서 DevOps 에이전트](https://docs.aws.amazon.com/devopsagent/latest/userguide/) 기능의 전체 범위에 대해 알아봅니다.

1. 자동화된 인프라 관리를 위해 AWS CDK 배포를 CI/CD 파이프라인에 통합하는 것이 좋습니다.

## 추가 리소스
<a name="additional-resources"></a>
+ [AWS DevOps 에이전트 사용 설명서](https://docs.aws.amazon.com/devopsagent/latest/userguide/)
+ GitHub 웹 사이트의 [샘플 CDK 리포지토리](https://github.com/aws-samples/sample-aws-devops-agent-cdk) 
+ [CLI 온보딩 가이드](https://docs.aws.amazon.com/devopsagent/latest/userguide/getting-started-with-aws-devops-agent-cli-onboarding-guide.html)