From 17ada823f741b2e270205904c9b0a941f9c2938e Mon Sep 17 00:00:00 2001 From: nbykov0 <166552198+nbykov0@users.noreply.github.com> Date: Mon, 2 Feb 2026 17:11:54 +0300 Subject: [PATCH 1/2] [operations] Describe upgrade to v1.0 Signed-off-by: nbykov0 <166552198+nbykov0@users.noreply.github.com> --- content/en/docs/operations/upgrades/_index.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 content/en/docs/operations/upgrades/_index.md diff --git a/content/en/docs/operations/upgrades/_index.md b/content/en/docs/operations/upgrades/_index.md new file mode 100644 index 00000000..3d012c11 --- /dev/null +++ b/content/en/docs/operations/upgrades/_index.md @@ -0,0 +1,37 @@ +--- +title: "Upgrades" +linkTitle: "Upgrades" +description: "Upgrade guides" +weight: 1 +--- + +## Upgrading to v1.0 + +Version 1.0 brings major change to Cozystack control-plane: it is now completely modular and is composed of independent packages. +To manage packages a cozystack-operator was introduced, which replaces previous installer. +Assets server is now replaced with a single oci image, and it could be replaced with a git repository if needed. + +However, underlying entities are still helm releases made of helm charts, so during an upgrade no workloads would be recreated or affected in any way. + +### 1. Prerequisites +Along with version 1.0 new management tools were introduced: `cozyhr` and `cozypkg`. You will need their latest versions to proceed with the upgrade. +- Take `cozypkg` from the Cozystack Releases page: https://github.com/cozystack/cozystack/releases +- Take `cozyhr` from its repository: https://github.com/cozystack/cozyhr/releases +You will also need regular tools such as flux, jq, kubectl, and such. + +### 2. Upgrade +- Upgrade to the most recent v0.4x version, such as v0.41.5 +- Apply `cozystack-crds.yaml` from the Cozystack Releases page, it contains definitions for new custom resources, such as Package and PackageSource. +- Generate and apply the main package for your installation with the `/hack/migrate-to-version-1.0.sh` script from the Cozystack repository. + It will gather values from existing configmaps in the `cozy-system` namespace, and assemble a `Package` resource with all the values. +- Scale down `installer` and `assets-server` so that they do not interfere with the new control-plane: + `kubectl -n cozy-system scale deploy/cozystack --replicas=0` + `kubectl -n cozy-system scale sts/cozystack-assets --replicas=0` +- Apply `cozystack-operator.yaml` from the Cozystack Releases page, it will bring cozystack operator to the cluster. + As soon as it is deployed, it will start migrations and upgrades, and you can track the progress by checking `HelmRelease` statuses with + `kubectl get hr -A` +- After the upgrade is complete, it's time for a cleanup: + `flux -n cozy-system suspend hr cozystack-resource-definition-crd && flux -n cozy-system delete hr cozystack-resource-definition-crd` + `kubectl -n cozy-system get hr bootbox-rd -o yaml | grep -q HelmRepository && flux -n cozy-system suspend hr bootbox-rd && flux -n cozy-system delete hr bootbox-rd` + +And that's it! From ced3eb7b9213ebc042b31014c1f008689c01e211 Mon Sep 17 00:00:00 2001 From: Andrei Kvapil Date: Wed, 4 Feb 2026 01:58:09 +0100 Subject: [PATCH 2/2] docs(upgrades): simplify v1.0 upgrade instructions Migrations now automatically clean up legacy components: - Old installer deployment - Assets-server statefulset - Obsolete HelmReleases (cozystack-resource-definition-crd, bootbox-rd) Manual cleanup steps are no longer required. Co-Authored-By: Claude Signed-off-by: Andrei Kvapil --- content/en/docs/operations/upgrades/_index.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/content/en/docs/operations/upgrades/_index.md b/content/en/docs/operations/upgrades/_index.md index 3d012c11..e0871f86 100644 --- a/content/en/docs/operations/upgrades/_index.md +++ b/content/en/docs/operations/upgrades/_index.md @@ -22,16 +22,12 @@ You will also need regular tools such as flux, jq, kubectl, and such. ### 2. Upgrade - Upgrade to the most recent v0.4x version, such as v0.41.5 - Apply `cozystack-crds.yaml` from the Cozystack Releases page, it contains definitions for new custom resources, such as Package and PackageSource. -- Generate and apply the main package for your installation with the `/hack/migrate-to-version-1.0.sh` script from the Cozystack repository. +- Apply `cozystack-operator.yaml` from the Cozystack Releases page, it will bring cozystack operator to the cluster. +- Generate and apply the main package for your installation with the `/hack/migrate-to-version-1.0.sh` script from the Cozystack repository. It will gather values from existing configmaps in the `cozy-system` namespace, and assemble a `Package` resource with all the values. -- Scale down `installer` and `assets-server` so that they do not interfere with the new control-plane: - `kubectl -n cozy-system scale deploy/cozystack --replicas=0` - `kubectl -n cozy-system scale sts/cozystack-assets --replicas=0` -- Apply `cozystack-operator.yaml` from the Cozystack Releases page, it will bring cozystack operator to the cluster. - As soon as it is deployed, it will start migrations and upgrades, and you can track the progress by checking `HelmRelease` statuses with - `kubectl get hr -A` -- After the upgrade is complete, it's time for a cleanup: - `flux -n cozy-system suspend hr cozystack-resource-definition-crd && flux -n cozy-system delete hr cozystack-resource-definition-crd` - `kubectl -n cozy-system get hr bootbox-rd -o yaml | grep -q HelmRepository && flux -n cozy-system suspend hr bootbox-rd && flux -n cozy-system delete hr bootbox-rd` + +As soon as the Package is applied, the operator will start migrations and upgrades automatically. +Migrations will clean up legacy components (old installer, assets-server, and obsolete HelmReleases). +You can track the progress by checking `HelmRelease` statuses with `kubectl get hr -A`. And that's it!