Configuring the Eventing Operator custom resource¶

Use this collection to select a configuration change for an existing Operator-managed Eventing installation. The examples are independent entry points, not a required sequence.

Choose a configuration goal¶

Goal	Start here
Set defaults for newly created routing resources	Default Channel, Channel for a Channel-based Broker, or default Broker class
Use other system images or registry credentials	Image references and pull secrets, including Eventing-specific container identifiers
Tune system availability and placement	Replica counts, workload overrides, system Services, or PodDisruptionBudgets
Deploy to another cluster	Remote-cluster deployment for prerequisites, steps, and verification

For ConfigMap mapping and field destinations, see the Operator configuration field map. For release changes, use Operator upgrades.

Before changing configuration¶

You need an Operator-managed KnativeEventing resource, permission to update it, and a recoverable copy of its current manifest. Examples use the name and namespace knative-eventing; substitute your actual values. Merge the selected fields into your authoritative manifest and preserve other settings. If GitOps manages the resource, make the change in that source.

Before selecting a Channel or Broker default, install the chosen implementation and check its supported API version. Changing defaults is not a migration of existing Channels or Brokers. After selecting an example, follow Apply and verify a configuration change.

Setting a default channel¶

If you are using different channel implementations, like the KafkaChannel, or you want a specific configuration of the InMemoryChannel to be the default configuration, you can change the default behavior by updating the default-ch-webhook ConfigMap.

You can do this by modifying the KnativeEventing CR:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  config:
    default-ch-webhook:
      default-ch-config: |
        clusterDefault:
          apiVersion: messaging.knative.dev/v1beta1
          kind: KafkaChannel
          spec:
            numPartitions: 10
            replicationFactor: 1
        namespaceDefaults:
          my-namespace:
            apiVersion: messaging.knative.dev/v1
            kind: InMemoryChannel
            spec:
              delivery:
                backoffDelay: PT0.5S
                backoffPolicy: exponential
                retry: 5

Note

The clusterDefault setting determines the global, cluster-wide default channel type. You can configure channel defaults for individual namespaces by using the namespaceDefaults setting.

Setting the default channel for the broker¶

If you are using a Channel based Broker, you can change the default Channel type for the Broker from InMemoryChannel to KafkaChannel, by updating the config-br-default-channel ConfigMap.

The example uses the full ConfigMap name in spec.config. The shortened key br-default-channel is also accepted. If both entries are present, the full-name entry takes precedence; their data is not merged. See the ConfigMap mapping reference.

You can do this by modifying the KnativeEventing CR:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  config:
    config-br-default-channel:
      channel-template-spec: |
        apiVersion: messaging.knative.dev/v1beta1
        kind: KafkaChannel
        spec:
          numPartitions: 6
          replicationFactor: 1

Private repository and private secrets¶

The Knative Eventing Operator CR is configured the same way as the Knative Serving Operator CR. See the documentation on Private repository and private secret.

Knative Eventing also specifies only one container within each Deployment resource. However, the container does not use the same name as its parent Deployment, which means that the container name in Knative Eventing is not the same unique identifier as it is in Knative Serving.

List of containers within each Deployment resource:

Component	Deployment name	Container name
Core eventing	`eventing-controller`	`eventing-controller`
Core eventing	`eventing-webhook`	`eventing-webhook`
Eventing Broker	`broker-controller`	`eventing-controller`
In-Memory Channel	`imc-controller`	`controller`
In-Memory Channel	`imc-dispatcher`	`dispatcher`

The default field can still be used to replace the images in a predefined format. However, if the container name is not a unique identifier, for example eventing-controller, you must use the override field to replace it, by specifying deployment/container as the unique key.

Some images are defined by using the environment variable in Knative Eventing. They can be replaced by taking advantage of the override field.

Download images in a predefined format without secrets¶

This example shows how you can define custom image links that can be defined in the KnativeEventing CR using the simplified format docker.io/knative-images/${NAME}:{CUSTOM-TAG}.

In this example:

The custom tag latest is used for all images.
All image links are accessible without using secrets.
Images are defined in the accepted format docker.io/knative-images/${NAME}:{CUSTOM-TAG}.

To define your image links:

Push images to the following image tags:

Deployment	Container	Docker image
`eventing-controller`	`eventing-controller`	`docker.io/knative-images/eventing-controller:latest`
	`eventing-webhook`	`docker.io/knative-images/eventing-webhook:latest`
`broker-controller`	`eventing-controller`	`docker.io/knative-images/broker-eventing-controller:latest`
	`controller`	`docker.io/knative-images/controller:latest`
	`dispatcher`	`docker.io/knative-images/dispatcher:latest`

Define your KnativeEventing CR with following content:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  registry:
    default: docker.io/knative-images/${NAME}:latest
    override:
      broker-controller/eventing-controller: docker.io/knative-images-repo1/broker-eventing-controller:latest

