jongminchungtech
EN
ReferenceKubernetes

rke2spray와 GitOps 운영 참조

현재 코드가 선언한 RKE2 클러스터, Ansible 수명주기, GitOps 인계, 애플리케이션과 검증 계약을 조회합니다.

업데이트 검증 근거 자료이 페이지 편집

핵심 요약

  • rke2spray는 호스트, RKE2, 클러스터 기반 AddOn과 Argo CD bootstrap을 소유함
  • GitOps 저장소는 Root Application 이후의 플랫폼, 데이터, 관측성과 스토리지 리소스를 소유함
  • 클러스터별 RKE2, CNI, 토폴로지와 네트워크 값은 inventory/<cluster>/에서 선언됨
  • GitOps는 root bootstrap을 포함한 15개 Argo CD Application과 총 299Gi의 애플리케이션 PVC를 검증함
  • NFS endpoint, 외부 L4 load balancer와 외부 backup 부재가 현재 가용성·복구 경계를 구성함

문서 범위와 기준

  • 검증 기준일은 2026-08-30이며 두 저장소의 현재 main 코드를 기준으로 함
    • rke2spray 기준 저장소는 jongminchung/rke2spray임
    • GitOps 기준은 대상 저장소의 bootstrap/, apps/와 tests/ 코드임
    • README와 실행 코드가 다르면 Inventory, Playbook, manifest와 검증 script를 우선함
조회 대상기준 코드
클러스터 버전·토폴로지rke2spray/inventory/<cluster>/
Ansible 공개 APIrke2spray/cluster.yml, root Playbook과 Makefile
Kubespray 호환 범위rke2spray/docs/kubespray-api-compatibility.yml
GitOps 인계 조건rke2spray/extra_playbooks/gitops_bootstrap.yml
Argo CD 애플리케이션bootstrap/templates/applications.yaml
Workload 선언값apps/
배포 완료 조건tests/integration/verify.sh

저장소 소유권

리소스 또는 상태소유 저장소소유 코드
호스트 준비와 system packagerke2sprayroles/bootstrap-os, roles/system_packages
RKE2 server·agent와 embedded etcdrke2sprayroles/kubernetes, roles/etcd
Cilium과 Gateway API 기반rke2sprayInventory와 roles/network_plugin
cert-manager, trust-manager와 external-dnsrke2sprayroles/kubernetes-apps/rke2_native
NFS CSI와 StorageClassrke2sprayroles/kubernetes-apps/rke2_native
Argo CD 설치와 Root Applicationrke2sprayroles/kubernetes-apps/argocd, extra_playbooks/gitops_bootstrap.yml
Namespace, NetworkPolicy와 플랫폼 기반GitOps 저장소apps/platform
PostgreSQL과 PoolerGitOps 저장소apps/data
ClickStack과 OpenTelemetryGitOps 저장소apps/observability
SeaweedFS와 S3 경로GitOps 저장소apps/storage
Rancher·HyperDX 공개 경로GitOps 저장소apps/platform-routes
  • 동일 Kubernetes 리소스의 동시 소유는 허용되지 않음
    • RKE2 manifest owner는 /var/lib/rancher/rke2/server/manifests/<owner>에 대응함
    • AddOn 소유권 이전은 native-addons-handoff의 owner·basename·checksum 검증을 사용함
    • ownership-only ledger 항목은 Kubernetes 리소스를 삭제하지 않고 소유권만 이전함
    • prune ledger 항목은 정확한 확인 문자열과 일치할 때만 제거 대상이 됨

rke2spray 클러스터 선언

토폴로지

항목선언 변수 또는 group
Inventory profileinventory/<cluster>/
RKE2 topologyrke2_topology_mode
Control planekube_control_plane Inventory group
Workerkube_node Inventory group
Datastoreembedded etcd 또는 rke2_external_datastore
Bootstrap hostrke2_bootstrap_server
Failure-domain labelrke2_failure_domain_mode
Registration endpointrke2_registration_address

버전과 네트워크

