fix(operations): replace the component removal recipe that undoes itself

content/en/docs/next/operations/configuration/components.md

@@ -41,11 +41,7 @@ Bundles have optional components that need to be explicitly enabled (included) i
 Regular bundle components can, on the other hand, be disabled (excluded) from the installation, when you don't need them.
 
 Use `bundles.enabledPackages` and `bundles.disabledPackages` in the Platform Package values.
-Every entry in those lists is a fully-qualified Package name — the same name you see with
-`kubectl get package`. All platform packages live under the `cozystack.` prefix (for example,
-`cozystack.metallb`, `cozystack.hetzner-robotlb`, `cozystack.nfs-driver`). Run
-`kubectl get package` to see the exact names available on your cluster before editing
-the Platform Package.
+Every entry in those lists is a fully-qualified name under the `cozystack.` prefix (for example, `cozystack.metallb`, `cozystack.hetzner-robotlb`, `cozystack.nfs-driver`). Run `kubectl get packagesource` to see the exact names available on your cluster before editing the Platform Package. `kubectl get package` answers only for `disabledPackages`, because an optional component has no Package object until its name is already in `enabledPackages`.
 
 For example, [installing Cozystack in Hetzner]({{% ref "/docs/next/install/providers/hetzner" %}})
 requires swapping the default load balancer, MetalLB, with one made specifically for Hetzner, called RobotLB:
@@ -70,8 +66,42 @@ spec:
 
 Disabling components must be done before installing Cozystack.
 Applying updated configuration with `disabledPackages` will not remove components that are already installed.
-To remove already installed components, delete the Helm release manually using this command:
+Removing one that is already installed takes two steps. Add its name to `disabledPackages` in the Platform Package above, then wait for the operator to carry that edit across. The name appears in this output once it has:
 
 ```bash
-kubectl delete hr -n <namespace> <component>
+kubectl get helmrelease cozystack-platform --namespace cozy-system \
+  --output jsonpath='{.spec.values.bundles.disabledPackages}'
 ```
+
+Then delete the Package object.
+
+{{% alert title="Warning" color="warning" %}}
+Deleting the Package uninstalls the component's Helm release, and that destroys more than the workloads. Anything the chart rendered as an ordinary template without `helm.sh/resource-policy: keep` goes with the release, CRDs and namespaces included, and Kubernetes deletes every custom resource of those CRD kinds along with them. The annotation is not the only thing that keeps an object alive. From v1.5.0 the platform installs a ValidatingAdmissionPolicy that denies DELETE on anything labelled `platform.cozystack.io/no-delete: "true"`, and several component charts render objects that carry it; `kubectl get <kind> --all-namespaces --selector platform.cozystack.io/no-delete=true` lists them for a given kind. One denial fails the whole uninstall: Helm deletes what it can and then errors out, and the controller keeps its finalizer and retries, so the HelmRelease sits in deletion and the wait below runs to its timeout. Taking the label off hands the object to the uninstall, which is the whole point of the guard, and it has to come off every labelled object in the release: the `cert-manager-issuers` release of `cozystack.cert-manager` labels three ClusterIssuers, and unlabelling one of them still leaves the other two to fail the uninstall. The command is `kubectl label <kind> <name> --namespace <ns> platform.cozystack.io/no-delete-`, without `--namespace` for cluster-scoped kinds. Weigh what that costs before doing it: `cozystack.cozystack-basics` labels two objects, the `tenant-root` Namespace and the `tenant-root` HelmRelease, and only the Namespace is one the uninstall would delete, since the HelmRelease also carries the keep annotation. Unlabelling that Namespace means the uninstall takes the root tenant and every application in it. Removing `cozystack.metallb` takes every CRD the MetalLB chart bundles, subcharts included, and with them every custom resource of those kinds cluster-wide; removing `cozystack.cozystack-basics` takes the `cozy-public` namespace and everything stored in it. Back up anything you still need first.
+{{% /alert %}}
+
+The namespace a component installs into is the exception: the operator applies that one itself, outside the component's release and with no ownerReference, so the uninstall never had it to remove.
+
+List the releases the Package owns before deleting it. The operator labels every HelmRelease it renders with the name of the Package that produced it, and one Package can own several:
+
+```bash
+kubectl get helmrelease --all-namespaces --selector cozystack.io/package=<package-name> \
+  --output custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,SUSPENDED:.spec.suspend'
+```
+
+Clear `spec.suspend` on any release that shows `true` before going on. Flux skips the uninstall for a suspended HelmRelease and only drops its own finalizer, so that release disappears with everything it installed left behind and nothing left managing it.
+
+```bash
+kubectl delete package.cozystack.io <package-name>
+```
+
+Nothing holds a finalizer on the Package, so this command returns as soon as the object is gone and the uninstall it triggers runs afterwards. Wait on each release from the listing to know the destructive part has finished:
+
+```bash
+kubectl wait --for=delete helmrelease/<name> --namespace <namespace> --timeout=10m
+```
+
+`kubectl wait --for=delete` exits 0 for a name that was never there, silently and with nothing to tell it apart from a deletion it watched, so take both values from the listing rather than guessing them. A returned wait says the HelmRelease is gone, not that the uninstall ran.
+
+Deleting the Package while the platform values still render it means the next platform upgrade brings it back, undoing the removal one level up. Nothing reports this at the time: the delete succeeds either way and the Package reappears whenever that upgrade happens to run.
+
+`kubectl delete hr` is not a lighter-weight version of this. Flux uninstalls the release when an unsuspended HelmRelease goes away, so it destroys the same CRDs and custom resources, and then the Package recreates the HelmRelease and the chart reinstalls. The workloads come back, the custom resources do not. If you have run it before, those custom resources are already gone and have to be recreated from your own manifests or a backup.

