GitLab을 통해 새 클러스터를 생성하거나 Amazon Elastic Kubernetes Service (EKS)에서 호스팅되는 기존 클러스터를 추가할 수 있습니다.

기존 EKS 클러스터 연결#

이미 EKS 클러스터가 있고 GitLab에 연결하려면 GitLab Kubernetes 에이전트를 사용하세요.

새 EKS 클러스터 생성#

GitLab에서 새 클러스터를 생성하려면 Infrastructure as Code를 사용하세요.

클러스터 인증서를 통한 EKS 새 클러스터 생성 방법 (Deprecated)#

히스토리

• GitLab 14.0에서 Deprecated.

사전 요구 사항:

• Amazon Web Services 계정.
• IAM 리소스 관리 권한.

인스턴스 레벨 클러스터의 경우 GitLab Self-Managed 인스턴스 추가 요구 사항을 참조하세요.

인증서 기반 방식으로 프로젝트, 그룹 또는 인스턴스에 새 Kubernetes 클러스터를 생성하려면:

1. 클러스터의 접근 제어(RBAC 또는 ABAC) 정의.
2. GitLab에서 클러스터 생성.
3. Amazon에서 클러스터 준비.
4. GitLab에서 클러스터 데이터 구성.

추가 단계:

1. 기본 Storage Class 생성.
2. EKS에 앱 배포.

GitLab에서 새 EKS 클러스터 생성#

클러스터 인증서를 통해 프로젝트, 그룹 또는 인스턴스용 새 EKS 클러스터를 생성하려면:

1. 다음으로 이동하세요:
   • 프로젝트 레벨 클러스터의 경우: 프로젝트의 Operate > Kubernetes clusters 페이지.
   • 그룹 레벨 클러스터의 경우: 그룹의 Kubernetes 페이지.
   • 인스턴스 레벨 클러스터의 경우: Admin 영역의 Kubernetes 페이지.
2. Integrate with a cluster certificate를 선택하세요.
3. Create new cluster 탭에서 Amazon EKS를 선택하면 이후 단계에서 필요한 Account ID와 External ID가 표시됩니다.
4. IAM Management Console에서 IAM 정책을 생성하세요:

   1. 왼쪽 패널에서 Policies를 선택하세요.

   2. Create Policy를 선택하면 새 창이 열립니다.

   3. JSON 탭을 선택하고 기존 내용 대신 다음 스니펫을 붙여넣으세요. 이 권한은 GitLab이 리소스를 생성하되 삭제하지는 않도록 합니다:

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "autoscaling:CreateAutoScalingGroup",
                      "autoscaling:DescribeAutoScalingGroups",
                      "autoscaling:DescribeScalingActivities",
                      "autoscaling:UpdateAutoScalingGroup",
                      "autoscaling:CreateLaunchConfiguration",
                      "autoscaling:DescribeLaunchConfigurations",
                      "cloudformation:CreateStack",
                      "cloudformation:DescribeStacks",
                      "ec2:AuthorizeSecurityGroupEgress",
                      "ec2:AuthorizeSecurityGroupIngress",
                      "ec2:RevokeSecurityGroupEgress",
                      "ec2:RevokeSecurityGroupIngress",
                      "ec2:CreateSecurityGroup",
                      "ec2:createTags",
                      "ec2:DescribeImages",
                      "ec2:DescribeKeyPairs",
                      "ec2:DescribeRegions",
                      "ec2:DescribeSecurityGroups",
                      "ec2:DescribeSubnets",
                      "ec2:DescribeVpcs",
                      "eks:CreateCluster",
                      "eks:DescribeCluster",
                      "iam:AddRoleToInstanceProfile",
                      "iam:AttachRolePolicy",
                      "iam:CreateRole",
                      "iam:CreateInstanceProfile",
                      "iam:CreateServiceLinkedRole",
                      "iam:GetRole",
                      "iam:listAttachedRolePolicies",
                      "iam:ListRoles",
                      "iam:PassRole",
                      "ssm:GetParameters"
                  ],
                  "Resource": "*"
              }
          ]
      }
      

      이 과정에서 오류가 발생하면 GitLab이 변경 사항을 롤백하지 않습니다. 수동으로 리소스를 제거해야 합니다. 관련 CloudFormation 스택을 삭제하여 이를 수행할 수 있습니다.

   4. Review policy를 선택하세요.

   5. 이 정책에 적합한 이름을 입력하고 Create Policy를 선택하세요. 이제 이 창을 닫아도 됩니다.

