클러스터와 함께 GitLab CI/CD 사용하기
에이전트 승인하기
- 에이전트가 프로젝트에 액세스하도록 승인하기
- 그룹 내 프로젝트에 액세스하도록 에이전트 승인하기
.gitlab-ci.yml 파일을 업데이트하여 kubectl 명령 실행
위임 사용하여 프로젝트 및 그룹 액세스 제한
프로젝트 및 그룹 액세스를 특정 환경에 제한하기
관련 주제
문제 해결

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

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에서 소개됨.
GitLab 14.5에서 GitLab Free로 이동함.
Linux 패키지 설치 지원은 GitLab 14.5에서 소개됨.
인증서 기반 클러스터 및 에이전트 간 전환 기능은 GitLab 14.9에서 소개됨. 인증서 기반 클러스터 구성은 항상 gitlab-deploy로 지칭됨.
_CI/CD tunnel_이 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 클러스터를 업데이트하려면:

작동하는 Kubernetes 클러스터와 매니페스트가 GitLab 프로젝트에 있는지 확인하세요.
같은 GitLab 프로젝트에서 GitLab 에이전트를 등록하고 설치하세요.
에이전트의 Kubernetes 컨텍스트를 선택하고 Kubernetes API 명령을 실행하기 위해 .gitlab-ci.yml 파일을 업데이트하세요.
파이프라인을 실행하여 클러스터로 배포하거나 업데이트하세요.

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

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

에이전트 승인하기

여러 GitLab 프로젝트가 있다면, 에이전트가 Kubernetes 매니페스트를 보관하는 프로젝트에 대한 액세스를 승인해야 합니다. 개별 프로젝트에 대한 에이전트의 액세스를 승인하거나 그룹 또는 서브그룹을 승인하여 그 안에 있는 모든 프로젝트에 액세스할 수 있도록 설정할 수 있습니다. 추가적인 보안을 위해 가장할 수도 있습니다.

승인 구성은 1~2분 정도의 시간이 소요될 수 있습니다.

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

GitLab 14.4에서 소개됨.
계층 제한을 제거하도록 GitLab 15.6으로 변경되었습니다.
사용자 네임스페이스 내 프로젝트를 승인하는 데 대한 변경은 GitLab 15.7에서 이루어졌습니다.

Kubernetes 매니페스트를 보관하는 GitLab 프로젝트를 선택하고 검색 또는 이동 메뉴에서 왼쪽 사이드바를 선택하세요.

config.yaml 파일에 접속해 편집하세요. ci_access 키워드 아래에 projects 속성을 추가하세요.
id에 프로젝트의 경로를 추가하세요.
```
ci_access:
  projects:
    - id: path/to/project
```
- 승인된 프로젝트는 에이전트의 구성 프로젝트와 동일한 루트 그룹 또는 사용자 네임스페이스를 가져야 합니다.
- 추가 계층을 수용하기 위해 동일한 클러스터에 추가적인 에이전트를 설치할 수 있습니다.
- 최대 100개의 프로젝트를 승인할 수 있습니다.

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

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

GitLab 14.3에서 소개됨.
계층 제한을 제거하도록 GitLab 15.6으로 변경되었습니다.

그룹이나 서브그룹 안에 있는 모든 GitLab 프로젝트에 에이전트가 접근하도록 승인하려면:

좌측 사이드바에서 그룹 내에서 에이전트 구성 파일인 config.yaml을 가지고 있는 GitLab 프로젝트를 선택하세요.

config.yaml 파일에 접속해 편집하세요. ci_access 키워드 아래에 groups 속성을 추가하세요.
id에 경로를 추가하세요.
```
ci_access:
  groups:
    - id: path/to/group/subgroup
```
- 승인된 그룹은 에이전트의 구성 프로젝트와 동일한 루트 그룹을 가져야 합니다.
- 추가 계층을 수용하기 위해 동일한 클러스터에 추가적인 에이전트를 설치할 수 있습니다.
- 승인된 그룹의 모든 서브그룹은 개별적으로 지정하지 않아도 동일한 에이전트에 접근할 수 있습니다.
- 최대 100개의 그룹을 승인할 수 있습니다.

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

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

쿠버네티스 명령을 실행하려는 프로젝트에서 프로젝트의 .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 변수를 정의합니다. 예:

KUBE_CONTEXT라는 두 변수를 정의합니다.
첫 번째 변수에 대해:
1. 환경을 staging으로 설정합니다.
2. 값을 스테이징 에이전트의 컨텍스트로 설정합니다.
두 번째 변수에 대해:
1. 환경을 production으로 설정합니다.
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)의 경우 (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을 설정합니다.
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

GitLab 14.5에 도입됨.
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.
- 이 작업이 속한 환경의 슬러그(slug)와 티어(tier) 디렉터리.
  예: group1/group1-1/project1에서 실행되는 CI 작업인 경우:
  - 그룹 group1의 ID는 23입니다.
  - 그룹 group1/group1-1의 ID는 25입니다.
  - 프로젝트 group1/group1-1/project1의 ID는 150입니다.
  - production 환경을 갖는 프로덕션 환경에 있는 작업의 경우.
그룹 디렉터리은 [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

정적 ID로 위장

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

access_as 키 아래에서 제공된 ID를 사용하여 요청을 수행하기 위해 impersonate 키를 추가하세요.

다음과 같은 키로 ID를 지정할 수 있습니다:

username (필수)
uid
groups
extra

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

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

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, 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 작업은 에이전트에 액세스할 수 있습니다.
staging 또는 review/* 환경을 가진 project-2의 CI/CD 작업은 에이전트에 액세스할 수 있습니다.
- *은 와일드카드이므로 review/*는 review 하위의 모든 환경과 일치합니다.
group-1의 프로젝트의 production 환경을 가진 CI/CD 작업은 에이전트에 액세스할 수 있습니다.

문제 해결

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

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

TLS 활성화

Self-managed 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 호출이 다음과 같은 오류를 반환할 수 있습니다:

kubectl get pods
Unable to connect to the server: 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을 사용하세요.

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

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

에이전트 승인하기

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

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

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

Auto DevOps를 사용하는 환경

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

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

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

에이전트 위임

클러스터에 액세스하는 CI/CD 작업 위임

CI/CD 작업 제한하는 예시 RBAC

정적 ID로 위장

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

관련 주제

문제 해결

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

TLS 활성화

서명되지 않은 기권자가 서명한 인증서로 서버에 연결할 수 없음

유효성 검사 오류

도움말

기능 사용 가능성과 제품 평가판

도움받기

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

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

에이전트 승인하기

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

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

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

Auto DevOps를 사용하는 환경

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

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

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

에이전트 위임

클러스터에 액세스하는 CI/CD 작업 위임

CI/CD 작업 제한하는 예시 RBAC

정적 ID로 위장

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

관련 주제

문제 해결

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

TLS 활성화

서명되지 않은 기권자가 서명한 인증서로 서버에 연결할 수 없음

유효성 검사 오류

도움말

기능 사용 가능성과 제품 평가판

도움받기

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

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