Astarte Operator
Astarte Operator v24.5.0

View Source Upgrade v1.0.x-v22.11.x

This page describes the required steps to upgrade your Astarte cluster from v1.0.x to v22.11.x. Your Astarte instance will not need to be upgraded. The change in the versioning scheme of the Astarte Operator is meant to better keep up with Kubernetes release cycle (see the related issue for more information).

Starting from the Astarte Operator v22.11 release, the old api.astarte-platform.org/v1alpha1 APIs are deprecated and will be removed in the next release.

In the following, the upgrade path is described.

The upcoming sections will cover the following topics:

  • upgrading the Astarte Operator,
  • making sure that the Astarte, AstarteVoyagerIngress and Flow CR are stored using v1alpha2 API version,
  • upgrading the Astarte, AstarteVoyagerIngress and Flow CRDs to have only v1alpha2 as storage version.

Before starting with the upgrade procedure it is strongly advised to backup your Astarte resources.

upgrade-astarte-operator

 Upgrade Astarte Operator

The Astarte Operator upgrade procedure is handled by Helm.

The current section assumes that the Operator's chart landing version is v22.11.x. It is your responsibility referencing the proper v22.11.x chart using the --version flag when running helm commands.

Please, make sure that the values you set for both the Operator's name and namespace match the naming you already adopted when installing the Operator. A wrong naming can lead to a malfunctioning Astarte cluster.

For standard deployments the following variables should be ok. However, it is your responsibility checking that the values you set are consistent with your setup:

export ASTARTE_OP_RELEASE_NAME=astarte-operator
export ASTARTE_OP_RELEASE_NAMESPACE=astarte-operator
export ASTARTE_OP_CHART_VERSION=<22.11.x>

Update your local Helm charts:

helm repo update

To upgrade the Operator use the dedicated helm upgrade command:

helm upgrade $ASTARTE_OP_RELEASE_NAME astarte/astarte-operator -n $ASTARTE_OP_RELEASE_NAMESPACE \
  --version $ASTARTE_OP_CHART_VERSION

The optional --version switch allows to specify the version to upgrade to - when not specified, the latest version will be fetched and used.

By design, Astarte Operator's Helm charts cannot univocally be mapped to Operator's releases in a one-to-one relationship. However each chart is tied to a specific Operator's version, which is user configurable.

Therefore, upgrading a chart leads to an Operator's upgrade if and only if the Operator's tag referenced by the chart is changed. You can check the Operator's tag bound to the chart simply running:

helm show values astarte/astarte-operator

As usual, you can use the --version flag to point to a specific chart version.

make-sure-astarte-is-stored-using-the-api-astarte-platform-org-v1alpha2-apiversion

 Make sure Astarte is stored using the api.astarte-platform.org/v1alpha2 apiVersion

To do so, simply edit the Astarte resource in the cluster. Open the yaml file describing the Astarte resource with:

kubectl edit astarte -n astarte

Find the apiVersion field in the Astarte Spec section and change it (if needed) to api.astarte-platform.org/v1alpha2.

After having done this, you Astarte CR will look like this:

apiVersion: api.astarte-platform.org/v1alpha2
kind: Astarte
...
spec:
  ...
status:
  ...

Once the yaml file is applied, the Operator will take over ensuring the reconciliation of your Astarte instance. This will in turn change the version in which the Astarte CR is stored in Kubernetes to api.astarte-platform.org/v1alpha2.

make-sure-flow-is-stored-using-the-api-astarte-platform-org-v1alpha2-apiversion

 Make sure Flow is stored using the api.astarte-platform.org/v1alpha2 apiVersion

To do so, simply edit the Flow resource in the cluster.
Open the yaml file describing the Flow resource with:

kubectl edit flow -n astarte

Find the apiVersion field in the Flow Spec section and change it (if needed) to api.astarte-platform.org/v1alpha2.

After having done this, your Flow CR will look like this:

apiVersion: api.astarte-platform.org/v1alpha2
kind: Flow
...
spec:
  ...
status:
  ...

Once the yaml file is applied, the Operator will take over ensuring the reconciliation of your Flow instance. This will in turn change the version in which the Flow CR is stored in Kubernetes to api.astarte-platform.org/v1alpha2.

make-sure-the-apiversion-of-astartevoyageringress-is-api-astarte-platform-org-v1alpha2

 Make sure the apiVersion of AstarteVoyagerIngress is api.astarte-platform.org/v1alpha2

The AstarteVoyagerIngress is deprecated and will be removed starting from Astarte Operator v23.5.0. Please consider switching to the new AstarteDefaultIngress.

If you already have dropped the AstarteVoyagerIngress, you can skip this section.

To do so, simply edit the AstarteVoyagerIngress resource in the cluster. Open the yaml file describing the AstarteVoyagerIngress resource with:

kubectl edit avi -n astarte

Find the apiVersion field in the AstarteVoyagerIngress Spec section and change it (if needed) to api.astarte-platform.org/v1alpha2.

After having done this, your AstarteVoyagerIngress CR will look like this:

apiVersion: api.astarte-platform.org/v1alpha2
kind: AstarteVoyagerIngress
...
spec:
  ...
status:
  ...

Once the yaml file is applied, the Operator will take over ensuring the reconciliation of your AstarteVoyagerIngress instance. This will in turn change the version in which the AstarteVoyagerIngress CR is stored in Kubernetes to api.astarte-platform.org/v1alpha2.

upgrade-the-crds-to-the-new-storage-version

 Upgrade the CRDs to the new storage version

This step is handled by astartectl. Ensure that astartectl is installed on your machine and its version is at least >= v22.11.00.

Performing the actual upgrade is as simple as executing the following command:

$ astartectl cluster instances migrate storage-version

If an error occurs during the migration procedure, changes made by migrate storage-version will be reverted, so that you can make sure of having performed all necessary steps described in this page before trying again.

what-happens-under-the-hood

 What happens under the hood?

When invoking the migrate storage-version command, astartectl interacts with your Astarte cluster and retrieves the Astarte, Flow and AVI CRDs which are installed. Then, it checks that the CRDs are in a state consistent with the migration step it needs to perform, i.e. that each one of them has both v1alpha1 and v1alpha2 as storedVersions. For example, your Astarte CRD will look like this:

name: astartes.api.astarte-platform.org
...
spec:
  ...
status:
  ...
  storedVersions:
  - v1alpha1
  - v1alpha2

Then, astartectl simply shrinks the status.storedVersions field to just v1alpha2. After having run the command, your Astarte CRD will look like this:

name: astartes.api.astarte-platform.org
...
spec:
  ...
status:
  ...
  storedVersions:
  - v1alpha2

If one of the previous tasks is not successful, the migration logic is reverted as not to leave your cluster in a broken state.