Skip to content

Commit 0de97f4

Browse files
committed
chore(helm): remove pre-1.0.0 upgrade fluff + tighten .helmignore
This is the 1.0.0 release of the chart — there is no pre-1.0.0 predecessor for users to upgrade from, so all of the dedicated upgrade narration was hypothetical. - Drop the 'Upgrading from a pre-1.0.0 build' README section and the matching troubleshooting entry. - Drop the .Release.IsUpgrade block from NOTES.txt: items 5 (StatefulSet orphan-delete), 6 (INTERNAL_API_SECRET 'new in 1.0.0'), 7 (networkPolicy.egress shape change). Each described a migration off a chart version that never shipped. - Delete references/upgrade-pre-1.0.0.md and remove the corresponding pointers from SKILL.md. - Anchor .helmignore patterns to chart root so /tests/ (unit suites) and /examples/ are dropped from the packaged tarball without also dropping templates/tests/ (the helm test hook).
1 parent 4dc7966 commit 0de97f4

6 files changed

Lines changed: 10 additions & 198 deletions

File tree

helm/sim/.claude/skills/sim-helm/SKILL.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: sim-helm
3-
description: Install, upgrade, and operate the Sim Helm chart on Kubernetes. Covers install path selection (inline / existingSecret / External Secrets Operator), required secret generation, the values.yaml mental model (env vs envDefaults vs Secret), common failure triage, and the pre-1.0.0 → 1.0.0 StatefulSet upgrade procedure. Invoke when a user asks about deploying Sim to a cluster, authoring a Sim values.yaml, debugging a Sim pod that won't start, upgrading a Sim release, or wiring Sim into a secret manager.
3+
description: Install, upgrade, and operate the Sim Helm chart on Kubernetes. Covers install path selection (inline / existingSecret / External Secrets Operator), required secret generation, the values.yaml mental model (env vs envDefaults vs Secret), and common failure triage. Invoke when a user asks about deploying Sim to a cluster, authoring a Sim values.yaml, debugging a Sim pod that won't start, upgrading a Sim release, or wiring Sim into a secret manager.
44
license: Apache-2.0
55
---
66

@@ -20,7 +20,6 @@ Before recommending anything, ask (or infer from the conversation) all of these.
2020

2121
| Question | Why it matters |
2222
|---|---|
23-
| Fresh install or upgrade? | Upgrade-from-pre-1.0.0 has a mandatory StatefulSet orphan-delete step |
2423
| Cluster: EKS / GKE / AKS / OpenShift / kind / other? | Storage class, ingress class, identity provider differ |
2524
| Secret strategy: inline `--set`, pre-existing K8s Secret, or External Secrets Operator (ESO)? | The chart has three distinct code paths |
2625
| Postgres: chart-bundled, or external (RDS / Cloud SQL / Azure DB)? | Different value blocks (`postgresql.*` vs `externalDatabase.*`) |
@@ -40,7 +39,6 @@ Map the user's request to one of these categories and load the matching referenc
4039
| User needs to generate the required secrets | `references/secrets.md` |
4140
| User asks "what does this value do" / wants to author values.yaml | `references/values-model.md` |
4241
| Pod won't start, error message, `CrashLoopBackOff`, image pull error, ingress not routing | `references/troubleshooting.md` |
43-
| User is upgrading and `helm upgrade` failed with `Forbidden: updates to statefulset spec for fields other than...` | `references/upgrade-pre-1.0.0.md` |
4442
| User asks about ESO / Vault / AWS Secrets Manager / Azure Key Vault / GCP Secret Manager | `references/install-paths.md` (ESO section) |
4543
| User asks "is X production-ready" / autoscaling / network policy / security context | Read the README's "Production checklist" section directly — no separate reference |
4644

helm/sim/.claude/skills/sim-helm/references/troubleshooting.md

Lines changed: 1 addition & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -69,25 +69,6 @@ Match the error:
6969

7070
---
7171

