Chapter 5. Installing OpenShift Serverless

5.1. Installing OpenShift Serverless

This guide walks cluster administrators through installing the OpenShift Serverless Operator to an OpenShift Container Platform cluster.

Note

OpenShift Serverless is supported for installation in a restricted network environment. For more information, see Using Operator Lifecycle Manager on restricted networks.

Important

Before upgrading to the latest Serverless release, you must remove the community Knative Eventing Operator if you have previously installed it. Having the Knative Eventing Operator installed will prevent you from being able to install the latest version of Knative Eventing using the OpenShift Serverless Operator.

5.1.1. Defining cluster size requirements for an OpenShift Serverless installation

To install and use OpenShift Serverless, the OpenShift Container Platform cluster must be sized correctly. The minimum requirement for OpenShift Serverless is a cluster with 10 CPUs and 40GB memory. The total size requirements to run OpenShift Serverless are dependent on the applications deployed. By default, each pod requests approximately 400m of CPU, so the minimum requirements are based on this value. In the size requirement provided, an application can scale up to 10 replicas. Lowering the actual CPU request of applications can increase the number of possible replicas.

Note

The requirements provided relate only to the pool of worker machines of the OpenShift Container Platform cluster. Master nodes are not used for general scheduling and are omitted from the requirements.

Note

The following limitations apply to all OpenShift Serverless deployments:

  • Maximum number of Knative services: 1000
  • Maximum number of Knative revisions: 1000

5.1.2. Additional requirements for advanced use cases

For more advanced use cases such as logging or metering on OpenShift Container Platform, you must deploy more resources. Recommended requirements for such use cases are 24 CPUs and 96GB of memory.

If you have high availability (HA) enabled on your cluster, this requires between 0.5 - 1.5 cores and between 200MB - 2GB of memory for each replica of the Knative Serving control plane. HA is enabled for some Knative Serving components by default. You can disable HA by following the documentation on Configuring high availability replicas on OpenShift Serverless.

5.1.3. Scaling your cluster using machine sets

You can use the OpenShift Container Platform MachineSet API to manually scale your cluster up to the desired size. The minimum requirements usually mean that you must scale up one of the default machine sets by two additional machines. See Manually scaling a machine set.

5.1.4. Installing the OpenShift Serverless Operator

This procedure describes how to install and subscribe to the OpenShift Serverless Operator from the OperatorHub using the OpenShift Container Platform web console.

Procedure

  1. In the OpenShift Container Platform web console, navigate to the OperatorsOperatorHub page.
  2. Scroll, or type they keyword Serverless into the Filter by keyword box to find the OpenShift Serverless Operator.

    OpenShift Serverless Operator in the OpenShift Container Platform web console
  3. Review the information about the Operator and click Install.

    OpenShift Serverless Operator information
  4. On the Create Operator Subscription page:

    Create Operator Subscription page
    1. The Installation Mode is All namespaces on the cluster (default). This mode installs the Operator in the default openshift-operators namespace to watch and be made available to all namespaces in the cluster.
    2. The Installed Namespace will be openshift-operators.
    3. Select the 4.4 channel as the Update Channel. The 4.4 channel will enable installation of the latest stable release of the OpenShift Serverless Operator.
    4. Select Automatic or Manual approval strategy.
  5. Click Subscribe to make the Operator available to the selected namespaces on this OpenShift Container Platform cluster.
  6. From the CatalogOperator Management page, you can monitor the OpenShift Serverless Operator subscription’s installation and upgrade progress.

    1. If you selected a Manual approval strategy, the subscription’s upgrade status will remain Upgrading until you review and approve its install plan. After approving on the Install Plan page, the subscription upgrade status moves to Up to date.
    2. If you selected an Automatic approval strategy, the upgrade status should resolve to Up to date without intervention.

Verification steps

After the Subscription’s upgrade status is Up to date, select CatalogInstalled Operators to verify that the OpenShift Serverless Operator eventually shows up and its Status ultimately resolves to InstallSucceeded in the relevant namespace.

Installed Operators page

If it does not:

  1. Switch to the CatalogOperator Management page and inspect the Operator Subscriptions and Install Plans tabs for any failure or errors under Status.
  2. Check the logs in any pods in the openshift-operators project on the WorkloadsPods page that are reporting issues to troubleshoot further.

