Kubernetes용 GitLab 에이전트로 마이그레이션

요약

Kubernetes 클러스터를 GitLab과 연결하려면 다음을 사용할 수 있습니다: 인증서 기반 통합은 GitLab 14.5에서 지원 중단되었습니다. 인증서 기반 통합을 사용하고 있다면 가능한 빨리 다른 워크플로로 이전해야 합니다.

Kubernetes 클러스터를 GitLab과 연결하려면 다음을 사용할 수 있습니다:

인증서 기반 통합은 GitLab 14.5에서 지원 중단되었습니다. 단종 계획은 다음에 설명되어 있습니다:

인증서 기반 통합을 사용하고 있다면 가능한 빨리 다른 워크플로로 이전해야 합니다.

일반적으로 GitLab CI/CD에 의존하는 클러스터를 마이그레이션하려면 CI/CD 워크플로를 사용할 수 있습니다. 이 워크플로는 에이전트를 사용하여 클러스터에 연결합니다. 에이전트는:

인터넷에 노출되지 않습니다.
GitLab에 대한 전체 cluster-admin 접근 권한이 필요하지 않습니다.

Note

인증서 기반 통합은 GitLab 관리 앱, GitLab 관리 클러스터, Auto DevOps와 같은 인기 GitLab 기능에 사용되었습니다.

인증서 기반 클러스터 찾기#

전용 API를 사용하여 GitLab 인스턴스 또는 그룹(하위 그룹 및 프로젝트 포함) 내의 모든 인증서 기반 클러스터를 찾을 수 있습니다. 그룹 ID로 API를 쿼리하면 제공된 그룹 이하에서 정의된 모든 인증서 기반 클러스터가 반환됩니다.

이 경우 상위 그룹에 정의된 클러스터는 반환되지 않습니다. 이 동작은 그룹 소유자가 마이그레이션해야 하는 모든 클러스터를 찾는 데 도움이 됩니다.

비활성화된 클러스터도 반환되어 실수로 클러스터를 남기는 것을 방지합니다.

Note

클러스터 검색 API는 개인 네임스페이스에서는 작동하지 않습니다.

일반적인 배포 마이그레이션#

일반적인 배포를 마이그레이션하려면:

Kubernetes용 GitLab 에이전트를 설치합니다.
CI/CD 워크플로를 따라 에이전트가 그룹 및 프로젝트에 접근할 수 있도록 권한을 부여하거나, 가장(impersonation)으로 접근을 보안합니다.
왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
인증서 기반 클러스터 섹션에서 동일한 환경 범위를 제공하는 클러스터를 엽니다.
Details 탭을 선택하고 클러스터를 비활성화합니다.

GitLab 관리 클러스터에서 Kubernetes 리소스로 마이그레이션#

GitLab 관리 클러스터에서 GitLab은 모든 브랜치에 대해 별도의 서비스 계정과 네임스페이스를 생성하고 이러한 리소스를 사용하여 배포합니다.

이제 향상된 보안 제어로 리소스를 셀프서비스하기 위해 GitLab 관리 Kubernetes 리소스를 사용할 수 있습니다.

GitLab 관리 Kubernetes 리소스를 사용하면:

수동 개입 없이 안전하게 환경을 설정할 수 있습니다.
개발자에게 관리 클러스터 권한을 부여하지 않고 리소스 생성 및 접근을 제어할 수 있습니다.
개발자가 새 프로젝트나 환경을 생성할 때 셀프서비스 기능을 제공할 수 있습니다.
개발자가 전용 또는 공유 네임스페이스에서 테스트 및 개발 버전을 배포할 수 있습니다.

사전 요구사항:

Kubernetes용 GitLab 에이전트를 설치합니다.
관련 프로젝트 또는 그룹에 접근할 수 있도록 에이전트에 권한을 부여합니다.
인증서 기반 클러스터 통합 페이지에서 Namespace per environment 체크박스의 상태를 확인합니다.

GitLab 관리 클러스터에서 GitLab 관리 Kubernetes 리소스로 마이그레이션하려면:

기존 환경을 마이그레이션하는 경우 Kubernetes 대시보드 또는 Environments API를 통해 환경에 대한 에이전트를 구성합니다.

에이전트 구성 파일에서 리소스 관리를 활성화하도록 에이전트를 구성합니다:

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

