From 47987ba89a88caacaaf76329bfd74d8a62925096 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20Wanzenb=C3=B6ck?= Date: Mon, 20 Nov 2023 09:24:02 +0100 Subject: [PATCH] docs: wrapping index for v1 to v2 migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This index also contains the main changes between the different operator versions. Signed-off-by: Moritz Wanzenböck --- UPGRADE.md | 2 +- docs/how-to/upgrade/index.md | 60 ++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 docs/how-to/upgrade/index.md diff --git a/UPGRADE.md b/UPGRADE.md index 22bb1c5c..a724ea36 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -5,7 +5,7 @@ volumes and volumes already in use by a pod will continue to work without interr # Upgrades from v1 to v2 -There currently is no documented upgrade path from Operator v1 to v2. +Please follow the specialized [upgrade guides](./docs/how-to/upgrade/index.md). # Upgrade from v1.9 to v1.10 diff --git a/docs/how-to/upgrade/index.md b/docs/how-to/upgrade/index.md new file mode 100644 index 00000000..23d8f0e1 --- /dev/null +++ b/docs/how-to/upgrade/index.md @@ -0,0 +1,60 @@ +# Upgrading Piraeus Operator from Version 1 to Version 2 + +The following document guides you through the upgrade process for Piraeus Operator from version 1 ("v1") +to version 2 ("v2"). + +Piraeus Operator v2 offers improved convenience and customization. This however made it necessary to make significant +changes to the way Piraeus Operator manages Piraeus Datastore. As such, upgrading from v1 to v2 is a procedure +requiring manual oversight. + +Upgrading Piraeus Operator is done in four steps: + +* [Step 1]: (Optional) Migrate the LINSTOR database to use the `k8s` backend. +* [Step 2]: Collect information about the current deployment. +* [Step 3]: Remove the Piraeus Operator v1 deployment, keeping existing volumes untouched. +* [Step 4]: Deploy Piraeus Operator v2 using the information gathered in step 2. + +[Step 1]: ./1-migrate-database.md +[Step 2]: ./2-collect-information.md +[Step 3]: ./3-remove-operator-v1.md +[Step 4]: ./4-install-operator-v2.md + +## Prerequisites + +This guide assumes: + +* You used Helm to create the original deployment and are familiar with upgrading Helm deployments. +* Your Piraeus Datastore deployment is up-to-date with the latest v1 release. Check the releases [here](https://github.com/piraeusdatastore/piraeus-operator/releases?q=v1&expanded=true). +* You have the following command line tools available: + - [`kubectl`](https://kubernetes.io/docs/tasks/tools/) + - [`helm`](https://docs.helm.sh/docs/intro/install/) + - [`jq`](https://jqlang.github.io/jq/download/) +* You are familiar with the `linstor` command line utility, specifically to verify the cluster state. + +## Key Changes Between Operator V1 and V2 + +### Administrative Changes + +* The resources `LinstorController`, `LinstorSatelliteSet` and `LinstorCSIDriver` have been replaced by + [`LinstorCluster`](../../reference/linstorcluster.md) and + [`LinstorSatelliteConfgiuration`](../../reference/linstorsatelliteconfiguration.md). +* The default deployment runs the LINSTOR Satellite in the [container network](../drbd-host-networking.md). + The migration script will propose changing to the host network. + +### Operational Changes + +* In Operator v1, all labels on the Kubernetes node resource were replicated on the satellite, making them usable in the + `replicasOnSame` and `replicasOnDifferent` parameters on the storage class. In Operator v2, only the following + labels are automatically synchronized. + * `kubernetes.io/hostname` + * `topology.kubernetes.io/region` + * `topology.kubernetes.io/zone` + Use [`LinstorSatelliteConfiguration.spec.properties`](../../reference/linstorsatelliteconfiguration.md#specproperties) + to synchronize additional labels. +* The following settings are applied by Operator v2 cluster-wide: + * DrbdOptions/Net/rr-conflict: retry-connect + * DrbdOptions/Resource/on-suspended-primary-outdated: force-secondary + * DrbdOptions/Resource/on-no-data-accessible: suspend-io + * DrbdOptions/auto-quorum: suspend-io +* Operator v2 also includes a [High-Availability Controller](https://github.com/piraeusdatastore/piraeus-ha-controller) + deployment to prevent stuck nodes caused by suspended DRBD devices.