Additional resources

  • For more information on installing Operators, see the OpenShift Container Platform documentation on Adding Operators to a cluster.

5.1.5. Next steps

  • After the OpenShift Serverless Operator is installed, you can install the Knative Serving component. See the documentation on Installing Knative Serving.
  • After the OpenShift Serverless Operator is installed, you can install the Knative Eventing component. See the documentation on Installing Knative Eventing.

5.2. Installing Knative Serving

After you install the OpenShift Serverless Operator, you can install Knative Serving by following the procedures described in this guide.

This guide provides information about installing Knative Serving using the default settings. However, you can configure more advanced settings in the KnativeServing custom resource definition.

For more information about configuration options for the KnativeServing custom resource definition, see Advanced installation configuration options.

5.2.1. Creating the knative-serving namespace

When you create the knative-serving namespace, a knative-serving project will also be created.

Important

You must complete this procedure before installing Knative Serving.

If the KnativeServing object created during Knative Serving’s installation is not created in the knative-serving namespace, it will be ignored.

Prerequisites

  • An OpenShift Container Platform account with cluster administrator access
  • Installed OpenShift Serverless Operator

5.2.1.1. Creating the knative-serving namespace using the web console

Procedure

  1. In the OpenShift Container Platform web console, navigate to AdministrationNamespaces.

    Namespaces page
  2. Enter knative-serving as the Name for the project. The other fields are optional.

    Creating the `knative-eventing` namespace
  3. Click Create.

5.2.1.2. Creating the knative-serving namespace using the CLI

Procedure

  1. Create the knative-serving namespace by entering:

    $ oc create namespace knative-serving

5.2.2. Prerequisites

  • An OpenShift Container Platform account with cluster administrator access.
  • Installed OpenShift Serverless Operator.
  • Created the knative-serving namespace.

5.2.3. Installing Knative Serving using the web console

Procedure

  1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to OperatorsInstalled Operators.
  2. Check that the Project dropdown at the top of the page is set to Project: knative-serving.
  3. Click Knative Serving in the list of Provided APIs for the OpenShift Serverless Operator to go to the Knative Serving tab.

    Installed Operators page
  4. Click the Create Knative Serving button.

    Knative Serving tab
  5. In the Create Knative Serving page, you can install Knative Serving using the default settings by clicking Create.

    You can also modify settings for the Knative Serving installation by editing the KnativeServing object using either the form provided, or by editing the YAML.

    • Using the form is recommended for simpler configurations that do not require full control of KnativeServing object creation.
    • Editing the YAML is recommended for more complex configurations that require full control of KnativeServing object creation. You can access the YAML by clicking the edit YAML link in the top right of the Create Knative Serving page.

      After you complete the form, or have finished modifying the YAML, click Create.

      Note

      For more information about configuration options for the KnativeServing custom resource definition, see the documentation on Advanced installation configuration options.

      Create Knative Serving in Form View
      Create Knative Serving in YAML view
  6. After you have installed Knative Serving, the KnativeServing object is created, and you will be automically directed to the Knative Serving tab.

    Installed Operators page

    You will see knative-serving in the list of resources.

Verification steps

  1. Click on knative-serving in the Knative Serving tab.
  2. You will be automatically directed to the Knative Serving Overview page.

    Installed Operators page
  3. Scroll down to look at the list of Conditions.
  4. You should see a list of conditions with a status of True, as shown in the example image.

    Conditions
    Note

    It may take a few seconds for the Knative Serving resources to be created. You can check their status in the Resources tab.

  5. If the conditions have a status of Unknown or False, wait a few moments and then check again after you have confirmed that the resources have been created.

5.2.4. Installing Knative Serving using YAML

Procedure

  1. Create a file named serving.yaml.
  2. Copy the following sample YAML into serving.yaml:

    apiVersion: operator.knative.dev/v1alpha1
    kind: KnativeServing
    metadata:
        name: knative-serving
        namespace: knative-serving
  3. Apply the serving.yaml file:

    $ oc apply -f serving.yaml

