Configuring the Knative Serving Operator custom resource

You can modify the KnativeServing CR to configure different options for Knative Serving.

Configure the Knative Serving version

Cluster administrators can install a specific version of Knative Serving by using the spec.version field.

For example, if you want to install Knative Serving v1.5, you can apply the following KnativeServing custom resource:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   version: 1.5

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

  1. kn operator install --component serving -v 1.5 -n knative-serving

If spec.version is not specified, the Knative Operator installs the latest available version of Knative Serving.

If users specify an invalid or unavailable version, the Knative Operator does nothing.

The Knative Operator always includes the latest 3 release versions. For example, if the current version of the Knative Operator is v1.5, the earliest version of Knative Serving available through the Operator is v1.2.

If Knative Serving is already managed by the Operator, updating the spec.version field in the KnativeServing resource enables upgrading or downgrading the Knative Serving version, without needing to change the Operator.

Important

The Knative Operator only permits upgrades or downgrades by one minor release version at a time. For example, if the current Knative Serving deployment is version v1.3, you must upgrade to v1.4 before upgrading to v1.5.

Install customized Knative Serving

There are two modes available that you can use to install customized Knative Serving manifests: overwrite mode and append mode.

If you are using overwrite mode, under .spec.manifests, you must define all required manifests to install Knative Serving, because the Operator does not install any default manifests.

If you are using append mode, under .spec.additionalManifests, you only need to define your customized manifests. The customized manifests are installed after default manifests are applied.

Overwrite mode

You can use overwrite mode when you want to customize all Knative Serving manifests.

Important

You must specify both the version and valid URLs for your custom Knative Serving manifests.

For example, if you want to install customized versions of both Knative Serving and the Istio ingress, you can create a KnativeServing CR similar to the following example:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   version: $spec_version
  8.   manifests:
  9.   - URL: https://my-serving/serving.yaml
  10.   - URL: https://my-net-istio/net-istio.yaml

You can make the customized Knative Serving available in one or multiple links, as the spec.manifests supports a list of links.

Important

The ordering of manifest URLs is critical. Put the manifest you want to apply first at the top of the list.

This example installs the customized Knative Serving at version $spec_version which is available at https://my-serving/serving.yaml, and the customized ingress plugin net-istio which is available at https://my-net-istio/net-istio.yaml.

Append mode

You can use append mode to add your customized Knative Serving manifests in addition to the default manifests.

For example, if you only want to customize a few resources but you still want to install the default Knative Serving, you can create a KnativeServing CR similar to the following example:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   version: $spec_version
  8.   additionalManifests:
  9.   - URL: https://my-serving/serving-custom.yaml

This example installs the default Knative Serving manifests, and then installs the customized resources available at https://my-serving/serving-custom.yaml for the version $spec_version.

Private repository and private secrets

You can use the spec.registry section of the Operator CR to change the image references to point to a private registry or specify imagePullSecrets:

  • default: this field defines a image reference template for all Knative images. The format is example-registry.io/custom/path/${NAME}:{CUSTOM-TAG}. If you use the same tag for all your images, the only difference is the image name. ${NAME} is a pre-defined variable in the operator corresponding to the container name. If you name the images in your private repo to align with the container names ( activator, autoscaler, controller, webhook, autoscaler-hpa, net-istio-controller, and queue-proxy), the default argument should be sufficient.

  • override: a map from container name to the full registry location. This section is only needed when the registry images do not match the common naming format. For containers whose name matches a key, the value is used in preference to the image name calculated by default. If a container’s name does not match a key in override, the template in default is used.

  • imagePullSecrets: a list of Secret names used when pulling Knative container images. The Secrets must be created in the same namespace as the Knative Serving Deployments. See deploying images from a private container registry for configuration details.

Download images in a predefined format without secrets

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

In the following example:

  • The custom tag latest is used for all images.
  • All image links are accessible without using secrets.
  • Images are pushed as docker.io/knative-images/${NAME}:{CUSTOM-TAG}.