항목선언 변수
Kuberneteskube_version
RKE2rke2_version과 checksum release lock
CNIkube_network_plugin, cilium_version
RKE2 Cilium chartrke2_cilium_chart_url
kube-proxykube_proxy_remove
Cilium kube-proxy replacementcilium_kube_proxy_replacement
Gateway APIgateway_api_enabled, gateway_api_channel
Gateway exposurecilium_gateway_exposure_mode
Gateway 대상cilium_gateway_host_network_nodes
Pod CIDRkube_pods_subnet
Service CIDRkube_service_addresses
cert-managercert_manager_enabled, cert_manager_version
RKE2 ingress controllerrke2_ingress_controller

스토리지와 snapshot

항목선언 변수
Storage profilerke2_storage_profile
NFS endpointrke2_nfs_server, rke2_nfs_share
NFS versionrke2_nfs_version
RWO 계약rke2_storage_contract.durable_rwo
RWX 계약rke2_storage_contract.shared_rwx
local-path provisionerlocal_path_provisioner_enabled
etcd snapshot 주기rke2_etcd_snapshot_schedule_cron
etcd snapshot 보존 수rke2_etcd_snapshot_retention
etcd snapshot 압축rke2_etcd_snapshot_compress
  • durable-rwo와 shared-rwx는 workload 의도이며 현재는 동일한 NFS 장애 도메인을 사용함
  • Retain과 onDelete: retain은 PV 삭제를 제한하며 NFS 데이터 backup을 제공하지 않음

RKE2 native AddOn profile

Source역할
external-dns.yaml허용된 공개 DNS 레코드 관리
nfs-csi.yamlNFS CSI controller와 node plugin 관리
nfs-csi-pdb.yamlNFS CSI controller 가용성 정책 관리
reloader.yamlSecret·ConfigMap 변경 기반 rollout 관리
trust-manager.yaml클러스터 trust bundle 관리

rke2spray 운영 명령

  • 다음 target은 저장소 root의 Makefile을 기준으로 함
Target주요 입력동작
make check개발 도구lint, unit, contract, parity와 syntax 검사
make inventory-graphINVENTORY, VAULT_PASSWORD_FILE해석된 Inventory graph 출력
make inventory-vault-checkINVENTORY, VAULT_PASSWORD_FILESSH 없이 Vault 입력과 파일 권한 검사
make inventory-preflightInventory와 환경변수실제 노드의 토폴로지·포트·스토리지 사전 검사
make cluster-convergeInventory와 Vaultcluster.yml 실행
make cluster-healthInventory와 VaultAPI, Node, etcd와 service 상태 조회
make cluster-scale NODE=<node>worker 이름선택한 worker를 scale.yml로 수렴
make cluster-add-server NODE=<node>server 이름선택한 server를 cluster.yml --limit로 수렴
make cluster-upgrade갱신된 version lockcordon, drain, release 변경과 readiness 검사
make cluster-snapshot SNAPSHOT=<name>snapshot 이름수동 embedded-etcd snapshot 생성
make cluster-recover SERVER=<server> SNAPSHOT=<path>server와 절대 경로checksum 검증 후 control-plane 복구
make cluster-remove-node NODE=<node>node와 LB 제거 확인LB·etcd·Kubernetes Node와 RKE2 상태 제거
make cluster-rotate-certificatesInventory와 VaultRKE2 인증서 rotation 실행
make gateway-accessInventory와 VaultGateway 접근 계약 조회·검증
make gitops-bootstrapGitOps 입력과 Vault준비 gate 통과 후 Argo CD와 Root Application 적용
make gitops-integrationGITOPS_INTEGRATION_SCRIPTGitOps integration script를 bootstrap server에서 실행
  • cluster-reset, cluster-recover, cluster-remove-node, AddOn prune과 장애 검증은 파괴 가능 작업임
    • 각 target은 대상, 확인 문자열 또는 opt-in 환경변수를 요구함
    • server 제거 전 외부 LB의 80, 443, 6443, 9345 backend 제거 상태가 필요함
    • snapshot의 off-host 복사와 보관은 rke2spray 범위에 포함되지 않음

GitOps 인계 계약

Argo CD 선언

