Argo CD on k3s¶

이 문서는 tirosh-home site에서 k3s 기반 management cluster를 만들고, 그 위에 Argo CD를 설치한 뒤 RKE2 workload cluster를 배포 대상으로 등록하는 흐름을 설명합니다.

1. 전체 흐름¶

1-1. Argo CD의 역할¶

Argo CD는 workload를 실행할 cluster가 아니라, 다른 cluster를 배포 대상으로 관리하는 management plane입니다.

1-2. 구성 흐름¶

argocd VM
  |
  v
k3s management cluster
  context: tirosh-home/k3s
  |
  v
Argo CD 설치
  |
  v
RKE2 workload cluster 등록
  context: tirosh-home/rke2/gpu

1-3. 기본 실행 순서¶

처음 설치할 때는 아래 순서로 진행합니다.

make k3s/install SITE=tirosh-home ASK_PASS=true
make k3s/status SITE=tirosh-home ASK_PASS=true
make k3s/kubeconfig/merge SITE=tirosh-home ASK_PASS=true

make argocd/install SITE=tirosh-home ASK_PASS=true
make argocd/status SITE=tirosh-home ASK_PASS=true
make argocd/password SITE=tirosh-home ASK_PASS=true

argocd login gitops.internal.tirosh.ai --grpc-web --prompts-enabled
argocd account update-password

argocd cluster add tirosh-home/rke2/gpu \
  --kubeconfig ~/.kube/config \
  --name tirosh-home-rke2-gpu \
  --yes \
  --upsert

2. kubeconfig와 context¶

Argo CD 운영에서는 context가 두 종류로 등장합니다.

management cluster context
  Argo CD가 설치된 cluster
  tirosh-home/k3s

workload cluster context
  Argo CD에 등록할 배포 대상 cluster
  tirosh-home/rke2/gpu

Argo CD 설치, password 확인, port-forward는 management cluster context를 사용합니다. argocd cluster add는 management cluster에 접속한 뒤 workload cluster context를 Argo CD에 등록합니다.

이 구분이 중요한 이유는 Argo CD CLI가 한 번에 두 cluster 정보를 사용하기 때문입니다.

KUBECTX
  kubectl/port-forward가 Argo CD server를 찾을 cluster
  예: tirosh-home/k3s

CLUSTER_KUBECTX
  Argo CD에 배포 대상으로 등록할 cluster
  예: tirosh-home/rke2/gpu

두 값을 헷갈리면 Argo CD server를 찾지 못하거나, 반대로 management cluster 자신을 workload cluster로 등록하게 됩니다.

2-1. kubeconfig merge¶

이 repo는 cluster별 kubeconfig를 먼저 가져온 뒤 ~/.kube/config에 merge해서 사용합니다.

remote cluster kubeconfig
  |
  v
local per-cluster kubeconfig
  ~/.kube/tirosh-home.yml
  ~/.kube/tirosh-home-rke2.yml
  |
  v
main kubeconfig
  ~/.kube/config
  |
  v
named context
  tirosh-home/k3s
  tirosh-home/rke2/gpu

make k3s/kubeconfig/merge SITE=tirosh-home
make rke2/kubeconfig/merge SITE=tirosh-home

merge가 끝나면 context 목록에서 두 cluster가 보여야 합니다.

kubectl config get-contexts
kubectl --context tirosh-home/k3s get nodes
kubectl --context tirosh-home/rke2/gpu get nodes

자세한 kubeconfig, context, kubectx, k9s 배경은 k9s를 참고합니다.

2-2. profile 기본값¶

Argo CD 관련 Make target은 기본적으로 sites/<site_id>/profile.toml의 값을 사용합니다. profile.toml은 Argo CD 자체의 Kubernetes manifest가 아니라, Make가 kubectl, argocd, Ansible을 실행할 때 넘길 기본 인자를 정하는 실행 context입니다.

[kube]
kubeconfig = "~/.kube/config"

[kube.contexts]
argocd = "tirosh-home/k3s"
rke2_gpu = "tirosh-home/rke2/gpu"

