AWS Fargate용 GitLab 커스텀 실행기 드라이버는 각 GitLab CI 작업을 실행하기 위해 Amazon Elastic Container Service(ECS)에서 컨테이너를 자동으로 시작합니다.

이 문서의 작업을 완료하면 실행기는 GitLab에서 시작된 작업을 실행할 수 있습니다. GitLab에서 커밋이 발생할 때마다 GitLab 인스턴스는 새 작업이 사용 가능함을 러너에게 알립니다. 러너는 AWS ECS에서 구성한 작업 정의를 기반으로 대상 ECS 클러스터에서 새 태스크를 시작합니다. AWS ECS 작업 정의에서 어떤 Docker 이미지든 사용하도록 구성할 수 있습니다. 이 접근 방식으로 AWS Fargate에서 실행할 수 있는 빌드 유형에 대한 완전한 유연성을 가집니다.

이 문서는 구현에 대한 초기 이해를 제공하기 위한 예시를 보여줍니다. 운영 환경에 사용하기 위한 것이 아니며, AWS에서 추가적인 보안이 필요합니다.

예를 들어 두 개의 AWS 보안 그룹이 필요할 수 있습니다:

• GitLab Runner를 호스팅하는 EC2 인스턴스에 사용되며 제한된 외부 IP 범위에서만 SSH 연결을 허용하는 그룹(관리 액세스용).
• Fargate 태스크에 적용되며 EC2 인스턴스에서만 SSH 트래픽을 허용하는 그룹.

비공개 컨테이너 레지스트리의 경우, ECS 태스크에는 IAM 권한(AWS ECR만 해당) 또는 비ECR 비공개 레지스트리의 경우 태스크의 비공개 레지스트리 인증이 필요합니다.

CloudFormation 또는 Terraform을 사용하여 AWS 인프라 프로비저닝 및 설정을 자동화할 수 있습니다.

CI/CD 작업은 .gitlab-ci.yml 파일의 image: 키워드 값이 아닌 ECS 태스크에 정의된 이미지를 사용합니다. ECS는 ECS 태스크에 사용되는 이미지를 재정의하는 것을 허용하지 않습니다.

이 제한 사항을 해결하려면 다음을 수행할 수 있습니다:

• 러너가 사용되는 모든 프로젝트의 모든 빌드 종속성이 포함된 이미지를 ECS 작업 정의에서 생성하고 사용합니다.
• 다른 이미지로 여러 ECS 작업 정의를 생성하고 FARGATE_TASK_DEFINITION CI/CD 변수에서 ARN을 지정합니다.
• 공식 AWS EKS Blueprints를 따라 EKS 클러스터를 생성하는 것을 고려합니다.

자세한 내용은 1시간 만에 코드 없이 GitLab EKS Fargate 러너 시작하기를 참조하세요.

사전 요구 사항#

시작하기 전에 다음이 필요합니다:

• EC2, ECS 및 ECR 리소스를 생성하고 구성할 권한이 있는 AWS IAM 사용자.
• AWS VPC 및 서브넷.
• 하나 이상의 AWS 보안 그룹.

1단계: AWS Fargate 태스크용 컨테이너 이미지 준비#

컨테이너 이미지를 준비하세요. GitLab 작업이 실행될 때 컨테이너를 생성하는 데 사용할 수 있도록 이 이미지를 레지스트리에 업로드할 수 있습니다.

1. 이미지에 CI 작업을 빌드하는 데 필요한 도구가 있는지 확인하세요. 예를 들어 Java 프로젝트에는 Java JDK와 Maven 또는 Gradle 같은 빌드 도구가 필요합니다. Node.js 프로젝트에는 node와 npm이 필요합니다.
2. 이미지에 아티팩트와 캐싱을 처리하는 GitLab Runner가 있는지 확인하세요. 추가 정보는 커스텀 실행기 문서의 Run 단계 섹션을 참조하세요.
3. 컨테이너 이미지가 공개 키 인증을 통한 SSH 연결을 허용할 수 있는지 확인하세요. 러너는 이 연결을 사용하여 .gitlab-ci.yml 파일에 정의된 빌드 명령어를 AWS Fargate의 컨테이너로 전송합니다. SSH 키는 Fargate 드라이버에 의해 자동으로 관리됩니다. 컨테이너는 SSH_PUBLIC_KEY 환경 변수에서 키를 허용할 수 있어야 합니다.