항목선언 값 또는 변수
Argo CD3.5.1
Argo CD Helm chart10.4.0
helm-secrets4.7.7
SOPS3.13.3
Repositoryargocd_gitops_repo_url
Revisionargocd_gitops_revision
Destinationargocd_gitops_destination_server
초기 설치 지연argocd_defer_install_until_platform_ready
일반 cluster 실행의 Root 적용argocd_apply_root_application

Bootstrap gate

  • extra_playbooks/gitops_bootstrap.yml은 다음 조건을 모두 검사함

    • RKE2 API /readyz 응답이 ok인 상태
    • 모든 RKE2 Node가 Ready인 상태
    • Cilium과 CoreDNS rollout이 완료된 상태
    • Gateway API CRD가 Established이고 Cilium GatewayClass가 Accepted인 상태
    • cert-manager와 NFS CSI rollout이 완료된 상태
    • NFS migration gate의 status, database status, StorageClass UID와 cluster UID가 일치하는 상태

  • 비밀정보는 Ansible Vault에서 Argo CD Secret으로 전달됨

    • Git repository용 read-only SSH private key
    • GitHub known-hosts 값
    • SOPS age private key
    • 평문 private key는 두 저장소에 저장되지 않음

GitOps 애플리케이션

Application inventory

ApplicationWaveSourcePrune
bootstraprootbootstrap/ charttrue
platform-40apps/platformtrue
cloudnative-pg-30chart 0.29.0true
clickstack-operators-30chart 1.1.0true
clickstack-20chart 3.1.1과 SOPS valuesfalse
postgresql-10apps/data/postgresqlfalse
rancher-10chart 2.14.3true
seaweedfs-database-9apps/storage/seaweedfs-databasefalse
seaweedfs-foundation-8apps/storage/seaweedfs-foundationtrue
seaweedfs-7chart 4.42.0false
seaweedfs-route-6apps/storage/seaweedfs-routetrue
otel-agent0OTel chart 0.170.0true
otel-cluster0OTel chart 0.170.0true
otel-gateway0OTel chart 0.170.0false
platform-routes1apps/platform-routestrue
  • Prune이 false인 Application은 finalizer를 사용하지 않음
  • Prune이 true인 Application은 resources-finalizer.argocd.argoproj.io를 사용함
  • 모든 Application은 automated sync와 selfHeal: true를 사용함

Workload topology

Workload현재 topology영속 용량
PostgreSQL3 instancesinstance당 10Gi
PgBouncer RW·RO각 2 instances없음
ClickHouse1 shard × 3 replicasreplica당 60Gi
Keeper3 replicasreplica당 2Gi
MongoDB3 replicasdata 5Gi, log 1Gi
HyperDX2 replicas없음
ClickStack ingestion2 replicas없음
OTel Agentworker별 DaemonSet없음
OTel Cluster Collector1 replica없음
OTel Gateway2 replicasreplica당 1Gi queue
SeaweedFS Master3 replicasreplica당 1Gi
SeaweedFS Volume3 replicasreplica당 20Gi
SeaweedFS Filer2 replicasCNPG metadata 사용
SeaweedFS S32 replicas없음
  • 애플리케이션 PVC 논리 합계는 299Gi이며 배포 상한은 400Gi임
  • PostgreSQL, ClickHouse, Keeper, MongoDB, SeaweedFS Master와 Volume은 서로 다른 세 worker에 분산됨

서비스와 공개 경로

ClusterIP 서비스

용도Endpoint
OTLP gRPCotel-gateway.observability.svc.cluster.local:4317
OTLP HTTPotel-gateway.observability.svc.cluster.local:4318
PostgreSQL RWpostgresql-pooler-rw.postgresql.svc.cluster.local:5432
PostgreSQL ROpostgresql-pooler-ro.postgresql.svc.cluster.local:5432
  • observability, postgresql과 seaweedfs의 데이터 서비스에는 NodePort와 LoadBalancer가 허용되지 않음

Gateway API 경로

HostnameBackendListener
<rancher-hostname>cattle-system/rancher:80apps-https
<observability-hostname>observability/clickstack-app:3000apps-https
<s3-hostname>seaweedfs/seaweedfs-s3:8333s3-root-https
<s3-wildcard-hostname>seaweedfs/seaweedfs-s3:8333s3-https

