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

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 클러스터가 있고 매니페스트가 GitLab 프로젝트에 있는지 확인하세요.
  2. 동일한 GitLab 프로젝트에서 GitLab 에이전트를 등록하고 설치하세요.
  3. .gitlab-ci.yml 파일을 업데이트하세요 에이전트의 Kubernetes 컨텍스트를 선택하고 Kubernetes API 명령을 실행합니다.
  4. 파이프라인을 실행하여 클러스터에 배포하거나 업데이트합니다.

여러 개의 GitLab 프로젝트에 Kubernetes 매니페스트가 포함되어 있는 경우:

  1. GitLab 에이전트를 설치하세요 자체 프로젝트에 또는 Kubernetes 매니페스트를 보관하는 GitLab 프로젝트 중 하나에 설치하세요.
  2. 에이전트를 승인하세요 GitLab 프로젝트에 접근할 수 있도록.
  3. 선택 사항. 추가 보안을 위해 가장하는 기능을 사용하세요.
  4. .gitlab-ci.yml 파일을 업데이트하세요 에이전트의 Kubernetes 컨텍스트를 선택하고 Kubernetes API 명령을 실행합니다.
  5. 파이프라인을 실행하여 클러스터에 배포하거나 업데이트합니다.

에이전트 승인하기

여러 GitLab 프로젝트가 있는 경우, Kubernetes 매니페스트를 보관하는 프로젝트에 접근할 수 있도록 에이전트를 승인해야 합니다. 개별 프로젝트에 접근할 수 있도록 에이전트를 승인할 수도 있고 그룹 또는 하위 그룹을 승인하여 모든 프로젝트가 접근할 수 있도록 할 수도 있습니다. 추가 보안을 위해 가장하는 기능을 사용하세요.

승인 구성은 전파되는 데 1~2분이 걸릴 수 있습니다.

프로젝트에 접근할 수 있도록 에이전트 승인하기

Kubernetes 매니페스트를 보관하는 GitLab 프로젝트에 접근할 수 있도록 에이전트를 승인하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 에이전트 구성 파일 (config.yaml)이 포함된 프로젝트를 찾습니다.
  2. config.yaml 파일을 편집합니다. ci_access 키워드 아래에 projects 속성을 추가합니다.

  3. id에 프로젝트 경로를 추가합니다.

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

모든 CI/CD 작업은 이제 모든 공유 에이전트 연결에 대한 컨텍스트가 포함된 kubeconfig 파일을 포함합니다.

kubeconfig 경로는 환경 변수 $KUBECONFIG에서 사용할 수 있습니다.

CI/CD 스크립트에서 kubectl 명령을 실행할 컨텍스트를 선택하세요.

에이전트에게 귀하의 그룹에 있는 프로젝트에 접근할 수 있는 권한 부여

  • GitLab 15.6에서 계층 제한을 제거하기 위한 변경됨.

그룹 또는 하위 그룹의 GitLab 프로젝트에 대한 에이전트의 접근 권한을 부여하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하고 에이전트 구성 파일(config.yaml)이 포함된 프로젝트를 찾습니다.

  2. config.yaml 파일을 편집합니다. ci_access 키워드 아래에 groups 속성을 추가합니다.

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

    ci_access:
  groups:
    - id: path/to/group/subgroup

    • 승인된 그룹은 에이전트의 구성 프로젝트와 동일한 루트 그룹을 가져야 합니다.

    • 추가적인 계층을 수용하기 위해 동일한 클러스터에 추가 에이전트를 설치할 수 있습니다.

    • 승인된 그룹의 모든 하위 그룹은 동일한 에이전트에 대한 접근권한을 가지고 있습니다(개별적으로 지정할 필요 없습니다).

    • 최대 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. environment를 staging으로 설정합니다.
    2. 값을 스테이징 에이전트의 컨텍스트로 설정합니다.
  3. 두 번째 변수에 대해:
    1. environment를 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)(gitlab.com의 경우 kas.gitlab.com); URL로 대체
    # K8S_PROXY_URL: https://<GITLAB_DOMAIN>/-/kubernetes-agent/k8s-proxy/ # Omnibus의 에이전트 서버(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 클라이언트를 구성하여 인증서를 서명한 인증 기관(CA)을 신뢰해야 합니다.

클라이언트를 구성하려면 다음 중 하나를 수행하십시오:

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

임포르세이션을 사용하여 프로젝트 및 그룹 액세스 제한하기

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • 변경됨 GitLab 15.5에서 환경 계층에 대한 임포르세이션 지원을 추가합니다.

기본적으로 CI/CD 작업은 클러스터에 에이전트를 설치하는 데 사용된 서비스 계정의 모든 권한을 상속받습니다.

클러스터에 대한 액세스를 제한하려면 임포르세이션을 사용할 수 있습니다.

