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

GitLab.com을 사용하고 Amazon Elastic Container Service (ECS)에 배포하는 경우 ECS에 배포하기에 대한 내용을 읽어보세요.

AWS로 GitLab 인증#

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

1. AWS 계정에 로그인합니다.

2. IAM 사용자를 생성합니다.

3. 사용자를 선택하여 세부 정보에 액세스합니다. Security credentials > Create a new access key로 이동합니다.

4. Access key ID와 Secret access key를 기록합니다.

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

   환경 변수 이름	값
   AWS_ACCESS_KEY_ID	액세스 키 ID.
   AWS_SECRET_ACCESS_KEY	비밀 액세스 키.
   AWS_DEFAULT_REGION	리전 코드. 사용하려는 AWS 서비스가 선택한 리전에서 사용 가능한지 확인하는 것이 좋습니다.

6. 변수는 기본적으로 보호됩니다. 보호되지 않은 브랜치 또는 태그에서 GitLab CI/CD를 사용하려면 Protect variable 체크박스를 지웁니다.

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

이미지에 AWS Command Line Interface가 포함된 경우 프로젝트의 .gitlab-ci.yml 파일에서 이미지를 참조할 수 있습니다. 그런 다음 CI/CD job에서 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 이미지를 제공합니다:

• 이미지는 GitLab 컨테이너 레지스트리에 호스팅됩니다. 최신 이미지는 registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest입니다.
• 이미지는 GitLab 저장소에 저장됩니다.

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

타사 레지스트리의 이미지도 사용할 수 있습니다.

ECS에 애플리케이션 배포#

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

사전 요구 사항:

• AWS로 GitLab 인증.
• Amazon ECS에서 클러스터 생성.
• Amazon RDS의 ECS 서비스 또는 데이터베이스와 같은 관련 구성 요소 생성.
• 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	배포를 대상으로 하는 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부터 시작하여 완전히 새로운 태스크 정의가 생성됩니다.

   [!warning] 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 배포 job은 롤아웃이 완료될 때까지 기다린 후 종료합니다. 이 동작을 비활성화하려면 CI_AWS_ECS_WAIT_FOR_ROLLOUT_COMPLETE_DISABLED를 비어 있지 않은 값으로 설정합니다.

EC2에 애플리케이션 배포#

GitLab은 Amazon EC2에 배포를 지원하기 위한 AWS/CF-Provision-and-Deploy-EC2 템플릿을 제공합니다.

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

1. 스택 생성: AWS CloudFormation API를 사용하여 인프라가 프로비저닝됩니다.
2. S3 버킷으로 푸시: 빌드가 실행될 때 아티팩트가 생성됩니다. 아티팩트가 AWS S3 버킷으로 푸시됩니다.
3. EC2에 배포: 다음 다이어그램과 같이 콘텐츠가 AWS EC2 인스턴스에 배포됩니다:

템플릿과 JSON 구성#

EC2에 배포하려면 다음 단계를 완료합니다.

1. 스택에 대한 JSON을 생성합니다. AWS 템플릿을 사용합니다.

2. S3로 푸시할 JSON을 생성합니다. 다음 세부 정보를 포함합니다.

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

   source는 build job이 애플리케이션을 빌드한 위치입니다. 빌드가 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 job은 여전히 실행됩니다.
   • 빌드된 애플리케이션이 S3 버킷으로 푸시된 다음 관련 JSON 객체의 내용을 기반으로 EC2 인스턴스에 배포됩니다. 배포 job은 EC2에 배포가 완료되거나 실패하면 종료됩니다.

트러블슈팅#

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

이 오류는 Cloud Deploy 이미지에서 사용하는 aws-cli 유틸리티의 응답에 유니코드 문자가 포함되어 있을 때 발생할 수 있습니다. Cloud Deploy 이미지에는 정의된 로케일이 없으며 기본적으로 ASCII를 사용합니다. 이 오류를 해결하려면 다음 CI/CD 변수를 추가합니다:

variables:
  LANG: "UTF-8"