이벤트가 워크플로가 되기까지, 차트가 매니페스트가 되기까지

한 줄 요약

Argo Events 는 EventSource 가 바깥 사건을 CloudEvents 로 바꿔 EventBus 에 싣고, Sensor 가 그것을 의존성으로 받아 Trigger 를 실행하는 네 부품으로 돕니다. Argo CD 는 Helm 을 helm template 으로 매니페스트를 부풀리는(inflate) 데만 쓰고 수명주기는 직접 관리하며, path 에 kustomization.yaml 이 있으면 Kustomize 로 렌더합니다.

왜 이게 필요했나

"저장소에 push 되면 파이프라인을 돌려라", "S3 에 파일이 오면 처리 워크플로를 띄워라" 같은 요구는 사건(event)이 먼저 있고 그다음 실행이 옵니다. 워크플로 엔진 자체는 사건을 듣지 않습니다. Argo Events 는 이 앞단을 맡아 20개가 넘는 이벤트 소스(웹훅, S3, 일정, 메시지 큐, GCP PubSub, SNS, SQS 등)에서 사건을 받아 Kubernetes 오브젝트·Argo Workflow·서버리스 워크로드를 실행합니다. CAPA 의 Events 도메인(12%)은 이 네 구성요소가 각각 무엇을 맡고 사건이 어떤 순서로 흐르는지를 묻습니다.

Argo CD 쪽의 문제는 다릅니다. 팀은 Helm 차트나 Kustomize 오버레이로 배포물을 관리하는데, Argo CD 가 그것을 어떻게 매니페스트로 바꾸는지 모르면 "values 를 바꿨는데 반영이 안 된다", "앱이 계속 OutOfSync 다" 같은 문제의 원인을 찾지 못합니다. Argo CD 도메인(34%)의 Helm & Kustomize 항목이 이 부분입니다.

어떻게 동작하나

Argo Events 의 네 부품

| 구성요소 | 역할 | 문서의 정의 |
| --- | --- | --- |
| EventSource | 바깥 사건을 받아 CloudEvents 로 변환해 EventBus 로 보냄 | AWS SNS·SQS·PubSub·Webhook 등 외부 소스에서 사건을 소비하는 설정 |
| EventBus | EventSource 와 Sensor 를 잇는 전송 계층 | NATS(폐기 예정), Jetstream, Kafka 세 구현 |
| Sensor | 이벤트 의존성(입력)과 트리거(출력)의 집합 | EventBus 를 듣고 의존성이 풀리면 트리거를 실행하는 의존성 관리자 |
| Trigger | 의존성이 풀렸을 때 실행되는 리소스·워크로드 | Argo Workflow, K8s 오브젝트, HTTP, Lambda, Kafka/NATS 메시지, Slack, Argo Rollouts, Log 등 |

흐름은 이렇습니다. 웹훅 EventSource 를 만들면 event-source 파드와 서비스가 생기고(예제는 12000 포트), 여기에 POST 하면 사건이 CloudEvents 로 바뀌어 EventBus 에 실립니다. Sensor 는 dependencies 에 "어느 EventSource 의 어느 이벤트" 를 기다리는지 적고, triggers 에 무엇을 실행할지 적습니다. 트리거된 워크플로의 로그에는 사건의 context(type, source, eventID, time, subject)와 base64 로 인코딩된 data 가 함께 찍힙니다. 파라미터화(parameterization)로 사건의 특정 키를 꺼내 워크플로 인자로 넘길 수 있고, 트리거 정책(policy)으로 실행된 오브젝트의 상태를 보고 계속할지 멈출지 정합니다.

EventBus 는 네임스페이스 리소스이고, EventSource 와 Sensor 가 동작하려면 그 네임스페이스에 EventBus 가 있어야 합니다. 관례는 default 라는 이름으로 하나 두는 것이고, 다른 이름을 쓰거나 여러 개를 두려면 EventSource 와 Sensor 의 spec 에 eventBusName 을 적어 짝을 맞춥니다. 워크플로 로직이 이미 WorkflowTemplate 에 있으면 Sensor 가 단계를 다시 적을 필요 없이 workflowTemplateRef 로 참조하는 Workflow 를 제출합니다.

triggers:- template:    name: argo-workflow-trigger    argoWorkflow:      operation: submit      source:        resource:          apiVersion: argoproj.io/v1alpha1          kind: Workflow          metadata: {generateName: from-template-}          spec:            workflowTemplateRef: {name: workflow-template-print-message}

Argo CD 와 Helm — 부풀리기만 한다