.gitlab/agents/<agent-name>/environment_templates/default.yaml 아래에 환경 템플릿을 생성합니다. 인증서 기반 클러스터 통합 페이지에서 Namespace per environment 체크박스의 상태를 확인합니다.

Namespace per environment가 체크된 경우 다음 템플릿을 사용합니다:

objects:
  - apiVersion: v1
    kind: Namespace
    metadata:
      # the `.legacy_namespace` produces something like:
      # '{{ .project.slug }}-{{ .project.id }}-{{ .environment.slug }}'
      # that is compatible with what the certificate-based cluster integration
      # would have generated.
      name: '{}'
  - apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: 'bind-{{ .agent.id }}-{{ .project.id }}-{{ .environment.slug }}'
      namespace: '{}'
    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

Namespace per environment가 체크 해제된 경우 다음 템플릿을 사용합니다:

objects:
  - apiVersion: v1
    kind: Namespace
    metadata:
      name: '{{ .project.slug | slugify }}-{{ .project.id }}'
  - apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: 'bind-{{ .agent.id }}-{{ .project.id }}-{{ .environment.slug }}'
      namespace: '{{ .project.slug | slugify }}-{{ .project.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

CI/CD 구성에서 environment.kubernetes.agent: <path/to/agent/project:agent-name> 구문으로 에이전트를 사용합니다.
왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
인증서 기반 클러스터 섹션에서 동일한 환경 범위를 제공하는 클러스터를 엽니다.
Details 탭을 선택하고 클러스터를 비활성화합니다.

Auto DevOps에서 마이그레이션#

Auto DevOps 프로젝트에서 Kubernetes용 GitLab 에이전트를 사용하여 Kubernetes 클러스터와 연결할 수 있습니다.

사전 요구사항

Kubernetes용 GitLab 에이전트를 설치합니다.
관련 프로젝트 또는 그룹에 접근할 수 있도록 에이전트에 권한을 부여합니다.

Auto DevOps에서 마이그레이션하려면:

GitLab에서 Auto DevOps를 사용하는 프로젝트로 이동합니다.

세 가지 변수를 추가합니다. 왼쪽 사이드바에서 Settings > CI/CD를 선택하고 Variables를 펼칩니다.

애플리케이션 배포 도메인을 값으로 하는 KUBE_INGRESS_BASE_DOMAIN 키를 추가합니다.

path/to/agent/project:agent-name과 같은 값의 KUBE_CONTEXT 키를 추가합니다. 원하는 환경 범위를 선택합니다. 에이전트의 컨텍스트가 무엇인지 확실하지 않은 경우 .gitlab-ci.yml 파일을 편집하고 사용 가능한 컨텍스트를 확인하는 job을 추가합니다:

deploy:
  image: debian:13-slim
  variables:
    KUBECTL_VERSION: v1.34
    DEBIAN_FRONTEND: noninteractive
  script:
    # Follows https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#install-using-native-package-management
    - apt-get update
    - apt-get install -y --no-install-recommends apt-transport-https ca-certificates curl gnupg
    - curl --fail --silent --show-error --location "https://pkgs.k8s.io/core:/stable:/${KUBECTL_VERSION}/deb/Release.key" | gpg --dearmor --output /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    - chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    - echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/${KUBECTL_VERSION}/deb/ /" | tee /etc/apt/sources.list.d/kubernetes.list
    - chmod 644 /etc/apt/sources.list.d/kubernetes.list
    - apt-get update
    - apt-get install -y --no-install-recommends kubectl
    - kubectl config get-contexts

배포를 대상으로 하는 Kubernetes 네임스페이스 값의 KUBE_NAMESPACE 키를 추가합니다. 동일한 환경 범위를 설정합니다.

Add variable을 선택합니다.
왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
인증서 기반 클러스터 섹션에서 동일한 환경 범위를 제공하는 클러스터를 엽니다.
Details 탭을 선택하고 클러스터를 비활성화합니다.

.gitlab-ci.yml 파일을 편집하고 Auto DevOps 템플릿을 사용하고 있는지 확인합니다. 예를 들어:

include:
  template: Auto-DevOps.gitlab-ci.yml

variables:
  KUBE_INGRESS_BASE_DOMAIN: 74.220.23.215.nip.io
  KUBE_CONTEXT: "gitlab-examples/ops/gitops-demo/k8s-agents:demo-agent"
  KUBE_NAMESPACE: "demo-agent"