[argocd]
target_name = "argocd"
server = "gitops.internal.tirosh.ai"
login_args = "--grpc-web --prompts-enabled"
auto_port_forward = false
cluster_context = "tirosh-home/rke2/gpu"
cluster_name = "tirosh-home-rke2-gpu"

각 값은 아래처럼 사용됩니다.

key	의미	주로 쓰는 target
kube.kubeconfig	기본 kubeconfig 파일	argocd/status, argocd/password/update, argocd/cluster/add
kube.contexts.argocd	Argo CD가 설치된 management cluster context	argocd/port-forward, argocd/password/update
argocd.target_name	Ansible이 접속할 Argo CD VM alias	argocd/install, argocd/status, argocd/password
argocd.server	Argo CD CLI가 접속할 server 주소	argocd/password/update, argocd/cluster/add
argocd.login_args	Argo CD CLI login option	argocd/password/update, argocd/cluster/add
argocd.auto_port_forward	CLI 작업 전에 port-forward를 자동으로 띄울지 여부	argocd/password/update, argocd/cluster/add
argocd.cluster_context	Argo CD에 등록할 workload cluster context	argocd/cluster/add
argocd.cluster_name	Argo CD에 표시될 cluster 이름	argocd/cluster/add

필요하면 명령 실행 시 override합니다.

make argocd/status SITE=tirosh-home KUBECONFIG=$HOME/.kube/config KUBECTX=tirosh-home/k3s

3. VM과 inventory 준비¶

Argo CD는 argocd VM 위에 설치한 single-node k3s cluster에서 실행합니다.

3-1. VM 선언¶

sites/<site_id>/vms.tfvars에 Argo CD용 VM을 선언합니다.

argocd = {
  name      = "argocd"
  vm_id     = 1001
  tags      = ["ubuntu", "k3s", "argocd"]
  cpu_cores = 4
  memory_mb = 4096

  disk = {
    datastore_id = "local-lvm"
    size_gb      = 40
  }

  user_account = {
    username = "tirosh"
  }
}

VM plan/apply는 Proxmox VM workflow를 사용합니다.

make proxmox/vms/plan SITE=tirosh-home
make proxmox/vms/apply SITE=tirosh-home

DHCP를 사용하는 경우 VM 생성 후 Proxmox UI, DHCP lease, guest agent output 등으로 VM IP를 확인합니다.

3-2. inventory 등록¶

확인한 VM IP를 sites/<site_id>/inventory.toml의 vms.argocd.ansible_host에 입력합니다.

[vms.argocd]
ansible_host = "172.31.0.10"
ansible_user = "tirosh"
ansible_become_user = "root"
proxmox_vm_name = "argocd"
workloads = ["k3s", "argocd"]

수정 후 Ansible inventory를 다시 렌더링합니다.

make site/inventory/render SITE=tirosh-home

기본 target alias는 argocd입니다. 다른 host alias를 쓰려면 K3S_TARGET_NAME 또는 ARGOCD_TARGET_NAME을 지정합니다.

make k3s/install SITE=tirosh-home K3S_TARGET_NAME=argocd-staging

4. k3s 설치¶

k3s server option은 site별 변수 파일에서 관리합니다.

sites/tirosh-home/k3s/vars.yml

4-1. k3s 설정¶

기본 설치는 /etc/rancher/k3s/config.yaml을 생성하고, k3s service가 이 파일을 읽게 합니다.

k3s_config:
  write-kubeconfig-mode: "0644"
  tls-san:
    - internal.tirosh.ai
    - k3s.internal.tirosh.ai
    - 172.31.0.10

DNS 이름으로 Kubernetes API에 접근할 경우 tls-san에 그 DNS 이름을 넣어야 합니다. 예를 들어 kubeconfig의 server를 https://k3s.internal.tirosh.ai:6443로 사용할 계획이면 k3s.internal.tirosh.ai가 SAN에 포함되어야 합니다. Argo CD Ingress host인 gitops.internal.tirosh.ai와 Kubernetes API endpoint는 분리해서 관리합니다.

자주 조정하는 옵션 예시는 아래와 같습니다.

