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

[id='topic-operator-usage-recommendations-{context}']
= Topic Operator usage recommendations

When working with topics, be consistent and always operate on either `KafkaTopic` resources or topics directly. 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: Recommendations for identifiers and names in Kubernetes are outlined in link:https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/identifiers.md[Identifiers and Names in Kubernetes^] community article.

.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 KafkaTopic 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]
----
kind: KafkaTopic
metadata:
  name: topic-name-1
spec:
  topicName: topicName-1 # Upper case is invalid in Kubernetes
  # ...
----

cannot be changed to

[source,yaml]
----
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 valid names based on the Kafka names. Invalid characters are replaced and a hash is appended to the name.
