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

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

GitLab은 AWS로 배포하기 위해 필요한 라이브러리와 도구가 포함된 Docker 이미지를 제공합니다. 이러한 이미지를 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 지역 코드
  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를 포함한 Docker 이미지를 제공합니다.

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

세 번째로, 제3자 레지스트리에서 이미지를 사용할 수 있습니다.

애플리케이션을 ECS로 배포

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

준비 사항:

  • AWS를 GitLab과 연동합니다.
  • Amazon ECS에서 클러스터를 생성합니다.
  • Amazon RDS에서와 같이 관련 구성 요소를 생성합니다.
  • ECS 작업 정의를 생성하는데, containerDefinitions[].name 속성의 값은 대상 ECS 서비스에서 정의된 컨테이너 이름과 동일해야 합니다. 작업 정의는 다음과 같을 수 있습니다:
    • ECS에 이미 있는 작업 정의.
    • GitLab 프로젝트에 JSON 파일로 저장된 작업 정의. AWS 문서의 템플릿을 사용하여 파일을 저장합니다. 예를 들어 <프로젝트-루트>/ci/aws/task-definition.json.

클러스터에 배포하려면:

  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부터 시작합니다.

    경고: 만약 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을 프로젝트 리포지토리에 커밋 및 푸시합니다.

당신의 애플리케이션 Docker 이미지가 다시 빌드되고 GitLab 컨테이너 레지스트리에 푸시됩니다. 만일 이미지가 프라이빗 레지스트리에 있는 경우, task 정의가 새로운 Docker 이미지 위치로 업데이트되고 ECS의 새로운 리비전이 생성됩니다.

마지막으로, AWS ECS 서비스가 새로운 task 정의의 새로운 리비전을 사용하도록 업데이트되어 클러스터가 애플리케이션의 최신 버전을 가져옵니다.

note
ECS 배포 작업은 rollout이 완료될 때까지 대기합니다. 이 동작을 비활성화하려면, CI_AWS_ECS_WAIT_FOR_ROLLOUT_COMPLETE_DISABLED를 비어 있지 않은 값으로 설정합니다.

경고: 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. 파이프라인을 실행합니다.

    • 당신의 AWS CloudFormation 스택은 CI_AWS_CF_CREATE_STACK_FILE 변수의 내용을 기반으로 생성됩니다. 만약 스택이 이미 존재한다면, 이 단계는 건너뜁니다. 그러나 provision 작업은 여전히 실행됩니다.
    • 빌드된 애플리케이션이 S3 버킷으로 푸시되고 관련 JSON 객체의 내용에 따라 EC2 인스턴스에 배포됩니다. 배포 작업은 EC2로의 배포가 완료되거나 실패할 때까지 진행됩니다.

문제 해결

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

이 오류는 Cloud Deploy 이미지가 Unicode 문자를 포함한 aws-cli 유틸리티의 응답을 받았을 때 발생할 수 있습니다. 우리가 제공하는 Cloud Deploy 이미지에는 정의된 로캘이 없어 ASCII를 기본으로 사용합니다. 이 오류를 해결하려면 다음의 CI/CD 변수를 추가하세요. 

variables:
  LANG: "UTF-8"