파이프라인을 테스트하려면 왼쪽 사이드바에서 Build > Pipelines를 선택한 다음 New pipeline을 선택합니다.

예시는 이 프로젝트를 확인하세요.

GitLab 관리 애플리케이션에서 마이그레이션#

GitLab 관리 앱(GMA)은 GitLab 14.0에서 지원 중단되었으며 GitLab 15.0에서 제거되었습니다. Kubernetes용 에이전트는 이를 지원하지 않습니다. GMA에서 에이전트로 마이그레이션하려면 다음 단계를 따르세요:

클러스터 관리 프로젝트 마이그레이션#

Kubernetes용 GitLab 에이전트와 함께 클러스터 관리 프로젝트를 사용하는 방법을 참조하세요.

클러스터 모니터링 기능 마이그레이션#

Kubernetes용 에이전트를 사용하여 Kubernetes 클러스터를 GitLab에 연결하면 사용자 접근을 활성화한 후 Kubernetes 대시보드를 사용할 수 있습니다.

Kubernetes용 GitLab 에이전트로 마이그레이션

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

원문 보기

번역일: 2026-05-22

요약

Kubernetes 클러스터를 GitLab과 연결하려면 다음을 사용할 수 있습니다:

인증서 기반 통합은 GitLab 14.5에서 지원 중단되었습니다. 단종 계획은 다음에 설명되어 있습니다:

인증서 기반 통합을 사용하고 있다면 가능한 빨리 다른 워크플로로 이전해야 합니다.

인터넷에 노출되지 않습니다.
GitLab에 대한 전체 cluster-admin 접근 권한이 필요하지 않습니다.

Note

인증서 기반 통합은 GitLab 관리 앱, GitLab 관리 클러스터, Auto DevOps와 같은 인기 GitLab 기능에 사용되었습니다.

인증서 기반 클러스터 찾기#

비활성화된 클러스터도 반환되어 실수로 클러스터를 남기는 것을 방지합니다.

Note

클러스터 검색 API는 개인 네임스페이스에서는 작동하지 않습니다.

일반적인 배포 마이그레이션#

일반적인 배포를 마이그레이션하려면:

Kubernetes용 GitLab 에이전트를 설치합니다.
CI/CD 워크플로를 따라 에이전트가 그룹 및 프로젝트에 접근할 수 있도록 권한을 부여하거나, 가장(impersonation)으로 접근을 보안합니다.
왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
인증서 기반 클러스터 섹션에서 동일한 환경 범위를 제공하는 클러스터를 엽니다.
Details 탭을 선택하고 클러스터를 비활성화합니다.

GitLab 관리 클러스터에서 Kubernetes 리소스로 마이그레이션#

GitLab 관리 클러스터에서 GitLab은 모든 브랜치에 대해 별도의 서비스 계정과 네임스페이스를 생성하고 이러한 리소스를 사용하여 배포합니다.

이제 향상된 보안 제어로 리소스를 셀프서비스하기 위해 GitLab 관리 Kubernetes 리소스를 사용할 수 있습니다.

GitLab 관리 Kubernetes 리소스를 사용하면:

수동 개입 없이 안전하게 환경을 설정할 수 있습니다.
개발자에게 관리 클러스터 권한을 부여하지 않고 리소스 생성 및 접근을 제어할 수 있습니다.
개발자가 새 프로젝트나 환경을 생성할 때 셀프서비스 기능을 제공할 수 있습니다.
개발자가 전용 또는 공유 네임스페이스에서 테스트 및 개발 버전을 배포할 수 있습니다.

사전 요구사항:

Kubernetes용 GitLab 에이전트를 설치합니다.
관련 프로젝트 또는 그룹에 접근할 수 있도록 에이전트에 권한을 부여합니다.
인증서 기반 클러스터 통합 페이지에서 Namespace per environment 체크박스의 상태를 확인합니다.

GitLab 관리 클러스터에서 GitLab 관리 Kubernetes 리소스로 마이그레이션하려면:

기존 환경을 마이그레이션하는 경우 Kubernetes 대시보드 또는 Environments API를 통해 환경에 대한 에이전트를 구성합니다.

에이전트 구성 파일에서 리소스 관리를 활성화하도록 에이전트를 구성합니다:

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

Namespace per environment가 체크된 경우 다음 템플릿을 사용합니다:

objects:
  - apiVersion: v1
    kind: Namespace
    metadata:
      # the `.legacy_namespace` produces something like:
      # '{{ .project.slug }}-{{ .project.id }}-{{ .environment.slug }}'
      # that is compatible with what the certificate-based cluster integration
      # would have generated.
      name: '{}'
  - apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: 'bind-{{ .agent.id }}-{{ .project.id }}-{{ .environment.slug }}'
      namespace: '{}'
    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

Namespace per environment가 체크 해제된 경우 다음 템플릿을 사용합니다:

objects:
  - apiVersion: v1
    kind: Namespace
    metadata:
      name: '{{ .project.slug | slugify }}-{{ .project.id }}'
  - apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: 'bind-{{ .agent.id }}-{{ .project.id }}-{{ .environment.slug }}'
      namespace: '{{ .project.slug | slugify }}-{{ .project.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

CI/CD 구성에서 environment.kubernetes.agent: <path/to/agent/project:agent-name> 구문으로 에이전트를 사용합니다.
왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
인증서 기반 클러스터 섹션에서 동일한 환경 범위를 제공하는 클러스터를 엽니다.
Details 탭을 선택하고 클러스터를 비활성화합니다.

Auto DevOps에서 마이그레이션#

Auto DevOps 프로젝트에서 Kubernetes용 GitLab 에이전트를 사용하여 Kubernetes 클러스터와 연결할 수 있습니다.

사전 요구사항

Kubernetes용 GitLab 에이전트를 설치합니다.
관련 프로젝트 또는 그룹에 접근할 수 있도록 에이전트에 권한을 부여합니다.

Auto DevOps에서 마이그레이션하려면:

GitLab에서 Auto DevOps를 사용하는 프로젝트로 이동합니다.

세 가지 변수를 추가합니다. 왼쪽 사이드바에서 Settings > CI/CD를 선택하고 Variables를 펼칩니다.

애플리케이션 배포 도메인을 값으로 하는 KUBE_INGRESS_BASE_DOMAIN 키를 추가합니다.

deploy:
  image: debian:13-slim
  variables:
    KUBECTL_VERSION: v1.34
    DEBIAN_FRONTEND: noninteractive
  script:
    # Follows https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#install-using-native-package-management
    - apt-get update
    - apt-get install -y --no-install-recommends apt-transport-https ca-certificates curl gnupg
    - curl --fail --silent --show-error --location "https://pkgs.k8s.io/core:/stable:/${KUBECTL_VERSION}/deb/Release.key" | gpg --dearmor --output /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    - chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    - echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/${KUBECTL_VERSION}/deb/ /" | tee /etc/apt/sources.list.d/kubernetes.list
    - chmod 644 /etc/apt/sources.list.d/kubernetes.list
    - apt-get update
    - apt-get install -y --no-install-recommends kubectl
    - kubectl config get-contexts

배포를 대상으로 하는 Kubernetes 네임스페이스 값의 KUBE_NAMESPACE 키를 추가합니다. 동일한 환경 범위를 설정합니다.

Add variable을 선택합니다.
왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
인증서 기반 클러스터 섹션에서 동일한 환경 범위를 제공하는 클러스터를 엽니다.
Details 탭을 선택하고 클러스터를 비활성화합니다.

.gitlab-ci.yml 파일을 편집하고 Auto DevOps 템플릿을 사용하고 있는지 확인합니다. 예를 들어:

include:
  template: Auto-DevOps.gitlab-ci.yml

variables:
  KUBE_INGRESS_BASE_DOMAIN: 74.220.23.215.nip.io
  KUBE_CONTEXT: "gitlab-examples/ops/gitops-demo/k8s-agents:demo-agent"
  KUBE_NAMESPACE: "demo-agent"

파이프라인을 테스트하려면 왼쪽 사이드바에서 Build > Pipelines를 선택한 다음 New pipeline을 선택합니다.

예시는 이 프로젝트를 확인하세요.

GitLab 관리 애플리케이션에서 마이그레이션#

클러스터 관리 프로젝트 마이그레이션#

Kubernetes용 GitLab 에이전트와 함께 클러스터 관리 프로젝트를 사용하는 방법을 참조하세요.

클러스터 모니터링 기능 마이그레이션#

Kubernetes용 에이전트를 사용하여 Kubernetes 클러스터를 GitLab에 연결하면 사용자 접근을 활성화한 후 Kubernetes 대시보드를 사용할 수 있습니다.