From 52a09be22bb9180d577e33ebae9f50c9a81bb2ae Mon Sep 17 00:00:00 2001 From: Joseph19820124 Date: Wed, 15 Apr 2026 16:37:46 +0800 Subject: [PATCH] docs: add Helm values reference and expose nameOverride/fullnameOverride - Add nameOverride and fullnameOverride to values.yaml (already supported by _helpers.tpl but undocumented) - Add docs/helm-values-reference.md with complete table of all values, including envFrom, agentsMd --set-file pattern, and --set-string warning - Link to the new reference from README.md Closes #163 --- README.md | 2 + charts/openab/values.yaml | 6 ++ docs/helm-values-reference.md | 123 ++++++++++++++++++++++++++++++++++ 3 files changed, 131 insertions(+) create mode 100644 docs/helm-values-reference.md diff --git a/README.md b/README.md index 6ad1dbcd..fa2898c8 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,8 @@ The bot creates a thread. After that, just type in the thread — no @mention ne > 🔧 Running multiple agents? See [docs/multi-agent.md](docs/multi-agent.md) +> 📋 Full Helm values reference? See [docs/helm-values-reference.md](docs/helm-values-reference.md) + ## Local Development ```bash diff --git a/charts/openab/values.yaml b/charts/openab/values.yaml index 4cb6bacd..dd10e9e5 100644 --- a/charts/openab/values.yaml +++ b/charts/openab/values.yaml @@ -1,3 +1,9 @@ +# Override the chart name used in resource names (truncated to 63 chars) +nameOverride: "" +# Override the full resource name prefix entirely (takes precedence over nameOverride) +# Useful for multi-instance deployments (e.g., two agents on the same cluster) +fullnameOverride: "" + image: repository: ghcr.io/openabdev/openab # tag defaults to .Chart.AppVersion diff --git a/docs/helm-values-reference.md b/docs/helm-values-reference.md new file mode 100644 index 00000000..7eadda03 --- /dev/null +++ b/docs/helm-values-reference.md @@ -0,0 +1,123 @@ +# Helm Values Reference + +Complete reference for `charts/openab/values.yaml`. + +## Top-level + +| Key | Default | Description | +|-----|---------|-------------| +| `nameOverride` | `""` | Override the chart name used in resource names (truncated to 63 chars) | +| `fullnameOverride` | `""` | Override the full resource name prefix. Useful for multi-instance deployments (e.g., two agents on the same cluster) | +| `image.repository` | `ghcr.io/openabdev/openab` | Default image repository (used when no per-agent image is set) | +| `image.tag` | `""` | Image tag — defaults to `Chart.AppVersion` when empty | +| `image.pullPolicy` | `IfNotPresent` | Kubernetes image pull policy | +| `podSecurityContext` | see values.yaml | Pod-level security context (non-root user 1000) | +| `containerSecurityContext` | see values.yaml | Container-level security context (no privilege escalation) | + +## Per-agent (`agents.`) + +Each key under `agents` defines one agent deployment. The default agent is `kiro`. + +| Key | Default | Description | +|-----|---------|-------------| +| `enabled` | `true` | Set to `false` to skip creating resources for this agent | +| `image` | `""` | Per-agent image override (e.g., `ghcr.io/openabdev/openab-claude:latest`). Falls back to top-level `image` when empty | +| `command` | `kiro-cli` | Entrypoint command for the agent container | +| `args` | `["acp", "--trust-all-tools"]` | Arguments passed to `command` | +| `workingDir` | `/home/agent` | Working directory inside the container | +| `env` | `{}` | Extra environment variables as key/value pairs | +| `envFrom` | `[]` | Inject env vars from Secrets or ConfigMaps — preferred for credentials like `GH_TOKEN` | +| `agentsMd` | `""` | Agent identity/instructions file content. Use `--set-file` for large files (see below) | +| `resources` | `{}` | Kubernetes resource requests/limits | +| `nodeSelector` | `{}` | Node selector labels | +| `tolerations` | `[]` | Pod tolerations | +| `affinity` | `{}` | Pod affinity rules | + +### `agents..discord` + +| Key | Default | Description | +|-----|---------|-------------| +| `botToken` | `""` | Discord bot token | +| `allowedChannels` | `["YOUR_CHANNEL_ID"]` | ⚠️ Use `--set-string` to avoid float64 precision loss on large IDs | +| `allowedUsers` | `[]` | Restrict to specific user IDs. Empty = allow all users. ⚠️ Use `--set-string` | +| `allowBotMessages` | `"off"` | `"off"` \| `"mentions"` \| `"all"` — controls whether bot messages trigger the agent | +| `trustedBotIds` | `[]` | When `allowBotMessages` is not `"off"`, restrict to these bot IDs. Empty = any bot | + +### `agents..pool` + +| Key | Default | Description | +|-----|---------|-------------| +| `maxSessions` | `10` | Maximum concurrent ACP sessions | +| `sessionTtlHours` | `24` | Idle session TTL in hours | + +### `agents..reactions` + +| Key | Default | Description | +|-----|---------|-------------| +| `enabled` | `true` | Show emoji reactions while the agent is processing | +| `removeAfterReply` | `false` | Remove the reaction once the agent replies | + +### `agents..stt` + +Speech-to-text for Discord voice messages. + +| Key | Default | Description | +|-----|---------|-------------| +| `enabled` | `false` | Enable STT transcription | +| `apiKey` | `""` | API key for the STT provider | +| `model` | `whisper-large-v3-turbo` | STT model name | +| `baseUrl` | `https://api.groq.com/openai/v1` | STT API base URL | + +### `agents..persistence` + +| Key | Default | Description | +|-----|---------|-------------| +| `enabled` | `true` | Mount a PersistentVolumeClaim for agent state | +| `storageClass` | `""` | Storage class name. Empty = cluster default | +| `size` | `1Gi` | PVC size | +| `existingClaim` | `""` | Use a pre-existing PVC instead of creating one | + +--- + +## Common patterns + +### Passing credentials via Secret (recommended) + +Instead of putting tokens in Helm values, create a Secret and reference it with `envFrom`: + +```bash +kubectl create secret generic gh-token --from-literal=GH_TOKEN=ghp_xxx +``` + +```yaml +agents: + kiro: + envFrom: + - secretRef: + name: gh-token +``` + +### Loading a large `agentsMd` file + +```bash +helm install openab openab/openab \ + --set-file 'agents.kiro.agentsMd=./AGENTS.md' +``` + +### Multi-instance deployment (two agents on one cluster) + +Use `fullnameOverride` to avoid resource name collisions: + +```bash +helm install openab-kiro openab/openab --set fullnameOverride=openab-kiro ... +helm install openab-claude openab/openab --set fullnameOverride=openab-claude ... +``` + +### Channel and user IDs — always use `--set-string` + +Discord IDs are large integers that Helm converts to float64, corrupting the value. Always use `--set-string`: + +```bash +--set-string 'agents.kiro.discord.allowedChannels[0]=1234567890123456789' +--set-string 'agents.kiro.discord.allowedUsers[0]=9876543210987654321' +```