GitLab Runner와 SSH 구성이 포함된 Debian 예시를 확인하세요. Node.js 예시도 확인하세요.

2단계: 레지스트리에 컨테이너 이미지 푸시#

이미지를 만든 후 ECS 작업 정의에서 사용할 수 있도록 컨테이너 레지스트리에 이미지를 게시하세요.

• ECR에서 리포지터리를 만들고 이미지를 푸시하려면 Amazon ECR Repositories 문서를 따르세요.
• AWS CLI를 사용하여 ECR에 이미지를 푸시하려면 AWS CLI를 사용하여 Amazon ECR 시작하기 문서를 따르세요.
• GitLab Container Registry를 사용하려면 Debian 또는 NodeJS 예시를 사용할 수 있습니다. Debian 이미지는 registry.gitlab.com/tmaczukin-test-projects/fargate-driver-debian:latest에 게시됩니다. NodeJS 예시 이미지는 registry.gitlab.com/aws-fargate-driver-demo/docker-nodejs-gitlab-ci-fargate:latest에 게시됩니다.

3단계: GitLab Runner용 EC2 인스턴스 생성#

이제 AWS EC2 인스턴스를 생성합니다. 다음 단계에서 이 인스턴스에 GitLab Runner를 설치합니다.

1. https://console.aws.amazon.com/ec2/v2/home#LaunchInstanceWizard로 이동합니다.
2. 인스턴스에서 Ubuntu Server 18.04 LTS AMI를 선택합니다. 선택한 AWS 리전에 따라 이름이 다를 수 있습니다.
3. 인스턴스 유형으로 t2.micro를 선택합니다. Next: Configure Instance Details를 선택합니다.
4. Number of instances는 기본값을 유지합니다.
5. Network에서 VPC를 선택합니다.
6. Auto-assign Public IP를 Enable로 설정합니다.
7. IAM role 아래에서 Create new IAM role을 선택합니다. 이 권한은 테스트 목적으로만 사용되며 안전하지 않습니다.
   1. Create role을 선택합니다.
   2. AWS service를 선택하고 Common use cases 아래에서 EC2를 선택합니다. 그런 다음 Next: Permissions를 선택합니다.
   3. AmazonECS_FullAccess 정책의 확인란을 선택합니다. Next: Tags를 선택합니다.
   4. Next: Review를 선택합니다.
   5. IAM 권한의 이름(예: fargate-test-instance)을 입력하고 Create role을 선택합니다.
8. 인스턴스를 생성하는 브라우저 탭으로 돌아갑니다.
9. Create new IAM role 왼쪽의 새로 고침 버튼을 선택합니다. fargate-test-instance 권한을 선택합니다. Next: Add Storage를 선택합니다.
10. Next: Add Tags를 선택합니다.
11. Next: Configure Security Group을 선택합니다.
12. Create a new security group을 선택하고 fargate-test로 이름을 지정합니다. SSH에 대한 규칙이 정의되어 있는지 확인합니다(Type: SSH, Protocol: TCP, Port Range: 22). 인바운드 및 아웃바운드 규칙의 IP 범위를 지정해야 합니다.
13. Review and Launch를 선택합니다.
14. Launch를 선택합니다.
15. 선택 사항. Create a new key pair를 선택하고 fargate-runner-manager로 이름을 지정한 다음 Download Key Pair를 선택합니다. SSH용 개인 키가 컴퓨터에 다운로드됩니다(브라우저에서 구성된 디렉토리 확인).
16. Launch Instances를 선택합니다.
17. View Instances를 선택합니다.
18. 인스턴스가 시작될 때까지 기다립니다. IPv4 Public IP 주소를 메모합니다.

4단계: EC2 인스턴스에 GitLab Runner 설치 및 구성#

이제 Ubuntu 인스턴스에 GitLab Runner를 설치합니다.

