SRVCOM-1728: Update abstracts and structure of global config docs for Jupiter guidelines

abrennan89 · abrennan89 · commit fc41ea7cbd8f · 2022-04-18T14:36:06.000-05:00
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -3443,23 +3443,16 @@ Topics:
 - Name: Administer
   Dir: admin_guide
   Topics:
-  - Name: Configuring OpenShift Serverless
+  - Name: Global configuration
     File: serverless-configuration
     # Eventing
-  - Name: Configuring Knative Eventing defaults
-    File: serverless-configuring-eventing-defaults
   - Name: Knative Kafka
     File: serverless-kafka-admin
   - Name: Creating Knative Eventing components in the Administrator perspective
     File: serverless-cluster-admin-eventing
-#  - Name: Configuring the Knative Eventing custom resource
-#    File: knative-eventing-CR-config
-# Uncomment once we add some configs to this section, adding now for consistency with Serving docs as a placeholder
     # Serving
   - Name: Creating Knative Serving components in the Administrator perspective
     File: serverless-cluster-admin-serving
-  - Name: Configuring the Knative Serving custom resource
-    File: knative-serving-CR-config
   - Name: Autoscaling
     File: serverless-admin-autoscaling
     # Ingress options
diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml
@@ -275,18 +275,14 @@ Topics:
 - Name: Administer
   Dir: admin_guide
   Topics:
-  - Name: Configuring OpenShift Serverless
+  - Name: Global configuration
     File: serverless-configuration
-  - Name: Configuring Knative Eventing defaults
-    File: serverless-configuring-eventing-defaults
   - Name: Knative Kafka
     File: serverless-kafka-admin
   - Name: Creating Knative Eventing components in the Administrator perspective
     File: serverless-cluster-admin-eventing
   - Name: Creating Knative Serving components in the Administrator perspective
     File: serverless-cluster-admin-serving
-  - Name: Configuring the Knative Serving custom resource
-    File: knative-serving-CR-config
   - Name: Autoscaling
     File: serverless-admin-autoscaling
   - Name: Integrating Service Mesh with OpenShift Serverless
diff --git a/modules/knative-serving-CR-system-deployments.adoc b/modules/knative-serving-CR-system-deployments.adoc
@@ -1,14 +1,12 @@
 // Module included in the following assemblies:
 //
-// * /serverless/admin_guide/knative-serving-CR-config.adoc
+// * serverless/admin_guide/serverless-configuration.adoc
 
 :_content-type: REFERENCE
 [id="knative-serving-CR-system-deployments_{context}"]
 = Overriding system deployment configurations
 
-You can override the default configurations for some specific deployments by modifying the `deployments` spec in the `KnativeServing` custom resource (CR).
-
-Currently, overriding default configuration settings for the `replicas`, `labels`, `annotations`, and `nodeSelector` fields are supported.
+You can override the default configurations for some specific deployments by modifying the `deployments` spec in the `KnativeServing` custom resource (CR). Currently, overriding default configuration settings is supported for the `replicas`, `labels`, `annotations`, and `nodeSelector` fields.
 
 In the following example, a `KnativeServing` CR overrides the `webhook` deployment so that:
 
diff --git a/modules/serverless-channel-default.adoc b/modules/serverless-channel-default.adoc
@@ -1,14 +1,12 @@
 // Module included in the following assemblies:
 //
-//  * serverless/admin_guide/serverless-configuring-eventing-defaults.adoc
+//  * serverless/admin_guide/serverless-configuration.adoc
 
 :_content-type: PROCEDURE
 [id="serverless-channel-default_{context}"]
 = Configuring the default channel implementation
 
-The `default-ch-webhook` config map can be used to specify the default channel implementation for the cluster or for one or more namespaces.
-
-You can make changes to the `knative-eventing` namespace config maps, including the `default-ch-webhook` config map, by using the {ServerlessOperatorName} to propagate changes. To do this, you must modify the `KnativeEventing` custom resource.
+The `default-ch-webhook` config map can be used to specify the default channel implementation of Knative Eventing. The default channel implementation can be specified for the entire cluster, as well as for one or more namespaces. Currently the `InMemoryChannel` and `KafkaChannel` channel types are supported.
 
 .Prerequisites
 
@@ -21,6 +19,7 @@ ifdef::openshift-dedicated[]
 endif::[]
 
 * You have installed the {ServerlessOperatorName} and Knative Eventing on your cluster.
+* If you want to use Kafka channels as the default channel implementation, you must also install the `KnativeKafka` CR on your cluster.
 
 .Procedure
 
