Helm Charts: mcp-stack
- Purpose: Guide LLMs to reason about and automate Helm tasks for the gateway stack.
- Scope: `charts/mcp-stack` chart; local lint/test, install/upgrade flows, values, docs, and registry operations.
**Chart Layout**
- Location: `charts/mcp-stack`
- Key files:
- `Chart.yaml`: metadata (name, versions, kubeVersion, icon, keywords)
- `values.yaml`: default configuration (gateway, Postgres, Redis, ingress, secrets)
- `values.schema.json`: JSON Schema for values validation
- `README.md`: rendered chart docs (generated by helm-docs)
- `Makefile`: developer tasks (lint, test, install, package, push, docs)
**Prereqs**
- Tools: `helm` (3.14+), `kubectl`, a kube context, and optionally: `helm-docs`, `yamllint`, `kubeval`, `ajv`/`ajv-cli`, `cosign`.
- Namespace: defaults to `mcp-test` via Makefile, configurable with `NAMESPACE=<ns>`.
**Developer Commands (from charts/mcp-stack)**
- Info & version:
- `make info` — print chart/app versions and target registry
- `make version` — print chart version
- Lint & validate:
- `make lint` — `helm lint --strict`
- `make lint-yaml` — `yamllint` if available
- `make lint-values` — validates `values.yaml` against schema (if present)
- `make validate-all` — runs all lint steps
- Template & dry-run:
- `make test-template` — render templates with defaults → `tmp/rendered.yaml`
- `make test-template-values` — render with `my-values.yaml` if present
- `make test-dry-run` — `helm install ... --dry-run --debug`
- `make test-upgrade-dry-run` — `helm upgrade ... --dry-run --debug`
- `make test-kubeval` — validate rendered manifests with `kubeval` (if available)
- `make test-all` — run template + dry-run + kubeval
- Install/upgrade lifecycle:
- `make install` — install with defaults (creates namespace, waits)
- `make install-dev` — install with `my-values.yaml` if present
- `make upgrade` / `make upgrade-dev` — upgrade release
- `make uninstall` — uninstall release and wait for deletion
- Operate & debug:
- `make status`, `make history`, `make rollback`
- `make debug` — context, releases, and resource summary
- `make describe` — describe chart-managed resources
- `make logs` / `make logs-follow` — show/follow logs for all pods in the release
- `make port-forward` — forward local `4444` to service port `80`
- `make shell` — interactive shell into gateway deployment
- Package & registry:
- `make package` — package chart to `dist/` (with dependency update)
- `make package-dev` — package without validation
- `make push` — push packaged chart to `oci://ghcr.io/ibm/mcp-context-forge`
- `make sign` — sign `dist/*.tgz` with `cosign` (if installed)
- Docs & schema:
- `make docs` — generate README via `helm-docs` (uses README.md.gotmpl if present)
- `make readme` — update README values section via `helm-docs`
- `make schema` — generate `values.schema.generated.json` from `values.yaml` (helm schema plugin)
- `make schema-diff` — compare existing and generated schemas
- `make schema-validate` — validate `values.yaml` against `values.schema.json` using `ajv`/`helm lint`
- `make deps-update|deps-build|deps-clean` — manage chart deps
**Common Workflows**
- Local validation before commit:
- `make validate-all`
- `make test-template`
- Optional: `make test-dry-run`
- First-time install into a test namespace:
- `NAMESPACE=mcp-dev RELEASE_NAME=mcp-dev make install`
- Or with custom values: create `my-values.yaml`, then: `make install-dev`
- Upgrade with changes:
- `make upgrade-dev` (prefers `my-values.yaml` if present)
- Inspect/Debug:
- `make status` and `make logs`
- `make port-forward` then browse `http://localhost:4444` (gateway)
**Authoring my-values.yaml**
Minimal override example for development:
```yaml
mcpContextForge:
image:
tag: "latest"
pullPolicy: IfNotPresent
ingress:
enabled: true
className: nginx
host: gateway.local
config:
DEV_MODE: "true"
RELOAD: "false"
DEBUG: "false"
secret:
BASIC_AUTH_USER: admin
BASIC_AUTH_PASSWORD: changeme
JWT_SECRET_KEY: my-test-key
postgres:
enabled: true
credentials:
user: admin
password: test123
persistence:
storageClassName: manual
accessModes: [ReadWriteMany]
size: 5Gi
redis:
enabled: true
```
**Security/Secrets**
- Chart exposes `mcpContextForge.secret.*` values for common auth/JWT settings.
- Prefer external `Secret` objects for production and set `mcpContextForge.envFrom` refs.
- For network ingress, ensure TLS termination is configured at ingress or service mesh.
**CI/CD Considerations**
- Use `make lint` and `make validate-all` in pipelines.
- Package and push on tagged releases: `make package push` (with registry credentials set).
- Optionally sign charts with `make sign` and verify in downstream pipelines.
**Troubleshooting**
- `helm get values <release> -n <ns>` and `helm get manifest <release> -n <ns>` for applied values/manifests.
- `kubectl describe` events for pods or ingress to locate readiness/permission issues.
- Increase gateway replicas or tweak HPA via `mcpContextForge.hpa.*` in values.
