TL;DR

  • KubeZap은 쿠버네티스에서 CRD로 이벤트 기반 자동화를 선언하며, 웹 UI·전용 런타임·벤더 종속성 없이 클러스터 안에서 워크플로를 실행하는 도구임.
  • 웹훅, Kafka, 크론, 쿠버네티스 리소스 이벤트를 트리거로 사용하고, HTTP 호출·데이터 변환·조건 분기·대기·재시도를 YAML로 정의함.
  • 인증 정보는 컨트롤러가 메모리에서 처리하고 권한이 제한된 HTTP 실행기 파드에 전달하며, etcd나 별도 워크플로 데이터베이스에 저장되지 않음.
  • 워크플로 모델은 Trigger → Flow → FlowRun의 세 CRD로 구성되며, 각 실행을 쿠버네티스 객체로 조회할 수 있음.
  • 원시 매니페스트, Helm, OperatorHub/OLM으로 설치할 수 있고, 관측성·CLI·다중 네임스페이스·보안 기능을 제공함.

KubeZap 소개

  • KubeZap은 쿠버네티스용 선언형 워크플로 자동화 도구임.
  • 이벤트 기반 자동화를 CRD로 정의하며, 웹 UI·독점 런타임·벤더 종속성이 없음.
  • 웹훅, Kafka 메시지, 크론 일정, 쿠버네티스 리소스 이벤트를 트리거로 사용할 수 있음.
  • HTTP 호출, 데이터 변환, 조건 분기, 시간 대기, 재시도 정책을 포함한 다단계 흐름을 YAML로 선언하고 인프라 코드와 함께 버전 관리함.

KubeZap을 선택하는 이유

  • 인증 정보는 클러스터의 신뢰 경계 밖으로 나가지 않음.
  • 컨트롤러가 시크릿을 메모리에서 확인하고, 완전히 치환된 요청을 권한이 낮은 전용 HTTP 실행기 파드에 전달함.
  • HTTP 실행기에는 쿠버네티스 API 접근 권한이 없고, 시크릿 RBAC도 없으며, 별도의 SSRF 보호 기능이 있음.
  • API 키는 etcd에 기록되지 않으며 별도의 워크플로 데이터베이스에도 저장되지 않음.
  • 워크플로 모델은 세 CRD인 Trigger → Flow → FlowRun으로 구성되는 단일 모델임.
  • 모든 실행은 실제 쿠버네티스 객체이므로 어떤 이벤트가 실행을 촉발했는지, 각 단계가 무엇을 했는지, 이유가 무엇인지 kubectl get으로 처음부터 끝까지 확인할 수 있음.

설치

사전 요구 사항

  • Kubernetes 1.27 이상 또는 k3s / OpenShift 4.12 이상
  • 대상 클러스터에 맞게 설정된 kubectl
  • kustomize v5 이상 또는 이를 포함하는 kubectl 1.27 이상

원시 매니페스트

  • CRD를 config/crd에서 적용하고, 오퍼레이터를 config/default에서 배포하는 방식임.
  • 컨트롤러는 kubezap-system 네임스페이스에서 시작하며, 해당 네임스페이스의 파드 목록으로 실행 상태를 확인함.

Helm 차트

  • oci://ghcr.io/kubezap/charts/kubezap-operator 차트를 사용해 kubezap-system 네임스페이스에 설치할 수 있으며, 네임스페이스가 없으면 생성하는 방식임.
  • docs/overview.md에서 설치 모드(OwnNamespace, SingleNamespace, MultiNamespace)와 이미지 재정의 예제를 확인할 수 있음.

OperatorHub / OLM

  • KubeZap은 일반 쿠버네티스용 커뮤니티 OperatorHub(k8s-operatorhub/community-operators)에 등록되어 있음.
  • OperatorHub.io의 “Install” 버튼을 통해 대상 네임스페이스에 사용할 Subscription을 생성하는 방식으로 설치함.

로컬 개발

  • docs/contributing.md에 빌드 안내, 로컬 k3s 설정, 단위 테스트와 엔드투엔드(e2e) 테스트 실행 방법이 있음.

빠른 시작

  • 오퍼레이터 실행 후 default 네임스페이스에 Trigger와 Flow 리소스를 정의함.
  • 예시 Trigger는 automation.kubezap.io/v1alpha1 API를 사용하고, my-webhook이라는 이름으로 /hooks/my-webhook 경로의 POST 웹훅을 활성화하며 my-flow를 참조함.
  • 예시 Flow는 my-flow라는 이름으로 HTTP POST 단계를 정의하고, https://httpbin.org/post에 trigger.body.event 값을 포함한 JSON 본문을 전송함.
  • 두 매니페스트를 적용한 뒤 게이트웨이의 8080 포트에서 /hooks/my-webhook으로 {"event": "hello"}를 전송해 테스트 이벤트를 보낼 수 있음.
  • default 네임스페이스의 FlowRun 목록과 개별 FlowRun의 .status.phase를 조회해 실행 결과를 확인함.
  • 전체 단계별 안내는 examples/order-router/에서 확인할 수 있음.

문서

  • Overview: 아키텍처, 핵심 개념, CRD 참조
  • Getting Started: 웹훅 → 변환 → 조건부 알림 단계별 안내
  • Examples: 실행 가능한 예제 매니페스트와 단계별 지침
  • Flow CRD: HTTP, 변환, 게시, 대기 등 단계 작업 전체 참조
  • FlowRun CRD: 실행 모델, 가비지 컬렉션(GC), 상태 필드
  • Integration CRD: Kafka, 플러그인 프로토콜
  • Webhook Security: HMAC, 베어러, OIDC, API 키, IP 허용 목록, mTLS
  • Observability: Prometheus 메트릭, OpenTelemetry 트레이스, 액세스 로그

기능

  • 트리거 유형: 웹훅(HTTP), 크론, Kafka pub/sub, AMQP(베타), NATS JetStream(베타), 쿠버네티스 리소스 이벤트(알파)
  • 단계 작업: HTTP 호출, CEL 데이터 변환, 조건 분기, 시간 대기, Kafka 게시
  • 실행: 의존성 순서에 따른 DAG, 단계별 지수 백오프 재시도, 단계 및 전체 흐름 시간 제한
  • FlowRun GC: TTL 기반 정리, kubezap.io/retain 어노테이션, Trigger별 FlowRun 최대 개수 제한
  • 웹훅 인증: HMAC, 베어러 토큰, OIDC/JWT, API 키 헤더, IP 허용 목록, mTLS
  • 관측성: Prometheus 메트릭, OTLP/gRPC 기반 OpenTelemetry 트레이스, 구조화된 JSON 액세스 로그
  • CLI: kubezap 명령의 watch, history, triggers, flows 하위 명령
  • 다중 네임스페이스: WATCH_NAMESPACES에서 MultiNamespace, SingleNamespace, OwnNamespace 지원
  • OLM: CSV 번들에서 OwnNamespace, SingleNamespace, MultiNamespace 지원
  • 보안: distroless 이미지, 비루트 실행, 읽기 전용 루트 파일 시스템, restricted SCC 호환, 메모리 내 인증 정보 처리 및 etcd나 워크플로 데이터베이스에 미저장

도움말

  • 질문, 아이디어, 제작물 공유에는 GitHub Discussions를 사용하며, 질의응답·기능 아이디어·커뮤니티 공유를 위한 공간임.
  • 버그는 이슈로 제보함.

라이선스

  • Apache 2.0