Chapter 3. Installing Serverless

Procedure

1. In the OpenShift Container Platform web console, navigate to the Operators OperatorHub page.
2. Scroll, or type the keyword Serverless into the Filter by keyword box to find the OpenShift Serverless Operator.
3. Review the information about the Operator and click Install.

4. On the Install Operator page:

   1. The Installation Mode is All namespaces on the cluster (default). This mode installs the Operator in the default openshift-serverless namespace to watch and be made available to all namespaces in the cluster.
   2. The Installed Namespace is openshift-serverless.
   3. Select the stable channel as the Update Channel. The stable channel will enable installation of the latest stable release of the OpenShift Serverless Operator.
   4. Select Automatic or Manual approval strategy.
5. Click Install to make the Operator available to the selected namespaces on this OpenShift Container Platform cluster.

6. From the Catalog Operator 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.

1. Switch to the Catalog Operator 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-serverless project on the Workloads Pods page that are reporting issues to troubleshoot further.

Procedure

1. Create a YAML file containing Namespace, OperatorGroup, and Subscription objects to subscribe a namespace to the OpenShift Serverless Operator. For example, create the file serverless-subscription.yaml with the following content:

   Example subscription

   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: openshift-serverless
   ---
   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
     name: serverless-operators
     namespace: openshift-serverless
   spec: {}
   ---
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: serverless-operator
     namespace: openshift-serverless
   spec:
     channel: stable 1
     name: serverless-operator 2
     source: redhat-operators 3
     sourceNamespace: openshift-marketplace 4

   1

   The channel name of the Operator. The stable channel enables installation of the most recent stable version of the OpenShift Serverless Operator.

   2

   The name of the Operator to subscribe to. For the OpenShift Serverless Operator, this is always serverless-operator.

   3

   The name of the CatalogSource that provides the Operator. Use redhat-operators for the default OperatorHub catalog sources.

   4

   The namespace of the CatalogSource. Use openshift-marketplace for the default OperatorHub catalog sources.

2. Create the Subscription object:

   $ oc apply -f serverless-subscription.yaml

Procedure

1. Download the Knative (kn) CLI from the Command Line Tools page. You can access the Command Line Tools page by clicking the icon in the top right corner of the web console and selecting Command Line Tools in the list.

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

Procedure

1. Register with Red Hat Subscription Manager:

   # subscription-manager register

2. Pull the latest subscription data:

   # subscription-manager refresh

3. Attach the subscription to the registered system:

   # subscription-manager attach --pool=<pool_id> 1

   1

   Pool ID for an active OpenShift Container Platform subscription

4. Enable the repositories required by the Knative (kn) CLI:

   • Linux (x86_64, amd64)

     # subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-x86_64-rpms"

   • Linux on IBM Z and LinuxONE (s390x)

     # subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-s390x-rpms"

   • Linux on IBM Power (ppc64le)

     # subscription-manager repos --enable="openshift-serverless-1-for-rhel-8-ppc64le-rpms"

5. Install the Knative (kn) CLI as an RPM by using a package manager:

   Example yum command

   # yum install openshift-serverless-clients

Procedure

1. Download the relevant Knative (kn) CLI tar.gz archive:

   • Linux (x86_64, amd64)
   • Linux on IBM Z and LinuxONE (s390x)
   • Linux on IBM Power (ppc64le)

   You can also download any version of kn by navigating to that version’s corresponding directory in the Serverless client download mirror.

2. Unpack the archive:

   $ tar -xf <filename>

3. Move the kn binary to a directory on your PATH.

4. To check your PATH, run:

   $ echo $PATH

Procedure

1. Download the Knative (kn) CLI tar.gz archive.

   You can also download any version of kn by navigating to that version’s corresponding directory in the Serverless client download mirror.

2. Unpack and extract 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

Procedure

1. Download the Knative (kn) CLI ZIP archive.

   You can also download any version of kn by navigating to that version’s corresponding directory in the Serverless client download mirror.

2. Extract 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

Procedure

1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to Operators Installed 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.
4. Click Create Knative Serving.

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.

6. After you have installed Knative Serving, the KnativeServing object is created, and you are automatically directed to the Knative Serving tab. You will see the knative-serving custom resource in the list of resources.

Verification

1. Click on knative-serving custom resource in the Knative Serving tab.

2. You will be automatically directed to the Knative Serving 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.

   
   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.

Procedure

1. Create a file named serving.yaml and copy the following example YAML into it:

   apiVersion: operator.knative.dev/v1beta1
   kind: KnativeServing
   metadata:
       name: knative-serving
       namespace: knative-serving

2. Apply the serving.yaml file:

   $ oc apply -f serving.yaml

Verification

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}}'

   Example output

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

   Note

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

   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.

2. Check that the Knative Serving resources have been created:

   $ oc get pods -n knative-serving

   Example output

   NAME                                                        READY   STATUS      RESTARTS   AGE
   activator-67ddf8c9d7-p7rm5                                  2/2     Running     0          4m
   activator-67ddf8c9d7-q84fz                                  2/2     Running     0          4m
   autoscaler-5d87bc6dbf-6nqc6                                 2/2     Running     0          3m59s
   autoscaler-5d87bc6dbf-h64rl                                 2/2     Running     0          3m59s
   autoscaler-hpa-77f85f5cc4-lrts7                             2/2     Running     0          3m57s
   autoscaler-hpa-77f85f5cc4-zx7hl                             2/2     Running     0          3m56s
   controller-5cfc7cb8db-nlccl                                 2/2     Running     0          3m50s
   controller-5cfc7cb8db-rmv7r                                 2/2     Running     0          3m18s
   domain-mapping-86d84bb6b4-r746m                             2/2     Running     0          3m58s
   domain-mapping-86d84bb6b4-v7nh8                             2/2     Running     0          3m58s
   domainmapping-webhook-769d679d45-bkcnj                      2/2     Running     0          3m58s
   domainmapping-webhook-769d679d45-fff68                      2/2     Running     0          3m58s
   storage-version-migration-serving-serving-0.26.0--1-6qlkb   0/1     Completed   0          3m56s
   webhook-5fb774f8d8-6bqrt                                    2/2     Running     0          3m57s
   webhook-5fb774f8d8-b8lt5                                    2/2     Running     0          3m57s

3. Check that the necessary networking components have been installed to the automatically created knative-serving-ingress namespace:

   $ oc get pods -n knative-serving-ingress

   Example output

   NAME                                      READY   STATUS    RESTARTS   AGE
   net-kourier-controller-7d4b6c5d95-62mkf   1/1     Running   0          76s
   net-kourier-controller-7d4b6c5d95-qmgm2   1/1     Running   0          76s
   3scale-kourier-gateway-6688b49568-987qz   1/1     Running   0          75s
   3scale-kourier-gateway-6688b49568-b5tnp   1/1     Running   0          75s

Procedure

1. In the Administrator perspective of the OpenShift Container Platform web console, navigate to Operators Installed 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.
4. Click Create Knative Eventing.

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.

   • 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.
8. After you have installed Knative Eventing, the KnativeEventing object is created, and you are automatically directed to the Knative Eventing tab. You will see the knative-eventing custom resource in the list of resources.

Verification

1. Click on the knative-eventing custom resource in the Knative Eventing tab.

2. You are automatically directed to the 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.

   
   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.

Procedure

1. Create a file named eventing.yaml.

2. Copy the following sample YAML into eventing.yaml:

   apiVersion: operator.knative.dev/v1beta1
   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

1. Verify the installation is complete by entering the following command and observing the output:

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

   Example output

   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

   Example output

   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

Procedure

1. In the Administrator perspective, navigate to Operators Installed Operators.
2. Check that the Project dropdown at the top of the page is set to Project: knative-eventing.
3. In the list of Provided APIs for the OpenShift Serverless Operator, find the Knative Kafka box and click Create Instance.

4. Configure the KnativeKafka object in the Create Knative Kafka page.

   Important

   To use the Kafka channel, source, broker, or sink on your cluster, you must toggle the enabled switch for the options you want to use to true. These switches are set to false by default. Additionally, to use the Kafka channel, broker, or sink you must specify the bootstrap servers.

   Example KnativeKafka custom resource

   apiVersion: operator.serverless.openshift.io/v1alpha1
   kind: KnativeKafka
   metadata:
       name: knative-kafka
       namespace: knative-eventing
   spec:
       channel:
           enabled: true 1
           bootstrapServers: <bootstrap_servers> 2
       source:
           enabled: true 3
       broker:
           enabled: true 4
           defaultConfig:
               bootstrapServers: <bootstrap_servers> 5
               numPartitions: <num_partitions> 6
               replicationFactor: <replication_factor> 7
       sink:
           enabled: true 8

   1

   Enables developers to use the KafkaChannel channel type in the cluster.

   2

   A comma-separated list of bootstrap servers from your AMQ Streams cluster.

   3

   Enables developers to use the KafkaSource event source type in the cluster.

   4

   Enables developers to use the Knative Kafka broker implementation in the cluster.

   5

   A comma-separated list of bootstrap servers from your Red Hat AMQ Streams cluster.

   6

   Defines the number of partitions of the Kafka topics, backed by the Broker objects. The default is 10.

   7

   Defines the replication factor of the Kafka topics, backed by the Broker objects. The default is 3.

   8

   Enables developers to use a Kafka sink in the cluster.

   Note

   The replicationFactor value must be less than or equal to the number of nodes of your Red Hat AMQ Streams cluster.

   1. Using the form is recommended for simpler configurations that do not require full control of KnativeKafka object creation.
   2. Editing the YAML is recommended for more complex configurations that require full control of KnativeKafka object creation. You can access the YAML by clicking the Edit YAML link in the top right of the Create Knative Kafka page.
