// Module included in the following assemblies:
//
// assembly-config.adoc

[id='ref-operator-cluster-{context}']
= Configuring the Cluster Operator

[role="_abstract"]
Use environment variables to configure the Cluster Operator.
Specify the environment variables for the container image of the Cluster Operator in its `Deployment` configuration file.

NOTE: The `Deployment` configuration file provided with the Strimzi release artifacts is `install/cluster-operator/060-Deployment-strimzi-cluster-operator.yaml`.

You can use the following environment variables to configure the Cluster Operator.
If you are running Cluster Operator replicas in standby mode, there are additional xref:con-configuring-cluster-operator-leader-election-{context}[environment variables for enabling leader election].  

`STRIMZI_NAMESPACE`:: A comma-separated list of namespaces that the operator operates in.
When not set, set to empty string, or set to `*`, the Cluster Operator operates in all namespaces.
+
The Cluster Operator deployment might use the downward API to set this automatically to the namespace the Cluster Operator is deployed in.
+
.Example configuration for Cluster Operator namespaces
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace
----

`STRIMZI_FULL_RECONCILIATION_INTERVAL_MS`:: Optional, default is 120000 ms. 
The interval between xref:ref-operator-cluster-periodic-reconciliation-{context}[periodic reconciliations], in milliseconds.

`STRIMZI_OPERATION_TIMEOUT_MS`:: Optional, default 300000 ms.
The timeout for internal operations, in milliseconds. Increase this value when using Strimzi on clusters where regular Kubernetes operations take longer than usual (because of slow downloading of Docker images, for example).

`STRIMZI_ZOOKEEPER_ADMIN_SESSION_TIMEOUT_MS`:: Optional, default 10000 ms.
The session timeout for the Cluster Operator's ZooKeeper admin client, in milliseconds.
Increase the value if ZooKeeper requests from the Cluster Operator are regularly failing due to timeout issues.
There is a maximum allowed session time set on the ZooKeeper server side via the `maxSessionTimeout` config.
By default, the maximum session timeout value is 20 times the default `tickTime` (whose default is 2000) at 40000 ms.
If you require a higher timeout, change the `maxSessionTimeout` ZooKeeper server configuration value.

`STRIMZI_OPERATIONS_THREAD_POOL_SIZE`:: Optional, default 10.
The worker thread pool size, which is used for various asynchronous and blocking operations that are run by the Cluster Operator.

`STRIMZI_OPERATOR_NAME`:: Optional, defaults to the pod's hostname.
The operator name identifies the Strimzi instance when xref:proc-operator-restart-events-str[emitting Kubernetes events].

`STRIMZI_OPERATOR_NAMESPACE`:: The name of the namespace where the Cluster Operator is running.
Do not configure this variable manually. Use the downward API.
+
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_OPERATOR_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace
----

`STRIMZI_OPERATOR_NAMESPACE_LABELS`:: Optional.
The labels of the namespace where the Strimzi Cluster Operator is running.
Use namespace labels to configure the namespace selector in xref:ref-operator-cluster-network-policy-{context}[network policies].
Network policies allow the Strimzi Cluster Operator access only to the operands from the namespace with these labels.
When not set, the namespace selector in network policies is configured to allow access to the Cluster Operator from any namespace in the Kubernetes cluster.
+
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_OPERATOR_NAMESPACE_LABELS
    value: label1=value1,label2=value2
----

`STRIMZI_LABELS_EXCLUSION_PATTERN`:: Optional, default regex pattern is `^app.kubernetes.io/(?!part-of).*`.
The regex exclusion pattern used to filter labels propagation from the main custom resource to its subresources.
The labels exclusion filter is not applied to labels in template sections such as `spec.kafka.template.pod.metadata.labels`.
+
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_LABELS_EXCLUSION_PATTERN
    value: "^key1.*"
----

`STRIMZI_CUSTOM_{COMPONENT_NAME}_LABELS`:: Optional.
One or more custom labels to apply to all the pods created by the `{COMPONENT_NAME}` custom resource.
The Cluster Operator labels the pods when the custom resource is created or is next reconciled.
+
Labels can be applied to the following components:
+
* `KAFKA`
* `KAFKA_CONNECT`
* `KAFKA_CONNECT_BUILD`
* `ZOOKEEPER`
* `ENTITY_OPERATOR`
* `KAFKA_MIRROR_MAKER2`
* `KAFKA_MIRROR_MAKER`
* `CRUISE_CONTROL`
* `KAFKA_BRIDGE`
* `KAFKA_EXPORTER`