To define your image links:

  1. Push images to the following image tags:

    ContainerDocker Image
    activatordocker.io/knative-images/activator:latest
    autoscalerdocker.io/knative-images/autoscaler:latest
    controllerdocker.io/knative-images/controller:latest
    webhookdocker.io/knative-images/webhook:latest
    autoscaler-hpadocker.io/knative-images/autoscaler-hpa:latest
    net-istio-controllerdocker.io/knative-images/net-istio-controller:latest
    queue-proxydocker.io/knative-images/queue-proxy:latest

  2. Define your operator CR with following content:

    1. apiVersion: operator.knative.dev/v1beta1
    2. kind: KnativeServing
    3. metadata:
    4.   name: knative-serving
    5.   namespace: knative-serving
    6. spec:
    7.   registry:
    8.     default: docker.io/knative-images/${NAME}:latest

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

  1. ```bash
  2. kn operator configure images --component serving --imageKey default --imageURL docker.io/knative-images/${NAME}:latest -n knative-serving
  3. ```

Download images individually without secrets

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

For example, given the following images:

ContainerDocker Image
activatordocker.io/knative-images-repo1/activator:latest
autoscalerdocker.io/knative-images-repo2/autoscaler:latest
controllerdocker.io/knative-images-repo3/controller:latest
webhookdocker.io/knative-images-repo4/webhook:latest
autoscaler-hpadocker.io/knative-images-repo5/autoscaler-hpa:latest
net-istio-controllerdocker.io/knative-images-repo6/prefix-net-istio-controller:latest
net-istio-webhookdocker.io/knative-images-repo6/net-istio-webhooko:latest
queue-proxydocker.io/knative-images-repo7/queue-proxy-suffix:latest

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

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   registry:
  8.     override:
  9.       activator: docker.io/knative-images-repo1/activator:latest
  10.       autoscaler: docker.io/knative-images-repo2/autoscaler:latest
  11.       controller: docker.io/knative-images-repo3/controller:latest
  12.       webhook: docker.io/knative-images-repo4/webhook:latest
  13.       autoscaler-hpa: docker.io/knative-images-repo5/autoscaler-hpa:latest
  14.       net-istio-controller/controller: docker.io/knative-images-repo6/prefix-net-istio-controller:latest
  15.       net-istio-webhook/webhook: docker.io/knative-images-repo6/net-istio-webhook:latest
  16.       queue-proxy: docker.io/knative-images-repo7/queue-proxy-suffix:latest

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

  1. kn operator configure images --component serving --imageKey activator --imageURL docker.io/knative-images-repo1/activator:latest -n knative-serving
  2. kn operator configure images --component serving --imageKey autoscaler --imageURL docker.io/knative-images-repo2/autoscaler:latest -n knative-serving
  3. kn operator configure images --component serving --imageKey controller --imageURL docker.io/knative-images-repo3/controller:latest -n knative-serving
  4. kn operator configure images --component serving --imageKey webhook --imageURL docker.io/knative-images-repo4/webhook:latest -n knative-serving
  5. kn operator configure images --component serving --imageKey autoscaler-hpa --imageURL docker.io/knative-images-repo5/autoscaler-hpa:latest -n knative-serving
  6. kn operator configure images --component serving --deployName net-istio-controller --imageKey controller --imageURL docker.io/knative-images-repo6/prefix-net-istio-controller:latest -n knative-serving
  7. kn operator configure images --component serving --deployName net-istio-webhook --imageKey webhook --imageURL docker.io/knative-images-repo6/net-istio-webhook:latest -n knative-serving
  8. kn operator configure images --component serving --imageKey queue-proxy --imageURL docker.io/knative-images-repo7/queue-proxy-suffix:latest -n knative-serving

Note

If the container name is not unique across all Deployments, DaemonSets and Jobs, you can prefix the container name with the parent container name and a slash. For example, istio-webhook/webhook.

Download images with secrets

If your image repository requires private secrets for access, include the imagePullSecrets attribute.

This example uses a secret named regcred. You must create your own private secrets if these are required:

After you create this secret, edit the Operator CR by appending the following content:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   registry:
  8.     ...
  9.     imagePullSecrets:
  10.       - name: regcred

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

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   registry:
  8.     ...
  9.     imagePullSecrets:
  10.       - name: regcred
  11.       - name: regcred-2
  12.       ...

SSL certificate for controller

To enable tag to digest resolution, the Knative Serving controller needs to access the container registry. To allow the controller to trust a self-signed registry cert, you can use the Operator to specify the certificate using a ConfigMap or Secret.