content/en/docs/v0/operations/configuration/components.md

@@ -60,7 +60,11 @@ data:
 
 Disabling components must be done before installing Cozystack.
 Applying updated configuration with `bundle-disable` will not remove components that are already installed.
-To remove already installed components, delete the Helm release manually using this command:
+To remove already installed components, delete the Helm release manually.
+
+{{% alert title="Warning" color="warning" %}}
+Uninstalling the component's Helm release destroys more than the workloads. Anything the chart rendered as an ordinary template without `helm.sh/resource-policy: keep` goes with the release, CRDs and namespaces included, and Kubernetes deletes every custom resource of those CRD kinds along with them. Removing `metallb` takes every CRD the MetalLB chart bundles, subcharts included, and with them every custom resource of those kinds cluster-wide. Back up anything you still need first.
+{{% /alert %}}
 
 ```bash
 kubectl delete hr -n <namespace> <component>

content/en/docs/v1.0/install/providers/hetzner.md

@@ -344,9 +344,9 @@ The final stage of deploying a Cozystack cluster on Hetzner is to install Cozyst
           values:
             bundles:
               disabledPackages:
-                - metallb
+                - cozystack.metallb
               enabledPackages:
-                - hetzner-robotlb
+                - cozystack.hetzner-robotlb
             publishing:
               host: "example.org"
               apiServerEndpoint: "https://api.example.org:443"

content/en/docs/v1.0/operations/configuration/components.md

@@ -41,6 +41,7 @@ Bundles have optional components that need to be explicitly enabled (included) i
 Regular bundle components can, on the other hand, be disabled (excluded) from the installation, when you don't need them.
 
 Use `bundles.enabledPackages` and `bundles.disabledPackages` in the Platform Package values.
+Every entry in those lists is a fully-qualified name under the `cozystack.` prefix — run `kubectl get packagesource` to see the exact names on your cluster. `kubectl get package` answers only for `disabledPackages`, because an optional component has no Package object until its name is already in `enabledPackages`.
 For example, [installing Cozystack in Hetzner]({{% ref "/docs/v1.0/install/providers/hetzner" %}})
 requires swapping default load balancer, MetalLB, with one made specifically for Hetzner, called RobotLB:
 
@@ -56,16 +57,37 @@ spec:
       values:
         bundles:
           disabledPackages:
-            - metallb
+            - cozystack.metallb
           enabledPackages:
-            - hetzner-robotlb
+            - cozystack.hetzner-robotlb
         # rest of the config
 ```
 
