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.

Prerequisites

Java 17
An existing Apache Pulsar cluster
Migration-tool JAR downloaded from the latest release.

Scan and generate cluster CRDs

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:
  kubectl config get-contexts
  Result
  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
  Before running the migration tool, DataStax recommends switching to K8’s current context and ensuring connectivity, such as with kubectl get pods.
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, then the clusterName is pulsar-prod-cluster.
After you’ve added the retrieved values to input-cluster-specs.yaml, generate the report:
```
java -jar migration-tool.jar generate -i input-cluster-specs.yaml -o output
```
Find the link to the generated report in the logs, open the generated report in your browser, and then examine the differences between the existing cluster and the KAAP operator.

If everything looks good, proceed to the migration procedure.

If you need to change the generated CRD and simulate the migration again, run the following command after making the necessary changes:
```
java -jar migration-tool.jar diff -d output/<context-name>
```

Migration procedure

Create a new values.yaml file for the operator.

In the pulsar-operator.cluster section, enter the generated CRD’s spec.

pulsar-operator:
    cluster:
        create: true
        name: <cluster-name>
        spec:
            <generated spec from the CRD>

Install the operator release with the new values.yaml file:

helm install pulsar kaap/kaap-stack --values <values.yaml>

Wait for the PulsarCluster status to be in a Ready state, which indicates that the operator has assumed control of the cluster. Since the generated resources will match the existing cluster’s resources, the following behaviors are expected:
- The operator doesn’t create any new resources.
- The operator doesn’t delete any existing resources.
- The operator doesn’t restart every statefulset/deployment. This is done in a safe manner using the operator’s staged upgrades feature.

Cleanup

Delete the existing chart release:

kubectl delete secret -l name=<old-release-name>,owner=helm

Clean up Helm annotations and labels:
- You can safely remove the following annotations:
  - meta.helm.sh/release-name
  - meta.helm.sh/release-namespace
- You can safely remove the following labels:
  - app.kubernetes.io/managed-by
  - chart
  - release
  - heritage

Next steps

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