1. GitLab 프로젝트의 Settings > CI/CD로 이동하여 Runners 섹션을 펼칩니다. Set up a specific Runner manually 아래에서 등록 토큰을 메모합니다.

2. chmod 400 path/to/downloaded/key/file을 실행하여 키 파일에 올바른 권한이 있는지 확인합니다.

3. 다음을 사용하여 생성한 EC2 인스턴스에 SSH로 접속합니다:

   ssh ubuntu@[ip_address] -i path/to/downloaded/key/file
   

4. 연결에 성공하면 다음 명령어를 실행합니다:

   sudo mkdir -p /opt/gitlab-runner/{metadata,builds,cache}
   curl -s "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
   sudo apt install gitlab-runner
   

5. 1단계에서 메모한 GitLab URL과 등록 토큰으로 이 명령어를 실행합니다.

   sudo gitlab-runner register --url "https://gitlab.com/" --registration-token TOKEN_HERE --name fargate-test-runner --run-untagged --executor custom -n
   

6. sudo vim /etc/gitlab-runner/config.toml을 실행하고 다음 내용을 추가합니다:

   concurrent = 1
   check_interval = 0
   
   [session_server]
     session_timeout = 1800
   
   [[runners]]
     name = "fargate-test"
     url = "https://gitlab.com/"
     token = "__REDACTED__"
     executor = "custom"
     builds_dir = "/opt/gitlab-runner/builds"
     cache_dir = "/opt/gitlab-runner/cache"
     [runners.custom]
       volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"]
       config_exec = "/opt/gitlab-runner/fargate"
       config_args = ["--config", "/etc/gitlab-runner/fargate.toml", "custom", "config"]
       prepare_exec = "/opt/gitlab-runner/fargate"
       prepare_args = ["--config", "/etc/gitlab-runner/fargate.toml", "custom", "prepare"]
       run_exec = "/opt/gitlab-runner/fargate"
       run_args = ["--config", "/etc/gitlab-runner/fargate.toml", "custom", "run"]
       cleanup_exec = "/opt/gitlab-runner/fargate"
       cleanup_args = ["--config", "/etc/gitlab-runner/fargate.toml", "custom", "cleanup"]
   

7. 비공개 CA가 있는 GitLab Self-Managed 인스턴스를 사용하는 경우 다음 줄을 추가합니다:

          volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"]
   

   인증서 신뢰에 대해 자세히 알아보기.

   아래에 표시된 config.toml 파일의 섹션은 등록 명령어에 의해 생성됩니다. 변경하지 마세요.

   concurrent = 1
   check_interval = 0
   
   [session_server]
     session_timeout = 1800
   
   name = "fargate-test"
   url = "https://gitlab.com/"
   token = "__REDACTED__"
   executor = "custom"
   

8. sudo vim /etc/gitlab-runner/fargate.toml을 실행하고 다음 내용을 추가합니다:

   LogLevel = "info"
   LogFormat = "text"
   
   [Fargate]
     Cluster = "test-cluster"
     Region = "us-east-2"
     Subnet = "subnet-xxxxxx"
     SecurityGroup = "sg-xxxxxxxxxxxxx"
     TaskDefinition = "test-task:1"
     EnablePublicIP = true
   
   [TaskMetadata]
     Directory = "/opt/gitlab-runner/metadata"
   
   [SSH]
     Username = "root"
     Port = 22
   

   • Cluster 값과 TaskDefinition 이름을 메모합니다. 이 예시에서는 test-task에 개정 번호 :1이 표시됩니다. 개정 번호를 지정하지 않으면 최신 활성 개정이 사용됩니다.

   • 리전을 선택합니다. Subnet 값은 러너 매니저 인스턴스에서 가져옵니다.

   • 보안 그룹 ID를 찾으려면:

     1. AWS의 인스턴스 목록에서 생성한 EC2 인스턴스를 선택합니다. 세부 정보가 표시됩니다.
     2. Security groups 아래에서 생성한 그룹의 이름을 선택합니다.
     3. Security group ID를 복사합니다.

     운영 환경에서는 보안 그룹 설정 및 사용에 대한 AWS 가이드라인을 따르세요.

   • EnablePublicIP가 true로 설정되면 SSH 연결을 수행하기 위해 태스크 컨테이너의 공개 IP가 수집됩니다.

   • EnablePublicIP가 false로 설정되면:

     • Fargate 드라이버는 태스크 컨테이너의 비공개 IP를 사용합니다. false로 설정했을 때 연결을 설정하려면 VPC 보안 그룹에 소스가 VPC CIDR인 포트 22(SSH)에 대한 인바운드 규칙이 있어야 합니다.
     • 외부 종속성을 가져오려면 프로비저닝된 AWS Fargate 컨테이너가 공용 인터넷에 액세스할 수 있어야 합니다. AWS Fargate 컨테이너에 공용 인터넷 액세스를 제공하려면 VPC에서 NAT 게이트웨이를 사용할 수 있습니다.

   • SSH 서버의 포트 번호는 선택 사항입니다. 생략하면 기본 SSH 포트(22)가 사용됩니다.

   • 섹션 설정에 대한 자세한 내용은 Fargate 드라이버 문서를 참조하세요.