You can also run the following commands to make the equivalent change:

```bash
kn operator configure images --component eventing --imageKey default --imageURL 'docker.io/knative-images/${NAME}:latest' -n knative-eventing
kn operator configure images --component eventing --deployName broker-controller --imageKey eventing-controller --imageURL docker.io/knative-images-repo1/broker-eventing-controller:latest -n knative-eventing
```

- In Operator v1.24, `${NAME}` resolves to the image name parsed from the existing image reference, falling back to the container name when no image name is available. Check those names against your private registry; use explicit overrides where they differ.
- `default` is used to define the image format for all containers, except the container `eventing-controller` in the deployment `broker-controller`. To replace the image for this container, use the `override`
field to specify individually, by using `broker-controller/eventing-controller` as the key.

The single quotes in the CLI example preserve ${NAME} as a literal Operator template variable rather than expanding a variable in your shell. They are not part of the stored image reference.

Download images from different repositories without secrets¶

If your custom image links are not defined in a uniform format, you will need to individually include each link in the KnativeEventing CR.

For example, given the following list of images:

Deployment	Container	Docker Image
`eventing-controller`	`eventing-controller`	`docker.io/knative-images-repo1/eventing-controller:latest`
	`eventing-webhook`	`docker.io/knative-images-repo2/eventing-webhook:latest`
	`controller`	`docker.io/knative-images-repo3/imc-controller:latest`
	`dispatcher`	`docker.io/knative-images-repo4/imc-dispatcher:latest`
`broker-controller`	`eventing-controller`	`docker.io/knative-images-repo5/broker-eventing-controller:latest`

You must modify the KnativeEventing CR to include the full list. For example:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  registry:
    override:
      eventing-controller/eventing-controller: docker.io/knative-images-repo1/eventing-controller:latest
      eventing-webhook/eventing-webhook: docker.io/knative-images-repo2/eventing-webhook:latest
      imc-controller/controller: docker.io/knative-images-repo3/imc-controller:latest
      imc-dispatcher/dispatcher: docker.io/knative-images-repo4/imc-dispatcher:latest
      broker-controller/eventing-controller: docker.io/knative-images-repo5/broker-eventing-controller:latest

You can also run the following commands to make the equivalent change:

kn operator configure images --component eventing --deployName eventing-controller --imageKey eventing-controller --imageURL docker.io/knative-images-repo1/eventing-controller:latest -n knative-eventing

kn operator configure images --component eventing --deployName eventing-webhook --imageKey eventing-webhook --imageURL docker.io/knative-images-repo2/eventing-webhook:latest -n knative-eventing

kn operator configure images --component eventing --deployName imc-controller --imageKey controller --imageURL docker.io/knative-images-repo3/imc-controller:latest -n knative-eventing

kn operator configure images --component eventing --deployName imc-dispatcher --imageKey dispatcher --imageURL docker.io/knative-images-repo4/imc-dispatcher:latest -n knative-eventing

kn operator configure images --component eventing --deployName broker-controller --imageKey eventing-controller --imageURL docker.io/knative-images-repo5/broker-eventing-controller:latest -n knative-eventing

If you want to replace the image defined by the environment variable, you must modify the KnativeEventing CR. For example, if you want to replace the image defined by the environment variable DISPATCHER_IMAGE, in the container controller, of the deployment imc-controller, and the target image is docker.io/knative-images-repo5/DISPATCHER_IMAGE:latest, the KnativeEventing CR would be as follows:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  registry:
    override:
      eventing-controller/eventing-controller: docker.io/knative-images-repo1/eventing-controller:latest
      eventing-webhook/eventing-webhook: docker.io/knative-images-repo2/eventing-webhook:latest
      imc-controller/controller: docker.io/knative-images-repo3/imc-controller:latest
      imc-dispatcher/dispatcher: docker.io/knative-images-repo4/imc-dispatcher:latest
      broker-controller/eventing-controller: docker.io/knative-images-repo5/broker-eventing-controller:latest
      DISPATCHER_IMAGE: docker.io/knative-images-repo5/DISPATCHER_IMAGE:latest

You can also run the following commands to make the equivalent change:

kn operator configure images --component eventing --deployName eventing-controller --imageKey eventing-controller --imageURL docker.io/knative-images-repo1/eventing-controller:latest -n knative-eventing

kn operator configure images --component eventing --deployName eventing-webhook --imageKey eventing-webhook --imageURL docker.io/knative-images-repo2/eventing-webhook:latest -n knative-eventing

kn operator configure images --component eventing --deployName imc-controller --imageKey controller --imageURL docker.io/knative-images-repo3/imc-controller:latest -n knative-eventing

