Upgrading from v0.41 to v1.0

Overview

Version 1.0 introduces a major change to the Cozystack control plane: it is now completely modular and composed of independent packages managed by the new cozystack-operator.

Key changes:

• The old installer deployment is replaced by cozystack-operator.
• Configuration is no longer stored in ConfigMaps — it is now defined by a Package custom resource.
• The assets server is replaced with a single OCI image.
• New CRDs are introduced: Package and PackageSource.

The underlying entities are still Helm releases, so during the upgrade no workloads are recreated or affected.

Prerequisites

1. Install required tools

The following tools are required for the migration:

• kubectl and jq — standard cluster administration tools.
• helm — required for installing the new operator.
• cozypkg — new CLI for managing Package and PackageSource resources. Download from the Cozystack Releases page.
• cozyhr — tool for managing HelmRelease values. Download from the cozyhr repository.

2. Verify kubectl context

Make sure your current kubectl context points to the cluster you are upgrading:

kubectl config current-context

3. Upgrade to the latest v0.41.x

Before migrating to v1.0, make sure you are running the most recent v0.41 patch release.

Check your current version:

kubectl get configmap -n cozy-system cozystack -o jsonpath='{.metadata.labels.cozystack\.io/version}'

If you are on an older version, upgrade to the latest v0.41.x first using the standard upgrade procedure.

4. Verify cluster health

Before upgrading, verify that all HelmReleases are in a healthy state:

kubectl get hr -A | grep -v "True"

If any releases are not Ready, resolve those issues before proceeding.

Upgrade Steps

Step 1. 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), and creates the PackageSource resource for the platform.

helm install cozystack oci://ghcr.io/cozystack/cozystack/cozy-installer \
  --version <TARGET_VERSION> \
  --namespace cozy-system \
  --create-namespace \
  --take-ownership

Replace <TARGET_VERSION> with the desired release version (e.g., 1.0.0).

Verify the operator is running:

kubectl get pods -n cozy-system -l app=cozystack-operator

Step 2. 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.

Download and run the migration script from the Cozystack repository:

curl -fsSL https://raw.githubusercontent.com/cozystack/cozystack/main/hack/migrate-to-version-1.0.sh | bash

The script will:

1. Read configuration from existing ConfigMaps.
2. Convert old bundle naming (paas-*) to new variant naming (isp-*).
3. Generate a Package resource and display it for review.
4. Prompt for confirmation before applying.

curl -fsSL -o migrate-to-version-1.0.sh \
  https://raw.githubusercontent.com/cozystack/cozystack/main/hack/migrate-to-version-1.0.sh
chmod +x migrate-to-version-1.0.sh
./migrate-to-version-1.0.sh

Step 3. 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 to the new format, and reconcile all components under the new Package-based management.

Monitor HelmRelease statuses:

kubectl get hr -A

Wait until all releases show READY: True.

Step 4. Clean Up Old ConfigMaps

After verifying that all components are healthy, delete the old ConfigMaps that are no longer used:

kubectl delete configmap -n cozy-system cozystack cozystack-branding cozystack-scheduling

Step 5. Verify the Migration

Check that the Platform Package is reconciled:

kubectl get packages.cozystack.io cozystack.cozystack-platform

Run a full cluster health check:

kubectl get hr -A | grep -v "True"
kubectl get pods -n cozy-system

If any HelmReleases are not Ready, check the operator logs for details.

Troubleshooting

Operator fails to start

If the operator pod is in CrashLoopBackOff, check the logs:

kubectl logs -n cozy-system deploy/cozystack-operator --previous

HelmReleases stuck after migration

During the migration, some HelmReleases may temporarily show errors while the operator reconciles them. Wait a few minutes and check again. If issues persist, consult the Troubleshooting Checklist.