AWS CDK 및 를 사용하여 Amazon ECS Anywhere에서 하이브리드 워크로드에 대한 CI/CD 파이프라인 설정 GitLab - AWS 권장 가이드
요약사전 조건 및 제한 사항아키텍처도구모범 사례에픽문제 해결관련 리소스

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

AWS CDK 및 를 사용하여 Amazon ECS Anywhere에서 하이브리드 워크로드에 대한 CI/CD 파이프라인 설정 GitLab

작성자: Dr. Rahul Sharad Gaikwad(AWS)

코드 리포지토리: amazon-ecs-anywhere-cicd-pipeline-cdk-sample

환경: PoC 또는 파일럿

기술: 하이브리드 클라우드, 컨테이너 및 마이크로서비스, 인프라, DevOps

워크로드: 오픈 소스

AWS 서비스: AWS CDK, AWS CodePipeline, Amazon ECS, AWS Systems Manager, AWS CodeCommit

요약

알림: AWS CodeCommit 는 더 이상 신규 고객에게 제공되지 않습니다. 의 기존 고객은 서비스를 정상적으로 계속 사용할 AWS CodeCommit 수 있습니다. 자세히 알아보기

Amazon ECS Anywhere는 Amazon Elastic Container Service(Amazon)의 확장입니다ECS. 온프레미스 서버 또는 가상 머신(VM)과 같은 외부 인스턴스를 Amazon ECS 클러스터에 등록할 수 있는 지원을 제공합니다. 는 비용을 절감하고 복잡한 로컬 컨테이너 오케스트레이션 및 작업을 완화하는 데 도움이 되는 기능입니다. ECS Anywhere를 사용하여 온프레미스 및 클라우드 환경 모두에서 컨테이너 애플리케이션을 배포하고 실행할 수 있습니다. 따라서 팀이 여러 도메인과 기술을 배우거나 복잡한 소프트웨어를 자체적으로 관리할 필요가 없습니다.

이 패턴은 Amazon Web Services(AWS) 클라우드 개발 키트(AWS) CDK스택을 사용하여 Amazon ECS Anywhere 인스턴스로 Amazon ECS 클러스터를 프로비저닝하는 접근 방식을 설명합니다 step-by-step. 그런 다음 AWS CodePipeline 를 사용하여 지속적 통합 및 지속적 배포(CI/CD) 파이프라인을 설정합니다. 그런 다음 GitLab 코드 리포지토리를 에 복제AWS CodeCommit 하고 Amazon ECS 클러스터에 컨테이너화된 애플리케이션을 배포합니다.

이 패턴은 온프레미스 인프라를 사용하여 컨테이너 애플리케이션을 실행하고 를 사용하여 애플리케이션 코드 기반을 GitLab 관리하는 사용자에게 도움이 되도록 설계되었습니다. 기존 온프레미스 인프라를 방해하지 않고 AWS 클라우드 서비스를 사용하여 이러한 워크로드를 관리할 수 있습니다.

사전 조건 및 제한 사항

사전 조건 

제한 사항

제품 버전

  • AWS CDK 툴킷 버전 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(AmazonECR)

  • AWS 자격 증명 및 액세스 관리(IAM)

  • AWS 시스템 관리자

  • GitLab 리포지토리

대상 아키텍처 

Amazon ECS 클러스터 및 CI/CD 파이프라인을 설정하는 아키텍처 다이어그램입니다.