diff --git a/modules/serverless-config-emptydir.adoc b/modules/serverless-config-emptydir.adoc
@@ -1,14 +1,15 @@
 // Module included in the following assemblies:
 //
-// * /serverless/admin_guide/knative-serving-CR-config.adoc
+// * serverless/admin_guide/serverless-configuration.adoc
 
 :_content-type: REFERENCE
 [id="serverless-config-emptydir_{context}"]
 = Configuring the EmptyDir extension
+// should probably be a procedure doc, but this is out of scope for the abstracts PR
 
-This extension controls whether `emptyDir` volumes can be specified.
+`emptyDir` volumes are empty volumes that are created when a pod is created, and are used to provide temporary working disk space. `emptyDir` volumes are deleted when the pod they were created for is deleted.
 
-To enable using `emptyDir` volumes, you must modify the `KnativeServing` custom resource (CR) to include the following YAML:
+The `"kubernetes.podspec-volumes-emptydir"` extension controls whether `emptyDir` volumes can be used with Knative Serving. To enable using `emptyDir` volumes, you must modify the `KnativeServing` custom resource (CR) to include the following YAML:
 
 [source,yaml]
 ----
diff --git a/modules/serverless-https-redirect-global.adoc b/modules/serverless-https-redirect-global.adoc
@@ -1,13 +1,14 @@
 // Module included in the following assemblies:
 //
-// * /serverless/admin_guide/knative-serving-CR-config.adoc
+// * serverless/admin_guide/serverless-configuration.adoc
 
 :_content-type: REFERENCE
 [id="serverless-https-redirect-global_{context}"]
 = HTTPS redirection global settings
 
-You can enable HTTPS redirection for all services on the cluster by configuring the `httpProtocol` spec for the `KnativeServing` custom resource, as shown in the following example:
+HTTPS redirection provides redirection for incoming HTTP requests. These redirected HTTP requests are encrypted. You can enable HTTPS redirection for all services on the cluster by configuring the `httpProtocol` spec for the `KnativeServing` custom resource (CR).
 
+.Example `KnativeServing` CR that enables HTTPS redirection
 [source,yaml]
 ----
 apiVersion: operator.knative.dev/v1alpha1
diff --git a/modules/serverless-kourier-gateway-service-type.adoc b/modules/serverless-kourier-gateway-service-type.adoc
@@ -1,12 +1,13 @@
 // Module included in the following assemblies
 //
-// * serverless/admin_guide/knative-serving-CR-config.adoc
+// * serverless/admin_guide/serverless-configuration.adoc
 
 :_content-type: REFERENCE
 [id="serverless-kourier-gateway-service-type_{context}"]
 = Setting the Kourier Gateway service type
+// should probably be a procedure but this is out of scope for the abstracts PR
 
-The default service type by which the Kourier Gateway is exposed is `ClusterIP`, and is determined by the `service-type` ingress spec in the `KnativeServing` custom resource (CR):
+The Kourier Gateway is exposed by default as the `ClusterIP` service type. This service type is determined by the `service-type` ingress spec in the `KnativeServing` custom resource (CR).
 
 .Default spec
 [source,yaml]
diff --git a/modules/serverless-url-scheme-external-routes.adoc b/modules/serverless-url-scheme-external-routes.adoc
@@ -1,12 +1,13 @@
 // Module included in the following assemblies
 //
-// * serverless/admin_guide/knative-serving-CR-config.adoc
+// * serverless/admin_guide/serverless-configuration.adoc
 
 :_content-type: REFERENCE
 [id="serverless-url-scheme-external-routes_{context}"]
 = Setting the URL scheme for external routes
+// should probably be a procedure, but this is out of scope for the abstracts PR
 
-The URL scheme of external routes defaults to HTTPS for enhanced security. This scheme is determined by the `default-external-scheme` key in the `KnativeServing` custom resource (CR) spec:
+The URL scheme of external routes defaults to HTTPS for enhanced security. This scheme is determined by the `default-external-scheme` key in the `KnativeServing` custom resource (CR) spec.
 
 .Default spec
 [source,yaml]
diff --git a/serverless/admin_guide/knative-eventing-CR-config.adoc b/serverless/admin_guide/knative-eventing-CR-config.adoc
diff --git a/serverless/admin_guide/knative-serving-CR-config.adoc b/serverless/admin_guide/knative-serving-CR-config.adoc
diff --git a/serverless/admin_guide/serverless-configuration.adoc b/serverless/admin_guide/serverless-configuration.adoc
@@ -1,60 +1,33 @@
 :_content-type: ASSEMBLY
 include::_attributes/common-attributes.adoc[]
 [id="serverless-configuration"]
-= Configuring {ServerlessProductName}
+= Global configuration
 :context: serverless-configuration
 
 toc::[]
 
