Settings View Source Upgrade v0.11-v1.0

upgrade-astarte-operator

Upgrade Astarte Operator

The upgrade procedure from v0.11 to v1.0 requires some manual intervention as the deployment and handling of the Operator's lifecycle has changed: if v0.11 is entirely handled with astartectl, v1.0 employs Helm charts.

Helm is intended to be used as the operator's lifecycle management tool, thus make sure you are ready with a working Helm installation.

migrate-ca-certificate-and-key

Migrate CA certificate and key

Currently you have to manually migrate the CA certificate and private key to the new installation. This is critical since the devices in your realm have certificates signed with those CA credentials, and if the CA certificate changes all devices will have invalid credentials and will have to request new credentials.

tar must be installed onto your machine in order to successfully complete this step.

Export the following enviroment variables and ensure they matches the name of the corresponding components within your cluster:

• ASTARTE_RELEASE_NAME: the name of the Astarte instance deployed in your cluster,
• ASTARTE_RELEASE_NAMESPACE: the namespace in which your Astarte instance resides.

For instance, if you followed the standard naming conventions while installing Astarte it should be sufficient setting the following values:

export ASTARTE_RELEASE_NAME=astarte
export ASTARTE_RELEASE_NAMESPACE=astarte

However, it is your responsibility checking that these values match the ones of your cluster.

Now, migrate the CA certificates and key:

kubectl cp $ASTARTE_RELEASE_NAMESPACE/$ASTARTE_RELEASE_NAME-cfssl-0:/data/ca-key.pem tls.key
kubectl cp $ASTARTE_RELEASE_NAMESPACE/$ASTARTE_RELEASE_NAME-cfssl-0:/data/ca.pem tls.crt
kubectl create secret tls $ASTARTE_RELEASE_NAME-devices-ca -n $ASTARTE_RELEASE_NAMESPACE \
  --cert=tls.crt --key=tls.key

remove-astarte-operator-v0-11

Remove Astarte Operator v0.11

Remove the Operator's Service Account, Cluster Roles and Cluster Role Bindings:

kubectl delete serviceaccounts -n kube-system astarte-operator
kubectl delete clusterroles.rbac.authorization.k8s.io astarte-operator
kubectl delete clusterrolebindings.rbac.authorization.k8s.io astarte-operator

Delete the Operator's deployment:

kubectl delete deployments.app -n kube-system astarte-operator

DO NOT delete Astarte's CRDs! This will lead to the deletion of the entire Astarte deployment with a consequent data loss.

install-cert-manager

Install cert-manager

Please, before proceeding to the next steps make sure to be compliant with the new requirements for v1.0, i.e. if cert-manager is not installed yet, run the following commands:

helm repo add jetstack https://charts.jetstack.io
helm repo update
kubectl create namespace cert-manager
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version v1.7.0 \
  --set installCRDs=true

add-astarte-operator-s-helm-chart-repository

Add Astarte Operator's Helm Chart Repository

To restore the Operator's functionalities with v1.0, the first step is adding the Astarte Operator's Helm chart repository:

helm repo add astarte https://helm.astarte-platform.org
helm repo update

prepare-the-cluster-to-the-operator-v1-0-installation

Prepare the Cluster to the Operator v1.0 Installation

Set some environment variables that will come handy for the upcoming migration procedure:

• 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 will reside.

You can change the following values at your preference. However, the following values should be ok for the large majority of use cases.

Note that you are responsible for checking that ASTARTE_OP_RELEASE_NAMESPACE exists within the cluster.

export ASTARTE_OP_TEMPLATE_DIR=/tmp
export ASTARTE_OP_RELEASE_NAME=astarte-operator
export ASTARTE_OP_RELEASE_NAMESPACE=kube-system

Generate 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

The outcome of this command consists of a series of yaml files located in $ASTARTE_OP_TEMPLATE_DIR/astarte-operator/templates.

Leveraging the templating capabilities of Helm, the generated templates can be customized according to your needs. For instance, if you want to refer to a particular Operator's tag all you have to do is to append --set image.tag=<the-required-tag> to the previous command. To check all the configurable values run helm show values astarte/astarte-operator.

Before moving on, make sure that gawk is installed on your host machine. If you are on OSX, running the following command will be sufficient:

$ brew install gawk

while on any Debian based OS run:

# apt install gawk

