Argo CD

1. 개요

Argo CD 는 Git 에 적힌 쿠버네티스 객체(YAML)를 읽어 클러스터의 실제 상태와 비교하고, 다르면 Git 쪽 내용으로 맞추는 도구다. 사람이 kubectl apply 하던 일을 클러스터 안의 프로그램이 대신 하고, 무엇이 배포돼야 하는지의 기준을 Git 에 둔다. 이 방식을 GitOps 라고 부른다.

kubectl -n argocd get applications     # Argo CD 가 관리하는 연결 목록
argocd app diff kukie-dev-apps         # Git 과 클러스터의 차이
argocd app sync kukie-dev-apps         # Git 쪽으로 맞추기

2. 구성 요소

Argo CD 자체도 클러스터 안의 Pod 몇 개다. 보통 argocd 네임스페이스에 설치한다.

application-controller 는 넣을 수 있는 권한이 넓다(보통 클러스터 관리자급). 그래서 “무엇을 넣어도 되는가” 를 Argo CD 안에서 다시 좁히는 장치가 5절의 AppProject 다.

3. 추가하는 리소스 종류

원래 쿠버네티스에는 Application 도 프로젝트도 없다. Argo CD 를 설치하면 CRD 로 아래 세 종류가 API 에 추가되고, Argo CD 를 지우면 함께 사라진다.

kubectl api-resources --api-group=argoproj.io
# applications     app,apps     argoproj.io/v1alpha1   true   Application
# applicationsets  appset       argoproj.io/v1alpha1   true   ApplicationSet
# appprojects      appproj      argoproj.io/v1alpha1   true   AppProject

세 종류의 객체는 Argo CD 가 설치된 네임스페이스(argocd)에 둔다. 다른 네임스페이스에 두려면 따로 켜야 한다.

4. Application

Application 은 Argo CD 가 관리하는 단위다. “이 레포의 이 폴더를 저 클러스터의 이 네임스페이스에” 를 적는다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kukie-dev-apps
  namespace: argocd
spec:
  project: kukie-apps              # 속한 AppProject 이름
  source:
    repoURL: https://github.com/durokukie/kukie-manifest.git
    targetRevision: main
    path: envs/dev
  destination:
    server: https://kubernetes.default.svc   # Argo CD 가 설치된 그 클러스터
    namespace: kukie-dev

4.1. project 칸

• Application 하나는 AppProject 하나에만 속한다. 한 AppProject 에는 Application 이 여러 개 속할 수 있다
• 둘은 포함 관계가 아니라 나란히 있는 별개의 객체다. Application 이 project: 에 이름을 적어 가리킬 뿐이다
• 비워 두면 default 프로젝트에 속한다 (5.2. 참고)

4.2. 상태 표시

두 값은 application-controller 가 Application 객체의 status 칸에 적고, 웹 UI · kubectl get applications · argocd app get 은 모두 그 칸을 읽어 보여 준다. 수동 동기화인 Application 은 Git 을 읽고 차이를 계산만 한다. 처음 연결했을 때 OutOfSync · Missing 으로 보이는 것은 아직 아무것도 넣지 않았다는 뜻이다.

5. AppProject

AppProject 는 그 프로젝트에 속한 Application 이 어디서 가져와 어디에 무엇을 넣을 수 있는지의 한계선이다. Application 이 Git 에 뭐라고 적든 이 선 밖이면 Argo CD 가 동기화를 거부한다.

5.1. 제한 항목

동기화할 때는 이 항목들을 아래 순서로 검사한다.

5.2. default 프로젝트

Argo CD 를 설치하면 default 프로젝트가 자동으로 생긴다. 모든 레포 · 모든 클러스터 · 모든 종류를 허용하는(*) 사실상 울타리가 없는 프로젝트다. 고칠 수는 있지만 지울 수는 없다. 그래서 운영에서는 용도별 프로젝트를 따로 만들고 Application 이 default 를 쓰지 않게 한다.

5.3. 쿠버네티스 기본 장치와의 차이

Argo CD 의 application-controller 는 권한이 넓은 하나의 서비스 계정으로 움직인다. RBAC 만으로는 Application 마다 다르게 막을 수 없어서 AppProject 가 그 한 겹을 더한다.

5.4. Application 을 쓸 수 있는 곳

AppProject 는 Application 의 project: 칸으로 정해진다. Application 객체를 새로 쓸 수 있는 사람은 더 넓은 프로젝트를 골라 적을 수도 있다는 뜻이다. 그래서 Application · AppProject 객체는 앱 매니페스트와 다른 레포(관리자만 push 하는 곳)에 두고, 앱 레포 쪽 프로젝트의 허용 종류에는 Application · AppProject 를 넣지 않는다.