Verification steps

  1. To verify the installation is complete, enter the following command:

    $ oc get knativeserving.operator.knative.dev/knative-serving -n knative-serving --template='{{range .status.conditions}}{{printf "%s=%s\n" .type .status}}{{end}}'

    The output should be similar to:

    DependenciesInstalled=True
    DeploymentsAvailable=True
    InstallSucceeded=True
    Ready=True
    Note

    It may take a few seconds for the Knative Serving resources to be created.

  2. If the conditions have a status of Unknown or False, wait a few moments and then check again after you have confirmed that the resources have been created.
  3. Check that the Knative Serving resources have been created by entering:

    $ oc get pods -n knative-serving

    The output should look similar to:

    NAME                               READY   STATUS    RESTARTS   AGE
    activator-5c596cf8d6-5l86c         1/1     Running   0          9m37s
    activator-5c596cf8d6-gkn5k         1/1     Running   0          9m22s
    autoscaler-5854f586f6-gj597        1/1     Running   0          9m36s
    autoscaler-hpa-78665569b8-qmlmn    1/1     Running   0          9m26s
    autoscaler-hpa-78665569b8-tqwvw    1/1     Running   0          9m26s
    controller-7fd5655f49-9gxz5        1/1     Running   0          9m32s
    controller-7fd5655f49-pncv5        1/1     Running   0          9m14s
    kn-cli-downloads-8c65d4cbf-mt4t7   1/1     Running   0          9m42s
    webhook-5c7d878c7c-n267j           1/1     Running   0          9m35s

5.2.5. Next steps

  • For cloud events functionality on OpenShift Serverless, you can install the Knative Eventing component. See the documentation on Installing Knative Eventing.
  • Install the Knative CLI to use kn commands with Knative Serving. For example, kn service commands. See the documentation on Installing the Knative CLI (kn).

5.3. Installing Knative Eventing

After you install the OpenShift Serverless Operator, you can install Knative Eventing by following the procedures described in this guide.

Important

Knative Eventing is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

This guide provides information about installing Knative Eventing using the default settings.

5.3.1. Creating the knative-eventing namespace

When you create the knative-eventing namespace, a knative-eventing project will also be created.

Important

You must complete this procedure before installing Knative Eventing.

If the KnativeEventing object created during Knative Eventing’s installation is not created in the knative-eventing namespace, it will be ignored.

Prerequisites

  • An OpenShift Container Platform account with cluster administrator access
  • Installed OpenShift Serverless Operator

5.3.1.1. Creating the knative-eventing namespace using the web console

Procedure

  1. In the OpenShift Container Platform web console, navigate to AdministrationNamespaces.
  2. Click Create Namespace.

    Namespaces page
  3. Enter knative-eventing as the Name for the project. The other fields are optional.

    Creating the `knative-eventing` namespace
  4. Click Create.

5.3.1.2. Creating the knative-eventing namespace using the CLI

Procedure

  1. Create the knative-eventing namespace by entering:

    $ oc create namespace knative-eventing

5.3.2. Prerequisites

  • An OpenShift Container Platform account with cluster administrator access
  • Installed OpenShift Serverless Operator
  • Created the knative-eventing namespace

5.3.3. Installing Knative Eventing using the web console

Procedure

  1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to OperatorsInstalled Operators.
  2. Check that the Project dropdown at the top of the page is set to Project: knative-eventing.
  3. Click Knative Eventing in the list of Provided APIs for the OpenShift Serverless Operator to go to the Knative Eventing tab.

    Installed Operators page
  4. Click the Create Knative Eventing button.

    Knative Eventing tab
  5. In the Create Knative Eventing page, you can choose to configure the KnativeEventing object by using either the default form provided, or by editing the YAML.

    • Using the form is recommended for simpler configurations that do not require full control of KnativeEventing object creation.

      Optional. If you are configuring the KnativeEventing object using the form, make any changes that you want to implement for your Knative Eventing deployment.

  6. Click Create.

    Create Knative Eventing using the form
    • Editing the YAML is recommended for more complex configurations that require full control of KnativeEventing object creation. You can access the YAML by clicking the edit YAML link in the top right of the Create Knative Eventing page.

      Optional. If you are configuring the KnativeEventing object by editing the YAML, make any changes to the YAML that you want to implement for your Knative Eventing deployment.

  7. Click Create.

    Create Knative Eventing using YAML
  8. After you have installed Knative Eventing, the KnativeEventing object is created, and you will be automically directed to the Knative Eventing tab.

    Installed Operators page

    You will see knative-eventing in the list of resources.

