Skip to content

docs(upgrade): add step to protect namespace before upgrading #435

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kvaps merged 1 commit into from
Feb 28, 2026
Merged

docs(upgrade): add step to protect namespace before upgrading #435

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions content/en/docs/v1/operations/cluster/upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,22 @@ Make sure that the Platform Package is healthy and contains the expected configu
kubectl get packages.cozystack.io cozystack.cozystack-platform -o yaml
```

### 2. Upgrade the Cozystack Operator
### 2. Protect critical resources

Before upgrading, annotate the `cozy-system` namespace and the `cozystack-version` ConfigMap
with `helm.sh/resource-policy=keep` to prevent Helm from deleting them during the upgrade:

```bash
kubectl annotate namespace cozy-system helm.sh/resource-policy=keep --overwrite
kubectl annotate configmap -n cozy-system cozystack-version helm.sh/resource-policy=keep --overwrite
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To improve the robustness of the upgrade script, it's a good practice to check for the existence of the cozystack-version ConfigMap before attempting to annotate it. This prevents the command from failing if the ConfigMap is not present, which could confuse users and halt their upgrade process. The suggested change wraps the annotation command in an if block that first verifies the ConfigMap exists.

Suggested change
kubectl annotate configmap -n cozy-system cozystack-version helm.sh/resource-policy=keep --overwrite
# Annotate the cozystack-version ConfigMap only if it exists
if kubectl get configmap -n cozy-system cozystack-version >/dev/null 2>&1; then
kubectl annotate configmap -n cozy-system cozystack-version helm.sh/resource-policy=keep --overwrite
fi

```

{{% alert color="warning" %}}
**This step is required.** Without these annotations, removing or upgrading the Helm installer
release could delete the `cozy-system` namespace and all resources within it.
{{% /alert %}}

### 3. Upgrade the Cozystack Operator

Upgrade the Cozystack operator Helm release to the target version:

Expand All @@ -57,7 +72,7 @@ You can read the logs of the operator:
kubectl logs -n cozy-system deploy/cozystack-operator -f
```

### 3. Check the cluster status after upgrading
### 4. Check the cluster status after upgrading

```bash
kubectl get pods -n cozy-system
Expand Down
25 changes: 20 additions & 5 deletions content/en/docs/v1/operations/upgrades/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,22 @@ If any releases are not `Ready`, resolve those issues before proceeding.

## Upgrade Steps

### Step 1. Install the Cozystack Operator
### Step 1. Protect critical resources

Annotate the `cozy-system` namespace and the `cozystack-version` ConfigMap to prevent
Helm from deleting them when the installer release is upgraded:

```bash
kubectl annotate namespace cozy-system helm.sh/resource-policy=keep --overwrite
kubectl annotate configmap -n cozy-system cozystack-version helm.sh/resource-policy=keep --overwrite
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To make the upgrade steps more robust, it's better to check if the cozystack-version ConfigMap exists before trying to annotate it. This avoids a potential failure in the script if the ConfigMap is not found, which could cause confusion for the user. The suggested change adds a check for the ConfigMap's existence before running the kubectl annotate command.

Suggested change
kubectl annotate configmap -n cozy-system cozystack-version helm.sh/resource-policy=keep --overwrite
# Annotate the cozystack-version ConfigMap only if it exists
if kubectl get configmap -n cozy-system cozystack-version >/dev/null 2>&1; then
kubectl annotate configmap -n cozy-system cozystack-version helm.sh/resource-policy=keep --overwrite
fi

```

{{% alert color="warning" %}}
**This step is required.** Without these annotations, upgrading the Helm installer release
could delete the `cozy-system` namespace and all resources within it.
{{% /alert %}}

### Step 2. Install the Cozystack Operator

Install the new operator using Helm from the OCI registry.
This deploys the `cozystack-operator`, installs two new CRDs (`Package` and `PackageSource`),
Expand All @@ -218,7 +233,7 @@ Verify the operator is running:
kubectl get pods -n cozy-system -l app=cozystack-operator
```

### Step 2. Generate the Platform Package
### Step 3. Generate the Platform Package

The migration script reads your existing ConfigMaps (`cozystack`, `cozystack-branding`, `cozystack-scheduling`)
from the `cozy-system` namespace and converts them into a `Package` resource with the new values structure.
Expand Down Expand Up @@ -247,7 +262,7 @@ chmod +x migrate-to-version-1.0.sh
```
{{% /alert %}}

### Step 3. Monitor the Migration
### Step 4. Monitor the Migration

As soon as the Platform Package is applied, the operator starts the migration process.
Migrations remove the old installer deployment and assets server, transform existing manifests
Expand All @@ -261,7 +276,7 @@ kubectl get hr -A

Wait until all releases show `READY: True`.

### Step 4. Clean Up Old ConfigMaps
### Step 5. Clean Up Old ConfigMaps

After verifying that all components are healthy, delete the old ConfigMaps
that are no longer used:
Expand All @@ -270,7 +285,7 @@ that are no longer used:
kubectl delete configmap -n cozy-system cozystack cozystack-branding cozystack-scheduling
```

### Step 5. Verify the Migration
### Step 6. Verify the Migration

Check that the Platform Package is reconciled:

Expand Down