Merge pull request #40280 from abrennan89/SRVKS-552

SRVKS-552: Add information about serverless configuration options

Author: abrennan89

_topic_maps/_topic_map.yml

@@ -3163,31 +3163,16 @@ Topics:
     File: serverless-autoscaling-scale-bounds
   - Name: Concurrency
     File: serverless-autoscaling-concurrency
-# administer
-- Name: Monitor
-  Dir: monitor
-  Topics:
-  # logging
-  - Name: Cluster logging with OpenShift Serverless
-    File: cluster-logging-serverless
-  # Tracing
-  - Name: Tracing requests using Jaeger
-    File: serverless-tracing
-  # Metrics
-  - Name: Metrics
-    File: serverless-serving-metrics
-  # monitoring services
-  - Name: Monitoring Knative services
-    File: serverless-service-monitoring
-  - Name: Autoscaling dashboard
-    File: serverless-autoscaling-dashboard
-# Support
-- Name: Support
-  File: serverless-support
+  - Name: Traffic management
+    File: serverless-traffic-management
+  - Name: Routing
+    File: serverless-configuring-routes
 # Admin guide
-- Name: Administration guide
+- Name: Administer
   Dir: admin_guide
   Topics:
+  - Name: Configuring OpenShift Serverless
+    File: serverless-configuration
     # Ingress options
   - Name: Integrating Service Mesh with OpenShift Serverless
     File: serverless-ossm-setup
@@ -3211,6 +3196,26 @@ Topics:
     # HA
   - Name: High availability on OpenShift Serverless
     File: serverless-ha
+- Name: Monitor
+  Dir: monitor
+  Topics:
+  # logging
+  - Name: Cluster logging with OpenShift Serverless
+    File: cluster-logging-serverless
+  # Tracing
+  - Name: Tracing requests using Jaeger
+    File: serverless-tracing
+  # Metrics
+  - Name: Metrics
+    File: serverless-serving-metrics
+  # monitoring services
+  - Name: Monitoring Knative services
+    File: serverless-service-monitoring
+  - Name: Autoscaling dashboard
+    File: serverless-autoscaling-dashboard
+# Support
+- Name: Support
+  File: serverless-support
 # Security
 - Name: Security
   Dir: security
@@ -3221,16 +3226,6 @@ Topics:
     File: serverless-custom-domains
   - Name: Using a custom TLS certificate for domain mapping
     File: serverless-custom-tls-cert-domain-mapping
-# Knative Serving
-- Name: Knative Serving
-  Dir: knative_serving
-  Topics:
-    # Knative services
-  - Name: Traffic management
-    File: serverless-traffic-management
-    # Routes
-  - Name: Configuring routes for Knative services
-    File: serverless-configuring-routes
 # Knative Eventing
 - Name: Knative Eventing
   Dir: knative_eventing

modules/knative-serving-advanced-config.adoc

@@ -5,13 +5,10 @@
 [id="knative-serving-advanced-config_{context}"]
 = Knative Serving advanced configuration options
 
-[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.
-====
+This section provides information about advanced configuration options for Knative Serving.
 
 [id="knative-serving-controller-custom-certs_{context}"]
-== Controller Custom Certs
+== Controller custom certs
 
 If your registry uses a self-signed certificate, you must enable tag-to-digest resolution by creating a config map or secret.
 To enable tag-to-digest resolution, the Knative Serving controller requires access to the container registry.

serverless/admin_guide/serverless-configuration.adoc

@@ -0,0 +1,58 @@
+include::modules/serverless-document-attributes.adoc[]
+[id="serverless-configuration"]
+= Configuring {ServerlessProductName}
+include::modules/common-attributes.adoc[]
+: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].
+
+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.
+
+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:
+
+```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:
+
+```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.

serverless/knative_serving/serverless-configuring-routes.adoc renamed to serverless/develop/serverless-configuring-routes.adoc

@@ -1,6 +1,6 @@
 include::modules/serverless-document-attributes.adoc[]
 [id="serverless-configuring-routes"]
-= Configuring routes for Knative services
+= Routing
 :context: serverless-configuring-routes
 include::modules/common-attributes.adoc[]