Specify the following fields in spec.controller-custom-certs to select a custom registry certificate:

  • name: the name of the ConfigMap or Secret.
  • type: either the string “ConfigMap” or “Secret”.

If you create a ConfigMap named testCert containing the certificate, change your CR:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   controller-custom-certs:
  8.     name: testCert
  9.     type: ConfigMap

Replace the default Istio ingress gateway service

  1. Create a gateway Service and Deployment instance.

  2. Update the Knative gateway by updating the ingress.istio.knative-ingress-gateway spec to select the labels of the new ingress gateway:

    1. apiVersion: operator.knative.dev/v1beta1
    2. kind: KnativeServing
    3. metadata:
    4.   name: knative-serving
    5.   namespace: knative-serving
    6. spec:
    7.   ingress:
    8.     istio:
    9.       enabled: true
    10.       knative-ingress-gateway:
    11.         selector:
    12.           istio: ingressgateway

  3. Update the Istio ingress gateway ConfigMap:

    1. apiVersion: operator.knative.dev/v1beta1
    2. kind: KnativeServing
    3. metadata:
    4.   name: knative-serving
    5.   namespace: knative-serving
    6. spec:
    7.   ingress:
    8.     istio:
    9.       enabled: true
    10.       knative-ingress-gateway:
    11.         selector:
    12.           istio: ingressgateway
    13.   config:
    14.     istio:
    15.       gateway.knative-serving.knative-ingress-gateway: "custom-ingressgateway.custom-ns.svc.cluster.local"

    The key in spec.config.istio is in the format of gateway.<gateway_namespace>.<gateway_name>.

Replace the ingress gateway

  1. Create a gateway.

  2. Update the Istio ingress gateway ConfigMap:

    1. apiVersion: operator.knative.dev/v1beta1
    2. kind: KnativeServing
    3. metadata:
    4.   name: knative-serving
    5.   namespace: knative-serving
    6. spec:
    7.   config:
    8.     istio:
    9.       gateway.custom-ns.knative-custom-gateway: "istio-ingressgateway.istio-system.svc.cluster.local"

    The key in spec.config.istio is in the format of gateway.<gateway_namespace>.<gateway_name>.

Configuration of cluster local gateway

Update spec.ingress.istio.knative-local-gateway to select the labels of the new cluster-local ingress gateway:

Default local gateway name

Go through the installing Istio guide to use local cluster gateway, if you use the default gateway called knative-local-gateway.

Non-default local gateway name

If you create custom local gateway with a name other than knative-local-gateway, update config.istio and the knative-local-gateway selector:

This example shows a service and deployment knative-local-gateway in the namespace istio-system, with the label custom: custom-local-gw:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   ingress:
  8.     istio:
  9.       enabled: true
  10.       knative-local-gateway:
  11.         selector:
  12.           custom: custom-local-gateway
  13.   config:
  14.     istio:
  15.       local-gateway.knative-serving.knative-local-gateway: "custom-local-gateway.istio-system.svc.cluster.local"

Servers configuration for Istio gateways:

You can leverage the KnativeServing CR to configure the hosts and port of the servers stanzas for knative-local-gateway or knative-ingress-gateway gateways. For example, you would like to specify the host into <test-ip> and configure the port with number: 443, name: https, protocol: HTTPS, and target_port: 8443 for knative-local-gateway, apply the following yaml content:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   ingress:
  8.     istio:
  9.       enabled: true
  10.       knative-local-gateway:
  11.         servers:
  12.         - port:
  13.             number: 443
  14.             name: https
  15.             protocol: HTTPS
  16.             target_port: 8443
  17.           hosts:
  18.           - <test-ip>
  19.   config:
  20.     istio:
  21.       local-gateway.knative-serving.knative-local-gateway: "custom-local-gateway.istio-system.svc.cluster.local"

High availability

By default, Knative Serving 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 deployments:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   high-availability:
  8.     replicas: 3

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

  1. kn operator configure replicas --component serving --replicas 3 -n knative-serving

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

  1. apiVersion: autoscaling/v2beta2
  2. kind: HorizontalPodAutoscaler
  3. metadata:
  4.   ...
  5. spec:
  6.   minReplicas: 3
  7.   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