Now it's time to prepare the cluster to allow the new operator installation by means of the templates generated in the previous step.

The following tasks will be performed:

• replacement of the Astarte's and AstarteVoyagerIngress' CRDs with their updated versions,
• installation of the Flow's CRD,
• installation of the Operator's RBACs,
• installation of the Operator's Webhooks,
• annotation of the installed resources as to allow Helm to manipulate and take control of them.

This bash script takes care of handling the aforementioned tasks. Download it and, assuming you saved it as upgrade-operator-011-10.sh, run the following:

bash path/to/your/upgrade-operator-011-10.sh \
    -d $ASTARTE_OP_TEMPLATE_DIR \
    -n $ASTARTE_OP_RELEASE_NAME \
    -N $ASTARTE_OP_RELEASE_NAMESPACE

In a more concise way you can perform the same task simply executing:

ASTARTE_OP_UPGRADE_SCRIPT_URL=https://raw.githubusercontent.com/astarte-platform/astarte-kubernetes-operator/master/hack/upgrade-operator-011-10.sh
curl -fsSL $ASTARTE_OP_UPGRADE_SCRIPT_URL > /tmp/upgrade-operator-011-10.sh
bash /tmp/upgrade-operator-011-10.sh \
    -d $ASTARTE_OP_TEMPLATE_DIR \
    -n $ASTARTE_OP_RELEASE_NAME \
    -N $ASTARTE_OP_RELEASE_NAMESPACE

install-astarte-operator-v1-0

Install Astarte Operator v1.0

Now it's time to install the Astarte Operator v1.0.

If during the preparation of the cluster you customized the chart values with the --set flag, please take care of setting the same values accordingly while installing Astarte Operator.

To install the Operator, simply run:

helm install $ASTARTE_OP_RELEASE_NAME astarte/astarte-operator -n $ASTARTE_OP_RELEASE_NAMESPACE \
    --skip-crds

Note that the --skip-crds flag is required as, following the migration path, we already updated/installed the required CRDs.

Version 1.0.0 is a safe landing version to perform the upgrade to. Upgrading to a more recent version may lead to a broken state with possible catastrophic aftermaths: if you choose to follow this path, make sure you know what you are doing. However deviating from the upgrade path outlined within the current page is strongly discouraged.

After the successful migration to v1.0, please upgrade to a more recent Operator's versions following the instructions outlined in the Upgrade Operator v1.0.0-v1.0.x section.

caveats-and-breaking-changes-v0-11-v1-0

Caveats and Breaking Changes v0.11-v1.0

Operator v1.0 introduced some breaking changes with respect to v0.11, which are relevant if you deployed your own Ingress instead of relying on AstarteVoyagerIngress.

With the upgrade to v1.0, some of the services were renamed:

$ASTARTE_RELEASE_NAME-appengine        --> $ASTARTE_RELEASE_NAME-appengine-api
$ASTARTE_RELEASE_NAME-housekeeping     --> $ASTARTE_RELEASE_NAME-housekeeping-api
$ASTARTE_RELEASE_NAME-pairing          --> $ASTARTE_RELEASE_NAME-pairing-api
$ASTARTE_RELEASE_NAME-realm-management --> $ASTARTE_RELEASE_NAME-realm-management-api

If you deployed your own Ingress, it is your responsibility renaming your services to ensure the cluster to be fully operational.

upgrade-astarte

Upgrade Astarte

Once you migrated Astarte Operator from v0.11 to v1.0, it is time to upgrade your Astarte instance. To do so, simply edit the Astarte resource in the cluster updating the version field to the one you want to upgrate to.

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. Once the yaml file will be saved, the Operator will take over ensuring the reconciliation of your Astarte instance to the requested version.

caveats

Caveats

CFSSL leftover persistent volume

Astarte v0.11 employs a persistent volume to store CA certificate and private key, while upgrading to v1.0 involves a change in how device certificates are stored as, behind the scenes, these data are held as a Kubernetes TLS secret.

Following the Kubernetes conventions, the formerly used persistent volume and its corresponding claim are left within the cluster even if not used anymore.

If you followed the procedure described here you are free to remove the CFSSL persistent volume and claim without the need for your devices to request new credentials.

AppEngine /socket route removal

The /socket endpoint exposed by AppEngine to interact with Astarte Channels, which was already deprecated in Astarte v0.11, has been removed. You must use the new route /v1/socket instead.