Settings View Source Upgrade v24.5.x-v26.5.x

This page describes the required steps to upgrade your Astarte cluster from v24.5.x to v26.5.x. Since the Astarte Operator v26.5 supports Astarte 1.3+, be prepared to upgrade your Astarte instance. See the Astarte CHANGELOG to inspect what's changed.

[!WARNING]
To use Astarte v1.3.x, you must upgrade your Astarte Operator to v26.5.x. Similarly, to use Astarte Operator v26.5.x, you must upgrade your Astarte instance to v1.3.x. These two upgrades have a lot of breaking changes, so make sure to follow this guide carefully.

breaking-changes

Breaking changes

• Starting from Astarte Operator v26.5.x, the Operator will no longer handle the deployment of Scylla and RabbitMQ instances. Migration of existing Scylla and RabbitMQ instances outside of the Astarte Operator scope is required before proceeding with the upgrade.
• Astarte and ADI CRDs are bumped to v2alpha1. Older versions (Astarte v1alpha3, ADI v1alpha2) are unsupported. Convert existing CRs to v2alpha1 before proceeding with the upgrade.
• The Astarte Operator v26.5.x introduces support for the HAPROXY Ingress Controller as the default Ingress Controller for Astarte deployments. Deployments currently using the NGINX Ingress Controller may switch to HAPROXY during the upgrade process. NGINX is deprecated and its support will be removed in the next release cycle.

prerequisites

Prerequisites

[!WARNING]
Downtime will be required to perform this upgrade. Ensure to schedule a maintenance window accordingly.

step-0-block-data-entry-points

Step 0: Block data entry points

Block data entry points so no new data is exchanged through VerneMQ, RabbitMQ or stored in Scylla. This will help to ensure data consistency during the upgrade process.

step-1-scylla-and-rabbitmq-migration

Step 1: Scylla and RabbitMQ migration

From Operator 26.5.x onward, Scylla and RabbitMQ are no longer deployed or managed by the Operator. Before upgrading, ensure Astarte instances point to externally managed Scylla and RabbitMQ.

Ensure to:

• Identify whether the Astarte instance still relies on Operator-managed Scylla or RabbitMQ.
• Provision external Scylla and RabbitMQ (same cluster, separate cluster, VMs, or managed services all work).
• Migrate data from the Operator-managed services to the new external ones.
• Save connection details (hosts, ports, credentials, TLS) and update the Astarte CRs after conversion accordingly.

step-2-backup-astarte-resources

Step 2: Backup Astarte resources

Backing up Astarte resources is strongly recommended before proceeding with the upgrade. For more information about how to back up Astarte resources, refer to the following section

• How to backup Astarte resources

Specifically, ensure to back up:

• Astarte CR
• AstarteDefaultIngress CR
• Astarte devices CA certificate and key
• Housekeeping private and public keys

The upgrade procedure requires deleting the existing Astarte and ADI CRs from the cluster, so having a backup is crucial to restore the Astarte instance after the upgrade.

step-3-astarte-and-adi-cr-conversion

Step 3: Astarte and ADI CR conversion

Once you have backed up your Astarte resources, you need to convert your existing Astarte and ADI CRs to the new versions supported by Astarte Operator v26.5.x and Astarte v1.3.x.

• Convert the Astarte CR v1alpha3 or v1alpha2 to Astarte CR v2alpha1
• Convert the ADI CR v1alpha2 to ADI CR v2alpha1

The conversion can be done manually by following the CRD documentation for Astarte v2alpha1 and ADI v2alpha1.

Ensure that:

• The astarteInstanceID field value is the same in both the converted Astarte and ADI CRs.
• The replication strategy, replication factor, and replica distribution per datacenter are correctly set in the converted Astarte CR according to your Scylla cluster configuration.

See:

• Astarte CR Changes from v1alpha3 to v2alpha1
• ADI CR Changes from v1alpha1 to v2alpha1

upgrade-procedure

Upgrade procedure

step-1-delete-existing-astarte-and-adi-crs

Step 1: Delete existing Astarte and ADI CRs

Delete the existing Astarte and ADI CRs from the cluster. This triggers the deletion of all the resources managed by the Operator related to these CRs.

kubectl delete astarte -n <astarte-namespace> <astarte-name>
kubectl delete adi -n <astarte-namespace> <adi-name> 

Wait for the deletion process to complete and double check that all Astarte-related resources have been deleted from the cluster before proceeding with the next steps.

step-2-delete-existing-astarte-operator-with-helm

Step 2: Delete existing Astarte Operator (with Helm)

For Helm deployments, delete the Astarte Operator using the following commands:

helm list -A # Find the release name of the Astarte Operator
helm uninstall -n <operator-namespace> <release-name>

step-3-delete-crds-and-leftovers

Step 3: Delete CRDs and leftovers

Starting from v24.5.0, the removal of the Operator preserves the Astarte, AstarteDefaultIngress and Flow CRDs. To prevent unwanted deletion of the deployed custom resources, the removal of the CRDs must be performed manually.

