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

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

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

Install the operator release with the above values file.

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

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.

Cleanup

Delete the existing chart release.

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

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.