Upgrading KX Insights
This section details the steps to upgrade the KX Insights Platform from a current install.
If you are upgrading Kx Insights Platform on Azure Marketplace please refer to the guide here.
Having the following information to hand will help smooth the process
|INSIGHTS_NAMESPACE||kxi||Namespace KX Insights deployed to|
|INSIGHTS_VERSION||1.1.1||Version of insights to install|
|OPERATOR_VERSION||1.1.0||Version of insights operator to install|
|INSTALL_CONFIG_FILE||values.yaml||Install configuration created on initial install|
Currently the upgrade process will require downtime to ensure data integrity can be guaranteed. This means that before any upgrade is scheduled, a number of pre-flight checks are necessary
Stop ingestion feeds
Stop all feeds into Insights to avoid data loss with inflight data.
Ensure latest version of kxi-cli is installed
Ensure you have performed the Keycloak 18 migration steps if you are upgrading from 1.1.X to 1.2.0+
By default the Keycloak realm configuration is not automatically re-imported on upgrade. This is to avoid resetting runtime changes made to the default user account back to realm defaults but also means any additional roles added to KX Insights with the upgrade will not be imported. It is recommended you enable this realm import when upgrading; and if you are actively using the the default user, review and update these manually within the Keycloak UI.
To enable keycloak realm updates, add the following to your
keycloak: keycloakConfigCli: enabled: true
Please see the section about authentication upgrades for more information about how to incorporate realm changes, during an upgrade.
Please see Release Notes for any specific upgrade considerations for your version of KX Insights.
The kxi-cli is used to perform upgrades. The steps to upgrade KX Insights involves removing the current deployment and reinstalling the new version. This process does not remove the persisted data backing KX Insights configuration or databases. These remain as Persisted Volumes within the Kubernetes cluster.
The steps performed by the kxi cli are:
- Backup assemblies
- Teardown assemblies
- Uninstall insights, operator & CRDs
- Install operator (includes installing CRDs)
- Install insights
- Restore assemblies
To initiate the upgrade, run the following command. This steps through the upgrade, prompting the user where required
kxi install upgrade --filepath $INSTALL_CONFIG_FILE --version $INSIGHTS_VERSION --operator-version $OPERATOR_VERSION
Backup And Teardown Assemblies
The state of running assemblies are persisted to a local file. Respond
y to the prompt asking to delete each assembly. This will teardown the running assemblies. Persisted data will be retained upon completion of the upgrade. The upgrade will be exited and assembly state restored if the user responds
n to any of these prompts.
Backing up assemblies Persisted assembly definitions for ['dfx-assembly', 'iot-assembly'] to kxi-assembly-state.yaml Tearing down assemblies Assembly data will be persisted and state will be recovered post-upgrade Tearing down assembly dfx-assembly Are you sure you want to teardown dfx-assembly [y/N]: y Waiting for assembly to be torn down [------------------------------------] 0% Tearing down assembly iot-assembly Are you sure you want to teardown iot-assembly [y/N]: y Waiting for assembly to be torn down [------------------------------------] 0%
Uninstalling Insights And Operator
The KXI Operator is used to deploy the assemblies/data workflows. A number of Custom Resource Definitions (CRDs) power KX Insights data workflows. These need to be upgraded along with KX Insights. Respond
y to each prompt asking to uninstall Insights, the KXI Operator and CRDs.
Uninstalling insights and operator KX Insights is deployed. Do you want to uninstall? [y/N]: y Uninstalling release insights in namespace kxi release "insights" uninstalled The kxi-operator is deployed. Do you want to uninstall? [y/N]: y Uninstalling release insights in namespace kxi-operator release "insights" uninstalled The assemblies CRDs ['assemblies.insights.kx.com', 'assemblyresources.insights.kx.com'] exist. Do you want to delete them? [y/N]: y Deleting CRD assemblies.insights.kx.com Deleting CRD assemblyresources.insights.kx.com
y to the prompt asking to install the kxi-operator. This will also install the CRDs. The cli will then install Insights and restore assemblies to their running state
Reinstalling insights and operator kxi-operator not found. Do you want to install it? [Y/n]: y Installing chart kx-insights/kxi-operator with values from secret and values file from values.yaml Installing chart kx-insights/insights with values from secret and values file from values.yaml Reapplying assemblies Submitting assembly from kxi-assembly-state.yaml Submitting assembly dfx-assembly Custom assembly resource dfx-assembly created! Submitting assembly iot-assembly Custom assembly resource iot-assembly created! Upgrade to version 1.1.1 complete
Check the system is running correctly.
Expected version of KX Insights is running
kubectl describe cm insights-config | grep version version: insights-1.1.1
KXI Operator installed
helm ls -n kxi-operator
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION insights kxi-operator 1 2022-04-11 15:39:44.955236379 +0000 UTC deployed kxi-operator-1.1.0 1.1.0
KXI base charts installed
helm ls -n $INSIGHTS_NAMESPACE
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION insights kxi 1 2022-04-11 16:57:00.144126754 +0000 UTC deployed insights-1.1.1 1.1.1
KXI Operator in running state
kubectl get pods -n kxi-operator
NAME READY STATUS RESTARTS AGE insights-kxi-operator-6df4bcfddc-gnnjj 1/1 Running 0 85m insights-kxi-operator-6df4bcfddc-lqmrl 1/1 Running 0 85m insights-kxi-operator-6df4bcfddc-z45wq 1/1 Running 0 85m
KX Insights in running state
kubectl get pods -n $INSIGHTS_NAMESPACE
NAME READY STATUS RESTARTS AGE insights-aggregator-9959bdc87-4pg7z 2/2 Running 0 9m47s ... ... insights-sg-gateway-596b486d9f-pmhf4 1/1 Running 0 9m47s insights-sg-gateway-596b486d9f-qvzbr 1/1 Running 0 9m47s
KXI Assembly CRDs redeployed
kubectl get crds | grep insights.kx.com
assemblies.insights.kx.com 2022-04-11T15:23:53Z assemblyresources.insights.kx.com 2022-04-11T15:23:54Z
Ensure assembly is up and running successfully
kubectl get asm
NAME DESCRIPTION READY STATUS AGE dfx-assembly A KXI Assembly True 28m iot-assembly A KXI Assembly True 28m
Should the upgrade fail at any stage, insights can be installed by following the installation guide. Assemblies can be restored to their running state by executing
kxi assembly create --filepath kxi-assembly-state.yaml