kn operator configure images --component eventing --deployName imc-dispatcher --imageKey dispatcher --imageURL docker.io/knative-images-repo4/imc-dispatcher:latest -n knative-eventing

kn operator configure images --component eventing --deployName broker-controller --imageKey eventing-controller --imageURL docker.io/knative-images-repo5/broker-eventing-controller:latest -n knative-eventing

kn operator configure images --component eventing --imageKey DISPATCHER_IMAGE --imageURL docker.io/knative-images-repo5/DISPATCHER_IMAGE:latest -n knative-eventing

Download images with secrets¶

If your image repository requires private secrets for access, you must append the imagePullSecrets attribute to the KnativeEventing CR.

This example uses a secret named regcred. Refer to the Kubernetes documentation to create your own private secrets.

After you create the secret, edit the KnativeEventing CR:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  registry:
    # Retain any existing image template and overrides here.
    imagePullSecrets:
      - name: regcred

The field imagePullSecrets requires a list of secrets. You can add multiple secrets to access the images:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  registry:
    # Retain any existing image template and overrides here.
    imagePullSecrets:
      - name: regcred
      - name: regcred-2
      # Add further Secret names as list entries if needed.

Configuring the default broker class¶

Knative Eventing allows you to define a default Broker class when the user does not specify one. Setting a default class does not install a Broker implementation; select a class supported by an implementation installed in your cluster. See Broker types.

In Operator v1.24, the default Broker transform skips applying spec.defaultBrokerClass when default-br-config under either spec.config.br-defaults or spec.config.config-br-defaults contains brokerClass:. Otherwise, spec.defaultBrokerClass supplies the cluster default; if it is empty, the Operator uses MTChannelBasedBroker.

This behavior is implemented by the v1.24 default Broker transform. Class detection checks both naming forms, while the separate ConfigMap mapping transform selects the full-name entry first without merging them. Use one naming form to avoid conflicting entries.

The following example CR explicitly specifies MTChannelBasedBroker, which is also the fallback when no class is configured:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  defaultBrokerClass: MTChannelBasedBroker

Deploy Knative Eventing to a remote cluster¶

Starting with Knative Operator v1.22, you can target a remote cluster by setting spec.clusterProfileRef on the KnativeEventing CR. The Operator resolves the referenced ClusterProfile, deploys Knative Eventing components on that cluster, and manages their lifecycle through the same CR on the hub.

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  clusterProfileRef:
    name: spoke-cluster-1
    namespace: fleet-system

Before applying this CR, enable multi-cluster support on the Operator and register the spoke as a ClusterProfile. See Deploy Knative to a remote cluster for the complete procedure.

Important

spec.clusterProfileRef is immutable. To move a KnativeEventing resource between clusters, delete it and re-create it with the new reference.

High availability¶

By default, Knative Eventing runs a single instance of each deployment. The spec.high-availability field allows you to configure the number of replicas for all deployments managed by the operator.

The following configuration specifies a replica count of 3 for the workloads:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  high-availability:
    replicas: 3

The replicas field also configures the HorizontalPodAutoscaler resources based on the spec.high-availability. Let's say the operator includes the following HorizontalPodAutoscaler:

apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
  # Other metadata omitted from this illustrative fragment.
  name: example-hpa
spec:
  minReplicas: 3
  maxReplicas: 5

If you configure replicas: 2, which is less than minReplicas, the operator transforms minReplicas to 1.

If you configure replicas: 6, which is more than maxReplicas, the operator transforms maxReplicas to maxReplicas + (replicas - minReplicas) which is 8.

Override system deployments¶

To override a system workload, use spec.workloads in the KnativeEventing CR, as shown below. The following sections cover resources and scheduling. Check the CRD installed by your Operator release for supported fields.

Override the resources¶

The KnativeEventing custom resource is able to configure system resources for the Knative system containers based on the deployment. Requests and limits can be configured for all the available containers within the deployment, like eventing-controller, eventing-webhook, imc-controller, etc.

For example, the following KnativeEventing resource configures the container eventing-controller in the deployment eventing-controller to request 0.3 CPU and 100MB of RAM, and sets hard limits of 1 CPU and 250MB RAM:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  workloads:
  - name: eventing-controller
    resources:
    - container: eventing-controller
      requests:
        cpu: 300m
        memory: 100M
      limits:
        cpu: 1000m
        memory: 250M

You can also run the following command to make the equivalent change:

kn operator configure resources --component eventing --deployName eventing-controller --container eventing-controller --requestCPU 300m --requestMemory 100M --limitCPU 1000m --limitMemory 250M -n knative-eventing

Override the nodeSelector¶

The KnativeEventing resource is able to override the nodeSelector for the Knative Eventing deployment resources. For example, if you would like to add the following tolerations

nodeSelector:
  disktype: hdd