Verification steps

  1. Click on knative-eventing in the Knative Eventing tab.
  2. You will be automatically directed to the Knative Eventing Overview page.

    Knative Eventing Overview page
  3. Scroll down to look at the list of Conditions.
  4. You should see a list of conditions with a status of True, as shown in the example image.

    Conditions
    Note

    It may take a few seconds for the Knative Eventing resources to be created. You can check their status in the Resources tab.

  5. If the conditions have a status of Unknown or False, wait a few moments and then check again after you have confirmed that the resources have been created.

5.3.4. Installing Knative Eventing using YAML

Procedure

  1. Create a file named eventing.yaml.
  2. Copy the following sample YAML into eventing.yaml:

    apiVersion: operator.knative.dev/v1alpha1
    kind: KnativeEventing
    metadata:
        name: knative-eventing
        namespace: knative-eventing
  3. Optional. Make any changes to the YAML that you want to implement for your Knative Eventing deployment.
  4. Apply the eventing.yaml file by entering:

    $ oc apply -f eventing.yaml

Verification steps

  1. To verify the installation is complete, enter:

    $ oc get knativeeventing.operator.knative.dev/knative-eventing \
      -n knative-eventing \
      --template='{{range .status.conditions}}{{printf "%s=%s\n" .type .status}}{{end}}'

    The output should be similar to:

    InstallSucceeded=True
    Ready=True
    Note

    It may take a few seconds for the Knative Eventing resources to be created.

  2. If the conditions have a status of Unknown or False, wait a few moments and then check again after you have confirmed that the resources have been created.
  3. Check that the Knative Eventing resources have been created by entering:

    $ oc get pods -n knative-eventing

    The output should look similar to:

    NAME                                   READY   STATUS    RESTARTS   AGE
    broker-controller-58765d9d49-g9zp6     1/1     Running   0          7m21s
    eventing-controller-65fdd66b54-jw7bh   1/1     Running   0          7m31s
    eventing-webhook-57fd74b5bd-kvhlz      1/1     Running   0          7m31s
    imc-controller-5b75d458fc-ptvm2        1/1     Running   0          7m19s
    imc-dispatcher-64f6d5fccb-kkc4c        1/1     Running   0          7m18s

5.3.5. Next steps

  • For services and serving functionality on OpenShift Serverless, you can install the Knative Serving component. See the documentation on Installing Knative Serving.
  • Install the Knative CLI to use kn commands with Knative Eventing. For example, kn source commands. See the documentation on Installing the Knative CLI (kn).

5.4. Advanced installation configuration options

This guide provides information for cluster administrators about advanced installation configuration options for OpenShift Serverless components.

5.4.1. Knative Serving supported installation configuration options

This guide provides information for cluster administrators about advanced installation configuration options for Knative Serving.

Important

Do not modify any YAML contained inside the config field. Some of the configuration values in this field are injected by the OpenShift Serverless Operator, and modifying them will cause your deployment to become unsupported.

Create Knative Serving form in web console Administrator Perspective

5.4.1.1. Controller Custom Certs

If your registry uses a self-signed certificate, you must enable tag-to-digest resolution by creating a ConfigMap or Secret. The OpenShift Serverless Operator then automatically configures Knative Serving controller access to the registry.

To enable tag-to-digest resolution, the Knative Serving controller requires access to the container registry.

Important

The ConfigMap or Secret must reside in the same namespace as the Knative Serving CustomResourceDefinition (CRD).

The following example triggers the OpenShift Serverless Operator to:

  1. Create and mount a volume containing the certificate in the controller.
  2. Set the required environment variable properly.

Example YAML

apiVersion: operator.knative.dev/v1alpha1
kind: KnativeServing
metadata:
  name: knative-serving
  namespace: knative-serving