-The {ServerlessOperatorName} manages the global configuration of a Knative installation, including propagating values from the `KnativeServing` and `KnativeEventing` custom resources to system link:https://kubernetes.io/docs/concepts/configuration/configmap/[config maps].
+The {ServerlessOperatorName} manages the global configuration of a Knative installation, including propagating values from the `KnativeServing` and `KnativeEventing` custom resources to system link:https://kubernetes.io/docs/concepts/configuration/configmap/[config maps]. Any updates to config maps which are applied manually are overwritten by the Operator. However, modifying the Knative custom resources allows you to set values for these config maps.
 
-Any updates to config maps which are applied manually are overwritten by the Operator. However, modifying the Knative custom resources allows you to set values for these config maps.
-
-Knative has multiple config maps that are named with the prefix `config-`.
-
-All Knative config maps are created in the same namespace as the custom resource that they apply to. For example, if the `KnativeServing` custom resource is created in the `knative-serving` namespace, all Knative Serving config maps are also created in this namespace.
+Knative has multiple config maps that are named with the prefix `config-`. All Knative config maps are created in the same namespace as the custom resource that they apply to. For example, if the `KnativeServing` custom resource is created in the `knative-serving` namespace, all Knative Serving config maps are also created in this namespace.
 
 The `spec.config` in the Knative custom resources have one `<name>` entry for each config map, named `config-<name>`, with a value which is be used for the config map `data`.
 
-.Examples of global configuration
-
-You can specify that the `KnativeServing` custom resource uses the `config-domain` config map  as follows:
-
-[source,yaml]
-----
-apiVersion: operator.knative.dev/v1alpha1
-kind: KnativeServing
-metadata:
-  name: knative-serving
-  namespace: knative-serving
-spec:
-  config:
-    domain: <1>
-      example.org: |
-        selector:
-          app: prod
-      example.com: ""
-----
-<1> Specifies the `config-domain` config map.
-
-You can apply values to multiple config maps. This example sets `stable-window` to 60s in the `config-autoscaler` config map, as well as specifying the `config-domain` config map:
-
-[source,yaml]
-----
-apiVersion: operator.knative.dev/v1alpha1
-kind: KnativeServing
-metadata:
-  name: knative-serving
-  namespace: knative-serving
-spec:
-  config:
-    domain: <1>
-      example.org: |
-        selector:
-          app: prod
-      example.com: ""
-    autoscaler: <2>
-      stable-window: "60s"
-----
-<1> Specifies the `config-domain` config map.
-<2> Specifies the `stable-window` setting in the `config-autoscaler` config map.
+// Knative Eventing
+include::modules/serverless-channel-default.adoc[leveloffset=+1]
+
+// Knative Serving
+include::modules/knative-serving-CR-system-deployments.adoc[leveloffset=+1]
+include::modules/serverless-config-emptydir.adoc[leveloffset=+1]
+// global https redirect
+include::modules/serverless-https-redirect-global.adoc[leveloffset=+1]
+// URL scheme for external routes
+include::modules/serverless-url-scheme-external-routes.adoc[leveloffset=+1]
+// Kourier Gateway service type
+include::modules/serverless-kourier-gateway-service-type.adoc[leveloffset=+1]
+
+ifdef::openshift-enterprise[]
+[id="additional-resources_knative-serving-CR-config"]
+[role="_additional-resources"]
+== Additional resources
+* xref:../../operators/understanding/crds/crd-managing-resources-from-crds.adoc[Managing resources from custom resource definitions]
+endif::[]
diff --git a/serverless/admin_guide/serverless-configuring-eventing-defaults.adoc b/serverless/admin_guide/serverless-configuring-eventing-defaults.adoc
diff --git a/serverless/discover/serverless-channels.adoc b/serverless/discover/serverless-channels.adoc
@@ -51,4 +51,4 @@ For more information about Kafka channels, see the xref:../../serverless/develop
 == Next steps
 
 * xref:../../serverless/develop/serverless-creating-channels.adoc#serverless-creating-channels[Create a channel] and a xref:../../serverless/develop/serverless-subs.adoc#serverless-subs[subscription] that allows event sinks to subscribe to channels and receive events.
-* If you are a cluster administrator, you can configure default settings for channels. See xref:../../serverless/admin_guide/serverless-configuring-eventing-defaults.adoc#serverless-channel-default_serverless-configuring-eventing-defaults[Configuring channel defaults].
+* If you are a cluster administrator, you can configure default settings for channels. See xref:../../serverless/admin_guide/serverless-configuration.adoc#serverless-channel-default_serverless-configuration[Configuring channel defaults].
