Kubernetes 클러스터에서 GitLab CI/CD 사용하기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

GitLab CI/CD를 사용하여 Kubernetes 클러스터를 안전하게 연결, 배포, 및 업데이트할 수 있습니다.

이를 위해, 클러스터에 에이전트를 설치합니다. 그러면 Kubernetes 컨텍스트가 생기고, GitLab CI/CD 파이프라인에서 Kubernetes API 명령을 실행할 수 있습니다.

클러스터 접근이 안전하게 보장하려면:

  • 각 에이전트는 별도의 컨텍스트(kubecontext)를 갖습니다.
  • 에이전트가 구성된 프로젝트와 추가로 승인한 프로젝트만 클러스터의 에이전트에 접근할 수 있습니다.

GitLab CI/CD를 사용하여 클러스터와 상호 작용하려면, 러너가 GitLab에 등록되어야 합니다. 그러나 이러한 러너들은 에이전트가 있는 클러스터에 있을 필요는 없습니다.

클러스터와 함께 GitLab CI/CD 사용하기

GitLab CI/CD로 Kubernetes 클러스터를 업데이트하려면:

  1. 작동하는 Kubernetes 클러스터가 있고 Manifests가 GitLab 프로젝트에 있다는 것을 확인합니다.
  2. 동일한 GitLab 프로젝트에서 GitLab 에이전트를 등록하고 설치합니다.
  3. .gitlab-ci.yml 파일을 업데이트하여 에이전트의 Kubernetes 컨텍스트를 선택하고 Kubernetes API 명령을 실행합니다.
  4. 파이프라인을 실행하여 클러스터에 배포하거나 업데이트합니다.

만약 Kubernetes Manifests를 포함하는 여러 GitLab 프로젝트가 있다면:

  1. 각각의 프로젝트에 GitLab 에이전트를 설치하거나 Kubernetes Manifests를 유지하는 GitLab 프로젝트 중 하나에 설치합니다.
  2. 에이전트에 승인을 부여하여 GitLab 프로젝트에 액세스합니다.
  3. 선택 사항. 추가 보안을 위해 가장자리를 사용.
  4. .gitlab-ci.yml 파일을 업데이트하여 에이전트의 Kubernetes 컨텍스트를 선택하고 Kubernetes API 명령을 실행합니다.
  5. 파이프라인을 실행하여 클러스터에 배포하거나 업데이트합니다.

에이전트에 승인

여러 GitLab 프로젝트가 있는 경우, 프로젝트에서 Kubernetes Manifests를 보관하는 경우 에이전트에 액세스 권한을 부여해야 합니다. 개별 프로젝트에 에이전트를 승인하거나 그룹 또는 서브그룹에 에이전트를 승인할 수 있습니다. 추가 보안을 위해 가장자리 사용할 수도 있습니다.

승인 구성은 1분 또는 2분이 소요될 수 있습니다.

에이전트를 프로젝트에 액세스하도록 승인

Kubernetes Manifests를 보관하는 GitLab 프로젝트를 선택하고 왼쪽 사이드바에서 검색 또는 이동을 선택합니다. config.yaml 파일을 편집합니다. ci_access 키워드 아래에 projects 속성을 추가합니다. id에 프로젝트의 경로를 추가합니다. 

   ci_access:
     projects:
       - id: 경로/프로젝트
  • 승인된 프로젝트는 에이전트의 구성 프로젝트와 동일한 루트 그룹 또는 사용자 네임스페이스를 가져야 합니다.
  • 추가 계층을 수용하기 위해 동일한 클러스터에 추가적인 에이전트를 설치할 수 있습니다.
  • 최대 500개의 프로젝트를 승인할 수 있습니다.

모든 CI/CD 잡은 이제 공유된 에이전트 연결의 컨텍스트를 갖는 kubeconfig 파일이 포함됩니다. $KUBECONFIG 환경 변수에서 kubeconfig 경로를 사용할 수 있습니다. CI/CD 스크립트에서 kubectl 명령을 실행할 컨텍스트를 선택하십시오.

그룹 내 프로젝트에 액세스하도록 에이전트에 승인

그룹이나 서브그룹에 있는 모든 GitLab 프로젝트에 에이전트에 액세스할 수 있도록 승인하려면:

  1. Kubernetes Manifests를 포함하는 GitLab 프로젝트를 선택하고 왼쪽 사이드바에서 검색 또는 이동을 선택합니다.
  2. config.yaml 파일을 편집합니다. ci_access 키워드 아래에 groups 속성을 추가합니다.

  3. id에 경로를 추가합니다: 

    ci_access:
  groups:
    - id: 경로/그룹/서브그룹
    • 승인된 그룹은 에이전트의 구성 프로젝트와 동일한 루트 그룹을 가져야 합니다.
    • 추가 계층을 수용하기 위해 동일한 클러스터에 추가적인 에이전트를 설치할 수 있습니다.
    • 승인된 그룹의 모든 서브그룹에도 별도로 지정하지 않고 동일한 에이전트에 액세스할 수 있습니다.
    • 최대 500개의 그룹을 승인할 수 있습니다.

