기존 Kubernetes 클러스터가 있는 경우 프로젝트, 그룹 또는 인스턴스에 추가하여 GitLab과의 통합 혜택을 받을 수 있습니다.

사전 요구사항#

기존 클러스터를 GitLab에 추가하려면 아래 사전 요구사항을 참조하세요.

모든 클러스터#

GitLab에 클러스터를 추가하려면 다음이 필요합니다:

• GitLab.com 또는 GitLab Self-Managed 인스턴스의 계정.

• 그룹 수준 및 프로젝트 수준 클러스터에 대한 Maintainer 권한.

• 인스턴스 수준 클러스터에 대한 관리자 영역 접근.

• Kubernetes 클러스터.

• kubectl을 사용한 클러스터에 대한 클러스터 관리 접근.

EKS, GKE, 온프레미스 및 다른 공급자에서 클러스터를 호스팅할 수 있습니다. 온프레미스 및 다른 공급자에서 호스팅하려면 EKS 또는 GKE 방법을 사용하여 안내받고 클러스터 설정을 수동으로 입력합니다.

EKS 클러스터#

기존 EKS 클러스터를 추가하려면 다음이 필요합니다:

• 워커 노드가 제대로 구성된 Amazon EKS 클러스터.

• EKS 클러스터 접근을 위해 설치 및 구성된 kubectl.

• 계정의 토큰이 클러스터에 대한 관리자 권한을 가지고 있는지 확인합니다.

GKE 클러스터#

기존 GKE 클러스터를 추가하려면 다음이 필요합니다:

• 클러스터 역할 바인딩을 만들기 위한 container.clusterRoleBindings.create 권한. 접근 권한을 부여하려면 Google Cloud 문서를 따를 수 있습니다.

기존 클러스터를 추가하는 방법#

프로젝트, 그룹 또는 인스턴스에 Kubernetes 클러스터를 추가하려면:

• 다음으로 이동합니다:

  프로젝트 수준 클러스터의 경우 프로젝트의 운영 > Kubernetes 클러스터 페이지.

  • 그룹 수준 클러스터의 경우 그룹의 Kubernetes 페이지.

  • 인스턴스 수준 클러스터의 경우 관리자 영역의 Kubernetes 페이지.

• Kubernetes 클러스터 페이지의 액션 드롭다운 목록에서 인증서로 연결 옵션을 선택합니다.

• 클러스터 연결 페이지에서 세부 정보를 입력합니다:

  Kubernetes 클러스터 이름(필수) - 클러스터에 지정할 이름.

  • 환경 범위(필수) - 이 클러스터의 연결된 환경.

  • API URL(필수) - GitLab이 Kubernetes API에 접근하는 데 사용하는 URL. Kubernetes는 여러 API를 노출합니다. 모든 API에 공통된 "기본" URL을 사용합니다. 예를 들어 https://kubernetes.example.com/api/v1이 아닌 https://kubernetes.example.com.

    다음 명령을 실행하여 API URL을 가져옵니다:

kubectl cluster-info | grep -E 'Kubernetes master|Kubernetes control plane' | awk '/http/ {print $NF}'

• CA 인증서(필수) - 클러스터에 인증하려면 유효한 Kubernetes 인증서가 필요합니다. 기본으로 만들어진 인증서를 사용합니다.

  kubectl get secrets로 시크릿을 나열하면 default-token-xxxxx와 유사한 이름이 있어야 합니다. 아래에서 사용할 토큰 이름을 복사합니다.

• 다음 명령을 실행하여 인증서를 가져옵니다:

kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode

명령이 전체 인증서 체인을 반환하는 경우 체인 하단의 루트 CA 인증서와 중간 인증서를 복사해야 합니다.
체인 파일의 구조는 다음과 같습니다:

   -----BEGIN MY CERTIFICATE-----
   -----END MY CERTIFICATE-----
   -----BEGIN INTERMEDIATE CERTIFICATE-----
   -----END INTERMEDIATE CERTIFICATE-----
   -----BEGIN INTERMEDIATE CERTIFICATE-----
   -----END INTERMEDIATE CERTIFICATE-----
   -----BEGIN ROOT CERTIFICATE-----
   -----END ROOT CERTIFICATE-----

• 토큰 - GitLab은 특정 namespace로 범위가 지정된 서비스 토큰을 사용하여 Kubernetes에 인증합니다. 사용되는 토큰은 cluster-admin 권한이 있는 서비스 계정에 속해야 합니다. 이 서비스 계정을 만들려면:

  다음 내용으로 gitlab-admin-service-account.yaml 파일을 만듭니다:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: gitlab
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: gitlab-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
  - kind: ServiceAccount
    name: gitlab
    namespace: kube-system

