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

• GitOps 워크플로.
• GitLab CI/CD 워크플로.
• 인증서 기반 통합.

인증서 기반 통합은 GitLab 14.5에서 더 이상 사용되지 않습니다. 종료 계획은 다음에 설명되어 있습니다:

• GitLab.com 고객용.
• GitLab Self-Managed 고객용.

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

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

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

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

전용 API를 사용하면 하위 그룹과 프로젝트를 포함해 GitLab 인스턴스나 그룹 안의 모든 인증서 기반 클러스터를 찾을 수 있습니다. 그룹 ID로 API를 조회하면 해당 그룹과 그 하위에 정의된 모든 인증서 기반 클러스터를 반환합니다.

이때 상위 그룹에 정의된 클러스터는 반환되지 않습니다. 이 동작은 그룹 Owner가 마이그레이션해야 할 클러스터를 모두 찾는 데 도움이 됩니다.

클러스터를 실수로 빠뜨리지 않도록 비활성화된 클러스터도 함께 반환됩니다.

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

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

1. Kubernetes용 GitLab 에이전트를 설치합니다.
2. CI/CD 워크플로에 따라 에이전트에 그룹과 프로젝트 접근을 승인하거나, 가장으로 접근을 보호합니다.
3. 왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.
4. 인증서 기반 클러스터 섹션에서 동일한 환경 범위를 담당하는 클러스터를 엽니다.
5. Details 탭을 선택하고 클러스터를 끕니다.

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

GitLab 관리 클러스터에서는 GitLab 이 브랜치마다 별도의 서비스 계정과 네임스페이스를 만들고 이 리소스를 사용해 배포합니다.

이제 GitLab 관리 Kubernetes 리소스를 사용해 보안 제어가 강화된 방식으로 리소스를 셀프서비스로 사용할 수 있습니다.

GitLab 관리 Kubernetes 리소스로는 다음을 할 수 있습니다:

• 수작업 없이 환경을 안전하게 구성합니다.
• 개발자에게 클러스터 관리 권한을 주지 않고 리소스 생성과 접근을 제어합니다.
• 개발자가 새 프로젝트나 환경을 만들 때 셀프서비스 기능을 제공합니다.
• 개발자가 전용 네임스페이스나 공유 네임스페이스에 테스트 버전과 개발 버전을 배포하도록 허용합니다.

필수 조건:

• Kubernetes용 GitLab 에이전트를 설치합니다.
• 관련 프로젝트나 그룹에 접근하도록 에이전트를 승인합니다.
• 인증서 기반 클러스터 통합 페이지에서 Namespace per environment 체크박스의 상태를 확인합니다.

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

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

2. 에이전트 구성 파일에서 리소스 관리를 켜도록 에이전트를 구성합니다:

   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
   

3. .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
   

4. CI/CD 구성에서 environment.kubernetes.agent: <path/to/agent/project:agent-name> 구문으로 에이전트를 사용합니다.

5. 왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.

6. 인증서 기반 클러스터 섹션에서 동일한 환경 범위를 담당하는 클러스터를 엽니다.

7. Details 탭을 선택하고 클러스터를 끕니다.

Auto DevOps에서 마이그레이션#

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

필수 조건:

• Kubernetes용 GitLab 에이전트를 설치합니다.
• 관련 프로젝트나 그룹에 접근하도록 에이전트를 승인합니다.

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

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

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

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

   • KUBE_CONTEXT 키를 추가하고 값으로 path/to/agent/project:agent-name 형태를 지정합니다. 원하는 환경 범위를 선택합니다. 에이전트의 컨텍스트를 모르겠다면 .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
     

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

3. Add variable을 선택합니다.

4. 왼쪽 사이드바에서 Operate > Kubernetes clusters를 선택합니다.

5. 인증서 기반 클러스터 섹션에서 동일한 환경 범위를 담당하는 클러스터를 엽니다.

6. Details 탭을 선택하고 클러스터를 비활성화합니다.

7. .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"
   

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

예제는 이 프로젝트를 참고합니다.

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

GitLab 관리 앱(GMA)은 더 이상 사용되지 않으며 제거되었습니다. Kubernetes용 에이전트는 이를 지원하지 않습니다. GMA에서 에이전트로 마이그레이션하려면 다음 단계를 진행합니다:

1. GitLab 관리 앱에서 클러스터 관리 프로젝트로 마이그레이션합니다.
2. 클러스터 관리 프로젝트가 에이전트를 사용하도록 마이그레이션합니다.

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

Kubernetes용 GitLab 에이전트로 클러스터 관리 프로젝트를 사용하는 방법을 참고합니다.

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

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