GitLab 관리형 Kubernetes 리소스를 사용하여 환경 템플릿으로 Kubernetes 리소스를 프로비저닝합니다. 환경 템플릿은 다음을 수행할 수 있습니다:

• 새 환경에 대한 네임스페이스 및 서비스 계정 자동 생성
• 역할 바인딩을 통한 접근 권한 관리
• 기타 필요한 Kubernetes 리소스 구성

개발자가 애플리케이션을 배포하면 GitLab은 환경 템플릿을 기반으로 리소스를 생성합니다.

GitLab 관리형 Kubernetes 리소스 구성#

사전 요구 사항:

• Kubernetes용 GitLab 에이전트가 구성되어 있어야 합니다.
• 관련 프로젝트나 그룹에 접근하도록 에이전트에 권한을 부여했어야 합니다.
• (선택 사항) 권한 에스컬레이션을 방지하기 위해 에이전트 가장을 구성했어야 합니다. 기본 환경 템플릿은 ci_job 가장을 구성했다고 가정합니다.

Kubernetes 리소스 관리 켜기#

에이전트 구성 파일에서#

리소스 관리를 켜려면 에이전트 구성 파일을 수정하여 필요한 권한을 포함합니다:

ci_access:
  projects:
    - id: <your_group/your_project>
      access_as:
        ci_job: {}
      resource_management:
        enabled: true
  groups:
    - id: <your_other_group>
      access_as:
        ci_job: {}
      resource_management:
        enabled: true

CI/CD 작업에서#

에이전트가 환경의 리소스를 관리하도록 하려면 배포 작업에서 에이전트를 지정합니다. 예시:

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    kubernetes:
      agent: path/to/agent/project:agent-name

CI/CD 변수는 에이전트 경로에 사용할 수 있습니다. 자세한 내용은 변수를 사용할 수 있는 위치를 참조하세요.

환경 템플릿 생성#

환경 템플릿은 생성, 업데이트 또는 제거할 Kubernetes 리소스를 정의합니다.

기본 환경 템플릿은 Namespace를 생성하고 CI/CD 작업에 대한 RoleBinding을 구성합니다.

기본 템플릿을 덮어쓰려면 에이전트 디렉토리에 default.yaml이라는 템플릿 구성 파일을 추가합니다:

.gitlab/agents/<agent-name>/environment_templates/default.yaml

지원되는 Kubernetes 리소스#

다음 Kubernetes 리소스(kind)가 지원됩니다:

• Namespace
• ServiceAccount
• RoleBinding
• FluxCD Source Controller 객체:
  • GitRepository
  • HelmRepository
  • HelmChart
  • Bucket
  • OCIRepository
• FluxCD Kustomize Controller 객체:
  • Kustomization
• FluxCD Helm Controller 객체:
  • HelmRelease
• FluxCD Notification Controller 객체:
  • Alert
  • Provider
  • Receiver

환경 템플릿 예시#

다음 예시는 네임스페이스를 생성하고 그룹에 클러스터에 대한 관리자 접근 권한을 부여합니다.

objects:
  - apiVersion: v1
    kind: Namespace
    metadata:
      name: '{{ .environment.slug }}-{{ .project.id }}-{{ .agent.id }}'
  - apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: bind-{{ .environment.slug }}-{{ .project.id }}-{{ .agent.id }}
      namespace: '{{ .environment.slug }}-{{ .project.id }}-{{ .agent.id }}'
    subjects:
      - kind: Group
        apiGroup: rbac.authorization.k8s.io
        name: gitlab:project_env:{{ .project.id }}:{{ .environment.slug }}
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: admin

# Resource lifecycle configuration
apply_resources: on_start    # Resources are applied when environment is started/restarted
delete_resources: on_stop    # Resources are removed when environment is stopped

템플릿 변수#

환경 템플릿은 제한된 변수 치환을 지원합니다. 다음 변수를 사용할 수 있습니다:

모든 변수는 이중 중괄호 구문을 사용하여 참조해야 합니다. 예: {{ .project.id }}. 사용된 템플릿 시스템에 대한 자세한 내용은 text/template 문서를 참조하세요.

템플릿 함수#

환경 템플릿은 변수 값을 조작하는 제한된 함수를 지원합니다. 다음 함수를 사용할 수 있습니다:

Kubernetes 값(예: 네임스페이스 이름 또는 레이블)을 준수하기 위해 함수 수는 최소한의 함수 세트로 의도적으로 제한됩니다.

리소스 수명 주기 관리#

다음 설정을 사용하여 Kubernetes 리소스가 제거될 시기를 구성합니다:

# Never delete resources
delete_resources: never

# Delete resources when environment is stopped
delete_resources: on_stop

기본값은 on_stop이며 기본 환경 템플릿에 지정되어 있습니다.

관리형 리소스 레이블 및 어노테이션#

GitLab에서 생성한 리소스는 추적 및 트러블슈팅 목적으로 일련의 레이블과 어노테이션을 사용합니다.

다음 레이블은 GitLab에서 생성한 모든 리소스에 정의됩니다. 값은 의도적으로 비워 둡니다:

• agent.gitlab.com/id-<agent_id>: ""
• agent.gitlab.com/project_id-<project_id>: ""
• agent.gitlab.com/env-<gitlab_environment_slug>-<project_id>-<agent_id>: ""
• agent.gitlab.com/environment_slug-<gitlab_environment_slug>: ""

GitLab에서 생성한 모든 리소스에 agent.gitlab.com/env-<gitlab_environment_slug>-<project_id>-<agent_id> 어노테이션이 정의됩니다. 어노테이션의 값은 다음 키가 있는 JSON 객체입니다:

GitLab 관리형 Kubernetes 리소스 비활성화#

대시보드와 같은 다른 Kubernetes 기능을 계속 사용하면서 특정 환경에 대한 GitLab 관리형 Kubernetes 리소스를 비활성화할 수 있습니다. 관리형 리소스를 비활성화하면 기본적으로 관리형 리소스가 활성화된 전역 에이전트를 사용할 때 특정 프로젝트나 환경을 제외해야 하는 경우에 도움이 됩니다.

환경에 대한 관리형 리소스를 비활성화하려면 managed_resources.enabled: false 구성을 추가합니다:

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    kubernetes:
      agent: path/to/agent/project:agent-name
      managed_resources:
        enabled: false

트러블슈팅#

관리형 Kubernetes 리소스와 관련된 모든 오류는 다음에서 찾을 수 있습니다:

• GitLab 프로젝트의 환경 페이지
• 파이프라인에서 기능을 사용할 때 CI/CD 작업 로그