임포르세이션을 지정하려면 에이전트 구성 파일에서 access_as 속성을 사용하고 Kubernetes RBAC 규칙을 사용하여 임포르세이션된 계정 권한을 관리합니다.

임포르세이션할 수 있는 항목은 다음과 같습니다:

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

권한 구성은 전파되는 데 1~2분이 걸릴 수 있습니다.

에이전트 임포르세이션

에이전트는 기본적으로 임포르세이션됩니다. 임포르세이션을 위해 아무것도 할 필요가 없습니다.

클러스터에 액세스하는 CI/CD 작업 임포르세이션

클러스터에 액세스하는 CI/CD 작업을 임포르세이션하려면 access_as 키 아래에 ci_job: {} 키-값을 추가합니다.

에이전트가 실제 Kubernetes API에 요청을 할 때, 다음과 같은 방식으로 임포르세이션 자격 증명을 설정합니다:

  • UserName은 gitlab:ci_job:<job id>로 설정됩니다. 예: 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 환경에서 실행 중인 작업입니다.

    그룹 목록은 [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는 요청에 대한 추가 정보를 포함합니다. 임포르세이션된 신원에 대해 다음 속성이 설정됩니다:
속성 설명
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 작업의 신원으로 액세스를 제한하기 위한 예제 config.yaml:

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

예제 RBAC로 CI/CD 작업 제한하기

다음 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

정적 ID로 가장하기

주어진 연결에 대해 정적 ID를 사용하여 가장할 수 있습니다.

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

ID는 다음 키로 지정할 수 있습니다:

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

자세한 내용은 공식 Kubernetes 문서를 참조하십시오.

특정 환경에 대한 프로젝트 및 그룹 접근 제한하기

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

기본적으로 에이전트가 프로젝트에 사용 가능하면 모든 프로젝트의 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 아래의 CI/CD 작업 중 staging 또는 review/* 환경이 있는 경우에만 에이전트에 접근할 수 있습니다.
    • *는 와일드카드로, review/*는 review 아래의 모든 환경과 일치합니다.
  • group-1 아래의 프로젝트에 대한 CI/CD 작업이 production 환경에서 에이전트에 접근할 수 있습니다.

보호된 브랜치에 대한 에이전트 접근 제한하기

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated
  • 도입됨 GitLab 17.3 플래그와 함께 있으며 기본적으로 비활성화되어 있습니다.
이 기능의 사용 가능성은 기능 플래그에 의해 제어됩니다.

자세한 내용은 이력을 참조하십시오.

이 기능은 테스트 용도로 사용할 수 있지만 생산 사용에는 준비되지 않았습니다.

보호된 브랜치에서만 에이전트에 대한 접근을 제한하려면:

  • ci_access.projects 또는 ci_access.groups에 protected_branches_only: true를 추가하십시오. 예를 들면:
ci_access:
  projects:
    - id: path/to/project-1
      protected_branches_only: true
  groups:
    - id: path/to/group-1
      protected_branches_only: true
      environments:
        - production

기본적으로 protected_branches_only는 false로 설정되어 있으며, 에이전트는 보호되지 않은 브랜치와 보호된 브랜치 모두에서 접근할 수 있습니다.

추가 보안을 위해 이 기능을 환경 제한과 결합할 수 있습니다.

프로젝트에 여러 구성 요소가 있는 경우 가장 구체적인 구성만 사용됩니다.

예를 들어, 다음 구성은 example 그룹이 보호된 브랜치에만 접근을 부여하도록 설정되었음에도 불구하고 example/my-project에서 보호되지 않은 브랜치에 접근할 수 있게 만듭니다:

# .gitlab/agents/my-agent/config.yaml
ci_access:
  project:
    - id: example/my-project # 아래 그룹의 프로젝트
      protected_branches_only: false # 이 구성은 그룹 구성을 능가합니다
      environments:
        - dev
  groups:
    - id: example
      protected_branches_only: true
      environments:
        - dev

자세한 내용은 CI에서 Kubernetes 접근를 참조하십시오.

관련 주제

문제 해결

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

kubectl, Helm, kpt, 및 kustomize와 같은 도구들은 클러스터에 대한 정보를 ~/.kube/cache에 캐시합니다. 이 디렉토리에 쓰기 권한이 없다면, 도구는 각 호출 때마다 정보를 가져오게 되어 상호작용이 느려지고 클러스터에 불필요한 부하를 일으킵니다. 최상의 경험을 위해 .gitlab-ci.yml 파일에서 사용하는 이미지에서 이 디렉토리가 쓰기 가능하도록 하세요.

TLS 활성화

자체 관리형 GitLab 인스턴스를 사용하는 경우, 인스턴스가 전송 계층 보안(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
Unable to connect to the server: x509: certificate signed by unknown authority

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

이 문제를 해결하려면 자체 서명 인증서를 사용하는 KAS 환경에 대해 kubectl을 신뢰하도록 구성하세요.

검증 오류

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을 사용하세요.