이 다이어그램은 다음과 같이 Amazon ECS 클러스터를 프로비저닝하고 CI/CD pipeline that sets up and deploys the CI/CD 파이프라인을 설정하는 이 패턴에 설명된 두 가지 기본 워크플로를 나타냅니다.

  1. Amazon ECS 클러스터 프로비저닝

    1. 첫 번째 AWS CDK 스택을 배포하면 에 CloudFormation 스택이 생성됩니다AWS.

    2. 이 CloudFormation 스택은 Amazon ECS 클러스터 및 관련 AWS 리소스를 프로비저닝합니다.

    3. Amazon ECS 클러스터에 외부 인스턴스를 등록하려면 VM에 AWS Systems Manager 에이전트(SSM 에이전트)를 설치하고 VM을 AWS Systems Manager 관리형 인스턴스로 등록해야 합니다. 

    4. Amazon ECS 클러스터에 외부 인스턴스로 등록하려면 VM에 Amazon ECS 컨테이너 에이전트 및 Docker도 설치해야 합니다.

    5. 외부 인스턴스가 Amazon ECS 클러스터에 등록되고 구성된 경우 외부 인스턴스로 등록된 VM에서 여러 컨테이너를 실행할 수 있습니다.

    6. Amazon ECS 클러스터가 활성 상태이며 컨테이너를 통해 애플리케이션 워크로드를 실행할 수 있습니다. Amazon ECS Anywhere 컨테이너 인스턴스는 온프레미스 환경에서 실행되지만 클라우드의 Amazon ECS 클러스터와 연결되어 있습니다.

  2. CI/CD 파이프라인 설정 및 배포

    1. 두 번째 AWS CDK 스택을 배포하면 에 다른 CloudFormation 스택이 생성됩니다AWS.

    2. 이 CloudFormation 스택은 CodePipeline 및 관련 AWS 리소스에서 파이프라인을 프로비저닝합니다.

    3. 애플리케이션 코드 변경 사항을 온프레미스 GitLab 리포지토리로 푸시하고 병합합니다. 

    4. GitLab 리포지토리는 리포 CodeCommit 지토리에 자동으로 복제됩니다.

    5. CodeCommit 리포지토리 업데이트가 자동으로 시작됩니다 CodePipeline. 

    6. CodePipeline 에서 코드를 복사 CodeCommit 하고 에서 배포 가능한 애플리케이션 빌드를 생성합니다 CodeBuild.

    7. CodePipeline 는 CodeBuild 빌드 환경의 Docker 이미지를 생성하여 Amazon ECR 리포지토리로 푸시합니다.

    8. CodePipeline 는 Amazon ECR리포지토리에서 컨테이너 이미지를 가져오는 CodeDeploy 작업을 시작합니다.

    9. CodePipeline 는 Amazon ECS 클러스터에 컨테이너 이미지를 배포합니다.

자동화 및 규모 조정

이 패턴은 를 인프라 코드(IaC ) 도구AWSCDK로 사용하여 이 아키텍처를 구성하고 배포합니다. AWS CDK 는 AWS 리소스를 오케스트레이션하고 Amazon ECS Anywhere 및 CI/CD 파이프라인을 설정하는 데 도움이 됩니다.

도구

AWS 서비스

  • AWS 클라우드 개발 키트(AWS CDK)는 코드로 AWS 클라우드 인프라를 정의하고 프로비저닝하는 데 도움이 되는 소프트웨어 개발 프레임워크입니다.

  • AWS CodeCommit 는 자체 소스 제어 시스템을 관리할 필요 없이 Git 리포지토리를 비공개로 저장하고 관리하는 데 도움이 되는 버전 제어 서비스입니다.

  • AWS CodePipeline 는 소프트웨어 릴리스의 다양한 단계를 빠르게 모델링하고 구성하며 소프트웨어 변경 사항을 지속적으로 릴리스하는 데 필요한 단계를 자동화합니다.

  • AWS 명령줄 인터페이스(AWS CLI)는 명령줄 쉘의 명령을 통해 AWS 서비스와 상호 작용하는 데 도움이 되는 오픈 소스 도구입니다.

  • Amazon Elastic Container Registry(Amazon ECR)는 안전하고 확장 가능하며 안정적인 관리형 컨테이너 이미지 레지스트리 서비스입니다.

  • Amazon Elastic Container Service(Amazon ECS)는 클러스터에서 컨테이너를 실행, 중지 및 관리하는 데 도움이 되는 빠르고 확장 가능한 컨테이너 관리 서비스입니다. 또한 이 패턴은 Amazon ECS Anywhere 를 사용하여 온프레미스 서버 또는 VM을 Amazon ECS 클러스터에 등록할 수 있도록 지원합니다.