72-
## Realtime pod connects to `http://localhost:3000` even though I set NEXT_PUBLIC_APP_URL
73-
74-
**Cause:** You set `NEXT_PUBLIC_APP_URL` in `app.env` but not `realtime.env`. In chart versions before the fix shipped in 1.0.0, the realtime Deployment would inline the localhost default from `realtime.envDefaults`, masking the Secret value.
75-
76-
**Fix (1.0.0+):** The chart now skips the realtime envDefault when the key is set in **either** `app.env` or `realtime.env`. Upgrade to chart 1.0.0+ if you're on an older build.
77-
78-
**Fix (older chart):** Mirror the value in `realtime.env`:
79-
80-
```yaml
81-
app:
82-
env:
83-
NEXT_PUBLIC_APP_URL: "https://sim.example.com"
84-
realtime:
85-
env:
86-
NEXT_PUBLIC_APP_URL: "https://sim.example.com"
87-
```
88-
89-
---
90-
9172
## Image pull errors (`ErrImagePull` / `ImagePullBackOff`)
9273

9374
```bash
@@ -136,19 +117,11 @@ kubectl describe ingress -n sim
136117

137118
---
138119

139-
## `helm upgrade` fails with `Forbidden: updates to statefulset spec for fields other than 'replicas', 'ordinals', 'template', 'updateStrategy'...`
140-
141-
**Cause:** You're upgrading from a pre-1.0.0 build. `StatefulSet.spec.serviceName` was renamed to point at a new headless Service. That field is immutable.
142-
143-
**Fix:** See `references/upgrade-pre-1.0.0.md`. Orphan-delete the StatefulSet first (pods + PVCs survive), then re-run `helm upgrade`.
144-
145-
---
146-
147120
## CronJob pods fail with `CreateContainerConfigError: couldn't find key CRON_SECRET in Secret`
148121

149122
**Cause:** `cronjobs.enabled=true` (the default) but `CRON_SECRET` isn't in the app Secret. Two paths:
150123

151-
1. Inline mode: `app.env.CRON_SECRET=""` — the chart will fail at template time in 1.0.0+. If you somehow got past that, regenerate and set it.
124+
1. Inline mode: `app.env.CRON_SECRET=""` — the chart will fail at template time. If you somehow got past that, regenerate and set it.
152125
2. Existing-Secret mode: your pre-created Secret doesn't include `CRON_SECRET`. Add it:
153126
```bash
154127
kubectl patch secret sim-app-secrets -n sim --type='json' \

helm/sim/.claude/skills/sim-helm/references/upgrade-pre-1.0.0.md

Lines changed: 0 additions & 101 deletions
This file was deleted.

helm/sim/.helmignore

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,11 @@
2121
.idea/
2222
*.tmproj
2323
.vscode/
24-
# Examples directory (included in chart but ignored during packaging)
25-
examples/
26-
# Test files
27-
*_test.yaml
28-
test/
24+
# Repo tooling — not part of the chart artifact (anchored to chart root)
25+
/.claude/
26+
/CONTRIBUTING.md
27+
/ci/
28+
# Examples — published in-repo, not in the packaged chart
29+
/examples/
30+
# Unit-test suites (helm-unittest) — distinct from templates/tests/ which IS shipped
31+
/tests/

helm/sim/README.md

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -133,26 +133,10 @@ helm install sim ./helm/sim --dry-run --debug \
133133

134134
## Upgrading
135135

136-
### Upgrading within the 1.x line
137-
138136
```bash
139137
helm upgrade sim ./helm/sim --namespace sim --values my-values.yaml
140138
```
141139

142-
### Upgrading from a pre-1.0.0 build
143-
144-
If you previously installed this chart from a git checkout before the `1.0.0` tag, the internal Postgres StatefulSets had their `serviceName` renamed to point at new headless Services. `StatefulSet.spec.serviceName` is immutable, so `helm upgrade` will fail with `Forbidden: updates to statefulset spec ...`. Orphan-delete the affected StatefulSet(s) first — pods and PVCs are preserved, traffic continues to flow:
145-
146-
```bash
147-
kubectl delete statefulset sim-postgresql --namespace sim --cascade=orphan
148-
# If copilot is enabled, also:
149-
kubectl delete statefulset sim-copilot-postgresql --namespace sim --cascade=orphan
150-
151-
helm upgrade sim ./helm/sim --namespace sim --values my-values.yaml
152-
```
153-
154-
Other defaults that changed in `1.0.0`: image tags default to `Chart.AppVersion` (not `latest`), `pullPolicy` defaults to `IfNotPresent` (not `Always`), Ollama mount moved from `/root/.ollama` to `/data` (models must be re-pulled), `networkPolicy.egress` became an object `{exceptCidrs, extraRules}` instead of a list, `automountServiceAccountToken: false` is set on every pod, and every value in `app.env` / `realtime.env` is now written to a chart-managed Secret instead of inlined on the Deployment (chart-computed values `DATABASE_URL`, `SOCKET_SERVER_URL`, `OLLAMA_URL` remain inline). ESO users must map every key via `externalSecrets.remoteRefs.app.<KEY>` — the chart fails template rendering if a key is missing.
155-
156140
---
157141

158142
## Uninstalling
@@ -424,10 +408,6 @@ kubectl describe ingress --namespace sim
424408
* `ingress.className` doesn't match your controller → set it to your installed class.
425409
* DNS not pointed at the ingress's external IP / LoadBalancer.
426410

427-
### `helm upgrade` fails with `Forbidden: updates to statefulset spec for fields other than...`
428-
429-
You're upgrading from a pre-1.0.0 build of the chart. The `StatefulSet.serviceName` rename requires an orphan-delete first — see [Upgrading from a pre-1.0.0 build](#upgrading-from-a-pre-100-build).
430-
431411
### Get logs from each component
432412

433413
```bash

