Settings View Source Upgrade v1.0.0-v1.0.x

The current section describes the required steps to upgrade your Astarte instance from v1.0.0 to v1.0.x. Currently, the last released patch version is v1.0.3 and, as such, the remainder of this page will refer to this version. The described upgrade path involves some heavy changes as a consequence of this Voyager announcement and the following Astarte design choice.

Before moving on, it must be clear that AstarteVoyagerIngress is deprecated and that the only supported managed ingress is the AstarteDefaultIngress .

The upcoming sections will cover the following topics:

• upgrading the Astarte Operator,
• upgrading the Astarte instance to allow for TLS termination at VerneMQ level,
• deployment of the AstarteDefaultIngress in place of the deprecated AstarteVoyagerIngress.

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

upgrade-astarte-operator

Upgrade Astarte Operator

Astarte Operator's upgrade procedure is handled by Helm. However, according to the Helm policies, upgrading the CRDs must be handled manually.

The current section assumes that the Operator's chart landing version is v1.0.3. If a more recent chart version is available, it is your responsibility referencing to the v1.0.3 chart using the --version flag when running helm commands.

To upgrade the Astarte CRDs, the following environment variables will be employed:

• ASTARTE_OP_TEMPLATE_DIR is the target directory in which the chart templates will be generated,
• ASTARTE_OP_RELEASE_NAME is the name of the Astarte Operator deployment,
• ASTARTE_OP_RELEASE_NAMESPACE is the namespace in which the Astarte Operator resides.

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_TEMPLATE_DIR=/tmp
export ASTARTE_OP_RELEASE_NAME=astarte-operator
export ASTARTE_OP_RELEASE_NAMESPACE=kube-system

Update your local Helm charts:

$ helm repo update

Render the Helm templates with the following:

helm template $ASTARTE_OP_RELEASE_NAME astarte/astarte-operator \
    --namespace $ASTARTE_OP_RELEASE_NAMESPACE \
    --output-dir $ASTARTE_OP_TEMPLATE_DIR

After these steps you will find the updated CRDs within $ASTARTE_OP_TEMPLATE_DIR/$ASTARTE_OP_RELEASE_NAME/templates/crds.yaml. Update the CRDs in your cluster by replacing the CRDs yaml file:

kubectl replace -f $ASTARTE_OP_TEMPLATE_DIR/$ASTARTE_OP_RELEASE_NAME/templates/crds.yaml

The previous command will raise an error saying customresourcedefinitions.apiextensions.k8s.io "astartedefaultingresses.ingress.astarte-platform.org" not found. It is nothing to worry about: under the hood the replace command has updated the CRDs for Astarte, AstarteVoyagerIngress and Flow, while it cannot replace the AstarteDefaultIngress CRD as it is not installed yet. This issue is easily fixed with the next command.

To upgrade the Operator use the dedicated helm upgrade command:

helm upgrade astarte-operator astarte/astarte-operator -n kube-system

The optional --version switch allows to specify the version to upgrade to - when not specified, the latest version will be fetched and used. If you choose to upgrade to a specific version of the chart by using the --version flag, please make sure to generate the updated CRDs template using the same chart version.

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 usual --version flag to point to a specific chart version.

upgrade-astarte

Upgrade Astarte

To upgrade your Astarte instance simply edit the Astarte resource in the cluster updating the version field to the one you want to upgrade to.

In order to properly expose your Astarte instance to the outer world through the AstarteDefaultIngress a configuration change for VerneMQ is required: in particular, TLS termination must be handled at VerneMQ level.

Open the yaml file describing the Astarte resource with:

kubectl edit astarte -n astarte

Find the version field in the Astarte Spec section and change it according to your needs (i.e.: set it to 1.0.3). Moreover, in the vernemq configuration section two new fields must be added, namely sslListener and sslListenerCertSecretName: the first field is a boolean that, when true, set VerneMQ to handle TLS termination, while the latter set the secret containing the TLS certificate (further details on certificates can be found here).

To summarize, the needed changes will look like the following sample snippet:

apiVersion: api.astarte-platform.org/v1alpha2
kind: Astarte
...
spec:
  ...
  vernemq:
    sslListener: true
    sslListenerCertSecretName: <your-tls-secret-name>
    ...
  version: 1.0.3

Once the yaml file is applied, the Operator will take over ensuring the reconciliation of your Astarte instance.

caveats-for-astarte-flow

Caveats for Astarte Flow

Currently, although Astarte Flow is a component of Astarte, it doesn't follow Astarte's release cycle. Therefore if you upgraded your Astarte instance to v1.0.3, Astarte Operator will try to deploy astarte/astarte_flow:1.0.3 which is currently not existent.

All you have to do to overcome this temporary limitation is to edit your Astarte resource by explicitly setting the Astarte Flow image you plan to use:

spec:
  ...
  components:
    ...
    flow:
      image: <the-astarte-flow-image>

All the available Astarte Flow's tags can be found here.

deploy-astartedefaultingress-in-place-of-astartevoyageringress

Deploy AstarteDefaultIngress in place of AstarteVoyagerIngress

The current section describes the procedure for replacing the deprecated AstarteVoyagerIngress with the new AstarteDefaultIngress. If the Voyager ingress is not deployed within your cluster, feel free to skip this section.

The advised migration path involves the employment of astartectl: this is the most straightforward way of performing the migration task and, as soon as all the requirements are satisfied, it requires the execution of one single command.

The Migrating to the AstarteDefaultIngress page extensively cover this topic.