// Module included in the following assemblies:
//
// assembly-using-the-topic-operator.adoc

[id='ref-operator-topic-{context}']
= Kafka topic resource

The `KafkaTopic` resource is used to configure topics, including the number of partitions and replicas.

The full schema for `KafkaTopic` is described in link:{BookURLConfiguring}#type-KafkaTopic-reference[`KafkaTopic` schema reference^].

== Identifying a Kafka cluster for topic handling

A `KafkaTopic` resource includes a label that specifies the name of the Kafka cluster (derived from the name of the `Kafka` resource) to which it belongs.

For example:

[source,yaml,subs="attributes+"]
----
apiVersion: {KafkaTopicApiVersion}
kind: KafkaTopic
metadata:
  name: topic-name-1
  labels:
    strimzi.io/cluster: my-cluster
----

The label is used by the Topic Operator to identify the `KafkaTopic` resource and create a new topic, and also in subsequent handling of the topic.

If the label does not match the Kafka cluster, the Topic Operator cannot identify the `KafkaTopic` and the topic is not created.

== Kafka topic usage recommendations

When working with topics, be consistent.
Always operate on either `KafkaTopic` resources or topics directly in Kubernetes.
Avoid routinely switching between both methods for a given topic.

Use topic names that reflect the nature of the topic, and remember that names cannot be changed later.

If creating a topic in Kafka, use a name that is a valid Kubernetes resource name,
otherwise the Topic Operator will need to create the corresponding `KafkaTopic` with a name that conforms to the Kubernetes rules.

NOTE: For information on the requirements for identifiers and names in Kubernetes, refer to link:https://kubernetes.io/docs/concepts/overview/working-with-objects/names[Object Names and IDs^].

== Kafka topic naming conventions

Kafka and Kubernetes impose their own validation rules for the naming of topics in Kafka and `KafkaTopic.metadata.name` respectively.
There are valid names for each which are invalid in the other.

Using the `spec.topicName` property, it is possible to create a valid topic in Kafka with a name that would be invalid for the Kafka topic in Kubernetes.

The `spec.topicName` property inherits Kafka naming validation rules:

* The name must not be longer than 249 characters.
* Valid characters for Kafka topics are ASCII alphanumerics, `.`, `_`, and `-`.
* The name cannot be `.` or `..`, though `.` can be used in a name, such as `exampleTopic.` or `.exampleTopic`.

`spec.topicName` must not be changed.

For example:

[source,yaml,subs="attributes+"]
----
apiVersion: {KafkaTopicApiVersion}
kind: KafkaTopic
metadata:
  name: topic-name-1
spec:
  topicName: topicName-1 <1>
  # ...
----
<1> Upper case is invalid in Kubernetes.

cannot be changed to:

[source,yaml,subs="attributes+"]
----
apiVersion: {KafkaTopicApiVersion}
kind: KafkaTopic
metadata:
  name: topic-name-1
spec:
  topicName: name-2
  # ...
----

[NOTE]
====
Some Kafka client applications, such as Kafka Streams, can create topics in Kafka programmatically.
If those topics have names that are invalid Kubernetes resource names, the Topic Operator gives them a valid `metadata.name` based on the Kafka name.
Invalid characters are replaced and a hash is appended to the name.
For example:

[source,yaml,subs="attributes+"]
----
apiVersion: {KafkaTopicApiVersion}
kind: KafkaTopic
metadata:
  name: mytopic---c55e57fe2546a33f9e603caf57165db4072e827e
spec:
  topicName: myTopic
  # ...
----
====
