- 클러스터와 함께 GitLab CI/CD 사용하기
- 에이전트에 승인
-
.gitlab-ci.yml
파일을 업데이트하여kubectl
명령어 실행 - 인증티켓을 사용하여 프로젝트 및 그룹 접근 제한
- 특정 환경에 대한 프로젝트 및 그룹 액세스 제한
- 관련 주제
- 문제 해결
Kubernetes 클러스터에서 GitLab CI/CD 사용하기
- 100에서 500으로 변경된 에이전트 연결 공유 제한은 GitLab 17.0에서 변경되었습니다.
GitLab CI/CD를 사용하여 Kubernetes 클러스터를 안전하게 연결, 배포, 및 업데이트할 수 있습니다.
이를 위해, 클러스터에 에이전트를 설치합니다. 그러면 Kubernetes 컨텍스트가 생기고, GitLab CI/CD 파이프라인에서 Kubernetes API 명령을 실행할 수 있습니다.
클러스터 접근이 안전하게 보장하려면:
- 각 에이전트는 별도의 컨텍스트(
kubecontext
)를 갖습니다. - 에이전트가 구성된 프로젝트와 추가로 승인한 프로젝트만 클러스터의 에이전트에 접근할 수 있습니다.
GitLab CI/CD를 사용하여 클러스터와 상호 작용하려면, 러너가 GitLab에 등록되어야 합니다. 그러나 이러한 러너들은 에이전트가 있는 클러스터에 있을 필요는 없습니다.
클러스터와 함께 GitLab CI/CD 사용하기
GitLab CI/CD로 Kubernetes 클러스터를 업데이트하려면:
- 작동하는 Kubernetes 클러스터가 있고 Manifests가 GitLab 프로젝트에 있다는 것을 확인합니다.
- 동일한 GitLab 프로젝트에서 GitLab 에이전트를 등록하고 설치합니다.
-
.gitlab-ci.yml
파일을 업데이트하여 에이전트의 Kubernetes 컨텍스트를 선택하고 Kubernetes API 명령을 실행합니다. - 파이프라인을 실행하여 클러스터에 배포하거나 업데이트합니다.
만약 Kubernetes Manifests를 포함하는 여러 GitLab 프로젝트가 있다면:
- 각각의 프로젝트에 GitLab 에이전트를 설치하거나 Kubernetes Manifests를 유지하는 GitLab 프로젝트 중 하나에 설치합니다.
- 에이전트에 승인을 부여하여 GitLab 프로젝트에 액세스합니다.
- 선택 사항. 추가 보안을 위해 가장자리를 사용.
-
.gitlab-ci.yml
파일을 업데이트하여 에이전트의 Kubernetes 컨텍스트를 선택하고 Kubernetes API 명령을 실행합니다. - 파이프라인을 실행하여 클러스터에 배포하거나 업데이트합니다.
에이전트에 승인
여러 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 프로젝트에 에이전트에 액세스할 수 있도록 승인하려면:
- Kubernetes Manifests를 포함하는 GitLab 프로젝트를 선택하고 왼쪽 사이드바에서 검색 또는 이동을 선택합니다.
-
config.yaml
파일을 편집합니다.ci_access
키워드 아래에groups
속성을 추가합니다. -
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 변수를 정의하십시오.
예를 들어:
-
KUBE_CONTEXT
라는 두 개의 변수를 정의하십시오. - 첫 번째 변수에 대해:
-
환경
을staging
으로 설정하십시오. - 스테이징 에이전트의 컨텍스트를 값에 설정하십시오.
-
- 두 번째 변수에 대해:
-
환경
을production
으로 설정하십시오. - 프로덕션 에이전트의 컨텍스트를 값에 설정하십시오.
-
인증서 기반 및 에이전트 기반 연결을 사용하는 환경
인증서 기반 클러스터(미지원)와 에이전트 연결이 모두 있는 환경에 배포하려면:
- 인증서 기반 클러스터의 컨텍스트는 항상
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’와 같이 구성합니다.
인증티켓을 사용하여 프로젝트 및 그룹 접근 제한
- 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 문서를 참조하세요.
특정 환경에 대한 프로젝트 및 그룹 액세스 제한
- 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 작업만 에이전트에 액세스할 수 있습니다.
관련 주제
- 자율 학습 가능한 워크샵 (AWS EKS를 사용하지만 다른 Kubernetes 클러스터에도 사용 가능)
- Auto DevOps 구성
문제 해결
~/.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
을 사용하세요.