6. ApplicationSet

ApplicationSet 은 목록(generator)과 틀(template)을 곱해 Application 을 여러 개 만든다. 환경이나 클러스터가 늘 때마다 Application 을 손으로 복사하지 않기 위해 쓴다.

Application 과 이름이 비슷하지만 별개의 종류이고, argocd-applicationset-controller 가 있어야 동작한다.

7. App of Apps

App of Apps 는 kind: Application 만 들어 있는 Git 폴더를 읽는 Application 하나를 두고, 그것이 나머지 Application 을 만들게 하는 구성이다. 맨 위의 것을 흔히 루트(root) Application 이라고 부른다.

7.1. 루트 Application

• 별도 종류가 아니다. 다른 Application 과 똑같이 kind: Application 이고, 자기 프로젝트의 제한을 그대로 받는다
• 읽는 폴더에 Application 객체가 들어 있어서 결과적으로 다른 Application 을 만들 뿐이다
• 루트 자체는 그 폴더 밖에서 넣는다(Terraform · Helm · kubectl apply 한 번). 폴더 안에 두면 처음에 그것을 읽어 줄 주체가 없다
• 이후 폴더에 Application 을 더하거나 빼는 것은 Git 머지만으로 된다

7.2. 삭제 전파

Application 에 resources-finalizer.argocd.argoproj.io finalizer 가 있으면, 그 Application 을 지울 때 그것이 넣은 객체도 함께 지운다. 루트에 붙어 있으면 루트를 지울 때 자식 Application 과 그 객체까지 전부 지워진다. finalizer 가 없으면 Application 만 지워지고 넣었던 객체는 클러스터에 남는다.

8. 관리 범위

Argo CD 가 하는 일은 객체를 클러스터(API 서버)에 넣는 데까지다. 넣은 객체를 읽고 클러스터 밖 자원을 만들거나 Pod 를 고치는 것은 그 종류를 맡은 컨트롤러다.

• Ingress 를 넣어도 로드밸런서 컨트롤러가 없으면 로드밸런서는 생기지 않는다
• 컨트롤러 자신도 Deployment 같은 객체로 띄워지므로, 컨트롤러 설치 역시 Argo CD 로 할 수 있다
• 컨트롤러가 만든 객체(ESO 가 만든 Secret 등)는 Git 에 없으므로 Argo CD 의 비교 대상이 아니다

9. 동기화

9.1. 수동과 자동

9.2. prune

자동 동기화는 기본적으로 지우지 않는다. Git 에서 파일을 지워도 클러스터의 객체는 남는다. prune: true 를 켜면 Git 에 더 이상 없는 객체를 동기화 때 함께 지운다.

9.3. selfHeal

기본적으로 클러스터에서 손으로 바꾼 값은 다음 Git 변경 전까지 그대로 남는다. selfHeal: true 를 켜면 클러스터 쪽 변경도 차이로 보고 Git 내용으로 되돌린다. 되돌리기는 기본 5초 간격으로 다시 시도한다.

9.4. ignoreDifferences

일부러 Git 과 달라지는 칸은 비교에서 뺀다. 예를 들어 Reloader 는 Secret 이 바뀌면 Deployment 의 Pod 템플릿에 재시작 표시 주석을 붙이는데, 이 칸을 빼지 않으면 selfHeal 이 그 표시를 계속 지운다.

ignoreDifferences:
  - group: apps
    kind: Deployment
    jsonPointers:
      - /spec/template/metadata/annotations/reloader.stakater.com~1last-reloaded-from
syncPolicy:
  syncOptions: [RespectIgnoreDifferences=true]   # 동기화 때도 이 칸을 덮어쓰지 않게

10. 관련 문서

• CRD — Application · AppProject · ApplicationSet 이 추가되는 방식
• kubelet — 객체를 읽고 실제 일을 하는 조정 루프의 예
• Admission Webhook — API 서버 단계에서 객체를 검증 · 변형하는 다른 장치
• Controller — 객체를 지켜보다 실제 일을 하는 프로그램 (예정)
• Helm · Kustomize — repo-server 가 렌더링하는 형식 (예정)

11. 출처

“Declaratively specify one Argo CD app that consists only of other apps.”

“Only admins should have push access to the parent Application’s source repository.”

“automated sync will not delete resources when Argo CD detects the resource is no longer defined in Git.”

• Argo CD — Overview
• Argo CD — Architecture
• Argo CD — Projects
• Argo CD — Automated Sync Policy
• Argo CD — Cluster Bootstrapping (App of Apps)
• Argo CD — Generating Applications with ApplicationSet
• Argo CD — Diffing Customization