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

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 14.1에 도입되었습니다.
  • 사전 구성된 변수 $KUBECONFIG은 GitLab 14.2에서 도입되었습니다.
  • ‘ci_access’ 속성이 GitLab 14.3에서 도입되었습니다.
  • 그룹을 승인하는 기능은 GitLab 14.3에서 도입되었습니다.
  • 14.5버전에서 GitLab Free으로 이전되었습니다.
  • 리눅스 패키지 설치 지원은 GitLab 14.5에서 도입되었습니다.
  • 인증서 기반의 클러스터와 에이전트 간 전환 기능은 GitLab 14.9에서 도입되었습니다. 인증서 기반 클러스터 컨텍스트는 항상 gitlab-deploy로 불립니다.
  • ‘CI/CD 터널’은 GitLab 14.9에서 ‘CI/CD workflow’로 이름이 변경되었습니다.

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분이 소요될 수 있습니다.

프로젝트에 에이전트 승인하기

  • GitLab 14.4에서 도입되었습니다.
  • 계층 제한을 제거하도록 GitLab 15.6이 변경되었습니다.
  • 사용자 네임스페이스 내의 프로젝트를 승인할 수 있도록 GitLab 15.7이 변경되었습니다.

Kubernetes 매니페스트를 보관하는 GitLab 프로젝트에 에이전트를 승인하기 위해서:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하여 에이전트 구성 파일(config.yaml)이 있는 프로젝트를 찾습니다.
  2. config.yaml 파일을 수정합니다. ci_access 키워드 아래에 projects 속성을 추가하세요.

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

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

이제 모든 CI/CD 작업에는 모든 공유된 에이전트 연결에 대한 컨텍스트를 포함한 kubeconfig 파일이 포함됩니다. 환경 변수 $KUBECONFIG에서 kubeconfig 경로를 확인하세요. CI/CD 스크립트에서 실행할 컨텍스트를 선택하세요.

에이전트에게 그룹 내 프로젝트 접근 권한 부여

  • 소개됨 GitLab 14.3에서.
  • 계층 제한을 제거하기 위해 변경되어 GitLab 15.6에서.

그룹 또는 하위 그룹의 GitLab 프로젝트에 대한 에이전트 액세스 권한을 부여하려면 다음을 수행합니다.

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

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

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

그룹 및 해당 하위 그룹에 속한 모든 프로젝트는 이제 에이전트에 액세스할 수 있습니다. 모든 CI/CD 작업에는 이제 모든 공유 에이전트 연결에 대한 컨텍스트가 포함된 kubeconfig 파일이 포함됩니다. kubeconfig 경로는 환경 변수 $KUBECONFIG에서 사용할 수 있습니다. CI/CD 스크립트에서 실행할 콘텍스트를 선택합니다.

.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는 스테이징 작업에는 한 에이전트를 사용하고 프로덕션 작업에는 다른 에이전트를 사용할 수 있습니다. 여러 에이전트를 사용하려면 환경 범위 CI/CD 변수를 각 에이전트에 정의합니다. 예:

  1. KUBE_CONTEXT라는 두 개의 변수를 정의합니다.
  2. 첫 번째 변수에 대해:
    1. environment를 스테이징으로 설정합니다.
    2. 값은 스테이징 에이전트의 콘텍스트로 설정합니다.
  3. 두 번째 변수에 대해:
    1. environment를 프로덕션으로 설정합니다.
    2. 값은 프로덕션 에이전트의 콘텍스트로 설정합니다.

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

인증 기반 클러스터(폐기 예정)와 에이전트 연결이 모두 있는 환경으로 배포하는 경우:

  • 인증 기반 클러스터의 콘텍스트는 항상 기본적으로 gitlab-deploy로 선택됩니다.
  • GitLab 14.9 이상에서 에이전트 콘텍스트가 $KUBECONFIG에 포함됩니다. kubectl config use-context <path/to/agent/project>:<agent-name>을 사용하여 선택할 수 있습니다.
  • GitLab 14.8 이하에서는 에이전트 연결을 계속 사용할 수 있지만, 이미 인증 기반 클러스터가 있는 환경에 대해 에이전트 연결은 $KUBECONFIG에 포함되지 않습니다.

인증 기반 연결이 있는 환경에서 에이전트 연결을 사용하려면 새로운 kubectl 구성 콘텍스트를 수동으로 구성할 수 있습니다. 예: 

deploy:
  variables:
    KUBE_CONTEXT: my-context # 새로운 콘텍스트에 사용할 이름
    AGENT_ID: 1234 # 귀하의 에이전트의 숫자 ID로 대체
    K8S_PROXY_URL: https://<KAS_DOMAIN>/k8s-proxy/ # Kubernetes 클러스터에 배포된 에이전트 서버(KAS)용(www.gitlab.com의 경우 kas.gitlab.com 사용); 귀하의 URL로 대체
    # K8S_PROXY_URL: https://<GITLAB_DOMAIN>/-/kubernetes-agent/k8s-proxy/ # Omnibus에서 에이전트 서버(KAS)용(www.gitlab.com의 경우 kas.gitlab.com 사용)
    # ... 구성한 기타 변수
  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을 설정합니다.
  • Kubernetes 클라이언트를 --certificate-authority=$KAS_CERTIFICATE로 구성합니다. 여기서 KAS_CERTIFICATE는 KAS의 CA 인증서가 포함된 CI/CD 변수입니다.
  • 작업 컨테이너 내의 적절한 위치에 인증서를 배치하려면 컨테이너 이미지를 업데이트하거나 러너를 통해 마운트합니다.
  • 권장하지 않음. Kubernetes 클라이언트를 --insecure-skip-tls-verify=true로 구성하세요.

사용자 위임을 사용하여 프로젝트 및 그룹 액세스 제한

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

기본적으로 귀하의 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 환경에서 실행되는 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는 요청에 대한 추가 정보를 포함합니다. 다음 속성이 위임된 식별에 설정됩니다:
속성 설명
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: {}

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

정적 ID를 통한 사칭

특정 연결에 대해 사칭을 위해 정적 ID를 사용할 수 있습니다.

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

다음 키로 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 작업은 에이전트에 액세스할 수 있습니다.
  • staging 또는 review/* 환경을 갖는 project-2의 CI/CD 작업은 에이전트에 액세스할 수 있습니다.
    • *은 와일드카드이므로 review/*는 review 하위의 모든 환경과 일치합니다.
  • production 환경을 갖는 group-1의 프로젝트의 CI/CD 작업은 에이전트에 액세스할 수 있습니다.

관련 주제

문제 해결

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

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

TLS 활성화

자체 관리 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
Unable to connect to the server: x509: certificate signed by unknown authority

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

이 문제를 해결하려면 작업이 서명된 CA를 신뢰하도록 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을 사용하세요.