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

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

[role="_abstract"]
You can configure the Cluster Operator using environment variables.
The supported environment variables are listed here. 

NOTE: The environment variables are specified for the container image of the Cluster Operator in its `Deployment` configuration file. 
(`install/cluster-operator/060-Deployment-strimzi-cluster-operator.yaml`)

`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-leader-election-{context}']
== Leader election environment variables 

Use leader election environment variables when xref:assembly-using-multiple-cluster-operator-replicas-{context}[running additional Cluster Operator replicas].
You might run additional replicas to safeguard against disruption caused by major failure.

`STRIMZI_LEADER_ELECTION_ENABLED`:: Optional, disabled (`false`) by default.
Enables or disables leader election, which allows additional Cluster Operator replicas to run on standby.

NOTE: Leader election is disabled by default.
It is only enabled when applying this environment variable on installation.  

`STRIMZI_LEADER_ELECTION_LEASE_NAME`:: Required when leader election is enabled.
The name of the Kubernetes `Lease` resource that is used for the leader election.

`STRIMZI_LEADER_ELECTION_LEASE_NAMESPACE`:: Required when leader election is enabled.
The namespace where the Kubernetes `Lease` resource used for leader election is created.
You can use the downward API to configure it to the namespace where the Cluster Operator is deployed.
+
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_LEADER_ELECTION_LEASE_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace
----

`STRIMZI_LEADER_ELECTION_IDENTITY`:: Required when leader election is enabled.
Configures the identity of a given Cluster Operator instance used during the leader election.
The identity must be unique for each operator instance.
You can use the downward API to configure it to the name of the pod where the Cluster Operator is deployed.
+
[source,yaml,options="nowrap"]
----
env:
  - name: STRIMZI_LEADER_ELECTION_IDENTITY
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
----

`STRIMZI_LEADER_ELECTION_LEASE_DURATION_MS`:: Optional, default 15000 ms.
Specifies the duration the acquired lease is valid.

`STRIMZI_LEADER_ELECTION_RENEW_DEADLINE_MS`:: Optional, default 10000 ms.
Specifies the period the leader should try to maintain leadership.

`STRIMZI_LEADER_ELECTION_RETRY_PERIOD_MS`:: Optional, default 2000 ms.
Specifies the frequency of updates to the lease lock by the leader.

[id='ref-operator-cluster-network-policy-{context}']
== Restricting Cluster Operator access with 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}']
== Setting the time interval for periodic reconciliation

Use the `STRIMZI_FULL_RECONCILIATION_INTERVAL_MS` variable to set the time interval for periodic reconciliations.

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}