spec:
  controller-custom-certs:
    name: certs
    type: ConfigMap

The following example uses a certificate in a ConfigMap named certs in the knative-serving namespace.

The supported types are ConfigMap and Secret.

If no controller custom cert is specified, this defaults to the config-service-ca ConfigMap.

Example default YAML

spec:
  controller-custom-certs:
    name: config-service-ca
    type: ConfigMap

5.4.1.2. High availability

High availability (HA) defaults to 2 replicas per controller if no number of replicas is specified.

You can set this to 1 to disable HA, or add more replicas by setting a higher integer.

Example YAML

spec:
  high-availability:
    replicas: 2

5.4.2. Additional resources

5.5. Upgrading OpenShift Serverless

If you installed a previous version of OpenShift Serverless, follow the instructions in this guide to upgrade to the latest version.

Important

Before upgrading to the latest Serverless release, you must remove the community Knative Eventing operator if you have previously installed it. Having the Knative Eventing operator installed will prevent you from being able to install the latest Technology Preview version of Knative Eventing.

5.5.1. Updating Knative services URL formats

When upgrading from older versions of OpenShift Serverless to 1.7.0, support for HTTPS requires a change to the format of routes. Knative services created on OpenShift Serverless 1.6.0 or older versions are no longer reachable at the old format URLs. You must retrieve the new URL for each service after upgrading OpenShift Serverless.

For more information on retrieving Knative services URLs, see Verifying your serverless application deployment.

5.5.2. Upgrading the Subscription Channel

To upgrade to the latest version of OpenShift Serverless on OpenShift Container Platform 4.4, you must update the channel to 4.4.

If you are upgrading from OpenShift Serverless version 1.5.0, or earlier, to version 1.7.0, you must complete the following steps:

  • Upgrade to OpenShift Serverless version 1.5.0, by selecting the techpreview channel.
  • After you have upgraded to 1.5.0, upgrade to 1.6.0 by selecting the preview-4.3 channel.
  • Finally, after you have upgraded to 1.6.0, upgrade to the latest version by selecting the 4.4 channel.
Important

After each channel change, wait for the pods in the knative-serving namespace to get upgraded before changing the channel again.

Prerequisites

  • You have installed a previous version of OpenShift Serverless Operator, and have selected Automatic updates during the installation process.

    Note

    If you have selected Manual updates, you will need to complete additional steps after updating the channel as described in this guide. The Subscription’s upgrade status will remain Upgrading until you review and approve its Install Plan. Information about the Install Plan can be found in the OpenShift Container Platform Operators documentation.

  • You have logged in to the OpenShift Container Platform web console.

Procedure

  1. Select the openshift-operators namespace in the OpenShift Container Platform web console.
  2. Navigate to the OperatorsInstalled Operators page.
  3. Select the OpenShift Serverless Operator Operator.
  4. Click SubscriptionChannel.
  5. In the Change Subscription Update Channel window, select 4.4, and then click Save.
  6. Wait until all pods have been upgraded in the knative-serving namespace and the KnativeServing custom resource reports the latest Knative Serving version.

Verification steps

To verify that the upgrade has been successful, you can check the status of pods in the knative-serving namespace, and the version of the KnativeServing CR.

  1. Check the status of the pods by entering the following command:

    $ oc get knativeserving.operator.knative.dev knative-serving -n knative-serving -o=jsonpath='{.status.conditions[?(@.type=="Ready")].status}'

    The previous command should return a status of True.

  2. Check the version of the KnativeServing CR by entering the following command:

    $ oc get knativeserving.operator.knative.dev knative-serving -n knative-serving -o=jsonpath='{.status.version}'

    The previous command should return the latest version of Knative Serving. You can check the latest version in the OpenShift Serverless Operator release notes.

5.6. Removing OpenShift Serverless

This guide provides details of how to remove the OpenShift Serverless Operator and other OpenShift Serverless components.

Note

Before you can remove the OpenShift Serverless Operator, you must remove Knative Serving and Knative Eventing.

5.6.1. Uninstalling Knative Serving

To uninstall Knative Serving, you must remove its custom resource and delete the knative-serving namespace.