helm/sim/templates/NOTES.txt

Lines changed: 0 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -81,48 +81,7 @@ Your release is named {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
8181
# Upgrade after changing values
8282
helm upgrade {{ .Release.Name }} ./helm/sim --namespace {{ .Release.Namespace }} -f your-values.yaml
8383

84-
{{- if .Release.IsUpgrade }}
85-
5. Upgrading from a pre-1.0.0 build?
86-
87-
The internal Postgres StatefulSet's `spec.serviceName` was renamed to point
88-
at a new headless Service. That field is immutable, so `helm upgrade` will
89-
fail with: `Forbidden: updates to statefulset spec for fields other than
90-
...`. Orphan-delete the StatefulSet first (preserves pods and PVCs, traffic
91-
keeps flowing):
92-
93-
kubectl --namespace {{ .Release.Namespace }} delete statefulset {{ include "sim.fullname" . }}-postgresql --cascade=orphan
94-
{{- if .Values.copilot.enabled }}
95-
kubectl --namespace {{ .Release.Namespace }} delete statefulset {{ include "sim.fullname" . }}-copilot-postgresql --cascade=orphan
96-
{{- end }}
97-
98-
Then re-run `helm upgrade`. See README → "Upgrading from a pre-1.0.0 build"
99-
for the full procedure. Skip this step if you're already on 1.0.0+.
100-
101-
6. Also new in 1.0.0: `app.env.INTERNAL_API_SECRET` is now required.
102-
103-
Older charts treated this as optional. Upgrades will fail at template
104-
render with `app.env.INTERNAL_API_SECRET is required for production
105-
deployment` if you never set it. Generate one and pass it on upgrade:
106-
107-
--set app.env.INTERNAL_API_SECRET=$(openssl rand -hex 32)
108-
109-
Store it durably (values.yaml / existingSecret / ESO) — the app and
110-
realtime pods both read it to authenticate inter-service requests.
111-
112-
7. Also new in 1.0.0: `networkPolicy.egress` shape changed.
113-
114-
Was: a list of custom egress rules.
115-
Now: a map with `exceptCidrs` (CIDRs excluded from broad HTTPS egress)
116-
and `extraRules` (custom rules appended to the policy).
117-
118-
If you previously set custom rules under `networkPolicy.egress:`, move
119-
them to `networkPolicy.egress.extraRules:` — old-shape values are
120-
silently ignored after upgrade.
121-
122-
8. Where to go next:
123-
{{- else }}
12484
5. Where to go next:
125-
{{- end }}
12685

12786
* Production checklist: helm/sim/README.md (search "Production checklist")
12887
* Troubleshooting: helm/sim/README.md (search "Troubleshooting")

0 commit comments

Comments
 (0)