k3s_config:
  write-kubeconfig-mode: "0644"
  tls-san:
    - internal.tirosh.ai
    - k3s.internal.tirosh.ai

  disable:
    - traefik
    - servicelb

  node-ip: 172.31.0.10
  advertise-address: 172.31.0.10

  node-label:
    - role=gitops
    - site=tirosh-home

4-2. 설치와 상태 확인¶

k3s 설치는 Ansible playbook으로 실행합니다.

make k3s/install SITE=tirosh-home
make k3s/status SITE=tirosh-home
make k3s/config SITE=tirosh-home

4-3. kubeconfig 가져오기¶

로컬 kubeconfig를 가져옵니다.

make k3s/kubeconfig SITE=tirosh-home

기본 저장 경로는 아래와 같습니다.

~/.kube/tirosh-home.yml

이 파일은 cluster credential이므로 git에 커밋하지 않습니다.

kubectl, kubectx, k9s가 export 없이 계속 이 context를 보게 하려면 ~/.kube/config에 merge합니다.

make k3s/kubeconfig/merge SITE=tirosh-home

merge 전 기존 ~/.kube/config는 ~/.kube/config.bak로 백업됩니다.

다른 경로에 저장하려면 K3S_KUBECONFIG_PATH를 지정합니다.

make k3s/kubeconfig SITE=tirosh-home K3S_KUBECONFIG_PATH=$HOME/.kube/lab.yml

현재 shell에서만 임시로 여러 kubeconfig를 합쳐 보고 싶으면 export 명령을 사용할 수 있습니다.

eval "$(make k3s/kubeconfig/export SITE=tirosh-home)"

5. Argo CD 설치¶

Argo CD는 공식 stable install manifest를 적용합니다.

make argocd/install SITE=tirosh-home
make argocd/status SITE=tirosh-home

Argo CD ApplicationSet CRD는 client-side apply annotation 크기 한도에 걸릴 수 있으므로, install playbook은 manifest를 server-side apply로 적용합니다.

설치 대상은 argocd VM 자체가 아니라, 그 VM 위에서 동작하는 k3s cluster입니다. playbook은 SSH로 argocd VM에 접속한 뒤, remote host의 kubeconfig를 사용해 argocd namespace와 Argo CD resource를 만듭니다.

local make
  |
  v
SSH to argocd VM
  |
  v
kubectl apply to local k3s
  |
  v
argocd namespace / argocd-server / repo-server / application-controller

5-1. Ingress 설정¶

Argo CD 외부 접속 설정은 site별 변수 파일에서 관리합니다.

sites/tirosh-home/argocd/vars.yml

기본 설정은 k3s에 내장된 Traefik Ingress를 사용합니다.

argocd_ingress_enabled: true
argocd_ingress_class_name: traefik
argocd_ingress_host: gitops.internal.tirosh.ai
argocd_ingress_service_port: 80
argocd_server_insecure: true

argocd_server_insecure: true는 Ingress controller가 argocd-server service의 HTTP port 80으로 프록시하도록 하는 설정입니다.

현재 internal.tirosh.ai 도메인은 OPNSense Caddy에서 내부 서비스 노출을 담당합니다. Caddy는 TLS를 종료하고 k3s node의 Traefik HTTP endpoint로 프록시합니다.

https://gitops.internal.tirosh.ai -> OPNSense Caddy -> http://172.31.0.10

Caddy 예시는 아래와 같습니다.

gitops.internal.tirosh.ai {
  reverse_proxy 172.31.0.10:80
}

따라서 k3s 내부 Ingress TLS는 기본으로 끄고, argocd_ingress_tls_enabled: false를 유지합니다.

5-2. 접속 확인¶

Web UI는 Ingress host로 접속합니다.

https://gitops.internal.tirosh.ai

Ingress 없이 임시로 접속할 때는 port-forward를 사용할 수 있습니다. 이 명령은 foreground에서 실행되므로 별도 터미널에서 유지합니다.

make argocd/port-forward SITE=tirosh-home

port-forward 접속 URL은 아래와 같습니다.

http://127.0.0.1:8080

