Kubernetes 클러스터는 배포 job의 대상이 될 수 있습니다. 상황별로 다음과 같습니다.

• 클러스터가 GitLab과 통합되어 있으면 job에 전용 배포 변수가 제공되며 별도 구성이 필요하지 않습니다. kubectl 이나 helm 같은 도구를 사용해 job에서 곧바로 클러스터와 상호 작용할 수 있습니다.
• GitLab 클러스터 통합을 사용하지 않더라도 클러스터에 배포할 수 있습니다. 다만 job에서 클러스터와 상호 작용하려면 CI/CD 변수를 사용해 Kubernetes 도구를 직접 구성해야 합니다.

배포 변수#

배포 변수를 사용하려면 Kubernetes가 레지스트리에 접근할 수 있도록 gitlab-deploy-token이라는 이름의 유효한 배포 토큰과 배포 job 스크립트의 다음 명령이 필요합니다.

• Kubernetes 1.18 이상을 사용하는 경우:

  kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run=client | kubectl apply -f -
  

• Kubernetes 1.18 미만을 사용하는 경우:

  kubectl create secret docker-registry gitlab-registry --docker-server="$CI_REGISTRY" --docker-username="$CI_DEPLOY_USER" --docker-password="$CI_DEPLOY_PASSWORD" --docker-email="$GITLAB_USER_EMAIL" -o yaml --dry-run | kubectl apply -f -
  

Kubernetes 클러스터 통합은 GitLab CI/CD 빌드 환경에서 배포 job에 이러한 배포 변수를 노출합니다. 배포 job에는 대상 환경이 정의되어 있습니다.

커스텀 네임스페이스#

Kubernetes 통합은 자동 생성된 네임스페이스가 포함된 KUBECONFIG를 배포 job에 제공합니다. 기본적으로 <prefix>-<environment> 형식의 프로젝트·환경별 네임스페이스를 사용하며, 여기서 <prefix>는 <project_name>-<project_id> 형식입니다. 자세한 내용은 배포 변수를 참고합니다.

배포 네임스페이스는 다음과 같은 방식으로 사용자 정의할 수 있습니다.

• 환경별 네임스페이스와 프로젝트별 네임스페이스 중 하나를 선택할 수 있습니다. 환경별 네임스페이스가 기본값이자 권장 설정이며, 프로덕션 환경과 비프로덕션 환경의 리소스가 섞이는 것을 방지합니다.
• 프로젝트 수준 클러스터를 사용하면 네임스페이스 접두사도 함께 사용자 정의할 수 있습니다. 환경별 네임스페이스를 사용할 때 배포 네임스페이스는 <prefix>-<environment> 이고, 그렇지 않으면 <prefix> 입니다.
• 비관리형 클러스터의 경우 자동 생성된 네임스페이스가 KUBECONFIG에 설정되지만, 해당 네임스페이스가 존재하는지 확인하는 책임은 사용자에게 있습니다. 이 값은 .gitlab-ci.yml의 environment:kubernetes:namespace로 자유롭게 사용자 정의할 수 있습니다.

네임스페이스를 사용자 정의해도 기존 환경은 클러스터 캐시를 지우기 전까지 현재 네임스페이스에 연결된 상태로 남습니다.

자격 증명 보호#

기본적으로 배포 job을 만들 수 있는 사람은 누구나 환경의 배포 job에 있는 모든 CI/CD 변수에 접근할 수 있습니다. 여기에는 클러스터의 연관 서비스 계정이 사용할 수 있는 모든 시크릿에 접근 권한을 주는 KUBECONFIG도 포함됩니다. 프로덕션 자격 증명을 안전하게 유지하려면 보호된 환경과 다음 중 하나를 함께 사용하는 방안을 고려합니다.

• GitLab 관리 클러스터 및 환경별 네임스페이스.
• 보호된 환경별로 범위를 지정한 클러스터. 동일한 클러스터를 제한된 서비스 계정을 여러 개 두어 여러 번 추가할 수 있습니다.

Kubernetes 클러스터용 웹 터미널#

Kubernetes 통합은 환경에 웹 터미널 지원을 추가합니다. 이는 Docker와 Kubernetes의 exec 기능을 기반으로 하므로, 기존 컨테이너에서 새 셸 세션을 사용할 수 있습니다. 이 통합을 사용하려면 이 페이지의 배포 변수를 사용해 Kubernetes에 배포하고, 모든 디플로이먼트·레플리카셋·Pod에 다음 애노테이션이 지정되어 있는지 확인해야 합니다.

• app.gitlab.com/env: $CI_ENVIRONMENT_SLUG
• app.gitlab.com/app: $CI_PROJECT_PATH_SLUG

$CI_ENVIRONMENT_SLUG와 $CI_PROJECT_PATH_SLUG는 CI/CD 변수의 값입니다.

터미널을 사용하려면 프로젝트 소유자이거나 maintainer 권한이 있어야 합니다. 지원 범위는 환경의 첫 번째 Pod에 있는 첫 번째 컨테이너로 제한됩니다.

문제 해결#

배포 job이 시작되기 전에 GitLab은 해당 배포 job을 위해 다음을 생성합니다.

• 네임스페이스.
• 서비스 계정.

그러나 GitLab이 이를 생성하지 못하는 경우도 있습니다. 이럴 때 job은 다음 메시지와 함께 실패할 수 있습니다.

This job failed because the necessary resources were not successfully created.

네임스페이스와 서비스 계정을 생성할 때 발생하는 이 오류의 원인을 찾으려면 로그를 확인합니다.

실패 원인은 다음과 같습니다.

• GitLab에 제공한 토큰에 GitLab이 요구하는 cluster-admin 권한이 없습니다.
• KUBECONFIG 또는 KUBE_TOKEN 배포 변수가 없습니다. 이 변수들이 job에 전달되려면 일치하는 environment:name이 있어야 합니다. job에 environment:name 이 설정되어 있지 않으면 Kubernetes 자격 증명은 전달되지 않습니다.