-Disabling components must be done before installing Cozystack.
-Applying updated configuration with `disabledPackages` will not remove components that are already installed.
-To remove already installed components, delete the Helm release manually using this command:
+Disabling a component before installing Cozystack keeps it out of the installation entirely.
+
+On v1.0 the platform does not annotate the Packages it renders with `helm.sh/resource-policy: keep`, so adding a name to `disabledPackages` also removes the component when it is already installed. The next platform reconcile drops the Package, the operator's ownerReference takes the component's HelmRelease with it, and Flux uninstalls the release. There is no second command and no confirmation step, so back up anything you still need before making that edit.
+
+{{% alert title="Warning" color="warning" %}}
+Uninstalling the component's Helm release destroys more than the workloads. Anything the chart rendered as an ordinary template without `helm.sh/resource-policy: keep` goes with the release, CRDs and namespaces included, and Kubernetes deletes every custom resource of those CRD kinds along with them. Removing `cozystack.metallb` takes every CRD the MetalLB chart bundles, subcharts included, and with them every custom resource of those kinds cluster-wide; removing `cozystack.cozystack-basics` takes the `cozy-public` and `tenant-root` namespaces and everything stored in them, which is every application in the root tenant. Back up anything you still need first.
+{{% /alert %}}
+
+The namespace a component installs into is the exception: the operator applies that one itself, outside the component's release and with no ownerReference, so the uninstall never had it to remove.
+
+The removal starts when the operator picks the edit up, so take the component's releases first — the Package the selector needs goes away with the component. The operator labels every HelmRelease it renders with the name of the Package that produced it, and one Package can own several:
 
 ```bash
-kubectl delete hr -n <namespace> <component>
+kubectl get helmrelease --all-namespaces --selector cozystack.io/package=<package-name> \
+  --output custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,SUSPENDED:.spec.suspend'
 ```
+
+Clear `spec.suspend` on any release that shows `true` before making the edit. Flux skips the uninstall for a suspended HelmRelease and only drops its own finalizer, so that release disappears with everything it installed left behind and nothing left managing it.
+
+Then wait on each release from the listing to know the destructive part has finished:
+
+```bash
+kubectl wait --for=delete helmrelease/<name> --namespace <namespace> --timeout=10m
+```
+
+`kubectl wait --for=delete` exits 0 for a name that was never there, silently and with nothing to tell it apart from a deletion it watched, so take both values from the listing rather than guessing them. A returned wait says the HelmRelease is gone, not that the uninstall ran.
+
+`kubectl delete hr` is not a lighter-weight way to do the same thing. Flux uninstalls the release when an unsuspended HelmRelease goes away, so it destroys the same CRDs and custom resources, and then the Package recreates the HelmRelease and the chart reinstalls. The workloads come back, the custom resources do not. If you have run it before, those custom resources are already gone and have to be recreated from your own manifests or a backup.

content/en/docs/v1.1/install/providers/hetzner.md

@@ -344,9 +344,9 @@ The final stage of deploying a Cozystack cluster on Hetzner is to install Cozyst
           values:
             bundles:
               disabledPackages:
-                - metallb
+                - cozystack.metallb
               enabledPackages:
-                - hetzner-robotlb
+                - cozystack.hetzner-robotlb
             publishing:
               host: "example.org"
               apiServerEndpoint: "https://api.example.org:443"

content/en/docs/v1.1/operations/configuration/components.md

@@ -41,6 +41,7 @@ Bundles have optional components that need to be explicitly enabled (included) i
 Regular bundle components can, on the other hand, be disabled (excluded) from the installation, when you don't need them.
 
 Use `bundles.enabledPackages` and `bundles.disabledPackages` in the Platform Package values.
+Every entry in those lists is a fully-qualified name under the `cozystack.` prefix — run `kubectl get packagesource` to see the exact names on your cluster. `kubectl get package` answers only for `disabledPackages`, because an optional component has no Package object until its name is already in `enabledPackages`.
 For example, [installing Cozystack in Hetzner]({{% ref "/docs/v1.1/install/providers/hetzner" %}})
 requires swapping default load balancer, MetalLB, with one made specifically for Hetzner, called RobotLB:
 