기타 도구

  • Node.js는 확장 가능한 네트워크 애플리케이션을 구축하기 위해 설계된 이벤트 기반 JavaScript 런타임 환경입니다.

  • npm은 Node.js 환경에서 실행되는 소프트웨어 레지스트리로, 패키지를 공유 또는 대여하고 개인 패키지의 배포를 관리하는 데 사용됩니다.

  • Vagrant는 휴대용 가상 소프트웨어 개발 환경을 구축하고 유지 관리하기 위한 오픈 소스 유틸리티입니다. 이 패턴은 데모용으로 Vagrant를 사용하여 온프레미스 VM을 만듭니다.

코드 리포지토리

이 패턴의 코드는 GitHub AWS리포지토리를 사용하여 Amazon ECS Anywhere의 CI/CD 파이프라인CDK에서 사용할 수 있습니다.

모범 사례

이 패턴을 배포할 때는 다음과 같은 모범 사례를 고려해 보십시오.

에픽

작업설명필요한 기술

AWS CDK 버전을 확인합니다.

다음 명령을 입력하여 AWS CDK Toolkit의 버전을 확인합니다.

cdk --version

이 패턴을 사용하려면 버전 2.27.0 이상이 필요합니다. 이전 버전이 있는 경우 AWS CDK 설명서의 지침에 따라 업데이트합니다.

DevOps 엔지니어

npm 버전을 확인합니다.

다음 명령을 입력하여 npm 버전을 확인합니다.

npm --version

이 패턴을 사용하려면 버전 7.20.3 이상이 필요합니다. 이전 버전이 있을 경우 npm 설명서의 지침에 따라 업데이트하세요.

DevOps 엔지니어

AWS 보안 인증 정보를 설정합니다.

aws configure 명령을 입력하고 프롬프트에 따라 AWS 자격 증명을 설정합니다.

$aws configure
AWS Access Key ID [None]: <your-access-key-ID>
AWS Secret Access Key [None]: <your-secret-access-key>
Default region name [None]: <your-Region-name>
Default output format [None]:
DevOps 엔지니어
작업설명필요한 기술

AWS CDK 코드 리포지토리를 복제합니다.

  1. 다음 명령을 입력하여 이 패턴에 대한 AWS리포지토리를 사용하여 Amazon ECS Anywhere의 CI/CD 파이프라인CDK을 복제합니다.

    git clone https://github.com/aws-samples/amazon-ecs-anywhere-cicd-pipeline-cdk-sample.git

  2. 다음 명령을 입력하여 복제된 디렉터리로 이동합니다.

    cd amazon-ecs-anywhere-cicd-pipeline-cdk-sample
DevOps 엔지니어

환경을 부트스트랩합니다.

다음 명령을 입력하여 사용하려는 계정 및 AWS 리전에 CloudFormation 템플릿을 배포합니다.

cdk bootstrap <account-number>/<Region>

자세한 내용은 AWS CDK 설명서의 Bootstrapping을 참조하세요.

DevOps 엔지니어
작업설명필요한 기술

패키지 종속성을 설치하고 TypeScript 파일을 컴파일합니다.

패키지 종속성을 설치하고 다음 명령을 입력하여 TypeScript 파일을 컴파일합니다.

$cd EcsAnywhereCdk
$npm install
$npm fund

이 명령은 샘플 저장소의 모든 패키지를 설치합니다. 자세한 내용은 npm 설명서에 있는 npm ci와 npm install을 참조하세요. 이러한 명령을 입력할 때 누락된 패키지와 관련된 오류가 발생하는 경우 이 패턴의 문제 해결 섹션을 참고하십시오.

DevOps 엔지니어

프로젝트를 빌드합니다.

프로젝트 코드를 빌드하려면 다음 명령을 입력하세요.

npm run build

프로젝트 구축 및 배포에 대한 자세한 내용은 AWS CDK 설명서의 첫 번째 AWS CDK 앱을 참조하세요.

DevOps 엔지니어

Amazon ECS Anywhere 인프라 스택을 배포합니다.

  1. 다음 명령을 입력하여 스택을 나열합니다.

    $cdk list

  2. 출력이 EcsAnywhereInfraStack 및 ECSAnywherePipelineStack 스택을 반환하는지 확인합니다.

  3. 다음 명령을 입력하여 EcsAnywhereInfraStack 스택을 배포합니다.

    $cdk  deploy EcsAnywhereInfraStack
DevOps 엔지니어

스택 생성 및 출력을 확인합니다.

  1. AWS 관리 콘솔에 로그인하고 에서 CloudFormation 콘솔을 엽니다https://console.aws.amazon.com/cloudformation/.

  2. 스택 페이지에서 EcsAnywhereInfraStack 스택을 선택합니다.

  3. 스택 상태가 CREATE_IN_PROGRESS 또는 CREATE_COMPLETE인지 확인합니다.

    Amazon ECS 클러스터를 설정하는 데 시간이 걸릴 수 있습니다. 스택 생성이 완료될 때까지는 진행하지 마십시오.

DevOps 엔지니어
작업설명필요한 기술

VM을 설정합니다.

Vagrantfile이 있는 루트 디렉터리에서 vagrant up 명령을 입력하여 Vagrant VM을 생성합니다. 자세한 내용은 Vagrant 설명서를 참조하세요.

DevOps 엔지니어

VM을 외부 인스턴스로 등록합니다.

  1. vagrant ssh 명령을 사용하여 Vagrant VM에 로그인합니다. 자세한 내용은 Vagrant 설명서를 참조하세요.

  2. AWS CLI 설치 지침에 따라 다음 명령을 입력하여 VMAWSCLI에 를 설치합니다. 

    $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" \
> -o "awscliv2.zip"
$sudo apt install unzip
$unzip awscliv2.zip
$sudo ./aws/install
$aws configure
AWS Access Key ID [None]: <your-access-key-ID>
AWS Secret Access Key [None]: <your-secret-access-key>
Default region name [None]: <your-Region-name>
Default output format [None]:

  1. AWS Systems Manager에 VM을 등록하고 외부 인스턴스를 활성화하는 데 사용할 수 있는 활성화 코드와 ID를 생성합니다. 이 명령의 출력에는 활성화 ID 및 활성화 코드 값이 포함됩니다.

    aws ssm create-activation \
> --iam-role EcsAnywhereInstanceRole \
> | tee ssm-activation.json

    이 명령을 실행할 때 오류가 발생하는 경우 문제 해결 섹션을 참고하십시오.

  2. 활성화 ID 및 코드 값을 내보냅니다.

    export ACTIVATION_ID=<activation-ID>
export ACTIVATION_CODE=<activation-code>

  3. VM에 설치 스크립트를 다운로드합니다.

    curl --proto "https" -o "ecs-anywhere-install.sh" \
> "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install-latest.sh"

  4. VM에서 설치 스크립트를 실행합니다.

    sudo bash ecs-anywhere-install.sh \
--cluster EcsAnywhereCluster \
--activation-id $ACTIVATION_ID \
--activation-code $ACTIVATION_CODE \
--region <region-name>

이렇게 하면 VM이 Amazon ECS Anywhere 외부 인스턴스로 설정되고 Amazon ECS 클러스터에 인스턴스가 등록됩니다. 자세한 내용은 Amazon ECS 설명서의 클러스터에 외부 인스턴스 등록을 참조하세요. 문제가 발생하는 경우 문제 해결 섹션을 참고하십시오.

DevOps 엔지니어

Amazon ECS Anywhere와 외부 VM의 상태를 확인합니다.

VM이 Amazon ECS 제어 영역에 연결되어 실행 중인지 확인하려면 다음 명령을 사용합니다.

$aws ssm describe-instance-information
$aws ecs list-container-instances --cluster $CLUSTER_NAME
DevOps 엔지니어
작업설명필요한 기술

CodeCommit 리포지토리에 브랜치를 생성합니다.

리포지토리에 대한 첫 번째 커밋을 생성하여 CodeCommit 리포지토리main에 라는 브랜치를 생성합니다. AWS 설명서에 따라 에서 커밋을 생성할 CodeCommit 수 있습니다. 다음 명령은 예제입니다.

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(GitLab 문서)을 참조하세요.

참고: 기본적으로 미러링은 리포지토리를 자동으로 동기화합니다. 리포지토리를 수동으로 업데이트하려면 미러 업데이트(GitLab 문서)를 참조하세요.

DevOps 엔지니어

CI/CD 파이프라인 스택을 배포합니다.

다음 명령을 입력하여 EcsAnywherePipelineStack 스택을 배포합니다.

$cdk  deploy EcsAnywherePipelineStack
DevOps 엔지니어

CI/CD 파이프라인을 테스트합니다.

  1. 애플리케이션 코드를 변경하고 소스, 온프레미스 GitLab 리포지토리로 푸시합니다. 자세한 내용은 푸시 옵션(GitLab 문서)을 참조하세요. 예를 들어 ../application/index.html 파일을 편집하여 애플리케이션 버전 값을 업데이트합니다.

  2. 코드가 CodeCommit 리포지토리에 복제되면 CI/CD 파이프라인이 시작됩니다. 다음 중 하나를 수행합니다.

    • 자동 미러링을 사용하여 GitLab 리포지토리를 CodeCommit 리포지토리와 동기화하는 경우 다음 단계로 진행합니다.

    • 수동 미러링을 사용하는 경우 미러 업데이트(GitLab 문서)의 지침에 따라 애플리케이션 코드 변경 사항을 CodeCommit 리포지토리로 푸시합니다. https://docs.gitlab.com/ee/user/project/repository/mirror/#update-a-mirror

  3. 로컬 컴퓨터의 웹 브라우저에서 http://localhost:80을 입력합니다. 포트 80이 Vagrantfile의 localhost로 전달되므로 NGINX 웹 페이지가 열립니다. 업데이트된 애플리케이션 버전 값을 볼 수 있는지 확인하십시오. 이렇게 하면 파이프라인 및 이미지 배포가 검증됩니다.

  4. (선택 사항) AWS 관리 콘솔에서 배포를 확인하려면 다음을 수행합니다.

    1. 에서 Amazon ECS 콘솔을 엽니다https://console.aws.amazon.com/ecs/.

    2. 탐색 모음에서 사용할 리전을 선택합니다.

    3. 탐색 창에서 클러스터를 선택합니다.

    4. 클러스터 페이지에서 EcsAnywhereCluster 클러스터를 선택합니다.

    5. 작업 정의를 선택합니다.

    6. 컨테이너가 실행 중인지 확인합니다.

DevOps 엔지니어
작업설명필요한 기술

리소스를 정리하고 삭제합니다.

이 패턴을 살펴본 후에는 생성한 리소스를 제거 proof-of-concept해야 합니다. 정리하려면 다음 명령을 입력합니다.

$cdk destroy EcsAnywherePipelineStack
$cdk destroy EcsAnywhereInfraStack
DevOps 엔지니어

문제 해결

문제Solution

패키지 종속 항목을 설치할 때 누락된 패키지와 관련된 오류가 발생합니다.

다음 명령 중 하나를 입력하여 누락된 패키지를 해결하십시오.

$npm ci

또는

$npm install -g @aws-cdk/<package_name>

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

관련 리소스