이 문서의 이후 CLI 예시는 Ingress와 DNS가 동작한다는 전제에서 gitops.internal.tirosh.ai를 사용합니다. 127.0.0.1:8080은 DNS/Ingress가 아직 준비되지 않았거나, 내부망에서 임시로 확인해야 할 때만 사용합니다.

6. Admin password¶

초기 계정은 admin입니다.

Argo CD admin password는 세 단계로 다룹니다.

초기 password 확인
  |
  v
Argo CD CLI로 login
  |
  v
새 password로 변경

이 저장소에는 password를 저장하지 않습니다. 초기 bootstrap이 끝나면 사람이 직접 password를 바꾸고, 이후 운영에서는 SSO/RBAC 또는 별도 secret 관리 방식을 붙이는 것을 기본으로 봅니다.

6-1. 초기 password 확인¶

초기 admin password를 확인합니다. 이 값은 Argo CD가 설치될 때 argocd-initial-admin-secret에 생성됩니다.

make argocd/password SITE=tirosh-home

이 명령은 Ansible로 argocd VM에 접속해서 k3s 안의 secret을 읽습니다. 따라서 여기서는 KUBECONFIG보다 inventory.yml의 argocd host 접속 정보가 먼저 중요합니다.

6-2. password 변경¶

초기 로그인 후 admin password를 변경합니다. Argo CD CLI가 없다면 먼저 설치합니다.

brew install argocd

argocd login gitops.internal.tirosh.ai --grpc-web --prompts-enabled
argocd account update-password

DNS 경로가 준비된 뒤에는 Argo CD CLI도 gitops.internal.tirosh.ai로 직접 접속합니다. Caddy가 TLS를 종료하고 Traefik으로 프록시하므로, CLI에는 보통 --grpc-web만 추가하면 됩니다.

argocd login gitops.internal.tirosh.ai
  |
  v
Argo CD API over Ingress
  |
  v
argocd account update-password

같은 작업을 Make target으로 실행할 수도 있습니다. tirosh-home profile은 argocd.server = "gitops.internal.tirosh.ai", argocd.login_args = "--grpc-web --prompts-enabled", argocd.auto_port_forward = false를 기본값으로 사용합니다.

make argocd/password/update SITE=tirosh-home

Make target의 기본값은 아래와 같습니다.

• KUBECONFIG: profile.toml의 kube.kubeconfig
• KUBECTX: profile.toml의 kube.contexts.argocd
• ARGOCD_SERVER: profile.toml의 argocd.server
• ARGOCD_LOGIN_ARGS: profile.toml의 argocd.login_args
• ARGOCD_AUTO_PORT_FORWARD: profile.toml의 argocd.auto_port_forward

다른 kubeconfig나 context를 명시하려면 아래처럼 지정합니다.

make argocd/password/update SITE=tirosh-home KUBECONFIG=$HOME/.kube/config KUBECTX=tirosh-home/k3s

현재 Argo CD server는 Ingress 뒤에서 HTTP로 동작하도록 argocd_server_insecure: true를 사용합니다. 내부 DNS 경로에서는 Caddy가 HTTPS를 종료하므로 gitops.internal.tirosh.ai로 접속하고, port-forward fallback에서는 plaintext local endpoint를 사용합니다.

DNS/Ingress가 준비되지 않았을 때는 port-forward fallback을 명시적으로 켭니다.

make argocd/password/update SITE=tirosh-home \
  ARGOCD_SERVER=127.0.0.1:8080 \
  ARGOCD_LOGIN_ARGS='--plaintext --skip-test-tls --prompts-enabled' \
  ARGOCD_AUTO_PORT_FORWARD=true

password 변경이 실패하면 먼저 세 가지를 확인합니다.

• kubectl --context tirosh-home/k3s get pods -n argocd
• argocd login gitops.internal.tirosh.ai --grpc-web --prompts-enabled
• argocd version --client

7. Workload cluster 등록¶

RKE2 kubeconfig가 ~/.kube/config에 merge되어 있으면 Argo CD에 workload cluster로 등록할 수 있습니다.

이 단계는 RKE2 cluster에 workload를 바로 배포하는 단계가 아닙니다. Argo CD가 RKE2 Kubernetes API에 접근할 수 있도록 cluster credential과 RBAC를 등록하는 단계입니다.

