> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes(헬름 차트)

> 공식 Helm 차트를 사용하여 Kubernetes에 Myrm 플랫폼 배포

## 개요

공식 `myrm-platform` Helm 차트는 모든 Kubernetes 클러스터에 **제어 플레인 + 프런트엔드**를 이중 구성 요소 릴리스로 배포합니다. 샌드박스 인스턴스(사용자당 하나)는 K8s API을 통해 제어 평면에 의해 동적으로 생성됩니다.

<Note>
  Helm 차트는 **클라우드 호스팅** 및 **엔터프라이즈 프라이빗 배포** 시나리오용입니다. 로컬 단일 사용자 설정의 경우 [데스크톱 앱](/docs/getting-started/desktop-app) 또는 [로컬 배포](/docs/getting-started/local-deployment)를 대신 사용하세요.
</Note>

## 전제조건

* 쿠버네티스 클러스터(v1.25+)
* 투구 3.10+
* 클러스터에 대해 구성된 `kubectl`
* 최소 `JWT_SECRET`을 포함하는 사전 생성된 Kubernetes 비밀

## 빠른 시작

```bash theme={null}
# 1. Create the required secret
kubectl create secret generic myrm-secrets \
  --from-literal=JWT_SECRET=$(openssl rand -hex 32) \
  --from-literal=MYRM_CP_ADMIN_API_KEY=$(openssl rand -hex 32)

# 2. Install the chart
helm install myrm deploy/helm/myrm-platform/ -f my-values.yaml

# 3. Access the frontend
kubectl port-forward svc/myrm-frontend 3000:3000
# Open http://localhost:3000
```

## 건축학

```
┌─────────────────────────────────────────────┐
│                  Ingress                     │
│  frontend.host → Frontend Service (3000)     │
│  api.host      → CP Service (8003)           │
└──────────────┬────────────┬─────────────────┘
               │            │
     ┌─────────▼──┐  ┌──────▼──────────┐
     │  Frontend   │  │  Control Plane   │
     │ (Next.js)   │  │  (FastAPI)       │
     │  Deployment │  │  Deployment      │
     └─────────────┘  │  + PVC (/data)   │
                      │  + ServiceAccount │
                      └──────┬───────────┘
                             │ K8s API
                    ┌────────▼────────┐
                    │  Sandbox Pods    │
                    │  (per-user,      │
                    │   dynamic)       │
                    └─────────────────┘
```

## 구성

모든 구성은 `values.yaml`에 중앙 집중화되어 있습니다. 차트는 제어 영역의 `ControlPlaneConfig` 필드에 1:1로 매핑됩니다.

### 이미지

```yaml theme={null}
images:
  controlPlane:
    repository: ghcr.io/myrmagent/myrm-control-plane
    tag: ""          # defaults to Chart.appVersion
    pullPolicy: IfNotPresent
  frontend:
    repository: ghcr.io/myrmagent/myrm-frontend
    tag: ""
    pullPolicy: IfNotPresent

global:
  imagePullSecrets: []
  #   - name: my-registry-secret
```

### 비밀

차트는 **외부 비밀** 패턴을 사용합니다. 즉, 비밀 비밀을 수동으로 생성하면 차트에서 이를 참조합니다.

```yaml theme={null}
existingSecret: myrm-secrets
```

필수 키: `JWT_SECRET`

선택적 키: `MYRM_CP_STRIPE_SECRET_KEY`, `MYRM_CP_GOOGLE_OAUTH_CLIENT_SECRET`, `MYRM_CP_GITHUB_OAUTH_CLIENT_SECRET`, `MYRM_CP_ADMIN_API_KEY`, `MYRM_CP_ENTERPRISE_LICENSE_KEY` 등

### 인그레스

```yaml theme={null}
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
  frontend:
    host: myrm.example.com
  api:
    host: api.myrm.example.com
  tls:
    - hosts: [myrm.example.com, api.myrm.example.com]
      secretName: myrm-tls
```

### 지속성

```yaml theme={null}
controlPlane:
  persistence:
    enabled: true
    size: 5Gi
    storageClass: ""    # uses cluster default
    accessModes:
      - ReadWriteOnce
```

### RBAC

제어 플레인에는 K8s API을 통해 샌드박스 Pod를 관리할 수 있는 권한이 필요합니다.

```yaml theme={null}
rbac:
  create: true
  serviceAccount:
    create: true
    name: ""
    annotations: {}    # e.g. eks.amazonaws.com/role-arn
```

## 선택적 엔터프라이즈 기능

기본적으로 모두 비활성화되어 있으며 필요에 따라 활성화합니다.

| Feature        | Config Key                          | Purpose                                |
| -------------- | ----------------------------------- | -------------------------------------- |
| Network Policy | `networkPolicy.enabled`             | Restrict traffic between components    |
| HPA            | `autoscaling.enabled`               | Auto-scale CP and frontend pods        |
| PDB            | `podDisruptionBudget.enabled`       | Guarantee availability during upgrades |
| PrometheusRule | `monitoring.prometheusRule.enabled` | Alert on CP downtime and high latency  |

### 예: 프로덕션 준비 구성

```yaml theme={null}
controlPlane:
  replicas: 3
  config:
    edition: enterprise
    runtime: docker
  persistence:
    enabled: true
    size: 50Gi
    storageClass: gp3

frontend:
  replicas: 2

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt
  frontend:
    host: myrm.mycompany.com
  api:
    host: api.myrm.mycompany.com
  tls:
    - hosts: [myrm.mycompany.com, api.myrm.mycompany.com]
      secretName: myrm-tls

rbac:
  create: true

networkPolicy:
  enabled: true

autoscaling:
  enabled: true
  controlPlane:
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70

podDisruptionBudget:
  enabled: true
  controlPlane:
    minAvailable: 1

monitoring:
  prometheusRule:
    enabled: true
    severity: critical
```

## 업그레이드 중

```bash theme={null}
helm upgrade myrm deploy/helm/myrm-platform/ -f my-values.yaml
```

차트는 ConfigMap 및 Secret 참조에 체크섬 주석을 사용하므로 구성이 변경되면 Pod가 자동으로 다시 시작됩니다.

### 샌드박스 포드의 정상적인 종료

각 샌드박스 포드는 **Gateway Drain Control**이 내장된 Myrm 에이전트 서버 인스턴스를 실행합니다. 롤링 업데이트 또는 포드 제거 중:

1. 포드는 Kubernetes로부터 SIGTERM을 수신합니다.
2. AgentGateway가 드레이닝 모드로 전환됩니다. 새 에이전트 요청은 사용자에게 친숙한 메시지와 함께 거부됩니다.
3. 기내 에이전트 턴은 최대 120초까지 자연스럽게 완료됩니다.
4. 드레이닝 타임아웃 이후 남은 작업은 안전하게 중단됩니다.

드레이닝이 완료되도록 하려면 샌드박스 포드 템플릿에 적절한 유예 기간이 설정되어 있는지 확인하세요.

```yaml theme={null}
terminationGracePeriodSeconds: 150   # 120s drain + 30s buffer
```

PDB(Pod Disruption Budget)를 사용하는 경우 에이전트 작업 손실 없이 다운타임 없는 업그레이드가 보장됩니다.

## 제거 중

```bash theme={null}
helm uninstall myrm
# PVCs are retained by default — delete manually if needed:
kubectl delete pvc myrm-control-plane-data
```