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

[id='con-operator-topic-names-{context}']
= Topic naming conventions

A `KafkaTopic` resource includes a name for the topic and a label that identifies the name of the Kafka cluster it belongs to. 

.Label identifying a Kafka cluster for topic handling
[source,yaml,subs="attributes+"]
----
apiVersion: {KafkaTopicApiVersion}
kind: KafkaTopic
metadata:
  name: topic-name-1
  labels:
    strimzi.io/cluster: my-cluster
spec:
  topicName: topic-name-1  
----

The label provides the cluster name of the `Kafka` resource.
The Topic Operator uses the label as a mechanism for determining which `KafkaTopic` resources to manage.
If the label does not match the Kafka cluster, the Topic Operator cannot see the `KafkaTopic`, and the topic is not created.

Kafka and Kubernetes have their own naming validation rules, and a Kafka topic name might not be a valid resource name in Kubernetes.
If possible, try and stick to a naming convention that works for both.

Consider the following guidelines:

* Use topic names that reflect the nature of the topic
* Be concise and keep the name under 63 characters
* Use all lower case and hyphens
* Avoid special characters, spaces or symbols

The `KafkaTopic` resource allows you to specify the Kafka topic name using the `metadata.name` field. 
However, if the desired Kafka topic name is not a valid Kubernetes resource name, you can use the `spec.topicName` property to specify the actual name. 
The `spec.topicName` field is optional, and when it's absent, the Kafka topic name defaults to the `metadata.name` of the topic.
When a topic is created, the topic name cannot be changed later.

.Example of supplying a valid Kafka topic name
[source,yaml,subs="attributes+"]
----
apiVersion: {KafkaTopicApiVersion}
kind: KafkaTopic
metadata:
  name: my-topic-1 # <1>
spec:
  topicName: My.Topic.1 # <2>
  # ...
----
<1> A valid topic name that works in Kubernetes.
<2> A Kafka topic name that uses upper case and periods, which are invalid in Kubernetes.

If more than one `KafkaTopic` resource refers to the same Kafka topic, the resource that was created first is considered to be the one managing the topic. 
The status of the newer resources is updated to indicate a conflict, and their `Ready` status is changed to `False`.

If a Kafka client application, such as Kafka Streams, automatically creates topics with invalid Kubernetes resource names, the Topic Operator generates a valid `metadata.name` when used in bidirectional mode. 
It replaces invalid characters and appends a hash to the name. 
However, this behavior does not apply in (preview) unidirectional mode.

.Example of replacing an invalid topic name
[source,yaml,subs="attributes+"]
----
apiVersion: {KafkaTopicApiVersion}
kind: KafkaTopic
metadata:
  name: my-topic---c55e57fe2546a33f9e603caf57165db4072e827e
  # ...
----

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