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 변수에 자격 증명을 저장하는 것보다 안전하지만 이 페이지의 지침과 함께 작동하지 않습니다.

GitLab을 AWS와 인증하기

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

  1. AWS 계정에 로그인합니다.
  2. IAM 사용자 생성합니다.
  3. 사용자를 선택하여 세부정보에 액세스합니다. 보안 자격 증명 > 새 액세스 키 생성으로 이동합니다.
  4. Access key ID와 Secret access key를 기록합니다.

  5. GitLab 프로젝트로 이동하여 Settings > CI/CD로 가세요. 다음 CI/CD 변수를 설정합니다:

    환경 변수 이름 값
    AWS_ACCESS_KEY_ID 귀하의 Access key ID입니다.
    AWS_SECRET_ACCESS_KEY 귀하의 secret access key입니다.
    AWS_DEFAULT_REGION 귀하의 지역 코드입니다. 사용하고자 하는 AWS 서비스가 선택한 지역에서 사용 가능한지 확인할 수 있습니다.
  6. 변수는 기본적으로 보호됩니다.
    GitLab CI/CD를 보호되지 않은 브랜치 또는 태그에서 사용하려면, Protect variable 체크박스를 비활성화하세요.

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 리포지토리에 이미지를 푸시하는 방법을 배우세요.

또한 모든 서드파티 레지스트리의 이미지를 사용할 수 있습니다.

애플리케이션을 ECS에 배포하기

애플리케이션의 배포를 Amazon ECS 클러스터에 자동화할 수 있습니다.

전제 조건:

  • AWS를 GitLab과 인증하기.
  • Amazon ECS에서 클러스터를 생성하세요.
  • ECS 서비스 또는 Amazon RDS에서 데이터베이스와 같은 관련 구성 요소를 생성하세요.
  • containerDefinitions[].name 속성 값이 대상 ECS 서비스에 정의된 Container name과 동일한 ECS 작업 정의를 생성하세요. 작업 정의는 다음과 같을 수 있습니다:
    • ECS의 기존 작업 정의.
    • GitLab 프로젝트의 JSON 파일. AWS 문서의 템플릿을 사용하고 파일을 프로젝트에 저장하세요. 예를 들어 <project-root>/ci/aws/task-definition.json.

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

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

    환경 변수 이름 값
    CI_AWS_ECS_CLUSTER 배포를 위해 targeting하는 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 컨테이너 레지스트리에 푸시됩니다.

귀하의 이미지가 개인 레지스트리에 있는 경우, 작업 정의가 조정된 repositoryCredentials 속성으로 설정되어 있는지 확인하세요.

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

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

참고:
ECS 배포 작업은 종료되기 전에 롤아웃이 완료되기를 기다립니다. 이 동작을 비활성화하려면 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. 이러한 템플릿을 개별적으로 포함하지 마세요. 오직 AWS/Deploy-ECS.gitlab-ci.yml 템플릿만 포함하세요. 이 다른 템플릿은 기본 템플릿과 함께 사용하도록 설계되어 있으며, 예기치 않게 이동하거나 변경될 수 있습니다. 또한, 이러한 템플릿 내의 작업 이름이 변경될 수 있습니다. 귀하의 파이프라인에서 이러한 작업 이름을 덮어쓰지 마세요, 왜냐하면 이름이 변경되면 덮어쓰기가 작동을 멈추기 때문입니다.

애플리케이션을 EC2에 배포하는 방법

GitLab은 Amazon EC2에 배포하는 데 도움이 되는 AWS/CF-Provision-and-Deploy-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 이미지에서 사용하는 aws-cli 유틸리티의 응답에 유니코드 문자가 포함될 때 발생할 수 있습니다. 우리가 제공하는 Cloud Deploy 이미지는 정의된 로케일이 없으며 기본적으로 ASCII를 사용합니다. 이 오류를 해결하려면 다음 CI/CD 변수를 추가하세요:

variables:
  LANG: "UTF-8"