# List Astarte-related CRDs
kubectl get crd | grep 'astarte-platform.org'

# Delete Astarte-related CRDs
kubectl delete crd astartes.api.astarte-platform.org
kubectl delete crd astartedefaultingresses.ingress.astarte-platform.org
kubectl delete crd flows.flow.astarte-platform.org

If the CRD deletion hangs due to finalizers, patch the resources and remove them:

kubectl patch crd astartes.api.astarte-platform.org .api.astarte-platform.org --type=json -p='[{"op": "remove", "path": "/metadata/finalizers"}]'
kubectl patch crd astartedefaultingresses.ingress.astarte-platform.org .ingress.astarte-platform.org --type=json -p='[{"op": "remove", "path": "/metadata/finalizers"}]'

At this point, all Astarte-related resources should be deleted from the cluster.

step-4-assign-an-astarte-instance-id-optional

Step 4: Assign an Astarte Instance ID (optional)

If the Astarte instance being upgraded does not have an instanceID assigned in the Astarte CR and if you are using RabbitMQ or Scylla shared among multiple Astarte instances, it is mandatory to assign an instanceID to the Astarte instance being upgraded. If you are using RabbitMQ and Scylla for one single Astarte, or if the Astarte instance being upgraded already has an instanceID assigned, skip this step.

Choose a unique astarteInstanceID for your Astarte instance. This can be any string that uniquely identifies your instance. Since each Astarte Realm is associated with a Scylla keyspace, you will need to define a new keyspace name for each realm using this astarteInstanceID. Refer to the Set up an instance id section for more information.

• The keyspace names must follow the pattern: <astarteInstanceID><realm_name>.
• Dashes (-) and underscores (_) characters are not allowed.
• The maximum length for keyspace names is 48 characters.
• Ensure that there are no keyspace name collisions with existing keyspaces in your Scylla instance.

Update the converted Astarte CR to include an instanceID field under spec. Set the value to the astarteInstanceID you chose for your instance.

For each realm associated with your Astarte instance, handle the corresponding Scylla keyspaces to include the new astarteInstanceID prefix in the name. Scylla does not support renaming keyspaces, so, for each Realm, you will need to:

• Create a new keyspace with the new name following the pattern <astarteInstanceID><realm_name> and the same replication settings as the old keyspace.
• Migrate the data from the old keyspace to the new keyspace.
• Drop the old keyspace once the data migration is complete.

step-5-restore-devices-ca-and-housekeeping-keys

Step 5: Restore devices CA and housekeeping keys

Restore the Astarte devices CA certificate and key as well as the Housekeeping private and public by creating the appropriate secrets in your Astarte namespace. When the Astarte Operator will be redeployed, it will detect these secrets and use them instead of generating new ones.

kubectl create secret generic astarte-housekeeping-private-key -n <astarte-namespace> \
  --from-file=private-key=./housekeeping_private.pem
  
kubectl create secret generic astarte-housekeeping-public-key -n <astarte-namespace> \
  --from-file=public-key=./housekeeping_public.pem
  
kubectl create secret tls astarte-devices-ca -n <astarte-namespace> \
  --key ./astarte-devices-ca.key \
  --cert ./astarte-devices-ca.crt

step-6-uninstall-nginx-ingress-controller-optional

Step 6: Uninstall NGINX Ingress Controller (OPTIONAL)

Starting from Astarte Operator v26.5.x ,the HAPROXY Ingress Controller is the default Ingress Controller for Astarte deployments. If you are currently using the NGINX Ingress Controller, you may choose to uninstall it and switch to HAPROXY. This step is optional, however, NGINX is deprecated and its support will be removed in the next release cycle.

step-7-install-haproxy-ingress-controller-optional

Step 7: Install HAProxy Ingress Controller (OPTIONAL)

If you decided to switch to the HAPROXY Ingress Controller, this is the moment to install it in your cluster if you haven't done it already. The annotation ingress.astarte-platform.org/ingress-controller-selector in the ADI CR can be used to specify which Ingress Controller the Astarte Operator should use.

By default, the Operator assumes the HAPROXY Ingress Controller is in use, in fact the annotation is set by default to:

ingress.astarte-platform.org/ingress-controller-selector: "haproxy.org"

To continue using NGINX, set the annotation to:

ingress.astarte-platform.org/ingress-controller-selector: "nginx.ingress.kubernetes.io"

Depending on the value of this annotation, the Operator will create Ingress resources compatible with the selected Ingress Controller. Ensure to adjust the annotation in your converted ADI CR accordingly.

step-8-deploy-astarte-operator-v26-5-x

Step 8: Deploy Astarte Operator v26.5.x

Deploy the Astarte Operator v26.5.x in your cluster. You can follow the installation instructions provided in the Installation Guide.

step-9-apply-converted-astarte-and-adi-crs

Step 9: Apply converted Astarte and ADI CRs

Apply the converted Astarte and ADI CRs to your cluster. This will trigger the deployment of Astarte v1.3.x and all its components.

kubectl apply -f converted-astarte-cr.yaml
kubectl apply -f converted-adi.yaml