기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # AWS CDK 및 GitLab을 사용하여 Amazon ECS Anywhere에서 하이브리드 워크로드를 위한 CI/CD 파이프라인 설정하기 *Rafael Ortiz, Amazon Web Services* ## 요약 Amazon ECS Anywhere는 Amazon Elastic Container Service(Amazon ECS)의 확장입니다. 온프레미스 서버 또는 가상 머신(VM)과 같은 *외부 인스턴스*를 Amazon ECS 클러스터에 등록하도록 지원합니다. 이 기능은 비용을 절감하고 복잡한 로컬 컨테이너 오케스트레이션 및 운영을 완화하는 데 도움이 됩니다. ECS Anywhere를 사용하여 온프레미스와 클라우드 환경 모두에서 컨테이너 애플리케이션을 배포하고 실행할 수 있습니다. 따라서 팀이 여러 도메인과 기술을 배우거나 복잡한 소프트웨어를 자체적으로 관리할 필요가 없습니다. 이 패턴은 Amazon Web Services(AWS) Cloud Development Kit(AWS CDK) 스택을 사용하여 Amazon ECS Anywhere 인스턴스로 Amazon ECS 클러스터를 프로비저닝하는 단계별 접근 방식을 설명합니다. 그런 다음 AWS CodePipeline을 사용하여 지속적인 통합 및 지속적인 배포(CI/CD) 파이프라인을 설정합니다. 그런 다음, GitLab 코드 리포지토리를 AWS CodeCommit에 복제하고 컨테이너식 애플리케이션을 Amazon ECS 클러스터에 배포합니다. 이 패턴은 온프레미스 인프라를 사용하여 컨테이너 애플리케이션을 실행하고 GitLab을 사용하여 애플리케이션 코드 베이스를 관리하는 사용자를 돕기 위해 설계되었습니다. 기존의 온프레미스 인프라를 방해하지 않고 AWS Cloud 서비스를 사용하여 이러한 워크로드를 관리할 수 있습니다. ## 사전 조건 및 제한 사항 **사전 조건 ** + 활성 상태의 계정 + 온프레미스 인프라에서 실행되는 컨테이너 애플리케이션입니다. + 애플리케이션 코드 베이스를 관리하는 GitLab 리포지토리입니다. 자세한 내용은 [리포지토리](https://docs.gitlab.com/ee/user/project/repository/)(GitLab)를 참조하세요. + AWS Command Line Interface(AWS CLI), 설치 및 구성됨. 자세한 내용은 [최신 버전의 AWS CLI 설치 또는 업데이트](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)(AWS CLI 설명서)를 참조하세요. + AWS CDK Toolkit, 전역적으로 설치 및 구성됨. 자세한 내용은 [AWS CDK 설치](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_install)(AWS CDK 설명서)를 참조하세요. + npm, TypeScript에서 AWS CDK용으로 설치 및 구성됨. 자세한 내용은 [Node.js 및 npm 다운로드 및 설치](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)(npm 설명서)를 참조하세요. **제한 사항 ** + 제한 사항 및 고려 사항은 Amazon ECS 설명서의 [외부 인스턴스(Amazon ECS Anywhere)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-anywhere.html#ecs-anywhere-considerations)를 참조하세요. **제품 버전** + AWS CDK Toolkit 버전 2.27.0 이상 + npm 버전 7.20.3 이상 + Node.js 버전 16.6.1 이상 ## 아키텍처 **대상 기술 스택** + AWS CDK + AWS CloudFormation + AWS CodeBuild + AWS CodeCommit + AWS CodePipeline + Amazon ECS Anywhere + Amazon Elastic Container Registry (Amazon ECR) + Identity and Access Management(IAM) + AWS Systems Manager + GitLab 리포지토리 **대상 아키텍처** ![Amazon ECS 클러스터 및 CI/CD 파이프라인을 설정하는 아키텍처 다이어그램.](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/images/pattern-img/b0f35986-a839-4b01-8eb0-4748182ddafc/images/85b8d4d9-3591-4d69-a54b-64aa543498f1.png) 이 다이어그램은 다음과 같이 이 패턴에 설명된 두 가지 기본 워크플로우를 나타냅니다. 하나는 Amazon ECS 클러스터를 프로비저닝하는 것이고 다른 하나는 CI/CD 파이프라인을 설정하고 배포하는 CI/CD 파이프라인을 설정하는 것입니다. 1. **Amazon ECS 클러스터 프로비저닝** 1. AWS CDK 스택을 배포하면 AWS에 CloudFormation 스택이 생성됩니다. 1. CloudFormation 스택은 Amazon ECS 클러스터 및 관련 AWS 리소스를 프로비저닝합니다. 1. Amazon ECS 클러스터에 외부 인스턴스를 등록하려면 VM에 AWS Systems Manager Agent(SSM Agent)를 설치하고 해당 VM을 AWS Systems Manager 관리형 인스턴스로 등록해야 합니다.  1. 또한 VM을 Amazon ECS 클러스터에 외부 인스턴스로 등록하려면 VM에 Amazon ECS 컨테이너 에이전트와 Docker를 설치해야 합니다. 1. Amazon ECS 클러스터에 외부 인스턴스를 등록하고 구성하면, 외부 인스턴스로 등록된 VM에서 여러 컨테이너를 실행할 수 있습니다. 1. Amazon ECS 클러스터는 활성 상태이며 컨테이너를 통해 애플리케이션 워크로드를 실행할 수 있습니다. Amazon ECS Anywhere 컨테이너 인스턴스는 온프레미스 환경에서 실행되지만 클라우드의 Amazon ECS 클러스터와 연결되어 있습니다. 1. **CI/CD 파이프라인 설정 및 배포** 1. 두 번째 AWS CDK 스택을 배포하면 AWS에 또 다른 CloudFormation 스택이 생성됩니다. 1. 이 CloudFormation 스택은 CodePipeline 및 관련 AWS 리소스에 파이프라인을 프로비저닝합니다. 1. 애플리케이션 코드 변경사항을 온프레미스 GitLab 리포지토리로 푸시하고 병합합니다.  1. GitLab 리포지토리는 CodeCommit 리포지토리에 자동으로 복제됩니다. 1. CodeCommit 리포지토리를 업데이트하면 CodePipeline이 자동으로 시작됩니다.  1. CodePipeline은 CodeCommit에서 코드를 복사하고 CodeBuild에서 배포 가능한 애플리케이션 빌드를 만듭니다. 1. CodePipeline은 CodeBuild 구축 환경의 Docker 이미지를 생성하여 Amazon ECR 리포지토리에 푸시합니다. 1. CodePipeline은 Amazon ECR 리포지토리에서 컨테이너 이미지를 가져오는 CodeDeploy 작업을 시작합니다. 1. CodePipeline은 컨테이너 이미지를 Amazon ECS 클러스터에 배포합니다. **자동화 및 규모 조정** 이 패턴은 AWS CDK를 코드형 인프라(IaC) 도구로 사용하여 이 아키텍처를 구성하고 배포합니다. AWS CDK를 사용하면 AWS 리소스를 오케스트레이션하고 Amazon ECS Anywhere 및 CI/CD 파이프라인을 설정할 수 있습니다. ## 도구 **서비스** + [AWS Cloud Development Kit(AWS CDK)](https://docs.aws.amazon.com/cdk/latest/guide/home.html)는 AWS 클라우드 인프라를 코드로 정의하고 프로비저닝하는 데 도움이 되는 소프트웨어 개발 프레임워크입니다. + [AWS CodeCommit](https://docs.aws.amazon.com/codecommit/latest/userguide/welcome.html)은 나만의 원본 제어 시스템을 관리할 필요 없이 Git 리포지토리를 비공개로 저장하고 관리할 수 있는 버전 제어 서비스입니다. + [AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html)은 소프트웨어 릴리스의 여러 단계를 신속하게 모델링하고 구성하고 소프트웨어 변경 내용을 지속적으로 릴리스하는 데 필요한 단계를 자동화합니다. + [AWS Command Line Interface(AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)는 명령줄 쉘에서 명령을 사용하여 AWS 서비스와 상호 작용할 수 있는 오픈 소스 도구입니다. + [Amazon Elastic Container Registry(Amazon ECR)](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)는 안전하고 확장 가능하고 신뢰할 수 있는 관리형 컨테이너 이미지 레지스트리 서비스입니다. + [Amazon Elastic Container Service(Amazon ECS)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html)는 클러스터에서 컨테이너를 실행, 중지 및 관리하는 데 도움이 되는 빠르고 확장 가능한 컨테이너 관리 서비스입니다. 또한 이 패턴은 온프레미스 서버 또는 VM을 Amazon ECS 클러스터에 등록하도록 지원하는 [Amazon ECS Anywhere](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-anywhere.html)를 사용합니다. **기타 도구** + [Node.js](https://nodejs.org/en/docs/)는 확장 가능한 네트워크 애플리케이션 구축을 위해 설계된 이벤트 기반 JavaScript 런타임 환경입니다. + [npm](https://docs.npmjs.com/about-npm)은 Node.js 환경에서 실행되는 소프트웨어 레지스트리로, 패키지를 공유 또는 대여하고 개인 패키지의 배포를 관리하는 데 사용됩니다. + [Vagrant](https://developer.hashicorp.com/vagrant/docs)는 휴대용 가상 소프트웨어 개발 환경을 구축하고 유지 관리하기 위한 오픈 소스 유틸리티입니다. 이 패턴은 데모용으로 Vagrant를 사용하여 온프레미스 VM을 만듭니다. **코드 리포지토리** 이 패턴의 코드는 GitHub [AWS CDK를 사용하는 Amazon ECS Anywhere용 CI/CD 파이프라인](https://github.com/aws-samples/amazon-ecs-anywhere-cicd-pipeline-cdk-sample)에서 사용할 수 있습니다. ## 모범 사례 이 패턴을 배포할 때는 다음과 같은 모범 사례를 고려해 보십시오. + [AWS CDK를 사용한 클라우드 인프라 개발 및 배포 모범 사례](https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html) + [AWS CDK를 사용한 클라우드 애플리케이션 개발 모범 사례](https://aws.amazon.com/blogs/devops/best-practices-for-developing-cloud-applications-with-aws-cdk/)(AWS Blog 게시물) ## 에픽 ### AWS CDK 구성 확인 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | AWS CDK 버전을 확인합니다. | 다음 명령을 입력하여 AWS CDK Toolkit의 버전을 확인합니다.
cdk --version

