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
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.
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 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.
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
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
Set some environment variables that will come handy for the upcoming migration procedure:
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 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
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
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.
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/v1.0.0/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
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.
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.
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.
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
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.
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.
/socket route removal
/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