`STRIMZI_CUSTOM_RESOURCE_SELECTOR`:: Optional.
The label selector to filter the custom resources handled by the Cluster Operator.
The operator will operate only on those custom resources that have the specified labels set.
Resources without these labels will not be seen by the operator.
The label selector applies to `Kafka`, `KafkaConnect`, `KafkaBridge`, `KafkaMirrorMaker`, and `KafkaMirrorMaker2` resources.
`KafkaRebalance` and `KafkaConnector` resources are operated only when their corresponding Kafka and Kafka Connect clusters have the matching labels.
+
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_CUSTOM_RESOURCE_SELECTOR
    value: label1=value1,label2=value2
----

`STRIMZI_KAFKA_IMAGES`:: Required.
The mapping from the Kafka version to the corresponding Docker image containing a Kafka broker for that version.
The required syntax is whitespace or comma-separated `_<version>_=_<image>_` pairs.
For example `{KafkaVersionLower}={DockerKafkaImagePrevious}, {KafkaVersionHigher}={DockerKafkaImageCurrent}`.
This is used when a `Kafka.spec.kafka.version` property is specified but not the `Kafka.spec.kafka.image` in the `Kafka` resource.

`STRIMZI_DEFAULT_KAFKA_INIT_IMAGE`:: Optional, default `{DockerKafkaInit}`.
The image name to use as default for the init container if no image is specified as the `kafka-init-image` in the `Kafka` resource.
The init container is started before the broker for initial configuration work, such as rack support. 

`STRIMZI_KAFKA_CONNECT_IMAGES`:: Required.
The mapping from the Kafka version to the corresponding Docker image of Kafka Connect for that version.
The required syntax is whitespace or comma-separated `_<version>_=_<image>_` pairs.
For example `{KafkaVersionLower}={DockerKafkaImagePrevious}, {KafkaVersionHigher}={DockerKafkaImageCurrent}`.
This is used when a `KafkaConnect.spec.version` property is specified but not the `KafkaConnect.spec.image`.

`STRIMZI_KAFKA_MIRROR_MAKER_IMAGES`:: Required.
The mapping from the Kafka version to the corresponding Docker image of MirrorMaker for that version.
The required syntax is whitespace or comma-separated `_<version>_=_<image>_` pairs.
For example `{KafkaVersionLower}={DockerKafkaImagePrevious}, {KafkaVersionHigher}={DockerKafkaImageCurrent}`.
This is used when a `KafkaMirrorMaker.spec.version` property is specified but not the `KafkaMirrorMaker.spec.image`.

`STRIMZI_DEFAULT_TOPIC_OPERATOR_IMAGE`:: Optional, default `{DockerTopicOperator}`.
The image name to use as the default when deploying the Topic Operator
if no image is specified as the `Kafka.spec.entityOperator.topicOperator.image` in the `Kafka` resource.

`STRIMZI_DEFAULT_USER_OPERATOR_IMAGE`:: Optional, default `{DockerUserOperator}`.
The image name to use as the default when deploying the User Operator
if no image is specified as the `Kafka.spec.entityOperator.userOperator.image` in the `Kafka` resource.

`STRIMZI_DEFAULT_TLS_SIDECAR_ENTITY_OPERATOR_IMAGE`:: Optional, default `{DockerEntityOperatorStunnel}`.
The image name to use as the default when deploying the sidecar container for the Entity Operator if
no image is specified as the `Kafka.spec.entityOperator.tlsSidecar.image` in the `Kafka` resource.
The sidecar provides TLS support. 

`STRIMZI_IMAGE_PULL_POLICY`:: Optional.
The `ImagePullPolicy` that is applied to containers in all pods managed by the Cluster Operator.
The valid values are `Always`, `IfNotPresent`, and `Never`.
If not specified, the Kubernetes defaults are used.
Changing the policy will result in a rolling update of all your Kafka, Kafka Connect, and Kafka MirrorMaker clusters.

`STRIMZI_IMAGE_PULL_SECRETS`:: Optional.
A comma-separated list of `Secret` names.
The secrets referenced here contain the credentials to the container registries where the container images are pulled from.
The secrets are specified in the `imagePullSecrets` property for all pods created by the Cluster Operator.
Changing this list results in a rolling update of all your Kafka, Kafka Connect, and Kafka MirrorMaker clusters.

`STRIMZI_KUBERNETES_VERSION`:: Optional.
Overrides the Kubernetes version information detected from the API server.
+
.Example configuration for Kubernetes version override
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_KUBERNETES_VERSION
    value: |
           major=1
           minor=16
           gitVersion=v1.16.2
           gitCommit=c97fe5036ef3df2967d086711e6c0c405941e14b
           gitTreeState=clean
           buildDate=2019-10-15T19:09:08Z
           goVersion=go1.12.10
           compiler=gc
           platform=linux/amd64