지금 그룹에 속한 모든 프로젝트와 서브그룹이 이제 에이전트에 액세스할 수 있습니다. 모든 CI/CD 잡은 이제 공유된 에이전트 연결의 컨텍스트를 갖는 kubeconfig 파일이 포함됩니다. $KUBECONFIG 환경 변수에서 kubeconfig 경로를 사용할 수 있습니다. CI/CD 스크립트에서 kubectl 명령을 실행할 컨텍스트를 선택하십시오.

.gitlab-ci.yml 파일을 업데이트하여 kubectl 명령어 실행

Kubernetes 명령을 실행하려는 프로젝트에서 프로젝트의 .gitlab-ci.yml 파일을 편집합니다.

script 키워드 아래의 첫 번째 명령어에서 에이전트의 컨텍스트를 설정합니다. <path/to/agent/project>:<agent-name> 형식을 사용합니다. 예를 들어: 

deploy:
  image:
    name: bitnami/kubectl:latest
    entrypoint: ['']
  script:
    - kubectl config get-contexts
    - kubectl config use-context path/to/agent/project:agent-name
    - kubectl get pods

에이후트의 컨텍스트가 무엇인지 확실하지 않은 경우, 터미널을 열고 클러스터에 연결하십시오. kubectl config get-contexts를 실행하십시오.

Auto DevOps를 사용하는 환경

Auto DevOps가 활성화된 경우, CI/CD 변수 KUBE_CONTEXT를 정의해야 합니다. KUBE_CONTEXT의 값을 Auto DevOps가 사용하길 원하는 에이전트의 컨텍스트로 설정하십시오: 

deploy:
  variables:
    KUBE_CONTEXT: path/to/agent/project:agent-name

서로 다른 에이전트를 별도의 Auto DevOps 잡에 할당할 수 있습니다. 예를 들어, Auto DevOps는 staging 잡에 하나의 에이전트를 사용하고, production 잡에 다른 에이전트를 사용할 수 있습니다. 여러 에이전트를 사용하려면, 환경에 맞게 제한된 CI/CD 변수를 정의하십시오. 예를 들어:

  1. KUBE_CONTEXT라는 두 개의 변수를 정의하십시오.
  2. 첫 번째 변수에 대해:
    1. 환경을 staging으로 설정하십시오.
    2. 스테이징 에이전트의 컨텍스트를 값에 설정하십시오.
  3. 두 번째 변수에 대해:
    1. 환경을 production으로 설정하십시오.
    2. 프로덕션 에이전트의 컨텍스트를 값에 설정하십시오.

인증서 기반 및 에이전트 기반 연결을 사용하는 환경

인증서 기반 클러스터(미지원)와 에이전트 연결이 모두 있는 환경에 배포하려면:

  • 인증서 기반 클러스터의 컨텍스트는 항상 gitlab-deploy로 선택됩니다.
  • 에이전트 컨텍스트는 $KUBECONFIG에 포함됩니다. kubectl config use-context <path/to/agent/project>:<agent-name>을 사용하여 선택할 수 있습니다.

인증서 기반 연결이 있는 환경에 에이전트 연결을 사용하는 경우, 새로운 kubectl 구성 컨텍스트를 매뉴얼으로 구성할 수 있습니다. 예를 들어: 

deploy:
  variables:
    KUBE_CONTEXT: my-context # 새 컨텍스트에 사용할 이름
    AGENT_ID: 1234 # 에이전트의 숫자 ID로 대체
    K8S_PROXY_URL: https://<KAS_DOMAIN>/k8s-proxy/ # Kubernetes 클러스터에 배포된 에이전트 서버 (KAS)에 대한 URL(예: gitlab.com의 경우 kas.gitlab.com); 사용하는 URL로 대체
    # K8S_PROXY_URL: https://<GITLAB_DOMAIN>/-/kubernetes-agent/k8s-proxy/ # 옴니버스에서 에이전트 서버 (KAS)를 사용하는 경우
    # ... 구성한 다른 변수
  before_script:
    - kubectl config set-credentials agent:$AGENT_ID --token="ci:${AGENT_ID}:${CI_JOB_TOKEN}"
    - kubectl config set-cluster gitlab --server="${K8S_PROXY_URL}"
    - kubectl config set-context "$KUBE_CONTEXT" --cluster=gitlab --user="agent:${AGENT_ID}"
    - kubectl config use-context "$KUBE_CONTEXT"
  # ... 잡 구성의 나머지 부분