5. Click Create after you have completed any of the optional configurations for Kafka. You are automatically directed to the Knative Kafka tab where knative-kafka is in the list of resources.

Verification

1. Click on the knative-kafka resource in the Knative Kafka tab. You are automatically directed to the Knative Kafka Overview page.

2. View the list of Conditions for the resource and confirm that they have a status of True.

   

   If the conditions have a status of Unknown or False, wait a few moments to refresh the page.

3. Check that the Knative Kafka resources have been created:

   $ oc get pods -n knative-eventing

   Example output

   NAME                                        READY   STATUS    RESTARTS   AGE
   kafka-broker-dispatcher-7769fbbcbb-xgffn    2/2     Running   0          44s
   kafka-broker-receiver-5fb56f7656-fhq8d      2/2     Running   0          44s
   kafka-channel-dispatcher-84fd6cb7f9-k2tjv   2/2     Running   0          44s
   kafka-channel-receiver-9b7f795d5-c76xr      2/2     Running   0          44s
   kafka-controller-6f95659bf6-trd6r           2/2     Running   0          44s
   kafka-source-dispatcher-6bf98bdfff-8bcsn    2/2     Running   0          44s
   kafka-webhook-eventing-68dc95d54b-825xs     2/2     Running   0          44s

Procedure

1. Start the Podman service that serves the Docker API on a UNIX socket at ${XDG_RUNTIME_DIR}/podman/podman.sock:

   $ systemctl start --user podman.socket

   Note

   On most systems, this socket is located at /run/user/$(id -u)/podman/podman.sock.

2. Establish the environment variable that is used to build a function:

   $ export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/podman/podman.sock"

3. Run the build command inside your function project directory with the -v flag to see verbose output. You should see a connection to your local UNIX socket:

   $ kn func build -v

Procedure

1. Create the Podman machine:

   $ podman machine init --memory=8192 --cpus=2 --disk-size=20

2. Start the Podman machine, which serves the Docker API on a UNIX socket:

   $ podman machine start
   Starting machine "podman-machine-default"
   Waiting for VM ...
   Mounting volume... /Users/myuser:/Users/user
   
   [...truncated output...]
   
   You can still connect Docker API clients by setting DOCKER_HOST using the
   following command in your terminal session:
   
   	export DOCKER_HOST='unix:///Users/myuser/.local/share/containers/podman/machine/podman-machine-default/podman.sock'
   
   Machine "podman-machine-default" started successfully

   Note

   On most macOS systems, this socket is located at /Users/myuser/.local/share/containers/podman/machine/podman-machine-default/podman.sock.

3. Establish the environment variable that is used to build a function:

   $ export DOCKER_HOST='unix:///Users/myuser/.local/share/containers/podman/machine/podman-machine-default/podman.sock'

4. Run the build command inside your function project directory with the -v flag to see verbose output. You should see a connection to your local UNIX socket:

   $ kn func build -v

Procedure

1. Identify the version of OpenShift Serverless Operator that was installed originally by searching in the OpenShift Serverless Release Notes.

   For example, the error message during attempted upgrade might contain the following string:

   The installed KnativeServing version is v1.5.0.

   In this example, the KnativeServing MAJOR.MINOR version is 1.5, which is covered in the release notes for OpenShift Serverless 1.26: OpenShift Serverless now uses Knative Serving 1.5.

2. Uninstall OpenShift Serverless Operator and all of its install plans.

3. Manually install the version of OpenShift Serverless Operator that you discovered in the first step. To install, first create a serverless-subscription.yaml file as shown in the following example:

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: serverless-operator
     namespace: openshift-serverless
   spec:
     channel: stable
     name: serverless-operator
     source: redhat-operators
     sourceNamespace: openshift-marketplace
     installPlanApproval: Manual
     startingCSV: serverless-operator.v1.26.0

4. Then, install the subscription by running the following command:

   $ oc apply -f serverless-subscription.yaml

5. Upgrade by manually approving the upgrade install plans as they appear.