Chapter 2. Common configuration properties

Use the replicas property to configure replicas.

The type of replication depends on the resource.

Use the bootstrapServers property to configure a list of bootstrap servers.

The bootstrap server lists can refer to Kafka clusters that are not deployed in the same OpenShift cluster. They can also refer to a Kafka cluster not deployed by Streams for Apache Kafka.

If on the same OpenShift cluster, each list must ideally contain the Kafka cluster bootstrap service which is named CLUSTER-NAME-kafka-bootstrap and a port number. If deployed by Streams for Apache Kafka but on different OpenShift clusters, the list content depends on the approach used for exposing the clusters (routes, ingress, nodeports or loadbalancers).

When using Kafka with a Kafka cluster not managed by Streams for Apache Kafka, you can specify the bootstrap servers list according to the configuration of the given cluster.

You can incorporate SSL configuration and cipher suite specifications to further secure TLS-based communication between your client application and a Kafka cluster. In addition to the standard TLS configuration, you can specify a supported TLS version and enable cipher suites in the configuration for the Kafka broker. You can also add the configuration to your clients if you wish to limit the TLS versions and cipher suites they use. The configuration on the client must only use protocols and cipher suites that are enabled on the broker.

A cipher suite is a set of security mechanisms for secure connection and data transfer. For example, the cipher suite TLS_AES_256_GCM_SHA384 is composed of the following mechanisms, which are used in conjunction with the TLS protocol:

The combination is encapsulated in the TLS_AES_256_GCM_SHA384 cipher suite specification.

The ssl.enabled.protocols property specifies the available TLS versions that can be used for secure communication between the cluster and its clients. The ssl.protocol property sets the default TLS version for all connections, and it must be chosen from the enabled protocols. Use the ssl.endpoint.identification.algorithm property to enable or disable hostname verification (configurable only in components based on Kafka clients - Kafka Connect, MirrorMaker 2, and Kafka Bridge).

# ...
config:
  ssl.cipher.suites: TLS_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 

  ssl.enabled.protocols: TLSv1.3, TLSv1.2 

  ssl.protocol: TLSv1.3 

  ssl.endpoint.identification.algorithm: HTTPS 

# ...

Use the tls and trustedCertificates properties to enable TLS encryption and specify secrets under which TLS certificates are stored in X.509 format. You can add this configuration to the Kafka Connect, Kafka MirrorMaker, and Kafka Bridge components for TLS connections to the Kafka cluster.

You can use the secrets created by the Cluster Operator for the Kafka cluster, or you can create your own TLS certificate file, then create a Secret from the file:

oc create secret generic <my_secret> \
--from-file=<my_tls_certificate_file.crt>

Use the pattern property to include all files in the secret that match the pattern. Using the pattern property means that the custom resource does not need to be updated if certificate file names change. However, you can specify a specific file using the certificate property instead of the pattern property.

tls:
  trustedCertificates:
    - secretName: my-cluster-cluster-cert
      pattern: "*.crt"
    - secretName: my-cluster-cluster-cert
      certificate: ca2.crt

If you want to enable TLS encryption, but use the default set of public certification authorities shipped with Java, you can specify trustedCertificates as an empty array:

tls:
  trustedCertificates: []

Similarly, you can use the tlsTrustedCertificates property in the configuration for oauth and keycloak authentication and authorization types that integrate with authorization servers. The configuration sets up encrypted TLS connections to the authorization server.

tlsTrustedCertificates:
  - secretName: oauth-server-ca
    pattern: "*.crt"

For information on configuring mTLS authentication, see the KafkaClientAuthenticationTls schema reference.

Configure resource requests and limits to control resources for Streams for Apache Kafka containers. You can specify requests and limits for memory and cpu resources. The requests should be enough to ensure a stable performance of Kafka.

How you configure resources in a production environment depends on a number of factors. For example, applications are likely to be sharing resources in your OpenShift cluster.

For Kafka, the following aspects of a deployment can impact the resources you need:

The values specified for resource requests are reserved and always available to the container. Resource limits specify the maximum resources that can be consumed by a given container. The amount between the request and limit is not reserved and might not be always available. A container can use the resources up to the limit only when they are available. Resource limits are temporary and can be reallocated.