KAS를 사용하는 환경에서 자체 서명된 인증서를 사용하는 경우

KAS를 사용하는 환경에서 자체 서명된 인증서를 사용한다면, 본인이 서명한 인증서를 신뢰할 수 있도록 Kubernetes 클라이언트를 구성해야 합니다.

클라이언트를 구성하려면 다음 중 하나를 수행하세요:

  • KAS 인증서를 PEM 형식으로 가진 CI/CD 변수 ‘SSL_CERT_FILE’을 설정합니다.
  • Kubernetes 클라이언트를 ‘–certificate-authority=$KAS_CERTIFICATE’와 같이 구성합니다. 여기서 ‘KAS_CERTIFICATE’는 KAS의 CA 인증서가 있는 CI/CD 변수입니다.
  • 작업 컨테이너 내에 적절한 위치에 인증서를 배치하고, 컨테이너 이미지를 업데이트하거나 러너를 통해 마운트합니다.
  • 권장되지 않습니다. Kubernetes 클라이언트를 ‘–insecure-skip-tls-verify=true’와 같이 구성합니다.

인증티켓을 사용하여 프로젝트 및 그룹 접근 제한

Tier: Premium, Ultimate Offering: GitLab.com, 온프레미스, GitLab Dedicated
  • GitLab 15.5에서 변경되어 환경 티어에 대한 인증티켓 지원이 추가되었습니다.

기본적으로 CI/CD 작업은 클러스터에 에이전트를 설치하는 데 사용된 서비스 계정으로부터 모든 권한을 상속받습니다. 클러스터 액세스를 제한하려면 인증티켓을 사용할 수 있습니다.

인증티켓을 지정하려면 에이전트 구성 파일의 ‘access_as’ 속성을 사용하고, Kubernetes RBAC 규칙을 사용하여 인증된 계정 권한을 관리하세요.

다음을 인증할 수 있습니다:

  • 에이전트 자체(기본값).
  • 클러스터에 액세스하는 CI/CD 작업.
  • 클러스터 내에서 정의된 특정 사용자 또는 시스템 계정.

권한 설정이 전파되기까지 1~2분이 걸릴 수 있습니다.

에이전트를 인증티켓으로 사용

기본적으로 에이전트는 별도의 조치 없이 인증티켓을 사용합니다.

클러스터에 액세스하는 CI/CD 작업을 인증티켓으로 사용

‘access_as’ 키 아래에 ‘ci_job: {}’ 키-값을 추가하여 클러스터에 액세스하는 CI/CD 작업을 인증티켓으로 사용하세요.

에이전트가 실제 Kubernetes API에 요청을 보낼 때 인증된 사용자 정보가 다음과 같이 설정됩니다:

  • ‘UserName’이 ‘gitlab:ci_job:'로 설정됩니다. 예: `gitlab:ci_job:1074499489`.

  • ‘Groups’는 다음과 같이 설정됩니다:

    • CI 작업으로부터 오는 모든 요청을 식별하기 위한 ‘gitlab:ci_job’.
    • 프로젝트가 속한 그룹 ID 디렉터리.
    • 프로젝트 ID.

    • 이 작업이 속한 환경의 슬러그 및 티어.

      예: group1/group1-1/project1에서 실행되는 CI 작업의 경우:

      • 그룹 group1의 ID는 23입니다.
      • 그룹 group1/group1-1의 ID는 25입니다.
      • 프로젝트 group1/group1-1/project1의 ID는 150입니다.
      • ‘production’ 환경 티어를 가진 prod 환경에서 실행되는 CI 작업의 경우.

    그룹 디렉터리은 [gitlab:ci_job, gitlab:group:23, gitlab:group_env_tier:23:production, gitlab:group:25, gitlab:group_env_tier:25:production, gitlab:project:150, gitlab:project_env:150:prod, gitlab:project_env_tier:150:production]와 같습니다.

  • ‘Extra’에는 요청에 대한 추가 정보가 포함됩니다. 인증된 ID에 다음 속성이 설정됩니다:
속성 설명
agent.gitlab.com/id 에이전트 ID
agent.gitlab.com/config_project_id 에이전트의 구성 프로젝트 ID
agent.gitlab.com/project_id CI 프로젝트 ID
agent.gitlab.com/ci_pipeline_id CI 파이프라인 ID
agent.gitlab.com/ci_job_id CI 작업 ID
agent.gitlab.com/username CI 작업을 실행하는 사용자명
agent.gitlab.com/environment_slug 환경의 슬러그 (환경에서 실행 중인 경우에만 설정)
agent.gitlab.com/environment_tier 환경의 티어 (환경에서 실행 중인 경우에만 설정)