----

`KUBERNETES_SERVICE_DNS_DOMAIN`:: Optional.
Overrides the default Kubernetes DNS domain name suffix.
+
By default, services assigned in the Kubernetes cluster have a DNS domain name that uses the default suffix `cluster.local`.
+
For example, for broker _kafka-0_:
+
[source,shell,subs="+quotes"]
----
_<cluster-name>_-kafka-0._<cluster-name>_-kafka-brokers._<namespace>_.svc._cluster.local_
----
+
The DNS domain name is added to the Kafka broker certificates used for hostname verification.
+
If you are using a different DNS domain name suffix in your cluster, change the `KUBERNETES_SERVICE_DNS_DOMAIN` environment variable from the default to the one you are using in order to establish a connection with the Kafka brokers.

`STRIMZI_CONNECT_BUILD_TIMEOUT_MS`:: Optional, default 300000 ms.
The timeout for building new Kafka Connect images with additional connectors, in milliseconds.
Consider increasing this value when using Strimzi to build container images containing many connectors or using a slow container registry.

`STRIMZI_NETWORK_POLICY_GENERATION`:: Optional, default `true`.
Network policy for resources.
Network policies allow connections between Kafka components.
+
Set this environment variable to `false` to disable network policy generation. You might do this, for example, if you want to use custom network policies. Custom network policies allow more control over maintaining the connections between components.

`STRIMZI_DNS_CACHE_TTL`:: Optional, default `30`.
Number of seconds to cache successful name lookups in local DNS resolver. Any negative value means cache forever. Zero means do not cache, which can be useful for avoiding connection errors due to long caching policies being applied.

`STRIMZI_POD_SET_RECONCILIATION_ONLY`:: Optional, default `false`.
When set to `true`, the Cluster Operator reconciles only the `StrimziPodSet` resources and any changes to the other custom resources (`Kafka`, `KafkaConnect`, and so on) are ignored.
This mode is useful for ensuring that your pods are recreated if needed, but no other changes happen to the clusters.

`STRIMZI_FEATURE_GATES`:: Optional.
Enables or disables the features and functionality controlled by xref:ref-operator-cluster-feature-gates-{context}[feature gates].

`STRIMZI_POD_SECURITY_PROVIDER_CLASS`:: Optional.
Configuration for the pluggable `PodSecurityProvider` class, which can be used to provide the security context configuration for Pods and containers.

[id='ref-operator-cluster-network-policy-{context}']
== Restricting access to the Cluster Operator using network policy

Use the `STRIMZI_OPERATOR_NAMESPACE_LABELS` environment variable to establish network policy for the Cluster Operator using namespace labels.

The Cluster Operator can run in the same namespace as the resources it manages, or in a separate namespace.
By default, the `STRIMZI_OPERATOR_NAMESPACE` environment variable is configured to use the downward API to find the namespace the Cluster Operator is running in.
If the Cluster Operator is running in the same namespace as the resources, only local access is required and allowed by Strimzi.

If the Cluster Operator is running in a separate namespace to the resources it manages, any namespace in the Kubernetes cluster is allowed access to the Cluster Operator unless network policy is configured.
By adding namespace labels, access to the Cluster Operator is restricted to the namespaces specified.

.Network policy configured for the Cluster Operator deployment
[source,yaml,options="nowrap"]
----
#...
env:
  # ...
  - name: STRIMZI_OPERATOR_NAMESPACE_LABELS
    value: label1=value1,label2=value2
  #...
----

[id='ref-operator-cluster-periodic-reconciliation-{context}']
== Configuring periodic reconciliation by the Cluster Operator

Use the `STRIMZI_FULL_RECONCILIATION_INTERVAL_MS` variable to set the time interval for periodic reconciliations by the Cluster Operator.
Replace its value with the required interval in milliseconds.

.Reconciliation period configured for the Cluster Operator deployment
[source,yaml,options="nowrap"]
----
#...
env:
  # ...
  - name: STRIMZI_FULL_RECONCILIATION_INTERVAL_MS
    value: "120000"
  #...
----

The Cluster Operator reacts to all notifications about applicable cluster resources received from the Kubernetes cluster.
If the operator is not running, or if a notification is not received for any reason, resources will get out of sync with the state of the running Kubernetes cluster.
In order to handle failovers properly, a periodic reconciliation process is executed by the Cluster Operator so that it can compare the state of the resources with the current cluster deployments in order to have a consistent state across all of them.


[role="_additional-resources"]
.Additional resources

* {K8sDownwardAPI}