local kubeconfig
  tirosh-home/rke2/gpu context
  |
  v
argocd cluster add
  |
  v
RKE2 cluster에 Argo CD용 ServiceAccount/RBAC 생성
  |
  v
Argo CD secret에 cluster credential 저장
  |
  v
Argo CD UI에서 cluster 표시

7-1. context 확인¶

이 단계에서는 두 context가 모두 필요합니다.

KUBECTX
  Argo CD가 설치된 management cluster
  기본값: tirosh-home/k3s

CLUSTER_KUBECTX
  Argo CD에 등록할 workload cluster
  기본값: tirosh-home/rke2/gpu

등록 전에 두 context가 모두 동작하는지 확인합니다.

kubectl --context tirosh-home/k3s get pods -n argocd
kubectl --context tirosh-home/rke2/gpu get nodes

7-2. cluster add¶

DNS 경로를 기준으로 workload cluster를 등록합니다. 먼저 Argo CD CLI가 gitops.internal.tirosh.ai에 로그인되어 있어야 합니다.

argocd login gitops.internal.tirosh.ai --grpc-web --prompts-enabled

argocd cluster add tirosh-home/rke2/gpu \
  --kubeconfig ~/.kube/config \
  --name tirosh-home-rke2-gpu \
  --yes \
  --upsert

argocd cluster list

argocd cluster add가 참조하는 workload cluster context는 로컬 ~/.kube/config에 있어야 합니다.

tirosh-home의 기본값은 sites/tirosh-home/profile.toml에서 가져옵니다.

• kubeconfig: ~/.kube/config
• Argo CD management context: tirosh-home/k3s
• 등록할 workload context: tirosh-home/rke2/gpu
• Argo CD cluster name: tirosh-home-rke2-gpu

Make target을 사용해도 같은 기본값을 사용합니다. tirosh-home에서는 DNS 경로인 gitops.internal.tirosh.ai로 Argo CD server에 접속합니다.

make argocd/cluster/add SITE=tirosh-home

DNS/Ingress가 준비되지 않았을 때는 port-forward fallback을 명시적으로 켭니다.

make argocd/cluster/add SITE=tirosh-home \
  ARGOCD_SERVER=127.0.0.1:8080 \
  ARGOCD_LOGIN_ARGS='--plaintext --skip-test-tls --prompts-enabled' \
  ARGOCD_AUTO_PORT_FORWARD=true

다른 cluster를 등록할 때는 필요한 값만 override합니다.

argocd cluster add <workload-context> \
  --kubeconfig ~/.kube/config \
  --name <argocd-cluster-name> \
  --yes \
  --upsert

등록 후에는 Argo CD와 Kubernetes 양쪽에서 확인합니다.

argocd cluster list
kubectl --context tirosh-home/rke2/gpu get serviceaccount -A | grep argocd

cluster 이름은 Argo CD에서 사람이 구분하기 위한 표시 이름입니다. Kubernetes context 이름과 같을 필요는 없지만, 운영자가 헷갈리지 않도록 site와 cluster 성격이 드러나게 정합니다.

8. GitHub repository 연결¶

Argo CD가 cluster를 알고 있어도, 배포할 manifest나 Helm chart가 들어 있는 Git repository를 모르면 Application을 동기화할 수 없습니다. GitHub repository 연결은 Argo CD가 GitHub에서 source를 읽을 수 있게 credential을 등록하는 단계입니다.

GitHub repository
  |
  v
Argo CD repository credential
  |
  v
Argo CD Application source
  |
  v
workload cluster sync

이 저장소에는 GitHub token, deploy key, password를 커밋하지 않습니다. credential은 로컬 shell에서 입력하거나, 나중에 별도 secret 관리 방식으로 옮깁니다.

8-1. 접속 준비¶

repository 연결은 Argo CD API에 접근해야 하므로 먼저 Argo CD CLI가 로그인할 수 있어야 합니다. Ingress와 DNS가 준비되어 있으면 gitops.internal.tirosh.ai로 직접 로그인합니다.