Procedure

  1. To remove Knative Serving, enter the following command:

    $ oc delete knativeservings.operator.knative.dev knative-serving -n knative-serving
  2. After the command has completed and all pods have been removed from the knative-serving namespace, delete the namespace by entering the following command:

    $ oc delete namespace knative-serving

5.6.2. Uninstalling Knative Eventing

To uninstall Knative Eventing, you must remove its custom resource and delete the knative-eventing namespace.

Procedure

  1. To remove Knative Eventing, enter the following command:

    $ oc delete knativeeventings.operator.knative.dev knative-eventing -n knative-eventing
  2. After the command has completed and all pods have been removed from the knative-eventing namespace, delete the namespace by entering the following command:

    $ oc delete namespace knative-eventing

5.6.3. Removing the OpenShift Serverless Operator

You can remove the OpenShift Serverless Operator from the host cluster by following the documentation on deleting Operators from a cluster.

5.6.4. Deleting OpenShift Serverless CRDs

After uninstalling the OpenShift Serverless, the Operator and API CRDs remain on the cluster. You can use the following procedure to remove the remaining CRDs.

Important

Removing the Operator and API CRDs also removes all resources that were defined using them, including Knative services.

5.6.5. Prerequisites

  • You uninstalled Knative Serving and removed the OpenShift Serverless Operator.

Procedure

  1. To delete the remaining OpenShift Serverless CRDs, enter the following command:

    $ oc get crd -oname | grep 'knative.dev' | xargs oc delete

5.7. Installing the Knative CLI (kn)

Note

kn does not have its own login mechanism. To log in to the cluster, you must install the oc CLI and use oc login.

Installation options for the oc CLI will vary depending on your operating system.

For more information on installing the oc CLI for your operating system and logging in with oc, see the CLI getting started documentation.

5.7.1. Installing the kn CLI using the OpenShift Container Platform web console

Once the OpenShift Serverless Operator is installed, you will see a link to download the kn CLI for Linux, macOS and Windows from the Command Line Tools page in the OpenShift Container Platform web console.

You can access the Command Line Tools page by clicking the question circle icon in the top right corner of the web console and selecting Command Line Tools in the drop down menu.

Procedure

  1. Download the kn CLI from the Command Line Tools page.
  2. Unpack the archive:

    $ tar -xf <file>
  3. Move the kn binary to a directory on your PATH.
  4. To check your path, run:

    $ echo $PATH
    Note

    If you do not use RHEL or Fedora, ensure that libc is installed in a directory on your library path. If libc is not available, you might see the following error when you run CLI commands:

    $ kn: No such file or directory

5.7.2. Installing the kn CLI for Linux using an RPM

For Red Hat Enterprise Linux (RHEL), you can install kn as an RPM if you have an active OpenShift Container Platform subscription on your Red Hat account.

Procedure

  • Use the following command to install kn:
# subscription-manager register
# subscription-manager refresh
# subscription-manager attach --pool=<pool_id> 1
# subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-x86_64-rpms"
# yum install openshift-serverless-clients
1
Pool ID for an active OpenShift Container Platform subscription

5.7.3. Installing the kn CLI for Linux

For Linux distributions, you can download the CLI directly as a tar.gz archive.

Procedure

  1. Download the CLI.
  2. Unpack the archive:

    $ tar -xf <file>
  3. Move the kn binary to a directory on your PATH.
  4. To check your path, run:

    $ echo $PATH
    Note

    If you do not use RHEL or Fedora, ensure that libc is installed in a directory on your library path. If libc is not available, you might see the following error when you run CLI commands:

    $ kn: No such file or directory

5.7.4. Installing the kn CLI for macOS

kn for macOS is provided as a tar.gz archive.

Procedure

  1. Download the CLI.
  2. Unpack and unzip the archive.
  3. Move the kn binary to a directory on your PATH.
  4. To check your PATH, open a terminal window and run:

    $ echo $PATH

5.7.5. Installing the kn CLI for Windows

The CLI for Windows is provided as a zip archive.

Procedure

  1. Download the CLI.
  2. Unzip the archive with a ZIP program.
  3. Move the kn binary to a directory on your PATH.
  4. To check your PATH, open the Command Prompt and run the command:

    C:\> path