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

[id='how-the-topic-operator-works-{context}']
= Understanding the Topic Operator

A fundamental problem that the operator has to solve is that there is no single source of truth:
Both the `KafkaTopic` resource and the topic within Kafka can be modified independently of the operator.
Complicating this, the Topic Operator might not always be able to observe changes at each end in real time (for example, the operator might be down).

To resolve this, the operator maintains its own private copy of the information about each topic.
When a change happens either in the Kafka cluster, or in Kubernetes, it looks at both the state of the other system and at its private copy in order to determine what needs to change to keep everything in sync.
The same thing happens whenever the operator starts, and periodically while it is running.

For example, suppose the Topic Operator is not running, and a `KafkaTopic` `my-topic` gets created.
When the operator starts it will lack a private copy of "my-topic", so it can infer that the `KafkaTopic` has been created since it was last running.
The operator will create the topic corresponding to "my-topic" and also store a private copy of the metadata for "my-topic".

The private copy allows the operator to cope with scenarios where the topic configuration gets changed both in Kafka and in Kubernetes, so long as the changes are not incompatible (for example, both changing the same topic config key, but to different values).
In the case of incompatible changes, the Kafka configuration wins, and the `KafkaTopic` will be updated to reflect that.

The private copy is held in the same ZooKeeper ensemble used by Kafka itself.
This mitigates availability concerns, because if ZooKeeper is not running then Kafka itself cannot run, so the operator will be no less available than it would even if it was stateless.