If you set limits without requests or vice versa, OpenShift uses the same value for both. Setting equal requests and limits for resources guarantees quality of service, as OpenShift will not kill containers unless they exceed their limits.

Configure resource requests and limits for components using resources properties in the spec of following custom resources:

Use the KafkaNodePool custom resource for Kafka nodes (spec.resources)

Use the Kafka custom resource for the following components:

For other components, resources are configured in the corresponding custom resource. For example:

apiVersion: kafka.strimzi.io/v1beta2
kind: KafkaNodePool
metadata:
  name: pool-a
  labels:
    strimzi.io/cluster: my-cluster
spec:
  replicas: 3
  roles:
    - broker
  resources:
      requests:
        memory: 64Gi
        cpu: "8"
      limits:
        memory: 64Gi
        cpu: "12"
  # ...

apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
spec:
  # ..
  entityOperator:
    #...
    topicOperator:
      #...
      resources:
        requests:
          memory: 512Mi
          cpu: "1"
        limits:
          memory: 512Mi
          cpu: "1"

If the resource request is for more than the available free resources in the OpenShift cluster, the pod is not scheduled.

Use the image property to configure the container image used by the component.

Overriding container images is recommended only in special situations where you need to use a different container registry or a custom image.

For example, if your network does not allow access to the container repository used by Streams for Apache Kafka, you can copy the Streams for Apache Kafka images or build them from the source. However, if the configured image is not compatible with Streams for Apache Kafka images, it might not work properly.

A copy of the container image might also be customized and used for debugging.

You can specify which container image to use for a component using the image property in the following resources:

Each environment variable maps Kafka versions to container images. These mappings are used when a custom resource does not explicitly specify an image. You can override the default image by specifying the image and the matching version in the custom resource.

The values for the environment variables and those specified for image and version in the component configuration determines the image and Kafka version used:

Even if the configuration is syntactically correct, it can still be invalid if the image and version mismatch. To ensure a valid configuration:

Here we can see what happens with versions 4.0.0 and 4.1.0 (the default).

Handling upgrades with custom images

When you set a custom image through the image property in a custom resource, you must keep the image and version in sync during upgrades. The Cluster Operator does not automatically update images defined this way. (This limitation does not apply when you use Kafka Connect Build or the default image mappings defined in the Cluster Operator environment variables.)

To avoid version mismatches when changing the Kafka version:

If you don’t follow these steps, the operator might attempt to upgrade the resource before the correct image is specified, leading to mismatches.

For more information on image environment variables, see Configuring the Cluster Operator.

apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    image: my-org/my-image:latest
    # ...

Use the livenessProbe and readinessProbe properties to configure healthcheck probes supported in Streams for Apache Kafka.

Healthchecks are periodical tests which verify the health of an application. When a Healthcheck probe fails, OpenShift assumes that the application is not healthy and attempts to fix it.

For more details about the probes, see Configure Liveness and Readiness Probes.

Both livenessProbe and readinessProbe support the following options:

# ...
readinessProbe:
  initialDelaySeconds: 15
  timeoutSeconds: 5
livenessProbe:
  initialDelaySeconds: 15
  timeoutSeconds: 5
# ...

For more information about the livenessProbe and readinessProbe options, see the Probe schema reference.

Use the metricsConfig property to enable and configure Prometheus metrics. Streams for Apache Kafka provides support for Prometheus JMX Exporter and Streams for Apache Kafka Metrics Reporter. Only one of these can be selected at any given time.

When metrics are enabled, they are exposed on port 9404.

When the metricsConfig property is not defined in the resource, the Prometheus metrics are not enabled.

For more information about setting up and deploying Prometheus and Grafana, see Introducing Metrics to Kafka.

To enable Prometheus metrics export without further configuration, you can reference a ConfigMap containing an empty file under metricsConfig.valueFrom.configMapKeyRef.key. When referencing an empty file, all metrics are exposed as long as they have not been renamed.

kind: ConfigMap
apiVersion: v1
metadata:
  name: my-configmap
data:
  my-key: |
    lowercaseOutputName: true
    rules:
    # Special cases and very specific rules
    - pattern: kafka.server<type=(.+), name=(.+), clientId=(.+), topic=(.+), partition=(.*)><>Value
      name: kafka_server_$1_$2
      type: GAUGE
      labels:
       clientId: "$3"
       topic: "$4"
       partition: "$5"
    # further configuration

apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    metricsConfig:
      type: jmxPrometheusExporter
      valueFrom:
        configMapKeyRef:
          name: my-config-map
          key: my-key
    # ...

To enable Streams for Apache Kafka Metrics Reporter, set the type to strimziMetricsReporter. The allowList configuration is a comma-separated list of regex patterns to filter the metrics that are collected. This defaults to .*, which allows all metrics.

apiVersion: kafka.strimzi.io/v1beta2
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    metricsConfig:
      type: strimziMetricsReporter
      values:
        allowList:
          key: ".*"
    # ...

The following Streams for Apache Kafka components run inside a Java Virtual Machine (JVM):

To optimize their performance on different platforms and architectures, you configure the jvmOptions property in the following resources:

You can specify the following options in your configuration:

Specify heap size to have more control over the memory allocated to your JVM. Heap sizes should make the best use of a container’s memory limit (and request) without exceeding it. Heap size and any other memory requirements need to fit within a specified memory limit. If you don’t specify heap size in your configuration, but you configure a memory resource limit (and request), the Cluster Operator imposes default heap sizes automatically. The Cluster Operator sets default maximum and minimum heap values based on a percentage of the memory resource configuration.

The following table shows the default heap values.

If a memory limit (and request) is not specified, a JVM’s minimum heap size is set to 128M. The JVM’s maximum heap size is not defined to allow the memory to increase as needed. This is ideal for single node environments in test and development.

Setting an appropriate memory request can prevent the following:

In this example, the JVM uses 2 GiB (=2,147,483,648 bytes) for its heap. Total JVM memory usage can be a lot more than the maximum heap size.

# ...
jvmOptions:
  "-Xmx": "2g"
  "-Xms": "2g"
# ...

Setting the same value for initial (-Xms) and maximum (-Xmx) heap sizes avoids the JVM having to allocate memory after startup, at the cost of possibly allocating more heap than is really needed.

jvmOptions:
  "-XX":
    "UseG1GC": "true"
    "MaxGCPauseMillis": "20"
    "InitiatingHeapOccupancyPercent": "35"
    "ExplicitGCInvokesConcurrent": "true"

-XX:+UseG1GC -XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35 -XX:+ExplicitGCInvokesConcurrent -XX:-UseParNewGC

jvmOptions:
  javaSystemProperties:
    - name: javax.net.debug
      value: ssl

For more information about the jvmOptions, see the JvmOptions schema reference.

The jvmOptions property also allows you to enable and disable garbage collector (GC) logging. GC logging is disabled by default. To enable it, set the gcLoggingEnabled property as follows:

# ...
jvmOptions:
  gcLoggingEnabled: true
# ...

Streams for Apache Kafka supports specifying additional volumes and volume mounts in the following components:

All additional mounted paths are located inside /mnt to ensure compatibility with future Kafka and Streams for Apache Kafka updates.

Supported Volume Types

kind: Kafka
spec:
  kafka:
    # ...
    template:
      pod:
        volumes:
          - name: example-secret
            secret:
              secretName: secret-name
          - name: example-configmap
            configMap:
              name: config-map-name
          - name: temp
            emptyDir: {}
          - name: example-pvc-volume
            persistentVolumeClaim:
              claimName: myclaim
          - name: example-csi-volume
            csi:
              driver: csi.cert-manager.io
              readOnly: true
              volumeAttributes:
                csi.cert-manager.io/issuer-name: my-ca
                csi.cert-manager.io/dns-names: ${POD_NAME}.${POD_NAMESPACE}.svc.cluster.local
          - name: example-oci-plugin
            image:
              reference: my-registry.io/oci-artifacts/example-plugin:latest
      kafkaContainer:
        volumeMounts:
          - name: example-secret
            mountPath: /mnt/secret-volume
          - name: example-configmap
            mountPath: /mnt/cm-volume
          - name: temp
            mountPath: /mnt/temp
          - name: example-pvc-volume
            mountPath: /mnt/data
          - name: example-csi-volume
            mountPath: /mnt/certificate
          - name: example-oci-plugin
            mountPath: /mnt/example-plugin

You can use volumes to store files containing configuration values for a Kafka component and then load those values using a configuration provider. For more information, see Loading configuration values from external sources.

You can also use additional volumes to mount custom plugins: