GitLab CI/CD를 통해 AWS로 배포하기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

GitLab은 AWS로 배포하기 위해 필요한 라이브러리 및 도구가 포함된 도커 이미지를 제공합니다. 이러한 이미지는 CI/CD 파이프라인에서 참조할 수 있습니다.

GitLab.com을 사용하고 Amazon Elastic Container Service (ECS)로 배포하는 경우 ECS로 배포하는 방법을 읽어보세요.

note
배포 구성에 익숙하고 AWS 자격 증명만 검색하려면 ID 토큰 및 OpenID Connect를 사용해보세요. ID 토큰은 CI/CD 변수에 자격 증명을 저장하는 것보다 안전하지만 본 페이지의 안내와는 호환되지 않습니다.

AWS와 GitLab 연동

AWS에 연결하려면 GitLab CI/CD를 사용하여 인증해야 합니다. 인증 설정을 완료한 후 CI/CD를 구성하여 배포할 수 있습니다.

  1. AWS 계정에 로그인합니다.
  2. IAM 사용자를 만듭니다.
  3. 사용자를 선택하여 해당 세부 정보에 액세스합니다. 보안 자격 증명 > 새 액세스 키 생성으로 이동합니다.
  4. 액세스 키 ID와 비밀 액세스 키를 메모합니다.

  5. GitLab 프로젝트에서 설정 > CI/CD로 이동합니다. 다음 CI/CD 변수를 설정합니다:

    환경 변수 이름 값
    AWS_ACCESS_KEY_ID 액세스 키 ID 입력
    AWS_SECRET_ACCESS_KEY 비밀 액세스 키 입력
    AWS_DEFAULT_REGION 지역 코드 입력. 사용하려는 AWS 서비스가 선택한 지역에서 사용 가능한지 확인하는 것이 좋습니다.
  6. 변수는 기본적으로 보호됨. 보호되지 않는 브랜치나 태그로 GitLab CI/CD를 사용하려면 변수 보호 확인란을 해제하세요.

이미지를 사용하여 AWS 명령 실행

이미지에 AWS Command Line Interface가 포함되어 있는 경우 프로젝트의 .gitlab-ci.yml 파일에서 해당 이미지를 참조할 수 있습니다. 그러면 CI/CD 작업에서 aws 명령을 실행할 수 있습니다.

예를 들어: 

deploy:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest
  script:
    - aws s3 ...
    - aws create-deployment ...
  environment: production

GitLab은 AWS CLI를 포함한 도커 이미지를 제공합니다:

또한 Amazon Elastic Container Registry (ECR) 이미지를 사용할 수도 있습니다. ECR 리포지터리에 이미지를 푸시하는 방법을 알아보세요.

제3자 레지스트리에서도 이미지를 사용할 수 있습니다.

ECS에 애플리케이션 배포

애플리케이션을 Amazon ECS 클러스터로 자동 배포할 수 있습니다.

전제 조건:

  • AWS를 GitLab과 연동합니다.
  • Amazon ECS에 클러스터를 만듭니다.
  • ECS 서비스나 Amazon RDS에서와 같이 관련 컴포넌트를 만듭니다.
  • ECS 작업 정의를 만듭니다. 여기서 containerDefinitions[].name 속성의 값은 대상 ECS 서비스에서 정의한 컨테이너 이름과 동일해야 합니다. 작업 정의는 다음과 같을 수 있습니다:
    • 기존 ECS 작업 정의.
    • GitLab 13.3 및 이후에는 GitLab 프로젝트에 JSON 파일로 저장됩니다. AWS 문서의 템플릿을 사용하여 파일을 저장합니다. 예: <프로젝트 루트>/ci/aws/task-definition.json.

ECS 클러스터로 배포하려면:

  1. GitLab 프로젝트에서 설정 > CI/CD로 이동합니다. 다음 CI/CD 변수를 설정합니다. 이 이름들은 Amazon ECS 대시보드에서 대상 클러스터를 선택하여 찾을 수 있습니다.

    환경 변수 이름 값
    CI_AWS_ECS_CLUSTER 배포 대상인 AWS ECS 클러스터 이름.
    CI_AWS_ECS_SERVICE AWS ECS 클러스터에 연결된 대상 서비스의 이름. 해당 변수는 적절한 환경 (production, staging, review/*)에 지정되어야 합니다.
    CI_AWS_ECS_TASK_DEFINITION ECS에 작업 정의가 있는 경우 해당 서비스에 연결된 작업 정의의 이름.
    CI_AWS_ECS_TASK_DEFINITION_FILE GitLab에 JSON 파일로 저장된 작업 정의의 파일 이름 및 경로. 예: ci/aws/my_task_definition.json. JSON 파일에 있는 작업 정의의 이름이 ECS에 있는 기존 작업 정의와 동일한 경우 CI/CD를 실행하면 새 리비전이 생성됩니다. 그렇지 않으면 새로운 작업 정의가 생성되며 리비전은 1부터 시작합니다.
    caution
    CI_AWS_ECS_TASK_DEFINITION_FILE 및 CI_AWS_ECS_TASK_DEFINITION 둘 다 정의한 경우 CI_AWS_ECS_TASK_DEFINITION_FILE이 우선됩니다.

  2. .gitlab-ci.yml에 이 템플릿을 포함합니다: 

    include:
  - template: AWS/Deploy-ECS.gitlab-ci.yml

    AWS/Deploy-ECS 템플릿은 GitLab과 함께 제공되며 GitLab.com에서 사용할 수 있습니다.

  3. 업데이트한 .gitlab-ci.yml을 커밋하고 프로젝트 리포지터리에 푸시합니다.

애플리케이션 도커 이미지가 다시 빌드되고 GitLab 컨테이너 레지스트리에 푸시됩니다. 이미지가 비공개 레지스트리에 있는 경우 작업 정의가 구성되어 있는지 확인하세요.

대상 작업 정의는 새로운 Docker 이미지의 위치로 업데이트되며 결과적으로 ECS에서 새 리비전이 생성됩니다.

마지막으로 AWS ECS 서비스가 새로운 작업 정의의 새 리비전으로 업데이트되어 클러스터가 새 버전의 애플리케이션을 가져옵니다.

note
ECS 배포 작업은 롤아웃이 완료될 때까지 대기합니다. 이 동작을 비활성화하려면 CI_AWS_ECS_WAIT_FOR_ROLLOUT_COMPLETE_DISABLED를 비어 있지 않은 값으로 설정하세요.
caution
AWS/Deploy-ECS.gitlab-ci.yml 템플릿에는 Jobs/Build.gitlab-ci.yml 및 Jobs/Deploy/ECS.gitlab-ci.yml 두 개의 템플릿이 포함되어 있습니다. 이러한 템플릿을 독립적으로 포함하지 마세요. 메인 템플릿과 함께만 사용하도록 설계되었습니다. 이러한 템플릿은 예기치 않게 이동하거나 변경될 수 있습니다. 또한 이러한 템플릿 내의 작업 이름이 변경될 수 있습니다. 사용자 고유의 파이프라인에서 이러한 작업 이름을 재정의하지 마세요. 이름이 변경되면 사용자 고유의 설정이 작동하지 않습니다.

EC2에 애플리케이션 배포

GitLab은 AWS/CF-Provision-and-Deploy-EC2라는 템플릿을 제공하여 Amazon EC2에 배포하는 데 도움을 줍니다.

관련 JSON 개체를 구성하고 해당 템플릿을 사용하면 파이프라인이 다음을 수행합니다.

  1. 스택 생성: AWS CloudFormation API를 사용하여 인프라가 프로비저닝됩니다.
  2. S3 버킷으로 푸시: 빌드가 실행되면 아티팩트가 생성됩니다. 해당 아티팩트는 AWS S3 버킷으로 푸시됩니다.
  3. EC2에 배포: 콘텐츠가 AWS EC2 인스턴스에 배포됩니다.

CF-Provision-and-Deploy-EC2 다이어그램

템플릿 및 JSON 구성

EC2에 배포하려면 다음 단계를 완료하세요.

  1. 스택용 JSON을 생성합니다. AWS 템플릿을 사용하세요.

  2. S3로 푸시하기 위한 JSON을 생성하세요. 다음 세부 정보를 포함하세요. 

    {
  "applicationName": "string",
  "source": "string",
  "s3Location": "s3://your/bucket/project_built_file...]"
}

    source는 build 작업이 애플리케이션을 빌드한 위치입니다. 빌드는 artifacts:paths에 저장됩니다.

  3. EC2에 배포하기 위한 JSON을 생성하세요. AWS 템플릿을 사용하세요.
  4. JSON 개체를 파이프라인에서 액세스할 수 있도록 만드세요:

    • 이러한 JSON 개체를 리포지터리에 저장하려면 개별 파일로 저장합니다.

      .gitlab-ci.yml 파일에 프로젝트 루트와 상대적인 파일 경로를 가리키는 CI/CD 변수를 추가하세요. 예를 들어, JSON 파일이 <project_root>/aws 폴더에 있는 경우: 

      variables:
  CI_AWS_CF_CREATE_STACK_FILE: 'aws/cf_create_stack.json'
  CI_AWS_S3_PUSH_FILE: 'aws/s3_push.json'
  CI_AWS_EC2_DEPLOYMENT_FILE: 'aws/create_deployment.json'

    • 리포지터리에 이러한 JSON 개체를 저장하고 싶지 않으면 프로젝트 설정에서 각 개체를 별도의 파일 유형 CI/CD 변수로 추가하세요. 위와 동일한 변수 이름을 사용하세요.

  5. .gitlab-ci.yml 파일에 스택 이름용 CI/CD 변수를 생성하세요. 예를 들어: 

    variables:
  CI_AWS_CF_STACK_NAME: 'YourStackName'

  6. .gitlab-ci.yml 파일에 CI 템플릿을 추가하세요: 

    include:
  - template: AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml

  7. 파이프라인을 실행하세요.

    • CI_AWS_CF_CREATE_STACK_FILE 변수의 내용을 기반으로 AWS CloudFormation 스택이 생성됩니다. 스택이 이미 존재하는 경우 해당 단계는 건너뜁니다. 그러나 해당 provision 작업은 여전히 실행됩니다.
    • 빌드된 애플리케이션이 S3 버킷으로 푸시되고 EC2 인스턴스로 배포됩니다. EC2로의 배포가 완료되거나 실패할 때 배포 작업이 완료됩니다.

문제 해결

오류 'ascii' codec can't encode character '\uxxxx'

이 오류는 Cloud Deploy 이미지에서 사용되는 aws-cli 유틸리티의 응답에 유니코드 문자가 포함되어 있을 때 발생할 수 있습니다. 우리가 제공하는 Cloud Deploy 이미지에는 정의된 로캘이 없어 ASCII를 사용하려고 합니다. 이 오류를 해결하려면 다음과 같은 CI/CD 변수를 추가하세요: 

variables:
  LANG: "UTF-8"