If you would like to override some configurations for a specific deployment, you can override the configuration by modifying the deployments spec in the KnativeServing CR. Currently resources, replicas, labels, annotations and nodeSelector are supported.

Override the resources

The KnativeServing CR 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 a deployment.

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

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   deployments:
  8.   - name: controller
  9.     resources:
  10.     - container: controller
  11.       requests:
  12.         cpu: 300m
  13.         memory: 100Mi
  14.       limits:
  15.         cpu: 1000m
  16.         memory: 250Mi

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

  1. kn operator configure resources --component serving --deployName controller --container controller --requestCPU 300m --requestMemory 100Mi --limitCPU 1000m --limitMemory 250Mi -n knative-serving

Override replicas, labels and annotations

The following KnativeServing resource overrides the webhook deployment to have 3 Replicas, the label mylabel: foo, and the annotation myannotations: bar, while other system deployments have 2 Replicas by using spec.high-availability.

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   high-availability:
  8.     replicas: 2
  9.   deployments:
  10.   - name: webhook
  11.     replicas: 3
  12.     labels:
  13.       mylabel: foo
  14.     annotations:
  15.       myannotations: bar

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

  1. kn operator configure replicas --component serving --replicas 2 -n knative-serving
  2. kn operator configure replicas --component serving --deployName webhook --replicas 3 -n knative-serving
  3. kn operator configure labels --component serving --deployName webhook --key mylabel --value foo -n knative-serving
  4. kn operator configure annotations --component serving --deployName webhook --key myannotations --value bar -n knative-serving

Note

The KnativeServing CR label and annotation settings override the webhook’s labels and annotations for Deployments and Pods.

Override the nodeSelector

The following KnativeServing CR overrides the webhook deployment to use the disktype: hdd nodeSelector:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   deployments:
  8.   - name: webhook
  9.     nodeSelector:
  10.       disktype: hdd

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

  1. kn operator configure nodeSelectors --component serving --deployName webhook --key disktype --value hdd -n knative-serving

Override the tolerations

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

  1. tolerations:
  2. - key: "key1"
  3.   operator: "Equal"
  4.   value: "value1"
  5.   effect: "NoSchedule"

to the deployment activator, you need to change your KnativeServing CR as below:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   deployments:
  8.   - name: activator
  9.     tolerations:
  10.     - key: "key1"
  11.       operator: "Equal"
  12.       value: "value1"
  13.       effect: "NoSchedule"

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

  1. kn operator configure tolerations --component serving --deployName activator --key key1 --operator Equal --value value1 --effect NoSchedule -n knative-serving

Override the affinity

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

  1. affinity:
  2.   nodeAffinity:
  3.     preferredDuringSchedulingIgnoredDuringExecution:
  4.     - weight: 1
  5.       preference:
  6.         matchExpressions:
  7.         - key: disktype
  8.           operator: In
  9.           values:
  10.           - ssd

to the deployment activator, you need to change your KnativeServing CR as below:

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   deployments:
  8.   - name: activator
  9.     affinity:
  10.       nodeAffinity:
  11.         preferredDuringSchedulingIgnoredDuringExecution:
  12.         - weight: 1
  13.           preference:
  14.             matchExpressions:
  15.             - key: disktype
  16.               operator: In
  17.               values:
  18.               - ssd

Override the environment variables

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

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   deployments:
  8.   - name: controller
  9.     env:
  10.     - container: controller
  11.       envVars:
  12.       - name: METRICS_DOMAIN
  13.         value: "knative.dev/my-repo"

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

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

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 KnativeServing resource overrides the webhook service to have the label mylabel: foo, the annotation myannotations: bar, the selector myselector: bar.

  1. apiVersion: operator.knative.dev/v1beta1
  2. kind: KnativeServing
  3. metadata:
  4.   name: knative-serving
  5.   namespace: knative-serving
  6. spec:
  7.   services:
  8.   - name: webhook
  9.     labels:
  10.       mylabel: foo
  11.     annotations:
  12.       myannotations: bar
  13.     selector:
  14.       myselector: bar

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

  1. kn operator configure labels --component serving --serviceName webhook --key mylabel --value foo -n knative-serving
  2. kn operator configure annotations --component serving --serviceName webhook --key myannotations --value bar -n knative-serving
  3. kn operator configure selectors --component serving --serviceName webhook --key myselector --value bar -n knative-serving