기존 클러스터를 클러스터 인증서를 통해 연결(사용 중단됨)

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed
caution
이 기능은 GitLab 14.5에서 사용 중단되었습니다. GitLab에 클러스터를 연결하려면 GitLab 에이전트 을(를) 대신 사용하세요.

기존의 Kubernetes 클러스터가 있는 경우, 해당 클러스터를 프로젝트, 그룹 또는 인스턴스에 추가하여 GitLab과 통합의 이점을 누릴 수 있습니다.

사전 요구 사항

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

모든 클러스터

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

  • GitLab.com 계정 또는 온프레미스 설치용 계정
  • 그룹수준 및 프로젝트수준 클러스터에 대한 유지자 역할
  • 인스턴스수준 클러스터에 대한 Admin Area 액세스
  • Kubernetes 클러스터
  • kubectl을 사용하여 클러스터에 대한 클러스터 관리 액세스

EKS, GKE, 온프레미스 및 다른 제공업체에서 클러스터를 호스트할 수 있습니다. 온프레미스 및 다른 제공업체에 클러스터를 호스트하려면 EKS 또는 GKE 방법 중 하나를 사용하여 지침을 따라 클러스터 설정을 매뉴얼으로 입력하세요.

caution
GitLab은 arm64 클러스터를 지원하지 않습니다. 자세한 내용은 이슈 Helm Tiller fails to install on arm64 cluster를 참조하세요.

EKS 클러스터

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

  • 적절하게 구성된 Amazon EKS 클러스터의 워커 노드
  • EKS 클러스터에 액세스하기 위해 kubectl이 설치 및 구성되어 있어야 합니다.
  • 클러스터에 대한 관리자 권한을 가진 계정의 토큰을 확인하세요.

GKE 클러스터

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

  • 클러스터 롤 바인딩을 생성할 container.clusterRoleBindings.create 권한이 필요합니다. Google Cloud 문서를 참조하여 액세스를 부여하세요.

기존 클러스터 추가하기

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

  1. 다음 중 하나로 이동하세요:
    1. 프로젝트의 운영 > Kubernetes 클러스터 페이지(프로젝트수준 클러스터)
    2. 그룹의 Kubernetes 페이지(그룹수준 클러스터)
    3. Admin Area의 Kubernetes 페이지(인스턴스수준 클러스터)
  2. Kubernetes 클러스터 페이지에서 동작 드롭다운 디렉터리에서 인증서로 연결 옵션을 선택합니다.
  3. 클러스터 연결 페이지에서 다음 정보를 입력합니다:
    1. Kubernetes 클러스터 이름 (필수) - 클러스터에 지정하고자 하는 이름입니다.
    2. 환경 범위 (필수) - 이 클러스터에 연결된 환경입니다.

    3. 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}'
    4. CA 인증서 (필수) - Kubernetes 클러스터에 인증하기 위해 유효한 Kubernetes 인증서가 필요합니다. 우리는 기본적으로 생성된 인증서를 사용합니다.
      1. kubectl get secrets로 시크릿을 나열하고, 하나는 default-token-xxxxx와 유사한 이름일 것입니다. 이 이름을 아래 사용하기 위해 복사하세요.

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

        kubectl get secret <시크릿 이름> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode

        명령이 전체 인증서 체인을 반환하면, 체인의 하단에 Root 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-----
    5. 토큰 - GitLab은 Kubernetes에 서비스 토큰을 사용하여 인증하며, 이 토큰은 특정 namespace에 한정됩니다. 사용되는 토큰은 cluster-admin 권한을 가진 서비스 계정에 속해야 합니다. 이 서비스 계정을 만들려면:

      1. 다음 내용의 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

      2. 서비스 계정 및 클러스터 롤 바인딩을 클러스터에 적용하세요: 

        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

      3. 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>
    6. GitLab 관리 클러스터 - 이 옵션을 선택하여 GitLab이 이 클러스터의 네임스페이스와 서비스 계정을 관리하도록 합니다. 자세한 내용은 관리형 클러스터 섹션을 참조하세요.
    7. 프로젝트 네임스페이스 (선택 사항) - 이 부분은 채우지 않아도 됩니다. 비워 두면 GitLab이 대신 생성합니다. 또한 다음 사항도 있습니다:
      • 각 프로젝트는 고유한 네임스페이스를 가져야 합니다.
      • 프로젝트 네임스페이스는 당신이 default와 같은 더 많은 권한을 가진 시크릿과 같은 넓은 권한을 가진 시크릿을 사용하는 경우에는 시크릿의 네임스페이스와 일치하지 않을 수 있습니다.
      • 프로젝트의 네임스페이스는 시크릿의 네임스페이스가 아닐 수도 있습니다.
      • 만약 프로젝트를 위해 특정하게 시크릿을 만들거나 누군가 만들었다면, 보통 default와 같은 한정된 권한을 가진 시크릿을 사용하는 경우, 시크릿의 네임스페이스와 프로젝트의 네임스페이스는 동일할 것입니다.
  4. Kubernetes 클러스터 추가 버튼을 선택합니다.

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

역할 기반 액세스 제어 (RBAC) 비활성화 (옵션)

GitLab 통합을 통해 클러스터를 연결할 때 클러스터가 RBAC(역할 기반 액세스 제어)를 사용하는지 여부를 지정할 수 있습니다. 이는 GitLab이 클러스터와 상호 작용하는 방식에 영향을 줍니다. 생성 시 RBAC가 활성화된 클러스터 확인란을 선택하지 않았다면, GitLab은 해당 클러스터와 상호 작용할 때 RBAC가 비활성화되어 있다고 간주합니다. 그렇다면 통합이 정상적으로 작동하려면 클러스터에서 RBAC를 비활성화해야 합니다.

RBAC

caution
RBAC를 비활성화하는 것은 클러스터에서 실행 중인 모든 애플리케이션 또는 클러스터에 인증할 수 있는 사용자가 전체 API 액세스 권한을 갖는다는 것을 의미합니다. 이는 보안 문제가 있을 수 있으며 원하는 바가 아닐 수 있습니다.

RBAC를 효과적으로 비활성화하기 위해 전체 액세스를 부여하는 전역 권한이 적용될 수 있습니다: 

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

문제 해결

클러스터를 인증하는 데 문제가 있습니다. CA 인증서 및 토큰이 유효한지 확인하십시오

쿠버네티스 클러스터를 연결하는 동안이 오류가 발생하면 서비스 토큰을 올바르게 붙여넣고 있는지 확인하십시오. 일부 셸은 서비스 토큰에 줄 바꿈을 추가하여 이를 무효화할 수 있습니다. 토큰을 편집기에 붙여넣고 추가 공백을 제거하여 줄 바꿈이 없는지 확인하십시오.

또한 인증서가 유효하지 않은 경우에도 이 오류를 경험할 수 있습니다. 클러스터의 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 인수는 호스트:포트 조합을 기대합니다. 예를 들어, https://kubernetes.example.com는 kubernetes.example.com:443가 됩니다. -servername 인수는 URI가 없는 도메인을 기대합니다. 예를 들어 kubernetes.example.com.