// Module included in the following assemblies:
//
// deploying/assembly_deploy-kafka-cluster.adoc

[id='deploying-kafka-cluster-{context}']
= Deploying the Kafka cluster

[role="_abstract"]
This procedure shows how to deploy a Kafka cluster to your Kubernetes cluster using the Cluster Operator.

The deployment uses a YAML file to provide the specification to create a `Kafka` resource.

Strimzi provides xref:deploy-examples-{context}[example configuration files].
For a Kafka deployment, the following examples are provided:

`kafka-persistent.yaml`:: Deploys a persistent cluster with three ZooKeeper and three Kafka nodes.
`kafka-jbod.yaml`:: Deploys a persistent cluster with three ZooKeeper and three Kafka nodes (each using multiple persistent volumes).
`kafka-persistent-single.yaml`:: Deploys a persistent cluster with a single ZooKeeper node and a single Kafka node.
`kafka-ephemeral.yaml`:: Deploys an ephemeral cluster with three ZooKeeper and three Kafka nodes.
`kafka-ephemeral-single.yaml`:: Deploys an ephemeral cluster with three ZooKeeper nodes and a single Kafka node.

In this procedure, we use the examples for an _ephemeral_ and _persistent_ Kafka cluster deployment.

Ephemeral cluster:: In general, an ephemeral (or temporary) Kafka cluster is suitable for development and testing purposes, not for production. This deployment uses `emptyDir` volumes for storing broker information (for ZooKeeper) and topics or partitions (for Kafka). Using an `emptyDir` volume means that its content is strictly related to the pod life cycle and is deleted when the pod goes down.
Persistent cluster:: A persistent Kafka cluster uses `PersistentVolumes` to store ZooKeeper and Kafka data. The `PersistentVolume` is
acquired using a `PersistentVolumeClaim` to make it independent of the actual type of the `PersistentVolume`. For example, it can use
ifdef::Kubernetes[HostPath volumes on Minikube or]
Amazon EBS volumes in Amazon AWS deployments without any changes in the YAML files. The `PersistentVolumeClaim` can use a `StorageClass` to trigger automatic volume provisioning.

The example YAML files specify the latest supported Kafka version, and configuration for its supported log message format version and inter-broker protocol version.
The `inter.broker.protocol.version` property for the Kafka `config` must be the version supported by the specified Kafka version (`spec.kafka.version`).
The property represents the version of Kafka protocol used in a Kafka cluster.

From Kafka 3.0.0, when the `inter.broker.protocol.version` is set to `3.0` or higher, the `log.message.format.version` option is ignored and doesn't need to be set.

An update to the `inter.broker.protocol.version` is required when xref:assembly-upgrading-kafka-versions-str[upgrading Kafka].

The example clusters are named `my-cluster` by default.
The cluster name is defined by the name of the resource and cannot be changed after the cluster has been deployed.
To change the cluster name before you deploy the cluster, edit the `Kafka.metadata.name` property of the `Kafka` resource in the relevant YAML file.

.Default cluster name and specified Kafka versions
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    version: {DefaultKafkaVersion}
    #...
    config:
      #...
      log.message.format.version: "{DefaultInterBrokerVersion}"
      inter.broker.protocol.version: "{DefaultInterBrokerVersion}"
  # ...
----

.Prerequisites

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

.Procedure

. Create and deploy an _ephemeral_ or _persistent_ cluster.
+
For development or testing, you might prefer to use an ephemeral cluster.
You can use a persistent cluster in any situation.

** To create and deploy an _ephemeral_ cluster:
+
[source,shell,subs="attributes+"]
kubectl apply -f examples/kafka/kafka-ephemeral.yaml

** To create and deploy a _persistent_ cluster:
+
[source,shell,subs="attributes+"]
kubectl apply -f examples/kafka/kafka-persistent.yaml

. Check the status of the deployment:
+
[source,shell,subs="+quotes"]
----
kubectl get pods -n _<my_cluster_operator_namespace>_
----
+
.Output shows the pod names and readiness
[source,shell,subs="+quotes"]
----
NAME                        READY   STATUS    RESTARTS
my-cluster-entity-operator  3/3     Running   0
my-cluster-kafka-0          1/1     Running   0
my-cluster-kafka-1          1/1     Running   0
my-cluster-kafka-2          1/1     Running   0
my-cluster-zookeeper-0      1/1     Running   0
my-cluster-zookeeper-1      1/1     Running   0
my-cluster-zookeeper-2      1/1     Running   0
----
+
`my-cluster` is the name of the Kafka cluster.
+
With the default deployment, you install an Entity Operator cluster, 3 Kafka pods, and 3 ZooKeeper pods.
+
`READY` shows the number of replicas that are ready/expected.
The deployment is successful when the `STATUS` shows as `Running`.

[role="_additional-resources"]
.Additional resources
link:{BookURLUsing}#assembly-config-kafka-str[Kafka cluster configuration^]