argocd login gitops.internal.tirosh.ai --grpc-web --prompts-enabled

Ingress를 사용하지 않는 경우에만 port-forward를 띄우고 local endpoint로 로그인합니다.

make argocd/port-forward SITE=tirosh-home

argocd login 127.0.0.1:8080 \
  --username admin \
  --plaintext \
  --skip-test-tls \
  --prompts-enabled

repository 연결은 아직 Make target이 없으므로 argocd repo add를 직접 사용합니다.

8-2. Public repository¶

public repository는 credential 없이 HTTPS URL만 등록할 수 있습니다.

argocd repo add https://github.com/tirosh-chain/tirosh-gitops.git
argocd repo list

이 방식은 가장 단순하지만 private repository에는 사용할 수 없습니다.

8-3. Private repository with token¶

private repository는 GitHub token을 사용하는 HTTPS 방식이 가장 이해하기 쉽습니다.

GitHub에서 fine-grained personal access token을 만들고, 대상 repository 권한을 부여합니다. organization repository라면 SSO 승인이 필요한지도 확인합니다.

권한은 사용 목적에 따라 다릅니다.

• Argo CD sync only: Contents: Read-only
• Argo CD Image Updater git write-back: Contents: Read and write
• Image Updater pull request mode: Contents: Read and write, Pull requests: Read and write

로컬 shell에서 token을 입력받아 등록합니다.

read -s GITHUB_TOKEN

argocd repo add https://github.com/tirosh-chain/tirosh-gitops.git \
  --name tirosh-gitops \
  --username <github-username> \
  --password "$GITHUB_TOKEN" \
  --upsert

unset GITHUB_TOKEN

여기서 --name은 Argo CD 안에서 repository credential을 구분하기 위한 이름입니다. Application의 repoURL은 이름이 아니라 repository URL을 그대로 사용합니다.

source:
  repoURL: https://github.com/tirosh-chain/tirosh-gitops.git

--username은 GitHub 사용자명이고, --password에는 GitHub account password가 아니라 token을 넣습니다. 기존 repository 설정을 수정할 때 credential이 빠지면 Invalid username or token 또는 Password authentication is not supported for Git operations 오류가 발생할 수 있으므로, --upsert할 때도 token을 함께 넘깁니다.

8-4. Private repository with deploy key¶

특정 repository 하나만 읽게 하고 싶다면 SSH deploy key 방식도 사용할 수 있습니다. GitHub repository의 Settings > Deploy keys에 public key를 등록합니다.

Argo CD sync only라면 Allow write access는 끕니다. Argo CD Image Updater가 같은 deploy key로 git write-back을 해야 한다면 Allow write access를 켜야 합니다.

ssh-keygen -t ed25519 -f ~/.ssh/argocd-github-tirosh-gitops -C argocd-github-tirosh-gitops

public key를 GitHub deploy key로 등록한 뒤 Argo CD에 private key를 넘깁니다.

argocd repo add git@github.com:tirosh-chain/tirosh-gitops.git \
  --name tirosh-gitops \
  --ssh-private-key-path ~/.ssh/argocd-github-tirosh-gitops

SSH host key 검증 문제가 나면 GitHub host key를 Argo CD에 추가합니다.

ssh-keyscan github.com > /tmp/github-known-hosts
argocd cert add-ssh github.com --from /tmp/github-known-hosts

8-5. 연결 확인¶

등록된 repository를 확인합니다.

argocd repo list
argocd repo get https://github.com/tirosh-chain/tirosh-gitops.git

SSH URL로 등록했다면 같은 URL로 확인합니다.

argocd repo get git@github.com:tirosh-chain/tirosh-gitops.git

정상이라면 repository connection 상태가 Successful로 표시됩니다. CREDS가 false로 보이면 credential 없이 접근 중이라는 뜻입니다. private repository 또는 Image Updater write-back repository에서는 credential이 등록되어 있어야 합니다.

실패하면 URL, credential 권한, GitHub organization SSO, SSH deploy key 등록 여부를 먼저 확인합니다.

8-6. 운영 기준¶

