Migrate existing cluster to KAAP operator

Migrating an existing Apache Pulsar cluster to one controlled by the KAAP Operator is a manual process, but we’ve included a migration tool to help you along the way.

The migration tool is a CLI application that connects to an existing Apache Pulsar cluster and generates a valid and equivalent PulsarCluster CRD. The migration tool simulates what would happen if the generated PulsarCluster would be submitted, retrieves the Kubernetes resources that would be created, and compares them with the existing cluster’s resources, generating a detailed HTML report. You can then examine the report and decide if you want to proceed with the cluster migration, or if you need to make some changes first.


  • Java 17

  • An existing Apache Pulsar cluster

  • Migration-tool JAR downloaded from the latest release.

Scan and generate cluster CRDs

  1. Create an input file called input-cluster-specs.yaml with the following content:

    context: <context-name>
    namespace: <namespace>
    clusterName: <cluster-name>
    1. To retrieve the context-name:

      • Helm

      • Result

      kubectl config get-contexts
      CURRENT   NAME                                         CLUSTER                                      AUTHINFO                                     NAMESPACE
      *         gke_gcp-techpubs_us-east1-b_pulsar-cluster   gke_gcp-techpubs_us-east1-b_pulsar-cluster   gke_gcp-techpubs_us-east1-b_pulsar-cluster   pulsar-cluster

      We recommend switching to K8’s current context and ensuring connectivity (kubectl get pods, for example) before running the migration tool.

    2. The namespace is the namespace with the Apache Pulsar resources you wish to scan.

    3. The clusterName is the prefix of each pod. For example, if the broker pod is pulsar-prod-cluster-broker-0, the clusterName is pulsar-prod-cluster.

  2. After you’ve added the retrieved values to input-cluster-specs.yaml, generate the report with:

    java -jar migration-tool.jar generate -i input-cluster-specs.yaml -o output
  3. You’ll find a link to the generated report in the logs. Open the generated report in your browser and examine the differences between the existing cluster and the KAAP operator. If everything looks good, proceed to the migration procedure. If you find you need to change the generated CRD and simulate the migration again, run:

    java -jar migration-tool.jar diff -d output/<context-name>

Migration procedure

  1. Create a new values.yaml file for the operator. Then in the pulsar-operator.cluster section, copy the generated CRD’s spec.

            create: true
            name: <cluster-name>
                <copy the generated spec from the CRD>
  2. Install the operator release with the above values file.

    helm install pulsar kaap/kaap-stack --values <values.yaml>
  3. Wait for the PulsarCluster status to be in a Ready state, indicating the operator has assumed control of the cluster. Since the generated resources will match the existing cluster’s resources, the following behaviours are expected:

    • The operator will not create any new resources.

    • The operator will not delete any existing resources.

    • The operator will restart every statefulset/deployment. This will be done in a safe manner using the staged upgrades feature of the operator.


  1. Delete the existing chart release.

    kubectl delete secret -l name=<old-release-name>,owner=helm
  2. Clean up Helm annotations and labels.

    1. You can safely remove the following annotations:

      • meta.helm.sh/release-name

      • meta.helm.sh/release-namespace

    2. You can safely remove the following labels:

      • app.kubernetes.io/managed-by

      • chart

      • release

      • heritage

What’s next?

Now that you’ve migrated your existing cluster to the operator, you can start using the operator’s features to manage your cluster.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com