GitLab에서 새 클러스터를 생성하고 Amazon Elastic Kubernetes Service(EKS)에 호스팅된 기존 클러스터를 추가할 수 있습니다.

기존 EKS 클러스터 연결#

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

새 EKS 클러스터 생성#

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

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

히스토리

• GitLab 14.0에서 더 이상 사용되지 않습니다.

사전 요구 사항:

• 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은 환경 목록과 각 배포 상태를 표시하고, 앱으로 이동하거나 모니터링 지표를 확인하거나 실행 중인 Pod의 셸에 접근하는 옵션도 함께 제공합니다.

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에 입력합니다.

문제 해결#

새 클러스터를 생성할 때 자주 발생하는 오류는 다음과 같습니다.

유효성 검사 실패: Role ARN은 유효한 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와 external ID가 AWS의 Trust relationships 탭에 정의된 값과 일치하는지 확인합니다.

   

이 VPC의 Security Groups를 로드할 수 없음#

구성 폼의 옵션을 채울 때 이 오류가 반환되는 이유는, GitLab 이 제공된 역할을 위임받는 데는 성공했지만 그 역할에 폼에 필요한 리소스를 가져올 권한이 부족하기 때문입니다. 해당 역할에 올바른 권한을 할당했는지 확인합니다.

Key Pairs가 로드되지 않음#

GitLab은 지정된 Cluster Region에서 키 페어를 불러옵니다. 해당 리전에 키 페어가 있는지 확인합니다.

클러스터 생성 중 ROLLBACK_FAILED#

GitLab 이 하나 이상의 리소스를 생성하는 중 오류가 발생해 생성 과정이 중단되었습니다. 연결된 CloudFormation 스택을 확인하면 생성에 실패한 구체적인 리소스를 찾을 수 있습니다.

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