문서의 한 문장이 핵심입니다. "Helm 은 helm template 으로 차트를 부풀리는 데만 쓰이고, 애플리케이션의 수명주기는 Helm 이 아니라 Argo CD 가 관리한다." Helm 저장소의 차트는 source.chart 와 repoURL, targetRevision 으로 지정하고(OCI 는 oci:// 접두어 없이), Git 에 있는 차트는 path 로 지정합니다. values 를 주는 방법은 여럿이고 우선순위가 정해져 있습니다.

낮음  valueFiles  →  values  →  valuesObject  →  parameters  높음      (여러 파일이면 뒤에 적은 파일이 이김)        (차트의 values.yaml 은 그보다 아래)

valueFiles 는 여러 개를 적을 수 있고 뒤에 적은 파일이 앞을 덮습니다. 없는 파일이 있으면 Helm 이 오류를 내는데 ignoreMissingValueFiles: true 로 무시할 수 있어 "기본 + 있으면 덮어쓰기" 패턴에 씁니다. glob(envs/*.yaml)은 사전순으로 펼쳐지므로 00-defaults.yaml, 10-region.yaml 처럼 숫자 접두어로 순서를 드러내는 것이 권장됩니다. 차트와 다른 저장소의 values 는 다중 소스(sources[].ref 와 $ref/path)로 가져옵니다. parameters 는 --set 에 해당하며 forceString 으로 문자열 취급을 강제할 수 있고, fileParameters 는 --set-file 입니다.

함정 세 가지를 문서에서 옮깁니다. 첫째, 릴리스 이름은 기본으로 Application 이름과 같고, releaseName 으로 바꾸면 Argo CD 가 추적용으로 붙이는 app.kubernetes.io/instance 라벨과 어긋나 셀렉터가 깨질 수 있습니다. 둘째, Argo CD 는 첫 설치인지 업그레이드인지 구분하지 못하고 모든 작업이 sync 이므로 pre-install 과 pre-upgrade 훅이 동시에 돕니다. Argo CD 훅을 하나라도 정의하면 Helm 훅은 전부 무시됩니다. 셋째, randAlphaNum 으로 값을 만드는 차트는 비교할 때마다 값이 달라져 항상 OutOfSync 이므로 값을 고정해야 합니다. CRD 를 차트가 설치하지 않게 하려면 skipCrds: true 를 씁니다.

Argo CD 와 Kustomize

repoURL 과 path 가 가리키는 곳에 kustomization.yaml 이 있으면 Argo CD 는 Kustomize 로 렌더합니다. 오버레이를 쓰려면 path 를 오버레이 디렉터리로 잡습니다. Application 의 source.kustomize 에는 namePrefix, nameSuffix, images(이미지 덮어쓰기), replicas, commonLabels, commonAnnotations, namespace, patches, components(2.10 부터) 등을 적을 수 있습니다. patches 는 Kustomization 파일의 patches 와 같은 논리로 동작하며 기존 patches 에 병합됩니다. 문서는 ApplicationSet 과 함께 쓰는 예를 들어, 클러스터마다 오버레이를 만드는 대신 템플릿의 kustomize.patches 에 생성기 속성({{.name}})을 넣어 한 번에 해결하는 방법을 보여 줍니다. 원격 base 가 비공개이면 앱 저장소의 자격증명을 물려받되, 다른 자격증명이 필요한 저장소에는 접근하지 못합니다.

source:  path: kustomize-guestbook  repoURL: https://github.com/argoproj/argocd-example-apps.git  targetRevision: master  kustomize:    patches:    - target: {kind: Deployment, name: guestbook-ui}      patch: |-        - op: replace          path: /spec/template/spec/containers/0/ports/0/containerPort          value: 443

현장에서 만나는 모습

Argo Events 에서 가장 흔한 첫 장애는 "EventSource 와 Sensor 를 만들었는데 파드가 안 뜬다" 입니다. 문서의 문제 해결 절차는 EventSource 와 Sensor 오브젝트의 Status 를 먼저 보고, 서비스 계정의 Role/RoleBinding 을 확인하고, 두 컨트롤러의 로그를 보는 것입니다. 네임스페이스에 EventBus 가 없으면 아무것도 동작하지 않으니 그것부터 확인합니다.

Argo CD 에서는 "UI 에서 values 가 다 안 보인다" 는 문의가 옵니다. 문서에 알려진 버그로 적혀 있는데, UI 는 parameters 만 보여 주고 values/valuesObject 로 넣은 값은 표시하지 않습니다. 렌더는 정확히 되므로 값이 빠진 것은 아니며, 문서는 한눈에 보이게 하려면 parameters 를 쓰라는 우회책을 제시합니다.

다음 퀴즈에서 확인할 것

네 구성요소의 역할과 EventBus 의 세 구현, EventBus 가 네임스페이스 리소스라는 점과 eventBusName, Helm values 의 우선순위와 ignoreMissingValueFiles, releaseName 을 바꿀 때의 라벨 문제, 훅과 randAlphaNum 의 함정, Kustomize 감지 조건과 kustomize.patches 를 묻습니다. 참고: [Argo Events Architecture](https://argoproj.github.io/argo-events/concepts/architecture/), [EventBus](https://argoproj.github.io/argo-events/eventbus/eventbus/), [Sensor](https://argoproj.github.io/argo-events/concepts/sensor/), [Argo CD Helm](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/), [Argo CD Kustomize](https://argo-cd.readthedocs.io/en/stable/user-guide/kustomize/).