9. Fargate 드라이버를 설치합니다:

   sudo curl -Lo /opt/gitlab-runner/fargate "https://gitlab-runner-custom-fargate-downloads.s3.amazonaws.com/latest/fargate-linux-amd64"
   sudo chmod +x /opt/gitlab-runner/fargate
   

5단계: ECS Fargate 클러스터 생성#

Amazon ECS 클러스터는 ECS 컨테이너 인스턴스의 그룹입니다.

1. https://console.aws.amazon.com/ecs/home#/clusters로 이동합니다.
2. Create Cluster를 선택합니다.
3. Networking only 유형을 선택합니다. Next step을 선택합니다.
4. test-cluster로 이름을 지정합니다(fargate.toml과 동일).
5. Create를 선택합니다.
6. View cluster를 선택합니다. Cluster ARN 값에서 리전과 계정 ID 부분을 메모합니다.
7. Update Cluster를 선택합니다.
8. Default capacity provider strategy 옆에서 Add another provider를 선택하고 FARGATE를 선택합니다. Update를 선택합니다.

ECS Fargate에서 클러스터 설정 및 작업에 대한 자세한 지침은 AWS 문서를 참조하세요.

6단계: ECS 태스크 정의 생성#

이 단계에서는 Fargate 유형의 태스크 정의를 생성하고 CI 빌드에 사용할 컨테이너 이미지를 참조합니다.

1. https://console.aws.amazon.com/ecs/home#/taskDefinitions로 이동합니다.
2. Create new Task Definition을 선택합니다.
3. FARGATE를 선택하고 Next step을 선택합니다.
4. test-task로 이름을 지정합니다. (참고: 이름은 fargate.toml 파일에서 정의된 값과 동일하지만 :1은 없습니다).
5. Task memory (GB) 및 Task CPU (vCPU) 값을 선택합니다.
6. Add container를 선택합니다. 그런 다음:
   1. Fargate 드라이버가 SSH_PUBLIC_KEY 환경 변수를 주입할 수 있도록 ci-coordinator로 이름을 지정합니다.
   2. 이미지를 정의합니다(예: registry.gitlab.com/tmaczukin-test-projects/fargate-driver-debian:latest).
   3. 22/TCP에 대한 포트 매핑을 정의합니다.
   4. Add를 선택합니다.
7. Create를 선택합니다.
8. View task definition을 선택합니다.

태스크 정의 설정 및 작업에 대한 자세한 지침은 AWS 문서를 참조하세요.

AWS ECR에서 이미지를 시작하는 데 필요한 ECS 서비스 권한에 대한 정보는 Amazon ECS 태스크 실행 IAM 권한을 참조하세요.

GitLab 인스턴스에서 호스팅되는 레지스트리를 포함한 비공개 레지스트리에 대한 ECS 인증에 대한 정보는 태스크의 비공개 레지스트리 인증을 참조하세요.

이 시점에서 러너 매니저와 Fargate 드라이버가 구성되어 AWS Fargate에서 작업을 실행할 준비가 완료되었습니다.

7단계: 설정 테스트#

설정이 이제 사용할 준비가 되어야 합니다.