처음에는 argocd repo add로 수동 등록해도 됩니다. 다만 운영 단계에서는 repository credential도 선언적으로 관리하는 편이 좋습니다.

권장 기준은 아래와 같습니다.

• public repo는 credential 없이 HTTPS URL 사용
• private repo는 최소 권한 token 또는 read-only deploy key 사용
• token과 private key는 git에 커밋하지 않음
• write 권한이 필요한 자동화가 아니라면 read-only 권한 유지
• Argo CD Image Updater를 사용할 때는 GitOps 상태가 Git에 남도록 git write-back 사용
• 여러 repository를 관리하게 되면 Argo CD repository credential template 또는 External Secrets 같은 별도 secret 관리로 전환

9. Argo CD Image Updater¶

CI가 container image를 build/push한 뒤에는 어떤 image tag 또는 digest를 배포할지 GitOps repository에 기록해야 합니다. 이 repo에서는 Argo CD Image Updater를 사용하고, GitOps 원칙에 맞게 git write-back 또는 git PR write-back 방식을 기본으로 봅니다.

CI
  |
  v
container image push
  |
  v
Argo CD Image Updater
  |
  v
GitOps repository에 image version commit 또는 PR
  |
  v
Argo CD sync

9-1. 운영 원칙¶

• Argo CD는 Git을 읽고 cluster에 sync합니다.
• Image Updater는 새 image version을 찾고 GitOps repository에 commit하거나 PR을 만듭니다.
• 배포 version의 source of truth는 GitOps repository입니다.
• latest 같은 mutable tag보다 semver tag 또는 digest 기반 운영을 우선합니다.
• cluster 안의 Argo CD Application만 직접 바꾸는 argocd write-back은 Git에 기록이 남지 않으므로 기본값으로 쓰지 않습니다.
• dev는 자동 image update와 자동 sync를 허용할 수 있습니다.
• stg, prd는 PR, 수동 tag/digest 변경, 수동 sync 같은 승격 gate를 둡니다.

Argo CD Image Updater v1 계열은 Application annotation보다 ImageUpdater CRD를 기본 구성 단위로 사용합니다. Image Updater controller와 ImageUpdater CR은 Argo CD Application 리소스가 있는 management cluster에 둡니다. tirosh-home에서는 Argo CD Application이 argocd namespace에 있으므로 Image Updater도 argocd namespace에 설치합니다.

9-2. GitHub 권한¶

Argo CD가 repository를 읽기만 하면 Contents: Read-only면 충분합니다. Image Updater가 Git에 commit/push하거나 PR을 만들려면 write 권한이 필요합니다.

목적	권한
Argo CD sync only	Contents: Read-only
Image Updater git write-back	Contents: Read and write
Image Updater pull request mode	Contents: Read and write, Pull requests: Read and write

write 권한은 Argo CD 전체 credential에 넓게 주기보다, 가능하면 Image Updater용 credential로 분리합니다.

tirosh-home에서는 credential 값을 GitOps repository에 커밋하지 않습니다. 로컬 .env나 shell environment에서 값을 읽어 Kubernetes Secret을 생성합니다.

Argo CD는 Git repository의 manifest를 읽고 cluster에 sync할 뿐, workload container image를 직접 pull하지 않습니다. Private image pull은 workload가 실행되는 namespace의 Pod 또는 ServiceAccount imagePullSecrets가 담당합니다. Argo CD Image Updater는 별도로 registry tag를 조회해야 하므로, controller가 실행되는 argocd namespace에도 registry credential Secret을 둡니다.

make kubernetes/secret/plan SITE=tirosh-home \
  KUBERNETES_SECRET=argocd-image-updater-gitops-writeback

make kubernetes/secret/apply SITE=tirosh-home \
  KUBERNETES_SECRET=argocd-image-updater-gitops-writeback

make kubernetes/secret/plan SITE=tirosh-home \
  KUBERNETES_SECRET=argocd-image-updater-ghcr-pull

make kubernetes/secret/apply SITE=tirosh-home \
  KUBERNETES_SECRET=argocd-image-updater-ghcr-pull

필요한 환경 변수는 아래와 같습니다.

