Kubernetes 에이전트와 함께 GitOps 사용하기(사라진 기능)

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 13.7 에서 소개되었습니다.
  • GitLab 14.0 에서 resource_inclusions 및 resource_exclusions 속성이 제거되고, reconcile_timeout, dry_run_strategy, prune, prune_timeout, prune_propagation_policy, inventory_policy 속성이 추가되었습니다.
  • GitLab 15.3 에서 GitLab Premium에서 GitLab Free로 이동되었습니다.
  • GitLab 15.7 에서 id 속성이 선택 사항으로 변경되었습니다.
  • 브랜치, 태그 또는 커밋 참조를 지정하여 Kubernetes 매니페스트 파일을 가져오기 GitLab 15.7 에서 소개되었습니다.

경고: 이 기능은 GitLab 16.2에서 사용 중단되었습니다. GitOps에는 Flux 통합을 사용해야 합니다. 기존 GitOps에서 Flux로 마이그레이션을 참조하세요.

이 다이어그램은 GitOps 배포에서 리포지토리와 주요 역할자를 보여줍니다.

sequenceDiagram participant D as Developer participant A as Application code repository participant M as Manifest repository participant K as GitLab agent participant C as Agent configuration repository loop 정기적으로 K-->>C: 구성 가져오기 end D->>+A: 코드 변경 푸시 A->>M: 매니페스트 업데이트 loop 정기적으로 K-->>M: 변경 사항 확인 M-->>K: 변경 사항 가져오고 적용 end

자세한 내용은 아키텍처 문서를 참조하세요.

GitOps 워크플로 스텝

GitOps를 사용하여 Kubernetes 클러스터를 업데이트하려면 다음 단계를 수행합니다.

  1. 작동하는 Kubernetes 클러스터가 있는지 확인하고 매니페스트가 GitLab 프로젝트에 있는지 확인합니다.
  2. 동일한 프로젝트에서 GitLab 에이전트를 등록하고 설치합니다.
  3. 에이전트 구성 파일을 구성하여 에이전트가 Kubernetes 매니페스트의 변경 사항을 모니터링하도록 합니다. GitOps 구성 참조를 참조하세요.

Kubernetes 매니페스트를 업데이트할 때마다 에이전트가 클러스터를 업데이트합니다.

GitOps 구성 참조

다음 코드 스니펫은 에이전트 구성 파일의 GitOps 섹션에 대한 가능한 키와 값의 예를 보여줍니다 (config.yaml). 

gitops:
  manifest_projects:
  - id: gitlab-org/cluster-integration/gitlab-agent
    ref: # `branch`, `tag` 또는 `commit` 중 하나를 지정할 수 있습니다
      branch: production
      # commit: <mysha>
      # tag: v1.0
    default_namespace: my-ns
    paths:
      # 이 디렉토리의 모든 YAML 파일을 읽습니다.
    - glob: '/team1/app1/*.yaml'
      # 'team2/apps' 및 모든 하위 디렉토리의 모든 .yaml 파일을 읽습니다.
    - glob: '/team2/apps/**/*.yaml'
      # 'paths'가 지정되지 않거나 빈 목록인 경우 아래의 구성이 사용됩니다.
    - glob: '/**/*.{yaml,yml,json}'
    reconcile_timeout: 3600s
    dry_run_strategy: none
    prune: true
    prune_timeout: 3600s
    prune_propagation_policy: foreground
    inventory_policy: must_match
키워드 설명
manifest_projects Kubernetes 매니페스트가 저장된 프로젝트입니다. 에이전트는 이러한 프로젝트의 저장소의 파일을 모니터링합니다. 매니페스트 파일이 변경되면 에이전트가 변경 사항을 클러스터에 배포합니다.
id YAML 또는 JSON 형식의 Kubernetes 매니페스트가 있는 Git 저장소의 경로입니다. 인증 메커니즘은 지원되지 않습니다. 기본값은 에이전트 구성 저장소입니다.
ref 선택 사항입니다. 설정된 Git 저장소의 Git 참조로부터 Kubernetes 매니페스트 파일을 가져옵니다. 지정되지 않거나 비어 있으면 기본 브랜치가 사용됩니다. 지정된 경우 branch, tag, 또는 commit 중 하나를 포함해야 합니다.
ref.branch 설정된 Git 저장소의 브랜치 이름입니다.
ref.tag 설정된 Git 저장소의 태그 이름입니다.
ref.commit 설정된 Git 저장소의 커밋 SHA입니다.
default_namespace 명시적으로 개체 매니페스트에 설정되지 않은 경우에 사용할 네임스페이스입니다. 인벤토리 ConfigMap 개체에도 사용됩니다.
paths 매니페스트 파일을 스캔할 저장소 경로입니다. 마침표(.)로 시작하는 이름의 디렉토리는 무시됩니다.
paths[].glob 필수 항목입니다. 글로빙 규칙에 대한 자세한 내용은 doublestar와 match 함수를 참조하세요.
reconcile_timeout 적용자가 당겨진 리소스가 모두 조화되어 있어야 하는지 여부와 그에 따라 얼마나 기다려야 하는지를 결정합니다. 기본값은 3600초(1시간)입니다.
dry_run_strategy 변경 을 수행해야 하는지를 결정합니다. none, client, 또는 server가 될 수 있습니다. 기본값은 none입니다.
prune 적용 이전에 이전에 적용된 객체를 제거해야 하는지 여부를 결정합니다. 기본값은 true입니다.
prune_timeout 가지치기 후에 모든 리소스가 완전히 삭제될 때까지 기다려야 하는지 여부 및 얼마나 기다려야 하는지를 결정합니다. 기본값은 3600초(1시간)입니다.
prune_propagation_policy 가지치기에 대해 사용할 삭제 전파 정책을 결정합니다. orphan, background, 또는 foreground가 될 수 있습니다. 기본값은 foreground입니다.
inventory_policy 인벤토리 객체가 다른 인벤토리 객체에 속하거나 어떤 인벤토리 객체에도 속하지 않는 객체를 업데이트할지 결정합니다. 패키지의 inventory-id 값과 라이브 객체의 owning-inventory 주석(config.k8s.io/owning-inventory) 의 비교에 따라 리소스의 적용/가지치기 작업을 수행할 수 있는지 결정합니다. must_match, adopt_if_no_inventory, 또는 adopt_all이 될 수 있습니다. 기본값은 must_match입니다.

GitOps 주석

쿠버네티스용 GitLab 에이전트에는 다음과 같은 주석을 사용할 수 있습니다:

  • 리소스 정렬: 특정 순서로 리소스를 적용하거나 삭제합니다.
  • 적용 시간 변이 사용: 다른 리소스 구성의 필드를 동적으로 다른 리소스에 대체합니다.

에이전트에는 기본 정렬이 있지만, 주석을 사용하여 순서를 세밀하게 조정하고 적용 시간 값을 주입할 수 있습니다.

GitOps 기능을 제공하기 위해 쿠버네티스용 GitLab 에이전트는 Kubernetes SIG 프로젝트인 cli-utils 라이브러리를 사용합니다. 자세한 내용은 cli-utils 문서에서 제공하는 주석을 확인하십시오.

자동 드리프트 교정

드리프트는 인프라 리소스의 현재 구성이 원하는 구성과 다른 경우에 발생합니다. 일반적으로 이는 사용된 인프라-지식-코드 메커니즘을 통해 직접 리소스를 편집하는 것에 의해 발생합니다. 드리프트의 위험을 최소화하면 구성 일관성과 성공적인 운영을 보장할 수 있습니다.

GitLab에서 쿠버네티스용 에이전트는 git 리포지토리의 원하는 상태와 Kubernetes 클러스터의 실제 상태를 정기적으로 비교합니다. git 상태와의 차이는 모든 확인에서 수정됩니다. 이 확인은 자동으로 5분마다 수행됩니다. 이러한 확인은 구성할 수 없습니다.

에이전트는 서버 측 적용을 사용합니다. 결과적으로 리소스의 각 필드마다 다른 관리자가 있을 수 있습니다. git에 의해 관리되는 필드만이 드리프트를 확인합니다. 이는 클러스터 내 컨트롤러를 사용하여 수평 Pod 오토스케일러와 같은 리소스를 수정하는 데 도움이 됩니다.

관련 주제

문제 해결

여러 프로젝트가 있는 경우 충돌을 피하는 방법

에이전트는 프로젝트의 paths 섹션에 설정된 각 glob 패턴을 독립적으로 감시하고 클러스터에 동시에 업데이트를 수행합니다. 여러 경로에서 변경 사항이 발견되면, 에이전트가 클러스터를 업데이트하려고 할 때 충돌이 발생할 수 있습니다.

이를 방지하려면, 하나의 곳에 논리적 그룹의 매니페스트를 저장하고 중복되는 glob을 피하기 위해 한 번만 참조하십시오.

예를 들어, 다음과 같이 두 가지 glob은 모두 루트 디렉토리의 *.yaml 파일과 일치하고 충돌을 일으킬 수 있습니다: 

gitops:
  manifest_projects:
  - id: project1
    paths:
    - glob: '/**/*.yaml'
    - glob: '/*.yaml'

대신에 모든 *.yaml 파일을 재귀적으로 일치하는 단일 glob을 지정하십시오: 

gitops:
  manifest_projects:
  - id: project1
    paths:
    - glob: '/**/*.yaml'

여러 에이전트 또는 프로젝트 사용

쿠버네티스 매니페스트를 별도의 GitLab 프로젝트에 저장하는 경우, 에이전트 구성 파일을 이러한 프로젝트의 위치로 업데이트하십시오.

경고: 에이전트의 구성 파일이 비공개 또는 공개일 수 있습니다. 쿠버네티스 매니페스트가 있는 다른 프로젝트는 반드시 공개되어야 합니다. 비공개 매니페스트 프로젝트 지원은 이 에픽에서 추적됩니다.