이 패턴을 사용하려면 버전 2.27.0 이상이 필요합니다. 이전 버전이 있을 경우 [AWS CDK 설명서](https://docs.aws.amazon.com/cdk/latest/guide/cli.html)의 지침에 따라 업데이트하세요. | DevOps 엔지니어 | | npm 버전을 확인합니다. | 다음 명령을 입력하여 npm 버전을 확인합니다.
npm --version

이 패턴을 사용하려면 버전 7.20.3 이상이 필요합니다. 이전 버전이 있을 경우 [npm 설명서](https://docs.npmjs.com/try-the-latest-stable-version-of-npm)의 지침에 따라 업데이트하세요. | DevOps 엔지니어 | | AWS 보안 인증을 설정합니다. | `aws configure` 명령을 입력하고 프롬프트를 따라 AWS 보안 인증을 설정합니다.
$aws configure
AWS Access Key ID [None]: 
AWS Secret Access Key [None]: 
Default region name [None]: 
Default output format [None]:
| DevOps 엔지니어 | ### AWS CDK 환경 부트스트랩 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | AWS CDK 코드 리포지토리를 복제합니다. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/set-up-a-ci-cd-pipeline-for-hybrid-workloads-on-amazon-ecs-anywhere-by-using-aws-cdk-and-gitlab.html) | DevOps 엔지니어 | | 환경을 부트스트랩합니다. | 다음 명령을 입력하여 사용하려는 계정 및 AWS 리전에 CloudFormation 템플릿을 배포합니다.
cdk bootstrap /

자세한 내용은 AWS CDK 설명서의 [부트스트래핑](https://docs.aws.amazon.com/cdk/latest/guide/bootstrapping.html)을 참조하세요. | DevOps 엔지니어 | ### Amazon ECS Anywhere에 대한 인프라 구축 및 배포 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | 패키지 종속성을 설치하고 TypeScript 파일을 컴파일하세요. | 다음 명령을 실행하여 패키지 종속성을 설치하고 TypeScript 파일을 컴파일하세요.
$cd EcsAnywhereCdk
$npm install
$npm fund

이 명령은 샘플 저장소의 모든 패키지를 설치합니다. 자세한 내용은 npm 설명서에 있는 [npm ci](https://docs.npmjs.com/cli/v7/commands/npm-ci)와 [npm install](https://docs.npmjs.com/cli/v7/commands/npm-install)을 참조하세요. 이러한 명령을 입력할 때 누락된 패키지와 관련된 오류가 발생하는 경우 이 패턴의 [문제 해결](#set-up-a-ci-cd-pipeline-for-hybrid-workloads-on-amazon-ecs-anywhere-by-using-aws-cdk-and-gitlab-troubleshooting) 섹션을 참고하십시오. | DevOps 엔지니어 | | 프로젝트를 빌드합니다. | 프로젝트 코드를 빌드하려면 다음 명령을 입력하세요.
npm run build

프로젝트 구축 및 배포에 대한 자세한 내용은 AWS CDK 설명서의 [첫 AWS CDK 앱](https://docs.aws.amazon.com/cdk/latest/guide/hello_world.html#:~:text=the%20third%20parameter.-,Synthesize%20an%20AWS%20CloudFormation%20template,-Synthesize%20an%20AWS)을 참조하세요. | DevOps 엔지니어 | | Amazon ECS Anywhere 인프라 스택을 배포합니다. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/set-up-a-ci-cd-pipeline-for-hybrid-workloads-on-amazon-ecs-anywhere-by-using-aws-cdk-and-gitlab.html) | DevOps 엔지니어 | | 스택 생성 및 출력을 확인합니다. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/set-up-a-ci-cd-pipeline-for-hybrid-workloads-on-amazon-ecs-anywhere-by-using-aws-cdk-and-gitlab.html) | DevOps 엔지니어 | ### 온프레미스 VM 설정 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | VM을 설정합니다. | Vagrantfile이 있는 루트 디렉터리에서 `vagrant up` 명령을 입력하여 Vagrant VM을 생성합니다. 자세한 내용은 [Vagrant 설명서](https://developer.hashicorp.com/vagrant/docs/cli/up)를 참조하세요. | DevOps 엔지니어 | | VM을 외부 인스턴스로 등록합니다. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/set-up-a-ci-cd-pipeline-for-hybrid-workloads-on-amazon-ecs-anywhere-by-using-aws-cdk-and-gitlab.html)[See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/set-up-a-ci-cd-pipeline-for-hybrid-workloads-on-amazon-ecs-anywhere-by-using-aws-cdk-and-gitlab.html)이렇게 하면 VM이 Amazon ECS Anywhere 외부 인스턴스로 설정되고 해당 인스턴스가 Amazon ECS 클러스터에 등록됩니다. 자세한 내용은 Amazon ECS 설명서의 [클러스터에 외부 인스턴스 등록](https://docs.amazonaws.cn/en_us/AmazonECS/latest/developerguide/ecs-anywhere-registration.html)을 참조하세요. 문제가 발생하는 경우 [문제 해결](#set-up-a-ci-cd-pipeline-for-hybrid-workloads-on-amazon-ecs-anywhere-by-using-aws-cdk-and-gitlab-troubleshooting) 섹션을 참고하십시오. | DevOps 엔지니어 | | Amazon ECS Anywhere와 외부 VM의 상태를 확인합니다. | VM이 Amazon ECS 컨트롤 플레인에 연결되어 실행 중인지 확인하려면 다음 명령을 사용하세요.
$aws ssm describe-instance-information
$aws ecs list-container-instances --cluster $CLUSTER_NAME
| DevOps 엔지니어 | ### CI/CD 파이프라인 배포 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | CodeCommit repo에서 분기를 생성합니다. | 리포지토리의 첫 번째 커밋을 만들어 CodeCommit 리포지토리에 `main`으로 이름이 지정된 브랜치를 생성합니다. AWS 설명서에 따라 [CodeCommit에서 커밋을 생성](https://docs.aws.amazon.com/codecommit/latest/userguide/how-to-create-commit.html#create-first-commit)할 수 있습니다. 다음 명령은 예제입니다.
aws codecommit put-file \
  --repository-name EcsAnywhereRepo \
  --branch-name main \
  --file-path README.md \
  --file-content "Test" \
  --name "Dev Ops" \
  --email "devops@example.com" \
  --commit-message "Adding README."
| DevOps 엔지니어 | | 리포지토리 미러링을 설정합니다. | GitLab 리포지토리를 외부 소스와 미러링하거나 외부 소스에서 미러링할 수 있습니다. 소스로 사용할 리포지토리를 선택할 수 있습니다. 브랜치, 태그, 커밋은 자동으로 동기화됩니다. 애플리케이션을 호스팅하는 GitLab 리포지토리와 CodeCommit 리포지토리 간에 푸시 미러를 설정합니다. 자세한 지침은 [GitLab에서 CodeCommit으로 푸시 미러 설정하기](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-aws-codecommit)(GitLab 설명서)를 참고하십시오.기본적으로 미러링은 리포지토리를 자동으로 동기화합니다. 리포지토리를 수동으로 업데이트하려면 [미러 업데이트](https://docs.gitlab.com/ee/user/project/repository/mirror/#update-a-mirror)(GitLab 설명서)를 참고하십시오. | DevOps 엔지니어 | | CI/CD 파이프라인 스택을 배포합니다. | 다음 명령을 입력하여 `EcsAnywherePipelineStack` 스택을 배포합니다.
$cdk  deploy EcsAnywherePipelineStack
| DevOps 엔지니어 | | CI/CD 파이프라인을 테스트합니다. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/ko_kr/prescriptive-guidance/latest/patterns/set-up-a-ci-cd-pipeline-for-hybrid-workloads-on-amazon-ecs-anywhere-by-using-aws-cdk-and-gitlab.html) | DevOps 엔지니어 | ### 정리 | 작업 | 설명 | 필요한 기술 | | --- | --- | --- | | 리소스를 정리하고 삭제합니다. | 이 패턴을 살펴본 후에는 생성한 개념 증명 리소스를 제거해야 합니다. 정리하려면 다음 명령을 입력합니다.
$cdk destroy EcsAnywherePipelineStack
$cdk destroy EcsAnywhereInfraStack
| DevOps 엔지니어 | ## 문제 해결 | 문제 | Solution | | --- | --- | | 패키지 종속 항목을 설치할 때 누락된 패키지와 관련된 오류가 발생합니다. | 다음 명령 중 하나를 입력하여 누락된 패키지를 해결하십시오.
$npm ci

또는
$npm install -g @aws-cdk/
| | VM에서 `aws ssm create-activation` 명령을 실행하면 다음 오류가 수신됩니다.
`An error occurred (ValidationException) when calling the CreateActivation operation: Nonexistent role or missing ssm service principal in trust policy: arn:aws:iam::000000000000:role/EcsAnywhereInstanceRole` | `EcsAnywhereInfraStack` 스택이 완전히 배포되지 않았고 이 명령을 실행하는 데 필요한 IAM 역할이 아직 생성되지 않았습니다. CloudFormation 콘솔에서 스택 상태를 확인합니다. 상태가 `CREATE_COMPLETE`로 변경된 후 명령을 재시도합니다. | | Amazon ECS 상태 확인이 `UNHEALTHY`를 반환되고 Amazon ECS 콘솔에 있는 클러스터의 **서비스** 섹션에 다음 오류가 표시됩니다.
`service EcsAnywhereService was unable to place a task because no container instance met all of its requirements. Reason: No Container Instances were found in your cluster.` | 다음 명령을 입력하여 Vagrant VM에서 Amazon ECS 에이전트를 다시 시작합니다.
$vagrant ssh
$sudo systemctl restart ecs
$sudo systemctl status ecs
| ## 관련 리소스 + [Amazon ECS Anywhere 마케팅 페이지](https://aws.amazon.com/ecs/anywhere/) + [Amazon ECS Anywhere 설명서](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-anywhere.html#ecs-anywhere-considerations) + [Amazon ECS Anywhere 데모](https://www.youtube.com/watch?v=-eud6yUXsJM)(동영상) + [Amazon ECS Anywhere 워크숍 샘플](https://github.com/aws-samples/aws-ecs-anywhere-workshop-samples)(GitHub) + [리포지토리 미러링](https://docs.gitlab.com/ee/user/project/repository/mirror/) (GitLab 설명서)