---
title: Helm 차트 관리 체계
updated: 2026-04-13
tags: [infra, k3s, helm, argocd, gitops]
---

## 개요

K3s 클러스터의 모든 서비스를 Helm으로 관리. 자체 차트는 Gitea에 호스팅하고 ArgoCD로 GitOps 배포.

## 차트 저장소

| 항목 | 값 |
|------|-----|
| Git 레포 | `gitea.inouter.com/kaffa/helm-charts` (private) |
| Helm 레지스트리 | `gitea.inouter.com/api/packages/kaffa/helm` |
| ArgoCD 레포 시크릿 | `repo-helm-charts` (argocd 네임스페이스) |

### BunnyCDN 캐시 바이패스

`iron-git` Pull Zone (ID 5584382)에 Edge Rule 적용:
- 패턴: `*/api/packages/*`
- ActionType: 3 (OverrideCacheTime), 값: 0
- 차트 업로드 후 index.yaml 캐시 문제 방지

## 자체 차트 구조

```
helm-charts/
├── charts/
│   ├── app/          # 범용 차트 (v0.4.0) — 단순 서비스용
│   ├── kroki/        # 전용 차트 — Kroki + Mermaid
│   ├── searxng/      # 전용 차트 — SearXNG + UA 패치 + TLS proxy CA
│   ├── outline/      # 전용 차트 — Outline Wiki + Redis
│   └── openmemory/   # 전용 차트 — MCP + UI + Qdrant
└── values/           # app 차트용 서비스별 values
    ├── juiceshop.yaml
    ├── cfb-manager.yaml
    ├── bunnycdn-mcp.yaml
    ├── smtp-relay.yaml
    ├── namecheap-api.yaml
    ├── vultr-api.yaml
    ├── pgcat.yaml        # sidecar(monitor) 포함
    ├── proxysql.yaml     # Galera 설정 포함
    ├── nas-proxy.yaml    # external service (Synology NAS)
    └── vault-mcp.yaml   # external service (Vault) + extraIngressRoutes
```

### app 차트 기능 (v0.4.0)

- Deployment + Service + IngressRoute 기본 구성
- `sidecars` — 사이드카 컨테이너 지원
- `configMaps` — multiline ConfigMap 생성
- `secrets` — Secret 생성
- `external` — selector 없는 Service + EndpointSlice (외부 서비스 프록시)
- `extraIngressRoutes` — 복수 도메인 IngressRoute
- `probes` — liveness/readiness probe

## 전체 Helm 릴리스 목록

### 공식/외부 차트 (20개)

| 릴리스 | 네임스페이스 | 차트 |
|--------|-------------|------|
| apisix | apisix | apisix |
| apisix-ingress-controller | apisix | apisix-ingress-controller |
| argocd | argocd | argo-cd |
| cert-manager | cert-manager | cert-manager |
| external-secrets | external-secrets | external-secrets |
| gitea | gitea | gitea |
| longhorn | longhorn-system | longhorn |
| metallb | metallb-system | metallb |
| n8n | n8n | n8n |
| nfs-provisioner | nfs-provisioner | nfs-subdir-external-provisioner |
| nocodb | tools | zekker6/nocodb |
| portainer | portainer | portainer |
| reflector | kube-system | reflector |
| safeline | safeline | safeline |
| sftpgo | sftpgo | sftpgo |
| sshpiper | sshpiper | sshpiper |
| synology-iscsi | democratic-csi | democratic-csi |
| teleport-cluster | teleport | teleport-cluster |
| traefik | kube-system | traefik |
| vector | logging | vector |
| vlogs | logging | victoria-logs-single |
| vm-stack | monitoring | victoria-metrics-k8s-stack |

### 자체 app 차트 (10개, ArgoCD 관리)

| 릴리스 | 네임스페이스 | 비고 |
|--------|-------------|------|
| juiceshop | juiceshop | |
| cfb-manager | tools | SSH key 마운트 |
| bunnycdn-mcp | mcp | IngressRoute: bunny.inouter.com |
| smtp-relay | mail | Mailgun relay |
| namecheap-api | api | |
| vultr-api | api | |
| pgcat | db | monitor sidecar 포함 |
| proxysql | db | Galera hostgroup 설정 |
| nas-proxy | tools | external → 192.168.9.100:5000 |
| vault-mcp | tools | external → 10.253.101.58, hcv.inouter.com + vault-mcp.inouter.com |

### 전용 차트 (4개, ArgoCD 관리)

| 릴리스 | 네임스페이스 | 구성 |
|--------|-------------|------|
| kroki | kroki | kroki + mermaid sidecar |
| searxng | searxng | UA 패치, TLS proxy CA, Google proxy |
| outline | outline | outline + redis + PVC + IngressRoute |
| openmemory | openmemory | MCP + UI + Qdrant + PVC 2개 |

### Operator 관리 (ArgoCD/Helm 외)

| 서비스 | 네임스페이스 | 관리 방식 |
|--------|-------------|-----------|
| rabbitmq-cluster-operator | rabbitmq-system | 직접 매니페스트 |
| rabbitmq-server | mq | RabbitmqCluster CRD → Operator |

## ArgoCD 앱 목록

14개 Application, 모두 `automated + prune + selfHeal`:

```
juiceshop, cfb-manager, bunnycdn-mcp, smtp-relay, namecheap-api, vultr-api,
pgcat, proxysql, nas-proxy, vault-mcp, kroki, searxng, outline, openmemory
```

### 주의사항

- **EndpointSlice는 ArgoCD 제외 대상** — `discovery.k8s.io` 그룹이 argocd-cm에서 제외됨. external service의 EndpointSlice는 수동 관리 필요
- ArgoCD 앱 소스는 Gitea `helm-charts` 레포의 `charts/` 경로 참조

## 배포 워크플로우

```
1. charts/ 또는 values/ 수정
2. helm template 로 렌더링 확인
3. git push → Gitea helm-charts
4. ArgoCD 자동 sync (또는 hard refresh)
5. 동작 확인
```

## 관련 문서

- [[external-secrets]] — ESO + Vault 시크릿 동기화
- [[k3s-ingress-architecture]] — Traefik/APISIX 인그레스 구조
- [[cert-manager]] — TLS 인증서