• 서비스 계정 및 클러스터 역할 바인딩을 클러스터에 적용합니다:

kubectl apply -f gitlab-admin-service-account.yaml

클러스터 수준 역할을 만들려면 `container.clusterRoleBindings.create` 권한이 필요합니다. 이 권한이 없는 경우
기본 인증을 활성화한 다음 관리자로 `kubectl apply` 명령을 실행할 수 있습니다:

kubectl apply -f gitlab-admin-service-account.yaml --username=admin --password=<password>

> [!note]
> Google Cloud Console을 사용하여 기본 인증을 켜고 비밀번호 자격 증명을 얻을 수 있습니다.

출력:

serviceaccount "gitlab" created
clusterrolebinding "gitlab-admin" created

• gitlab 서비스 계정의 토큰을 검색합니다:

kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab | awk '{print $1}')

출력에서 `<authentication_token>` 값을 복사합니다:

Name:         gitlab-token-b5zv4
Namespace:    kube-system
Labels:       <none>
Annotations:  kubernetes.io/service-account.name=gitlab
             kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8

Type:  kubernetes.io/service-account-token

Data
====
ca.crt:     1025 bytes
namespace:  11 bytes
token:      <authentication_token>

• GitLab 관리 클러스터 - GitLab이 이 클러스터의 네임스페이스와 서비스 계정을 관리하려면 이 옵션을 선택된 상태로 두세요. 자세한 내용은 관리 클러스터 섹션을 참조하세요.

• 프로젝트 네임스페이스(선택 사항) - 이것을 입력할 필요는 없습니다. 비워두면 GitLab이 자동으로 만듭니다. 또한:

  각 프로젝트는 고유한 네임스페이스를 가져야 합니다.

  • default와 같이 더 넓은 권한이 있는 시크릿을 사용하는 경우 프로젝트 네임스페이스는 반드시 시크릿의 네임스페이스와 같을 필요는 없습니다.

  • 프로젝트 네임스페이스로 default를 사용하면 안 됩니다.

  • 귀하 또는 다른 사람이 일반적으로 제한된 권한으로 프로젝트를 위해 특별히 시크릿을 만든 경우 시크릿의 네임스페이스와 프로젝트 네임스페이스가 같을 수 있습니다.

• Kubernetes 클러스터 추가 버튼을 선택합니다.

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

역할 기반 접근 제어(RBAC) 비활성화 (선택 사항)#

GitLab 통합을 통해 클러스터를 연결할 때 클러스터가 RBAC 활성화 여부를 지정할 수 있습니다. 이는 GitLab이 특정 작업에서 클러스터와 상호 작용하는 방식에 영향을 미칩니다. 만들 시점에 RBAC 활성화 클러스터 체크박스를 선택하지 않은 경우 GitLab은 클러스터와 상호 작용할 때 클러스터에 RBAC가 비활성화된 것으로 가정합니다. 그렇다면 통합이 제대로 작동하려면 클러스터에서 RBAC를 비활성화해야 합니다.

RBAC를 효과적으로 비활성화하려면 전체 접근 권한을 부여하는 전역 권한을 적용할 수 있습니다:

kubectl create clusterrolebinding permissive-binding \
  --clusterrole=cluster-admin \
  --user=admin \
  --user=kubelet \
  --group=system:serviceaccounts

문제 해결#

인증 중 CA 인증서 및 토큰 오류#

Kubernetes 클러스터를 연결하는 동안 이 오류가 발생하는 경우:

There was a problem authenticating with your cluster.
Please ensure your CA Certificate and Token are valid

서비스 토큰을 올바르게 붙여넣고 있는지 확인합니다. 일부 셸은 서비스 토큰에 줄 바꿈을 추가하여 유효하지 않게 만들 수 있습니다. 토큰을 편집기에 붙여넣고 추가 공백을 제거하여 줄 바꿈이 없는지 확인합니다.

인증서가 유효하지 않은 경우에도 이 오류가 발생할 수 있습니다. 인증서의 주체 대체 이름이 클러스터 API에 대한 올바른 도메인을 포함하고 있는지 확인하려면 다음 명령을 실행합니다:

echo | openssl s_client -showcerts -connect kubernetes.example.com:443 -servername kubernetes.example.com 2>/dev/null |
openssl x509 -inform pem -noout -text

-connect 인수는 host:port 조합을 예상합니다. 예를 들어 https://kubernetes.example.com은 kubernetes.example.com:443이 됩니다. -servername 인수는 URI 없이 도메인을 예상합니다. 예를 들어 kubernetes.example.com.