// Module included in the following assemblies:
//
// assembly-config.adoc

[id='proc-migrating-clusters-node-pools-{context}']
= Migrating existing Kafka clusters to use Kafka node pools

[role="_abstract"]
This procedure describes how to migrate existing Kafka clusters to use Kafka node pools.
After you have updated the Kafka cluster, you can use the node pools to manage the configuration of nodes within each pool.

NOTE: Currently, replica and storage configuration in the `KafkaNodePool` resource must also be present in the `Kafka` resource. The configuration is ignored when node pools are being used. 

.Prerequisites

* xref:deploying-cluster-operator-str[The Cluster Operator must be deployed.]

.Procedure

. Create a new `KafkaNodePool` resource.
+
--
.. Name the resource `kafka`.
.. Point a `strimzi.io/cluster` label to your existing `Kafka` resource.
.. Set the replica count and storage configuration to match your current Kafka cluster.
.. Set the roles to `broker`.
--
+
.Example configuration for a node pool used in migrating a Kafka cluster
[source,yaml,subs="+attributes"]
----
apiVersion: {KafkaNodePoolApiVersion}
kind: KafkaNodePool
metadata:
  name: kafka
  labels:
    strimzi.io/cluster: my-cluster
spec:
  replicas: 3
  roles:
    - broker
  storage:
    type: jbod
    volumes:
      - id: 0
        type: persistent-claim
        size: 100Gi
        deleteClaim: false
----
+
WARNING: To preserve cluster data and the names of its nodes and resources, the node pool name must be `kafka`, and the `strimzi.io/cluster` label matches the Kafka resource name. 
Otherwise, nodes and resources are created with new names, including the persistent volume storage used by the nodes. 
Consequently, your previous data may not be available.       

. Apply the `KafkaNodePool` resource:
+
[source,shell,subs=+quotes]
----
kubectl apply -f <node_pool_configuration_file>
----
+
By applying this resource, you switch Kafka to using node pools.
+
There is no change or rolling update and resources are identical to how they were before.

. Enable support for node pools in the `Kafka` resource using the `strimzi.io/node-pools: enabled` annotation.
+
.Example configuration for a node pool in a cluster using ZooKeeper
[source,yaml,subs="+attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
  annotations:
    strimzi.io/node-pools: enabled
spec:
  kafka:
    # ...
  zookeeper:
    # ...
----

. Apply the `Kafka` resource:
+
[source,shell,subs=+quotes]
----
kubectl apply -f <kafka_configuration_file>
----
+
There is no change or rolling update.
The resources remain identical to how they were before.

. Remove the replicated properties from the `Kafka` custom resource.
When the `KafkaNodePool` resource is in use, you can remove the properties that you copied to the `KafkaNodePool` resource, such as the `.spec.kafka.replicas` and `.spec.kafka.storage` properties.

.Reversing the migration

To revert to managing Kafka nodes using only `Kafka` custom resources:

. If you have multiple node pools, consolidate them into a single `KafkaNodePool` named `kafka` with node IDs from 0 to N (where N is the number of replicas).
. Ensure that the `.spec.kafka` configuration in the `Kafka` resource matches the `KafkaNodePool` configuration, including storage, resources, and replicas.
. Disable support for node pools in the `Kafka` resource using the `strimzi.io/node-pools: disabled` annotation.
. Delete the Kafka node pool named `kafka`.