Secret	Environment variables
argocd-image-updater-gitops-writeback	GITOPS_WRITEBACK_USERNAME, GITOPS_WRITEBACK_TOKEN
argocd-image-updater-ghcr-pull	GHCR_USERNAME, GHCR_PULL_TOKEN

9-3. Write-back 방식¶

기본 운영은 Git write-back입니다. dev처럼 자동 배포를 허용하는 환경은 tracked branch에 직접 commit할 수 있고, 승격 gate가 필요한 환경은 PR mode를 사용합니다.

writeBackConfig:
  method: git

Git write-back은 Application이 바라보는 Git branch에 변경을 commit하거나, pullRequest가 설정된 경우 해당 branch로 향하는 PR을 만듭니다. 따라서 Argo CD Application의 targetRevision은 고정 commit SHA나 tag보다 branch를 쓰는 편이 자연스럽습니다.

write-back target은 배포 manifest 구조에 맞춰 정합니다.

• Helm: values file의 image tag 또는 digest 값을 갱신
• Kustomize: kustomization image 값을 갱신
• Argo CD source parameter: .argocd-source-<appName>.yaml 사용

현재 tirosh-gitops의 Nexus backup image는 Kustomize images 항목으로 관리하므로, 파일럿 대상은 writeBackTarget: kustomization:/clusters/tirosh-home/k3s/platform/nexus를 사용합니다. 이 파일럿은 platform workload이므로 직접 main에 push하지 않고 GitHub PR mode로 둡니다.

9-4. 배포 위치¶

Argo CD Image Updater 자체는 cluster desired state이므로 tirosh-gitops가 배포 manifest를 소유합니다.

이 repo(tirosh-infra)는 아래를 소유합니다.

• Argo CD bootstrap과 cluster registration
• Image Updater 운영 모델
• GitHub 권한 기준
• Secret registry와 Make interface
• 검증 및 운영 문서

tirosh-gitops는 아래를 소유합니다.

• Image Updater Application
• Image Updater controller manifest 또는 Kustomize overlay
• ImageUpdater CR
• workload별 update strategy와 write-back target

9-5. 확인 포인트¶

Image Updater를 붙인 뒤에는 아래를 확인합니다.

• registry에 새 image tag 또는 digest가 생겼는가
• Image Updater가 해당 image를 감지했는가
• GitOps repository에 image version 변경 commit이 생겼는가
• Argo CD Application이 새 commit을 sync했는가
• workload cluster의 Pod image가 기대한 version으로 바뀌었는가

10. 문제 확인¶

Argo CD 설치나 cluster 등록이 실패하면 먼저 context와 namespace를 확인합니다.

10-1. management cluster 확인¶

kubectl --context tirosh-home/k3s get nodes
kubectl --context tirosh-home/k3s get pods -n argocd

10-2. workload cluster 확인¶

kubectl --context tirosh-home/rke2/gpu get nodes
kubectl --context tirosh-home/rke2/gpu get pods -A

10-3. repository 확인¶

GitHub repository 연결이 실패하면 Argo CD CLI 기준으로 먼저 확인합니다.

argocd repo list
argocd repo get https://github.com/tirosh-chain/tirosh-gitops.git

private repository에서 인증이 실패하면 GitHub token의 repository 접근 권한, organization SSO 승인, deploy key 등록 여부를 확인합니다. Invalid username or token 또는 Password authentication is not supported for Git operations 메시지가 나오면 GitHub account password가 아니라 token 또는 SSH key credential로 다시 등록합니다.

10-4. k9s로 보기¶

터미널에서 상태를 볼 때는 k9s를 사용할 수 있습니다.

k9s --context tirosh-home/k3s --namespace argocd
k9s --context tirosh-home/rke2/gpu

11. 다음 단계¶

11-1. 후속 개선 항목¶

첫 버전에서는 Argo CD 설치, repository 연결, cluster registration까지 다룹니다. 이후 단계에서 아래 항목을 추가합니다.

• Argo CD Application 또는 app-of-apps 구조
• Argo CD Image Updater 설치와 site별 ImageUpdater manifest
• TLS와 DNS 고도화
• repository credential 선언적 관리
• SSO와 RBAC