Overview
Inventory the installed topology, pin the target, preserve values, and rehearse recovery before changing a cluster. Treat standalone-to-umbrella consolidation as a downtime-bearing migration, not an ordinary chart bump.
Prerequisites
- Exact kube context, installation owner, current releases, chart/provider locks, and target
- Maintenance window, workload and platform owners, rollback threshold, and evidence path
- Current backups of declared values and infrastructure state references without secret material
Instructions
Step 1: Classify the installation
Use Bash(helm:*) to determine whether the namespace has one castai umbrella release or multiple standalone releases. Use Read and Grep to map Terraform, GitOps, console, and castctl ownership. Do not proceed while authorities conflict.
Step 2: Capture the baseline
Use Bash(kubectl:*) for component images, readiness, recent warning events, policy-visible workload health, PDBs, HPAs, and pending pods. Record selected umbrella mode and optional component overrides.
Step 3: Review target and render
Pin the target chart or provider from current release metadata. Use Bash(helm:) to render the proposed umbrella values and Bash(terraform:) to save a reviewed plan when Terraform owns delivery. Inspect CRDs, RBAC, webhooks, component modes, removed values, and automation changes.
Step 4: Choose upgrade or migration
For an existing umbrella release, use the documented chart upgrade with --reset-then-reuse-values; Helm 3.14 or newer is required. Pin the current chart version when changing configuration without changing components. For standalone releases, use Bash(castctl:*) with cluster migrate; expect a window where components and both autoscalers are paused.
Step 5: Protect recovery
Before standalone migration, set and protect the values-dump destination. If umbrella installation fails, preserve the generated values and debug snapshot, correct the conflict, then use documented values-file recovery. Do not publish dumps; they can contain sensitive configuration.
Step 6: Verify and promote
Confirm one intended release, component readiness, cluster identity, telemetry, policy state, automation mode, HPAs, PDBs, and node/workload behavior. Compare the baseline and hold promotion on any unexplained drift.
Tool Discipline
Use Read and Grep for release and ownership evidence. Use Write and Edit for the plan and recovery record. Use Bash(helm:), Bash(terraform:), Bash(kubectl:), and Bash(castctl:) only inside the approved render, migration, upgrade, and verification boundaries.
Output
- Current-versus-target topology and artifact pins
- Reviewed upgrade or migration plan
- Preserved values and recovery procedure
- Post-change parity and health receipt
Examples
A legacy cluster migrates four standalone releases with castctl during a maintenance window and verifies one umbrella release afterward. A GitOps cluster pins its current chart while changing values, avoiding an accidental component upgrade.
Error Handling
| Failure | Response |
|---|---|
| Helm is older than 3.14 | Upgrade the client before using reset-then-reuse-values |
| Migration dump contains secrets | Restrict it immediately and sanitize only a copy for review |
| Umbrella install fails | Preserve generated recovery artifacts and use documented values-file recovery |
| Post-change automation differs | Hold promotion and restore the reviewed mode |