1. GitLab 프로젝트에서 .gitlab-ci.yml 파일을 만듭니다:

   test:
     script:
       - echo "It works!"
       - for i in $(seq 1 30); do echo "."; sleep 1; done
   

2. 프로젝트의 CI/CD > Pipelines로 이동합니다.

3. Run Pipeline을 선택합니다.

4. 브랜치와 변수를 업데이트하고 Run Pipeline을 선택합니다.

정리#

AWS Fargate로 커스텀 실행기를 테스트한 후 정리를 수행하려면 다음 객체를 제거합니다:

• 3단계에서 생성한 EC2 인스턴스, 키 페어, IAM 권한, 보안 그룹.
• 5단계에서 생성한 ECS Fargate 클러스터.
• 6단계에서 생성한 ECS 태스크 정의.

비공개 AWS Fargate 태스크 구성#

높은 수준의 보안을 보장하려면 비공개 AWS Fargate 태스크를 구성하세요. 이 구성에서 실행기는 AWS 내부 IP 주소만 사용합니다. CI/CD 작업이 비공개 AWS Fargate 인스턴스에서 실행되도록 AWS에서 아웃바운드 트래픽만 허용합니다.

비공개 AWS Fargate 태스크를 구성하려면 다음 단계를 완료하여 AWS를 구성하고 비공개 서브넷에서 AWS Fargate 태스크를 실행하세요:

1. 기존 공개 서브넷이 VPC 주소 범위의 모든 IP 주소를 예약하지 않았는지 확인합니다. VPC 및 서브넷의 cird 주소 범위를 검사합니다. 서브넷 cird 주소 범위가 VPC cird 주소 범위의 부분 집합이면 2단계와 4단계를 건너뜁니다. 그렇지 않으면 VPC에 사용 가능한 주소 범위가 없으므로 VPC와 공개 서브넷을 삭제하고 다시 만들어야 합니다:

   1. 기존 서브넷과 VPC를 삭제합니다.
   2. 삭제한 VPC와 동일한 구성으로 VPC를 만들고 cird 주소를 업데이트합니다(예: 10.0.0.0/23).
   3. 삭제한 서브넷과 동일한 구성으로 공개 서브넷을 만듭니다. VPC 주소 범위의 부분 집합인 cird 주소를 사용합니다(예: 10.0.0.0/24).

2. 공개 서브넷과 동일한 구성으로 비공개 서브넷을 만듭니다. 공개 서브넷 범위와 겹치지 않는 cird 주소 범위를 사용합니다(예: 10.0.1.0/24).

3. NAT 게이트웨이를 만들고 공개 서브넷 내에 배치합니다.

4. 비공개 서브넷 라우팅 테이블을 수정하여 대상 0.0.0.0/0이 NAT 게이트웨이를 가리키도록 합니다.

5. farget.toml 설정을 업데이트합니다:

   Subnet = "private-subnet-id"
   EnablePublicIP = false
   UsePublicIP = false
   

6. Fargate 태스크와 관련된 IAM 권한에 다음 인라인 정책을 추가합니다(Fargate 태스크와 관련된 IAM 권한은 일반적으로 ecsTaskExecutionRole로 명명되어 이미 존재해야 합니다).

   {
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": [
                   "secretsmanager:GetSecretValue",
                   "kms:Decrypt",
                   "ssm:GetParameters"
               ],
               "Resource": [
                   "arn:aws:secretsmanager:*:<account-id>:secret:*",
                   "arn:aws:kms:*:<account-id>:key/*"
               ]
           }
       ]
   }
   

7. 보안 그룹의 "인바운드 규칙"을 보안 그룹 자체를 참조하도록 변경합니다. AWS 설정 대화 상자에서:

   • Type을 ssh로 설정합니다.
   • Source를 Custom으로 설정합니다.
   • 보안 그룹을 선택합니다.
   • 모든 호스트에서 SSH 액세스를 허용하는 기존 인바운드 규칙을 제거합니다.

자세한 내용은 다음 AWS 문서를 참조하세요:

• Amazon ECS 태스크 실행 IAM 권한
• Amazon ECR 인터페이스 VPC 엔드포인트(AWS PrivateLink)
• Amazon ECS 인터페이스 VPC 엔드포인트
• 공개 및 비공개 서브넷이 있는 VPC

트러블슈팅#

설정 테스트 시 No Container Instances were found in your cluster 오류#

error="starting new Fargate task: running new task on Fargate: error starting AWS Fargate Task: InvalidParameterException: No Container Instances were found in your cluster."

AWS Fargate 드라이버에는 ECS 클러스터가 기본 용량 공급자 전략으로 구성되어 있어야 합니다.

추가 정보:

• 기본 용량 공급자 전략은 각 Amazon ECS 클러스터와 연결됩니다. 다른 용량 공급자 전략이나 시작 유형이 지정되지 않은 경우 태스크가 실행되거나 서비스가 생성될 때 클러스터는 이 전략을 사용합니다.
• capacityProviderStrategy가 지정된 경우 launchType 파라미터를 생략해야 합니다. capacityProviderStrategy나 launchType이 지정되지 않은 경우 클러스터의 defaultCapacityProviderStrategy가 사용됩니다.

작업 실행 시 메타데이터 file does not exist 오류#

Application execution failed PID=xxxxx error="obtaining information about the running task: trying to access file \"/opt/gitlab-runner/metadata/<runner_token>-xxxxx.json\": file does not exist" cleanup_std=err job=xxxxx project=xx runner=<runner_token>

IAM 권한 정책이 올바르게 구성되어 /opt/gitlab-runner/metadata/에서 메타데이터 JSON 파일을 생성하는 쓰기 작업을 수행할 수 있는지 확인하세요. 비운영 환경에서 테스트하려면 AmazonECS_FullAccess 정책을 사용하세요. 조직의 보안 요구 사항에 따라 IAM 권한 정책을 검토하세요.

작업 실행 시 connection timed out#

Application execution failed PID=xxxx error="executing the script on the remote host: executing script on container with IP \"172.x.x.x\": connecting to server: connecting to server \"172.x.x.x:22\" as user \"root\": dial tcp 172.x.x.x:22: connect: connection timed out"

EnablePublicIP가 false로 구성된 경우 VPC 보안 그룹에 SSH 연결을 허용하는 인바운드 규칙이 있는지 확인하세요. AWS Fargate 태스크 컨테이너는 GitLab Runner EC2 인스턴스의 SSH 트래픽을 허용해야 합니다.

작업 실행 시 connection refused#

Application execution failed PID=xxxx error="executing the script on the remote host: executing script on container with IP \"10.x.x.x\": connecting to server: connecting to server \"10.x.x.x:22\" as user \"root\": dial tcp 10.x.x.x:22: connect: connection refused"

태스크 컨테이너에 포트 22가 노출되어 있고 6단계: ECS 태스크 정의 생성의 지침에 따라 포트 매핑이 구성되어 있는지 확인하세요. 포트가 노출되고 컨테이너가 구성된 경우:

1. Amazon ECS > Clusters > 태스크 정의 선택 > Tasks에서 컨테이너에 오류가 있는지 확인합니다.
2. Stopped 상태의 태스크를 보고 실패한 최신 태스크를 확인합니다. 컨테이너 실패가 있는 경우 logs 탭에 더 많은 세부 정보가 있습니다.

또는 Docker 컨테이너를 로컬에서 실행할 수 있는지 확인하세요.

오류: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain#

AWS Fargate 드라이버의 구버전으로 인해 지원되지 않는 키 유형이 사용되는 경우 다음 오류가 발생합니다.

Application execution failed PID=xxxx error="executing the script on the remote host: executing script on container with IP \"172.x.x.x\": connecting to server: connecting to server \"172.x.x.x:22\" as user \"root\": ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain"

이 이슈를 해결하려면 GitLab Runner EC2 인스턴스에 최신 AWS Fargate 드라이버를 설치하세요:

sudo curl -Lo /opt/gitlab-runner/fargate "https://gitlab-runner-custom-fargate-downloads.s3.amazonaws.com/latest/fargate-linux-amd64"
sudo chmod +x /opt/gitlab-runner/fargate