Skip to content

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.

Preflight

Having the following information to hand will help smooth the process

variable example further details
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

  1. Stop ingestion feeds

    Stop all feeds into Insights to avoid data loss with inflight data.

  2. Ensure latest version of kxi-cli is installed

  3. Ensure you have performed the Keycloak 18 migration steps if you are upgrading from 1.1.X to 1.2.0+

Authentication Upgrades

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 $INSTALL_CONFIG_FILE

keycloak:
  keycloakConfigCli:
    enabled: true

Please see the section about authentication upgrades for more information about how to incorporate realm changes, during an upgrade.

Version-Specific Considerations

Please see Release Notes for any specific upgrade considerations for your version of KX Insights.

Upgrading 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

Reinstalling

Respond 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

Post-Upgrade Checks

Check the system is running correctly.

  1. Expected version of KX Insights is running 

    kubectl describe cm insights-config | grep version
version: insights-1.1.1

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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

  7. 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

Rollback

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