ThingPark Enterprise Upgrade Procedure

caution

During the upgrade of a TPE High Availability (HA) cluster:

• End-devices uplink packets shall be queued by the Base Stations during the upgrade and sent to the Application Servers with higher latency than usual.
• APIs (including DX API downlinks) and GUI accesses are not available during the upgrade procedure.
• API and GUIs active sessions are closed at the beginning of the procedure, and user may have to re-enter login information in GUI or API after the upgrade.
• Downlinks from cloud connectors may be dropped if cloud brokers do not provide buffering capabilities (AWS/Azure clouds already support message buffering).
• Uplink delivery to cloud connectors may be delayed until the service is started.

ThingPark Enterprise release components matrix

As explained in the installation overview, a ThingPark Enterprise release consists of 4 Helm Charts. Upgrade must be done in the respect of version specified in Release Manifest

Prerequisites

• A Kubernetes cluster version 1.24, 1.25, 1.26,
• The custom values configuration files used for initial deployment,

Deployment preparation

The first step consists of updating parameters and Helm repository information:

1. Retrieve the custom-values.yaml file used for previous deployments.
2. Select the targeted version of upgrade. Use the tag name of the Thingpark Enterprise Release to set RELEASE variable:

# Set release version
export RELEASE=<release name>
# Set the deployment namespace as an environment variable
export NAMESPACE=thingpark-enterprise
# Value in l,xl,xxl
export SEGMENT=<segment>
# Value azure,amazon
export HOSTING=<hosting>
export CONFIG_REPO_BASEURL=https://raw.githubusercontent.com/actility/thingpark-enterprise-kubernetes/v$RELEASE
eval $(curl $CONFIG_REPO_BASEURL/VERSIONS)
helm repo update

3. Update deployment settings in values-data-stack.yaml and values-thingpark-stack.yaml using new versions available in the configuration repository

curl -o values-data-stack-new.yaml $CONFIG_REPO_BASEURL/examples/customization/values-data-stack.yaml
curl -o values-thingpark-stack-new.yaml $CONFIG_REPO_BASEURL/examples/customization/values-thingpark-stack.yaml

Repositories configuration

Configure the helm repository using InstallationID

helm repo add --username <InstallationID> --password <InstallationID> actility https://repository.thingpark.com/charts
helm repo update

Major upgrades

caution

Major Upgrade must be done from latest previous fix version

7.1 to 7.2

• Follow the 7.2 upgrade procedure

7.2 to 7.3

• Follow the 7.3 upgrade Procedure

Hotfix and Maintenance release upgrades

• 7.2 Hotfix versions have to be installed with the Generic procedure.

Post upgrade verifications

Wait for all statefulsets and deployments readiness:

kubectl get -n $NAMESPACE statefulsets.apps,deployments.apps
kubectl get -n $NAMESPACE -w statefulsets.apps
kubectl get -n $NAMESPACE -w deployments.apps

Post-upgrade procedures are automatically triggered to request data migrations after an upgrade of TPE instance.

The status of the post-upgrade procedure can be checked using Kubernetes API:

$ kubectl exec -n $NAMESPACE -it deploy/pum -- status
2 entrie(s)
uid: 2
     creationTimestamp: '2022-06-23T13:50:33.000Z'
     scope: 'ALL'
     serviceID: 'TWA'
     requestID: 'RDTP-7689-bs-certificate-migration'
     requestPath: '/thingpark/wireless/rest/systems/demons/migrateBsSecurity'
     requestBody: '{ "max" : 10 }'
     state: 'PROCESSED'
     stateTimestamp: '2022-06-27T14:05:11.000Z'
     lastResponse: '{"status":200,"message":"OK","data":{"countOnly":false,"max":10,"result":{"done":6,"remaining":0}}}'
     errorCounter: 0
     iterationCounter: 5
uid: 4
     creationTimestamp: '2022-06-23T13:50:33.000Z'
     scope: 'TPE-OCP'
     serviceID: 'TWA'
     requestID: 'RDTP-18480-alarm-email-notification-migration-for-tpe-ocp'
     requestPath: '/thingpark/wireless/rest/systems/demons/migrateUserAlarmNotifications'
     requestBody: '{ "max" : 100 }'
     state: 'PARTIALLY_PROCESSED'
     stateTimestamp: '2022-06-27T14:14:11.000Z'
     lastResponse: '{"status":250,"message":"Unknown","data":{"operatorID":null,"max":100,"countOnly":false,"result":{"done":0,"remaining":2}}}'
     errorCounter: 0
     iterationCounter: 2

The script displays the list of post-upgrade requests and for each request, the details of the request, including the processing state. The different processing state of a post-upgrade request can be:

• INIT: the post upgrade request has been added and must be processed.
• IN_PROGRESS: a HTTP POST is in progress for this request.
• PARTIALLY_PROCESSED: other iterations are needed to complete the post upgrade request.
• TRANSIENT_ERROR: the last HTTP POST failed and must be retried.
• ABORTED: the post upgrade manager was not able to complete the post upgrade request.
• PROCESSED: the post upgrade request is fully completed.
• SKIPPED: the post upgrade request was never applied on this system (because the procedure was flagged DEPRECATED or because the scope does not apply to this PF). Logs of the upgrade procedure can be retrieved on job stdout

kubectl logs -n $NAMESPACE  jobs.batch/pum-process

Finally, if for some reason you want to execute again the post-upgrade procedure, for example when it failed, you can do it in this way

kubectl exec -n $NAMESPACE -it deploy/pum -- restart

tip

To rollback upgrade for any reason, go to the Rollback procedure section