Amazon에서 클러스터 준비#

1. 클러스터용 EKS IAM 역할 생성 (역할 A).
2. Amazon 인증을 위한 또 다른 EKS IAM 역할 생성 (역할 B).

클러스터용 EKS IAM 역할 생성#

IAM Management Console에서 Amazon EKS 클러스터 IAM 역할 지침을 따라 EKS IAM 역할 (역할 A)을 생성하세요. 이 역할은 Amazon EKS가 관리하는 Kubernetes 클러스터가 서비스에서 사용하는 리소스를 관리하기 위해 귀하 대신 다른 AWS 서비스를 호출할 수 있도록 하는 데 필요합니다.

GitLab이 EKS 클러스터를 올바르게 관리하려면 가이드에서 제안하는 정책 외에 AmazonEKSClusterPolicy도 포함해야 합니다.

Amazon 인증을 위한 또 다른 EKS IAM 역할 생성#

IAM Management Console에서 AWS로 GitLab 인증을 위한 또 다른 IAM 역할 (역할 B)을 생성하세요:

1. AWS IAM 콘솔에서 왼쪽 패널의 Roles를 선택하세요.
2. Create role을 선택하세요.
3. Select type of trusted entity에서 Another AWS account를 선택하세요.
4. GitLab의 Account ID를 Account ID 필드에 입력하세요.
5. Require external ID를 체크하세요.
6. GitLab의 External ID를 External ID 필드에 입력하세요.
7. Next: Permissions를 선택하고 방금 생성한 정책을 선택하세요.
8. Next: Tags를 선택하고 필요에 따라 이 역할에 연결할 태그를 입력하세요.
9. Next: Review를 선택하세요.
10. 제공된 필드에 역할 이름과 선택적 설명을 입력하세요.
11. Create role을 선택하세요. 새 역할 이름이 상단에 표시됩니다. 이름을 선택하고 새로 생성된 역할에서 Role ARN을 복사하세요.

GitLab에서 클러스터 데이터 구성#

1. GitLab으로 돌아가서 복사한 역할 ARN을 Role ARN 필드에 입력하세요.
2. Cluster Region 필드에 새 클러스터에 사용할 리전을 입력하세요. GitLab은 역할 인증 시 이 리전에 접근 권한이 있는지 확인합니다.
3. Authenticate with AWS를 선택하세요.
4. 클러스터 설정을 조정하세요.
5. Create Kubernetes cluster 버튼을 선택하세요.

약 10분 후 클러스터가 준비됩니다.

클러스터 설정#

새 클러스터를 생성할 때 다음 설정을 사용할 수 있습니다:

기본 Storage Class 생성#

Amazon EKS에는 기본 Storage Class가 없어서 영구 볼륨 요청이 자동으로 처리되지 않습니다. Auto DevOps의 일환으로 배포된 PostgreSQL 인스턴스는 영구 스토리지를 요청하므로 기본 스토리지 클래스 없이는 시작할 수 없습니다.

기본 스토리지 클래스가 없는 경우 생성하려면 Storage Classes를 참조하세요.

또는 프로젝트 변수 POSTGRES_ENABLED를 false로 설정하여 PostgreSQL을 비활성화하세요.

EKS에 앱 배포#

RBAC가 비활성화되고 서비스가 배포되면 Auto DevOps를 활용하여 앱을 빌드, 테스트 및 배포할 수 있습니다.

아직 활성화되지 않은 경우 Auto DevOps를 활성화하세요. 로드 밸런서로 확인되는 와일드카드 DNS 항목이 생성된 경우 Auto DevOps 설정의 domain 필드에 입력하세요. 그렇지 않으면 배포된 앱이 클러스터 외부에서 접근할 수 없습니다.

GitLab이 새 파이프라인을 생성하고 앱 빌드, 테스트 및 배포를 시작합니다.

