The current section describes the required steps to upgrade your Astarte instance from
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
AstarteDefaultIngressin place of the deprecated
Before starting with the upgrade procedure it is strongly advised to backup your Astarte resources.
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
--version flag when running
To upgrade the Astarte CRDs, the following environment variables will be employed:
ASTARTE_OP_TEMPLATE_DIRis the target directory in which the chart templates will be generated,
ASTARTE_OP_RELEASE_NAMEis the name of the Astarte Operator deployment,
ASTARTE_OP_RELEASE_NAMESPACEis 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
--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.
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
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,
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.
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
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.
The current section describes the procedure for replacing the deprecated
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.