Migration from kube-opex-analytics to KubeLedger

A step-by-step guide to migrating from kube-opex-analytics to KubeLedger while preserving data.

This guide describes how to migrate your existing kube-opex-analytics instance to KubeLedger side-by-side to ensure a smooth transition with no data loss.

Overview

The migration strategy involves deploying KubeLedger in a new namespace (kubeledger) while keeping the existing kube-opex-analytics application running. Data is then copied from the old instance to the new one, followed by a verification and observation period.

Prerequisites

  • Access to the Kubernetes/OpenShift cluster with permissions to manage resources in both the existing namespace (e.g., kube-opex-analytics) and the new kubeledger namespace.
  • kubectl or oc CLI configured.

Step 1: Deploy KubeLedger

Follow the standard Installation on Kubernetes and OpenShift guide to deploy a fresh instance of KubeLedger in the kubeledger namespace.

Important: Do not modify or delete your existing kube-opex-analytics deployment yet.

Ensure the kubeledger-0 pod is running before proceeding:

kubectl get pods -n kubeledger

Step 2: Data Migration

We will copy the /data directory from the existing kube-opex-analytics-0 pod to the new kubeledger-0 pod.

Method: Using local machine as intermediary

This method is reliable and works even if direct network communication between namespaces is restricted.

  1. Create a local backup directory:

    mkdir -p koa-data-backup

  2. Copy data from the existing instance:

    Replace kube-opex-analytics with the actual namespace of your existing installation if different.

    kubectl cp kube-opex-analytics/kube-opex-analytics-0:/data ./koa-data-backup/

  3. Copy data to the new KubeLedger instance:

    We use the sourced directory contents to avoid creating a nested /data/data directory.

    # Copy the contents of the local backup to the remote /data directory
kubectl cp ./koa-data-backup/data/. kubeledger/kubeledger-0:/data/

    Note: The /. syntax ensures we copy the contents of the directory. If you end up with /data/data inside the pod, you may need to move the files.

Step 3: Restart and Verify

To ensure KubeLedger loads the migrated data (database files, etc.), restart the kubeledger-0 pod.

  1. Delete the pod to trigger a restart (StatefulSet will recreate it):

    kubectl delete pod kubeledger-0 -n kubeledger

  2. Wait for the pod to become ready:

    kubectl wait --for=condition=ready pod/kubeledger-0 -n kubeledger --timeout=300s

  3. Verify the Dashboard: Access the KubeLedger dashboard (via Ingress, Route, or port-forward) and verify that:

    • Historical data from kube-opex-analytics is visible.
    • Charts and configurations match your expectations.

Step 4: Observation Period

Keep both the old kube-opex-analytics instance and the new KubeLedger instance running for a couple of days.

  • Check for consistency between the two dashboards.
  • Ensure no regressions in data collection or display.

Step 5: Cleanup

Once you are confident the migration is successful:

  1. Remove the kube-opex-analytics instance: Delete the deployment, statefulset, or namespace associated with the old version.

    kubectl delete namespace kube-opex-analytics

    (Adjust the command if you deployed it differently)

  2. Finalize KubeLedger configuration: Ensure any external integrations (Ingress DNS, etc.) are fully pointed to the new KubeLedger instance.