파이프라인이 완료되면 앱이 EKS에서 실행되어 사용자가 접근할 수 있습니다. Operate > Environments를 선택하세요.

GitLab은 환경 목록과 배포 상태를 표시하며 앱 탐색, 모니터링 메트릭 보기, 실행 중인 파드에 대한 셸 접근 옵션도 제공합니다.

GitLab Self-Managed 인스턴스 추가 요구 사항#

GitLab Self-Managed를 사용하는 경우 Amazon 자격 증명을 구성해야 합니다. GitLab은 이 자격 증명을 사용하여 Amazon IAM 역할을 맡아 클러스터를 생성합니다.

IAM 사용자를 생성하고 사용자가 EKS 클러스터를 생성하는 데 필요한 역할을 맡을 수 있는 권한이 있는지 확인하세요.

예를 들어, 다음 정책 문서는 계정 123456789012에서 gitlab-eks-로 시작하는 이름의 역할을 맡을 수 있도록 허용합니다:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::123456789012:role/gitlab-eks-*"
  }
}

Amazon 인증 구성#

사전 요구 사항:

• 관리자 접근 권한.

GitLab에서 Amazon 인증을 구성하려면 Amazon AWS 콘솔에서 IAM 사용자의 접근 키를 생성하고 다음 단계를 따르세요:

1. 오른쪽 상단 모서리에서 Admin을 선택하세요.
2. 왼쪽 사이드바에서 Settings > General을 선택하세요.
3. Amazon EKS를 펼치세요.
4. Enable Amazon EKS integration을 체크하세요.
5. Account ID를 입력하세요.
6. 접근 키 및 ID를 입력하세요.
7. Save changes를 선택하세요.

EKS 접근 키 및 ID#

인스턴스 프로필을 사용하여 필요할 때 AWS에서 임시 자격 증명을 동적으로 검색할 수 있습니다. 이 경우 Access key ID 및 Secret access key 필드를 비워두고 EC2 인스턴스에 IAM 역할 전달을 사용하세요.

그렇지 않은 경우 Access key ID 및 Secret access key에 접근 키 자격 증명을 입력하세요.

트러블슈팅#

다음은 새 클러스터를 생성할 때 흔히 발생하는 오류입니다.

Validation failed: Role ARN must be a valid Amazon Resource Name#

Provision Role ARN이 올바른지 확인하세요. 유효한 ARN의 예:

arn:aws:iam::123456789012:role/gitlab-eks-provision'

Access denied: User is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::y#

이 오류는 Amazon 인증 구성에 정의된 자격 증명이 Provision Role ARN에 정의된 역할을 맡을 수 없을 때 발생합니다:

User `arn:aws:iam::x` is not authorized to perform: `sts:AssumeRole` on resource: `arn:aws:iam::y`

다음을 확인하세요:

1. 초기 AWS 자격 증명에 AssumeRole 정책이 있는지.

2. Provision Role에 지정된 리전에서 클러스터를 생성할 접근 권한이 있는지.

3. 계정 ID와 외부 ID가 AWS의 Trust relationships 탭에 정의된 값과 일치하는지:

   

Could not load Security Groups for this VPC#

구성 양식에서 옵션을 채울 때 GitLab이 이 오류를 반환합니다. GitLab이 제공된 역할을 성공적으로 맡았지만 역할에 양식에 필요한 리소스를 검색할 권한이 부족하기 때문입니다. 역할에 올바른 권한을 할당했는지 확인하세요.

Key Pairs are not loaded#

GitLab은 지정된 Cluster Region에서 키 페어를 로드합니다. 해당 리전에 키 페어가 있는지 확인하세요.

클러스터 생성 중 ROLLBACK_FAILED#

GitLab이 하나 이상의 리소스를 생성하는 중 오류가 발생하여 생성 프로세스가 중단되었습니다. 관련 CloudFormation 스택을 검사하여 생성에 실패한 특정 리소스를 찾을 수 있습니다.

Cluster 리소스가 The provided role doesn't have the Amazon EKS Managed Policies associated with it. 오류로 실패한 경우 Role name에 지정된 역할이 올바르게 구성되지 않은 것입니다.