to the deployment eventing-controller, you need to change your KnativeEventing CR as below:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  workloads:
  - name: eventing-controller
    nodeSelector:
      disktype: hdd

You can also run the following command to make the equivalent change:

kn operator configure nodeSelector --component eventing --deployName eventing-controller --key disktype --value hdd -n knative-eventing

Override the tolerations¶

The KnativeEventing resource is able to override tolerations for the Knative Eventing deployment resources. For example, if you would like to add the following tolerations

tolerations:
- key: "key1"
  operator: "Equal"
  value: "value1"
  effect: "NoSchedule"

to the deployment eventing-controller, you need to change your KnativeEventing CR as below:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  workloads:
  - name: eventing-controller
    tolerations:
    - key: "key1"
      operator: "Equal"
      value: "value1"
      effect: "NoSchedule"

You can also run the following command to make the equivalent change:

kn operator configure tolerations --component eventing --deployName eventing-controller --key key1 --operator Equal --value value1 --effect NoSchedule -n knative-eventing

Override the affinity¶

The KnativeEventing resource is able to override the affinity, including nodeAffinity, podAffinity, and podAntiAffinity, for the Knative Eventing deployment resources. For example, if you would like to add the following nodeAffinity

affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 1
      preference:
        matchExpressions:
        - key: disktype
          operator: In
          values:
          - ssd

to the deployment eventing-controller, you need to change your KnativeEventing CR as below:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  workloads:
  - name: eventing-controller
    affinity:
      nodeAffinity:
        preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 1
          preference:
            matchExpressions:
            - key: disktype
              operator: In
              values:
              - ssd

Override the environment variables¶

The KnativeEventing resource is able to override or add the environment variables for the containers in the Knative Eventing deployment resources. For example, if you would like to change the value of environment variable METRICS_DOMAIN in the container eventing-controller into "knative.dev/my-repo" for the deployment eventing-controller, you need to change your KnativeEventing CR as below:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  workloads:
  - name: eventing-controller
    env:
    - container: eventing-controller
      envVars:
      - name: METRICS_DOMAIN
        value: "knative.dev/my-repo"

You can also run the following command to make the equivalent change:

kn operator configure envvars --component eventing --deployName eventing-controller --container eventing-controller --name METRICS_DOMAIN --value "knative.dev/my-repo" -n knative-eventing

Override system services¶

If you would like to override some configurations for a specific service, you can override the configuration by using spec.services in CR. Currently labels, annotations and selector are supported.

Override labels and annotations and selector¶

The following KnativeEventing resource overrides the eventing-webhook service to have the label mylabel: foo, the annotation myannotations: bar, the selector myselector: bar.

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  services:
  - name: eventing-webhook
    labels:
      mylabel: foo
    annotations:
      myannotations: bar
    selector:
      myselector: bar

You can also run the following commands to make the equivalent change:

kn operator configure labels --component eventing --serviceName eventing-webhook --key mylabel --value foo -n knative-eventing
kn operator configure annotations --component eventing --serviceName eventing-webhook --key myannotations --value bar -n knative-eventing
kn operator configure selectors --component eventing --serviceName eventing-webhook --key myselector --value bar -n knative-eventing

Override system podDisruptionBudgets¶

A Pod Disruption Budget (PDB) allows you to limit the disruption to your application when its pods need to be rescheduled for maintenance reasons. Knative Operator allows you to configure the minAvailable for a specific podDisruptionBudget resource in Eventing based on the name. To understand more about the configuration of the resource podDisruptionBudget, click here. For example, if you would like to change minAvailable into 70% for the podDisruptionBudget named eventing-webhook, you need to change your KnativeEventing CR as below:

apiVersion: operator.knative.dev/v1beta1
kind: KnativeEventing
metadata:
  name: knative-eventing
  namespace: knative-eventing
spec:
  podDisruptionBudgets:
  - name: eventing-webhook
    minAvailable: 70%

Apply and verify a configuration change¶

Merge the selected fields into your existing custom resource manifest. Retain the previous values for recovery.

Validate and apply it, substituting your filename:

kubectl apply --dry-run=server -f <filename>.yaml
kubectl apply -f <filename>.yaml

Check readiness and status conditions:

kubectl get knativeeventing knative-eventing -n knative-eventing
kubectl get knativeeventing knative-eventing -n knative-eventing -o yaml

Confirm READY is True; otherwise, use installation troubleshooting.

Inspect the affected ConfigMap, workload, Service, or PDB in the component namespace. For routing defaults, verify a newly created Channel or Broker uses the intended implementation using Channel configuration or Broker configuration. Readiness and matching configuration do not prove end-to-end event delivery; test the intended event path separately.

To recover, restore previous values in the authoritative manifest and apply through the same workflow, then repeat the checks. Do not edit generated resources directly. For remote targets, follow multi-cluster verification.