[enterprise-4.5] Add configuration options for Knative Serving creation via form

_topic_map.yml

@@ -1682,22 +1682,24 @@ Topics:
   Topics:
   - Name: Installing OpenShift Serverless
     File: installing-openshift-serverless
-  - Name: Upgrading OpenShift Serverless
-    File: upgrading-serverless
   - Name: Installing Knative Serving
     File: installing-knative-serving
   - Name: Installing Knative Eventing
     File: installing-knative-eventing
-  - Name: Installing the Knative CLI
-    File: installing-kn
+  - Name: Advanced installation configuration options
+    File: serverless-install-config-options
+  - Name: Upgrading the OpenShift Serverless Operator
+    File: upgrading-serverless
   - Name: Removing OpenShift Serverless
     File: removing-openshift-serverless
+  - Name: Installing the Knative CLI
+    File: installing-kn
 # Apps
 - Name: Creating and managing serverless applications
   File: serving-creating-managing-apps
 # HA
-- Name: Configuring high-availability components
-  File: serverless-config-HA
+- Name: High availability on OpenShift Serverless
+  File: serverless-HA
 - Name: Tracing requests
   File: serverless-tracing
 # Knative CLI

modules/serverless-config-replicas.adoc

@@ -0,0 +1,49 @@
+// Module is included in the following assemblies:
+//
+// serverless/serverless-HA.adoc
+
+[id="serverless-config-replicas_{context}"]
+= Configuring high availability replicas on {ServerlessProductName}
+
+High availability (HA) functionality is available by default on {ServerlessProductName} for the `autoscaler-hpa`, `controller`, `activator` , `kourier-control`, and `kourier-gateway` components. These components are configured with two replicas by default.
+
+You modify the number of replicas that are created per controller by changing the configuration of `KnativeServing.spec.highAvailability` in the KnativeServing custom resource definition.
+// This field also specifies the minimum number of _activators_ if you are using the Horizontal Pod Autoscaler (HPA). For more information about HPA, see
+
+.Prerequisites
+* An {product-title} account with cluster administrator access.
+* Installed the {ServerlessOperatorName} and Knative Serving.
+
+.Procedure
+
+. In the {product-title} web console *Administrator* perspective, navigate to *OperatorHub* -> *Installed Operators*.
++
+image::serving-installed-operator.png[Installed Operators page]
++
+. Select the `knative-serving` namespace.
++
+. Click *Knative Serving* in the list of *Provided APIs* for the {ServerlessOperatorName} to go to the *Knative Serving* tab.
++
+image::serving-tab-created.png[Knative Serving tab]
++
+. Click *knative-serving*, then go to the *YAML* tab in the *knative-serving* page.
++
+image::serving-YAML-HA.png[Knative Serving YAML]
++
+. Edit the custom resource definition YAML:
++
+.Example YAML
+[source,yaml]
+----
+spec:
+  high-availability:
+    replicas: 3
+----
++
+[IMPORTANT]
+====
+Do not modify any YAML contained inside the `config` field. Some of the configuration values in this field are injected by the {ServerlessOperatorName}, and modifying them will cause your deployment to become unsupported.
+====
++
+* The default `replicas` value is `2`.
+* Changing the value to `1` will disable HA, or you can increase the number of replicas as required. The example configuration shown specifies a replica count of `3` for all HA controllers.

modules/serverless-disable-HA.adoc

@@ -1,36 +0,0 @@
-// Module included in the following assemblies:
-//
-// * serverless/serverless-config-HA.adoc
-
-[id="serving-disabling-HA_{context}"]
-= Disabling high availability
-
-You can disable HA for Knative Serving components by changing the configuration of the `KnativeServing.spec.highAvailability` field.
-
-[IMPORTANT]
-====
-Do not modify any YAML contained inside the `config` field. Some of the configuration values in this field are injected by the {ServerlessOperatorName}, and modifying them will cause your deployment to become unsupported.
-====
-
-.Prerequisites
-* An {product-title} account with cluster administrator access.
-* Installed the {ServerlessOperatorName} and Knative Serving.
-
-.Procedure
-
-. In the {product-title} web console, navigate to the *Catalog* -> *OperatorHub* -> *Installed Operators* page.
-. Select the *{ServerlessOperatorName}*.
-. Click *Knative Serving* in the list of *Provided APIs* for the {ServerlessOperatorName} to go to the *Knative Serving* tab.
-+
-image::serverless-installed-operator.png[Installed Operators page]
-. Click on *knative-serving* in the *Knative Serving* tab.
-. Click on *YAML* in the *knative-serving* page.
-+
-image::serving-YAML-HA.png[Knative Serving YAML]
-. In the `spec` section of the YAML, update the `high-availability.replicas` field to `1`:
-+
-[source,yaml]
-----
-  high-availability:
-    replicas: 1
-----

modules/serverless-install-serving-web-console.adoc

@@ -14,21 +14,21 @@ image::serving-installed-operator.png[Installed Operators page]
 . Click the *Create Knative Serving* button.
 +
 image::serverless-create-serving.png[Knative Serving tab]
-. In the *Create Knative Serving* page, you can choose to configure the `KnativeServing` object by using either the default form provided, or by editing the YAML.
+. 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.
-+
-Optional. If you are configuring the `KnativeServing` object using the form, make any changes that you want to implement for your Knative Serving deployment.
-+
-After you complete the form, click *Create*.
-+
-image::serving-form-view.png[Create Knative Serving in Form View]
-+
 * 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.
 +
-Optional. If you are configuring the `KnativeServing` object by editing the YAML, make any changes to the YAML that you want to implement for your Knative Serving deployment.
+After you complete the form, or have finished modifying the YAML, click *Create*.
 +
-After you 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_.
+====
++
+image::serving-form-view.png[Create Knative Serving in Form View]
 +
 image::serverless-create-serving-yaml.png[Create Knative Serving in YAML view]
 . After you have installed Knative Serving, the `KnativeServing` object is created, and you will be automically directed to the *Knative Serving* tab.

serverless/installing_serverless/installing-knative-eventing.adoc

@@ -11,18 +11,20 @@ After you install the {ServerlessOperatorName}, you can install Knative Eventing
 :FeatureName: Knative Eventing
 include::modules/technology-preview.adoc[leveloffset=+1]
 
-// Create Eventing project + namespace
-include::modules/serverless-create-eventing-namespace.adoc[leveloffset=+1]
+This guide provides information about installing Knative Eventing using the default settings.
+// However, you can configure more advanced settings in the KnativeEventing custom resource definition.
 
-== Installing Knative Eventing
+// For more information about configuration options for the KnativeEventing custom resource definition, see xref:../installing_serverless/serverless-install-config-options.adoc#serverless-install-config-options[Advanced installation configuration options].
+
+include::modules/serverless-create-eventing-namespace.adoc[leveloffset=+1]
 
 .Prerequisites
 * An {product-title} account with cluster administrator access
 * Installed {ServerlessOperatorName}
 * Created the `knative-eventing` namespace
 
-include::modules/serverless-install-eventing-web-console.adoc[leveloffset=+2]
-include::modules/serverless-install-eventing-yaml.adoc[leveloffset=+2]
+include::modules/serverless-install-eventing-web-console.adoc[leveloffset=+1]
+include::modules/serverless-install-eventing-yaml.adoc[leveloffset=+1]
 
 == Next steps
 

serverless/installing_serverless/installing-knative-serving.adoc

@@ -8,18 +8,19 @@ toc::[]
 
 After you install the {ServerlessOperatorName}, you can install Knative Serving by following the procedures described in this guide.
 
-// Create Serving project + namespace
-include::modules/serverless-create-serving-namespace.adoc[leveloffset=+1]
+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.
 
-== Installing Knative Serving
+For more information about configuration options for the KnativeServing custom resource definition, see xref:../installing_serverless/serverless-install-config-options.adoc#serverless-install-config-options[Advanced installation configuration options].
+
+include::modules/serverless-create-serving-namespace.adoc[leveloffset=+1]
 
 .Prerequisites
 * An {product-title} account with cluster administrator access.
 * Installed {ServerlessOperatorName}.
 * Created the `knative-serving` namespace.
 
-include::modules/serverless-install-serving-web-console.adoc[leveloffset=+2]
-include::modules/serverless-install-serving-yaml.adoc[leveloffset=+2]
+include::modules/serverless-install-serving-web-console.adoc[leveloffset=+1]
+include::modules/serverless-install-serving-yaml.adoc[leveloffset=+1]
 
 == Next steps
 

serverless/installing_serverless/installing-openshift-serverless.adoc

@@ -46,11 +46,11 @@ The following limitations apply to all {ServerlessProductName} deployments:
 For more advanced use-cases such as logging or metering on {product-title}, 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 xref:../../serverless-config-HA.adoc#serverless-config-HA[Configuring High Availability components].
+HA is enabled for some Knative Serving components by default. You can disable HA by following the documentation on xref:../serverless-HA.adoc#serverless-HA[Configuring high availability replicas on {ServerlessProductName}].
 
 [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 that is included with {ServerlessProductName} 1.7.0.
+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 using the {ServerlessOperatorName}.
 ====
 
 include::modules/serverless-install-web-console.adoc[leveloffset=+1]

serverless/installing_serverless/serverless-install-config-options.adoc

@@ -0,0 +1,87 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-install-config-options"]
+= Advanced installation configuration options
+include::modules/common-attributes.adoc[]
+:context: serverless-install-config-options
+
+toc::[]
+
+This guide provides information for cluster administrators about advanced installation configuration options for Knative Serving and Knative Eventing.
+
+The YAML configuration is shown by default when you are creating the Knative Serving or Knative Eventing custom resource definitions. However, you can access the form view by selecting *Edit Form* in the top right corner of the *Create Knative Serving* or *Create Knative Eventing* pages.
+
+[IMPORTANT]
+====
+Do not modify any YAML contained inside the `config` field. Some of the configuration values in this field are injected by the {ServerlessOperatorName}, and modifying them will cause your deployment to become unsupported.
+====
+
+== Knative Serving supported installation configuration options
+
+image::serving-form-view.png[Create Knative Serving form]
+
+=== 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 {ServerlessOperatorName} 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 custom resource definition.
+====
+
+The following example triggers the {ServerlessOperatorName} to:
+
+. Create and mount a volume containing the certificate in the controller.
+. Set the required environment variable properly.
+
+.Example YAML
+[source,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.
+
+You can also configure controller custom certs using the form view.
+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
+[source,yaml]
+----
+spec:
+  controller-custom-certs:
+    name: config-service-ca
+    type: ConfigMap
+----
+
+=== 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.
+
+For more information about configuring HA, see xref:../serverless-HA.adoc#serverless-HA[High availability on {ServerlessProductName}].
+
+.Example YAML
+[source,yaml]
+----
+spec:
+  high-availability:
+    replicas: 2
+----
+
+// == Knative Eventing supported installation configuration options
+
+// image::eventing-form-view.png[Create Knative Eventing form]

serverless/serverless-HA.adoc

@@ -0,0 +1,18 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-HA"]
+= High availability on {ServerlessProductName}
+include::modules/common-attributes.adoc[]
+:context: serverless-HA
+
+toc::[]
+
+High availability (HA) is a standard feature of Kubernetes APIs that helps to ensure that APIs stay operational if a disruption occurs.
+In an HA deployment, if an active controller crashes or is deleted, another controller is available to take over processing of the APIs that were being serviced by the controller that is now unavailable.
+
+HA in {ServerlessProductName} is available through leader election, which is enabled by default after the Knative Serving control plane is installed.
+
+When using a leader election HA pattern, instances of controllers are already scheduled and running inside the cluster before they are required.
+These controller instances compete to use a shared resource, known as the leader election lock.
+The instance of the controller that has access to the leader election lock resource at any given time is referred to as the leader.
+
+include::modules/serverless-config-replicas.adoc[leveloffset=+1]

serverless/serverless-config-HA.adoc

@@ -1,25 +0,0 @@
-include::modules/serverless-document-attributes.adoc[]
-[id="serverless-config-HA"]
-= High availability in {ServerlessProductName}
-include::modules/common-attributes.adoc[]
-:context: serverless-config-HA
-
-toc::[]
-
-Active/passive high availability (HA) is a standard feature of Kubernetes APIs that helps to ensure that APIs stay operational if a disruption occurs.
-In an HA deployment, if an active controller crashes or is deleted, another controller is available to take over processing of the APIs that were being serviced by the controller that is now unavailable.
-
-Active/passive HA in {ServerlessProductName} is available through leader election, which is enabled by default after the Knative Serving control plane is installed.
-
-When using a leader election HA pattern, instances of controllers are already scheduled and running inside the cluster before they are required.
-These controller instances compete to use a shared resource, known as the leader election lock.
-The instance of the controller that has access to the leader election lock resource at any given time is referred to as the leader.
-
-[id="serverless-ha_{context}"]
-== Configuring high-availability {ServerlessProductName} components
-
-This guide provides information about which components of {ServerlessProductName} are configured as high availability (HA) by default, and how you can modify HA settings.
-
-HA functionality is available by default on {ServerlessProductName} for the `autoscaler-hpa`, `controller`, `activator` , `kourier-control`, and `kourier-gateway` components. These components are configured with two replicas by default.
-
-include::modules/serverless-disable-HA.adoc[leveloffset=+2]

serverless/serverless-getting-started.adoc

@@ -26,3 +26,7 @@ include::modules/serverless-components.adoc[leveloffset=+1]
 
 :FeatureName: Knative Eventing
 include::modules/technology-preview.adoc[leveloffset=+2]
+
+== Next steps
+* Install the xref:../serverless/installing_serverless/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessOperatorName}] on your {product-title} cluster to get started with serverless applications.
+* View the xref:../serverless/serverless-release-notes.adoc#serverless-release-notes[{ServerlessProductName} release notes].