검증 계약

rke2spray 정적 검증

명령검사 범위
make checkYAML·Ansible lint, unit, Role interface, release lock, lifecycle, topology와 syntax
make parity고정된 Kubespray baseline과 공개 API parity
make inventory-vault-check.vault_pass mode와 Inventory Vault 값

GitOps 정적 검증

명령검사 범위
tests/static/validate.shpolicy, YAML·shell lint, gitleaks와 SOPS 암호화
tests/static/render.shbootstrap chart, 외부 chart와 Kustomize rendering
kubeconformKubernetes와 추출된 CRD schema

Live cluster 검증

  • tests/integration/verify.sh은 다음 상태를 완료 계약으로 사용함

    • 15개 Argo CD Application이 모두 Synced·Healthy인 상태
    • Stateful·stateless Application의 prune과 finalizer 정책이 일치하는 상태
    • 세 replica workload가 서로 다른 세 worker에서 Ready인 상태
    • 공개 금지 Service가 모두 ClusterIP인 상태
    • Pending Pod가 없고 모든 Node root filesystem 사용률이 60% 미만인 상태
    • durable-rwo가 nfs.csi.k8s.io, Immediate, Retain, onDelete=retain인 상태
    • 대상 PVC가 모두 durable-rwo를 사용하고 논리 합계가 299Gi인 상태
    • Gateway HTTPRoute가 Accepted=True·ResolvedRefs=True인 상태

  • 쓰기·삭제를 포함하는 검증은 명시적인 opt-in 변수를 요구함

    • NFS 성능 gate는 RUN_NFS_PERFORMANCE_GATE=true를 요구함
    • Database gate는 RUN_NFS_DATABASE_GATE=true를 요구함
    • Workload 장애 검증은 RUN_DISRUPTIVE_TESTS=true를 요구함

제한과 복구 경계

경계현재 계약
단일 node 장애control plane과 주요 stateful workload의 replica로 대응
외부 LB 장애저장소 외부의 인프라 장애 도메인
NFS endpoint 장애모든 NFS 기반 stateful workload에 영향을 줄 수 있음
PVC 삭제Retain과 stateful prune: false로 자동 삭제 제한
NFS 전체 손실저장소 내부 자산만으로 복구 불가
PostgreSQL backup·PITR현재 범위 밖
기존 PVC·legacy workload자동 migration 범위 밖
etcd snapshot off-host 보관rke2spray 범위 밖
Argo CD SSO·운영 RBAC 강화현재 범위 밖

문서 갱신 계약

  • 다음 코드가 변경되면 이 참조 문서의 updatedAt과 verifiedAt을 갱신해야 함
    • inventory/<cluster>의 version, topology, network 또는 storage 입력
    • Makefile의 공개 운영 target과 필수 변수
    • gitops_bootstrap.yml의 readiness gate
    • bootstrap/templates/applications.yaml의 Application, wave, chart version 또는 prune 정책
    • apps/의 replica, PVC, Service 또는 공개 route
    • tests/integration/verify.sh의 완료 조건

Cilium Gateway API 트래픽을 노드별 공인 IP로 받기

노드별 공인 IP를 VM에 연결하는 클라우드 SDN 환경에서 Cilium hostNetwork와 DNS로 외부 트래픽을 받습니다.

Cilium Gateway API 외부 트래픽 진입점 선택하기

Cilium Gateway API의 데이터 경로를 이해하고 LoadBalancer, NodePort, hostNetwork 중 환경에 맞는 외부 노출 방식을 선택합니다.

On this page

핵심 요약문서 범위와 기준저장소 소유권rke2spray 클러스터 선언토폴로지버전과 네트워크스토리지와 snapshotRKE2 native AddOn profilerke2spray 운영 명령GitOps 인계 계약Argo CD 선언Bootstrap gateGitOps 애플리케이션Application inventoryWorkload topology서비스와 공개 경로ClusterIP 서비스Gateway API 경로검증 계약rke2spray 정적 검증GitOps 정적 검증Live cluster 검증제한과 복구 경계문서 갱신 계약