@@ -56,16 +57,52 @@ spec:
       values:
         bundles:
           disabledPackages:
-            - metallb
+            - cozystack.metallb
           enabledPackages:
-            - hetzner-robotlb
+            - cozystack.hetzner-robotlb
         # rest of the config
 ```
 
 Disabling components must be done before installing Cozystack.
-Applying updated configuration with `disabledPackages` will not remove components that are already installed.
-To remove already installed components, delete the Helm release manually using this command:
+From v1.1.5 onward, applying updated configuration with `disabledPackages` will not remove components that are already installed.
+On v1.1.0 through v1.1.4 the platform does not annotate the Package with `helm.sh/resource-policy: keep`, so adding the name to `disabledPackages` does remove an installed component: the destruction described below happens at that point, and there is no second command to run. Back up anything you still need before making that edit. Take the listing below before making the edit and wait on the same releases afterwards: the Package its selector needs goes away with the component.
+
+From v1.1.5 onward, removing an installed component takes two steps. Add its name to `disabledPackages` in the Platform Package above, then wait for the operator to carry that edit across. The name appears in this output once it has:
+
+```bash
+kubectl get helmrelease cozystack-platform --namespace cozy-system \
+  --output jsonpath='{.spec.values.bundles.disabledPackages}'
+```
+
+Then delete the Package object.
+
+{{% alert title="Warning" color="warning" %}}
+Deleting the Package uninstalls the component's Helm release, and that destroys more than the workloads. Anything the chart rendered as an ordinary template without `helm.sh/resource-policy: keep` goes with the release, CRDs and namespaces included, and Kubernetes deletes every custom resource of those CRD kinds along with them. Removing `cozystack.metallb` takes every CRD the MetalLB chart bundles, subcharts included, and with them every custom resource of those kinds cluster-wide; removing `cozystack.cozystack-basics` takes the `cozy-public` and `tenant-root` namespaces and everything stored in them, which is every application in the root tenant. Back up anything you still need first.
+{{% /alert %}}
+
+The namespace a component installs into is the exception: the operator applies that one itself, outside the component's release and with no ownerReference, so the uninstall never had it to remove.
+
+List the releases the Package owns before deleting it. The operator labels every HelmRelease it renders with the name of the Package that produced it, and one Package can own several:
 
 ```bash
-kubectl delete hr -n <namespace> <component>
+kubectl get helmrelease --all-namespaces --selector cozystack.io/package=<package-name> \
+  --output custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,SUSPENDED:.spec.suspend'
 ```
+
+Clear `spec.suspend` on any release that shows `true` before going on. Flux skips the uninstall for a suspended HelmRelease and only drops its own finalizer, so that release disappears with everything it installed left behind and nothing left managing it.
+
+```bash
+kubectl delete package.cozystack.io <package-name>
+```
+
+Nothing holds a finalizer on the Package, so this command returns as soon as the object is gone and the uninstall it triggers runs afterwards. Wait on each release from the listing to know the destructive part has finished:
+
+```bash
+kubectl wait --for=delete helmrelease/<name> --namespace <namespace> --timeout=10m
+```
+
+`kubectl wait --for=delete` exits 0 for a name that was never there, silently and with nothing to tell it apart from a deletion it watched, so take both values from the listing rather than guessing them. A returned wait says the HelmRelease is gone, not that the uninstall ran.
+
+Deleting the Package while the platform values still render it means the next platform upgrade brings it back, undoing the removal one level up. Nothing reports this at the time: the delete succeeds either way and the Package reappears whenever that upgrade happens to run.
+
+`kubectl delete hr` is not a lighter-weight version of this. Flux uninstalls the release when an unsuspended HelmRelease goes away, so it destroys the same CRDs and custom resources, and then the Package recreates the HelmRelease and the chart reinstalls. The workloads come back, the custom resources do not. If you have run it before, those custom resources are already gone and have to be recreated from your own manifests or a backup.