CI/CD 작업의 ID별로 액세스를 제한하기 위한 config.yaml 예시: 

ci_access:
  projects:
    - id: path/to/project
      access_as:
        ci_job: {}

CI/CD 작업 제한을 위한 예시 RBAC

다음 RoleBinding 리소스는 모든 CI/CD 작업을 조회 권한으로 제한합니다. 

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ci-job-view
roleRef:
  name: view
  kind: ClusterRole
  apiGroup: rbac.authorization.k8s.io
subjects:
  - name: gitlab:ci_job
    kind: Group

정적 신분을 인증티켓으로 사용

특정 연결을 위해 인증티켓에 정적 신분을 사용할 수 있습니다.

‘access_as’ 키 아래에 ‘impersonate’ 키를 추가하여 제공된 신분을 사용하여 요청을 만듭니다.

다음 키로 신분을 지정할 수 있습니다:

  • username (필수)
  • uid
  • groups
  • extra

세부 내용은 공식 Kubernetes 문서를 참조하세요.

특정 환경에 대한 프로젝트 및 그룹 액세스 제한

Tier: Free, Premium, Ultimate Offering: GitLab.com, 온프레미스, GitLab Dedicated
  • GitLab 15.7에 도입되었습니다.

기본적으로, 에이전트가 프로젝트에 사용 가능하면 프로젝트의 모든 CI/CD 작업이 해당 에이전트를 사용할 수 있습니다.

에이전트에 대한 액세스를 특정 환경을 갖는 작업에만 허용하려면 ‘ci_access.projects’ 또는 ‘ci_access.groups’에 ‘environments’를 추가하세요. 예를 들면: 

  ci_access:
    projects:
      - id: path/to/project-1
      - id: path/to/project-2
        environments:
          - staging
          - review/*
    groups:
      - id: path/to/group-1
        environments:
          - production

이 예제에서:

  • ‘project-1’의 모든 CI/CD 작업이 에이전트에 액세스할 수 있습니다.
  • ‘project-2’의 staging 또는 review/* 환경에 속하는 CI/CD 작업만 에이전트에 액세스할 수 있습니다.
    • ‘*‘는 와일드카드로, ‘review’ 아래의 모든 환경과 일치합니다.
  • ‘group-1’에 속한 프로젝트의 production 환경에 대한 CI/CD 작업만 에이전트에 액세스할 수 있습니다.

관련 주제

문제 해결

~/.kube/cache에 쓰기 권한 부여

kubectl, Helm, kpt, kustomize 등의 도구는 클러스터에 관한 정보를 ~/.kube/cache에 캐시합니다. 이 디렉터리가 쓰기 가능하지 않으면 도구는 각 호출마다 정보를 가져와서 상호작용이 느려지고 클러스터에 불필요한 부하가 생깁니다. 최상의 경험을 위해, ‘.gitlab-ci.yml’ 파일에서 사용하는 이미지에서 이 디렉터리가 쓰기 가능하도록 해야 합니다.

TLS 활성화

Self-Managed형 GitLab 인스턴스를 사용하는 경우, 인스턴스가 Transport Layer Security (TLS)로 구성되었는지 확인하세요.

TLS 없이 kubectl을 사용하려고 시도하면 다음과 같은 오류가 발생할 수 있습니다. 

$ kubectl get pods
error: You must be logged in to the server (the server has asked for the client to provide credentials)

서버에 연결할 수 없음: 알 수 없는 권한이 서명한 인증서

KAS 및 자체 서명된 인증서 환경을 사용하는 경우, kubectl 호출 시 다음 오류가 발생할 수 있습니다. 

kubectl get pods
서버에 연결할 수 없음: x509: certificate signed by unknown authority

이 오류는 작업이 KAS 인증서를 서명한 인증 기관 (CA)를 신뢰하지 않기 때문에 발생합니다.

문제를 해결하려면, kubectl을 CA를 신뢰하도록 구성하세요.

유효성 검사 오류

kubectl 버전 v1.27.0 또는 v.1.27.1을 사용하는 경우, 다음과 같은 오류가 발생할 수 있습니다. 

error: error validating "file.yml": error validating data: the server responded with the status code 426 but did not return more information; if you choose to ignore these errors, turn validation off with --validate=false

이 문제는 kubectl 및 공유 Kubernetes 라이브러리를 사용하는 다른 도구들과 관련된 버그로 인해 발생합니다.

문제를 해결하려면, 다른 버전의 kubectl을 사용하세요.