# Upgrading muster-crds

`muster-crds` ships the `MCPServer` and `Workflow` CustomResourceDefinitions.
It is a regular Helm chart (the CRDs live in `files/crds/` and are rendered by
`templates/crds.yaml`), so CRD changes are applied on `helm upgrade` like any
other templated resource — unlike CRDs placed in the Helm 3 `crds/` directory,
which Helm never upgrades.

## Operator ordering

Always reconcile `muster-crds` **before** the `muster` application chart:

1. `helm upgrade --install muster-crds ...`
2. `helm upgrade --install muster ...`

The muster application chart no longer renders the CRDs (`muster.crds.install`
defaults to `false`) and expects them to already exist. Installing or upgrading
muster first risks the operator starting against missing or stale CRDs.

In an umbrella chart (`agentic-platform-crds`), encode this with an explicit
dependency ordering or a sync wave so the CRD chart always lands first.

## CRD schema-deprecation ratchet

CustomResourceDefinition schema changes are a one-way ratchet at the Kubernetes
API-server level. The API server validates that a new CRD revision does not
remove a `storage: true` version and that served versions remain mutually
convertible. Practical consequences for upgrades:

- **Additive changes are safe.** New optional fields, new served versions, and
  widened validation apply cleanly on `helm upgrade`.
- **Removing or narrowing fields can reject existing stored objects.** Before
  tightening validation, ensure no stored `MCPServer` / `Workflow` violates the
  new schema, or the API server will refuse to serve / convert them.
- **Never drop the storage version in a single step.** Add the new version as
  served, migrate stored objects, then remove the old version in a later
  release. Removing the only `storage: true` version is rejected.
- CRDs are generated by `controller-gen` (`make generate-crds`) and pinned to
  `controller-gen.kubebuilder.io/version: v0.21.0`. Regenerate rather than
  hand-editing the files in `files/crds/`.

## Uninstall / removal

The CRDs carry `helm.sh/resource-policy: keep`, so `helm uninstall muster-crds`
leaves them — and every `MCPServer` / `Workflow` resource — untouched. Removing
the CRDs is a deliberate, destructive operation that also deletes all dependent
custom resources:

```bash
kubectl delete crd mcpservers.muster.giantswarm.io workflows.muster.giantswarm.io
```
