// 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 the following xref:deploy-examples-{context}[example files] you can use to create a Kafka cluster:

`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 persistent volumes to store ZooKeeper and Kafka data. A `PersistentVolume` is acquired using a `PersistentVolumeClaim` to make it independent of the actual type of the `PersistentVolume`. The `PersistentVolumeClaim` can use a `StorageClass` to trigger automatic volume provisioning.
When no `StorageClass` is specified, Kubernetes will try to use the default `StorageClass`.
+
The following examples show some common types of persistent volumes:
+
* If your Kubernetes cluster runs on Amazon AWS, Kubernetes can provision Amazon EBS volumes
* If your Kubernetes cluster runs on Microsoft Azure, Kubernetes can provision Azure Disk Storage volumes
* If your Kubernetes cluster runs on Google Cloud, Kubernetes can provision Persistent Disk volumes
* If your Kubernetes cluster runs on bare metal, Kubernetes can provision local persistent volumes

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.
+
--
* 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:{BookURLConfiguring}#assembly-config-kafka-str[Kafka cluster configuration^]
