Merge pull request #46348 from abrennan89/SRVKS-914-2

[SRVKS-914]: Update config structure and cert docs

Author: abrennan89

modules/knative-serving-advanced-config.adoc

@@ -0,0 +1,47 @@
+// Module included in the following assemblies
+//
+// * serverless/admin_guide/serverless-configuration.adoc
+
+:_content-type: PROCEDURE
+[id="knative-serving-controller-custom-certs-secrets_{context}"]
+= Configuring tag-to-digest resolution by using a secret
+
+If the `controller-custom-certs` spec uses the `Secret` type, the secret is mounted as a secret volume. Knative components consume the secret directly, assuming that the secret has the required certificates.
+
+.Prerequisites
+
+ifdef::openshift-enterprise[]
+* You have cluster administrator permissions on {product-title}.
+endif::[]
+
+ifdef::openshift-dedicated[]
+* You have cluster or dedicated administrator permissions on {product-title}.
+endif::[]
+
+* You have installed the {ServerlessOperatorName} and Knative Serving on your cluster.
+
+.Procedure
+
+. Create a secret:
++
+.Example command
+[source,yaml]
+----
+$ oc -n knative-serving create secret generic custom-secret --from-file=<secret_name>.crt=<path_to_certificate>
+----
+
+. Configure the `controller-custom-certs` spec in the `KnativeServing` custom resource (CR) to use the `Secret` type:
++
+.Example KnativeServing CR
+[source,yaml]
+----
+apiVersion: operator.knative.dev/v1alpha1
+kind: KnativeServing
+metadata:
+  name: knative-serving
+  namespace: knative-serving
+spec:
+  controller-custom-certs:
+    name: custom-secret
+    type: Secret
+----

modules/knative-serving-controller-custom-certs-secrets.adoc

@@ -0,0 +1,13 @@
+// Module included in the following assemblies
+//
+// * serverless/admin_guide/serverless-configuration.adoc
+
+:_content-type: CONCEPT
+[id="serverless-tag-to-digest-resolution_{context}"]
+= Tag-to-digest resolution
+
+If the Knative Serving controller has access to the container registry, Knative Serving resolves image tags to a digest when you create a revision of a service. This is known as _tag-to-digest resolution_, and helps to provide consistency for deployments.
+
+To give the controller access to the container registry on {product-title}, you must create a secret and then configure controller custom certificates. You can configure controller custom certificates by modifying the `controller-custom-certs` spec in the `KnativeServing` custom resource (CR). The secret must reside in the same namespace as the `KnativeServing` CR.
+
+If a secret is not included in the `KnativeServing` CR, this setting defaults to using public key infrastructure (PKI). When using PKI, the cluster-wide certificates are automatically injected into the Knative Serving controller by using the `config-service-sa` config map. The {ServerlessOperatorName} populates the `config-service-sa` config map with cluster-wide certificates and mounts the config map as a volume to the controller.

modules/serverless-tag-to-digest-resolution.adoc

@@ -30,11 +30,15 @@ include::modules/serverless-kourier-gateway-service-type.adoc[leveloffset=+1]
 include::modules/serverless-enabling-pvc-support.adoc[leveloffset=+1]
 // enable init containers
 include::modules/serverless-admin-init-containers.adoc[leveloffset=+1]
+// Tag to digest resolution
+include::modules/serverless-tag-to-digest-resolution.adoc[leveloffset=+1]
+include::modules/knative-serving-controller-custom-certs-secrets.adoc[leveloffset=+2]
 
 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]
 * xref:../../storage/understanding-persistent-storage.adoc#understanding-persistent-storage[Understanding persistent storage]
+* xref:../../networking/configuring-a-custom-pki.adoc[Configuring a custom PKI]
 endif::[]

serverless/admin_guide/serverless-configuration.adoc

@@ -6,14 +6,10 @@ include::_attributes/common-attributes.adoc[]
 
 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.
+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 readily available. This controller takes 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 or Eventing 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.
+HA in {ServerlessProductName} is available through leader election, which is enabled by default after the Knative Serving or Eventing 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 called the leader.
 
 [id="serverless-ha-configuring-replicas"]
 == Configuring high availability replicas on {ServerlessProductName}

serverless/admin_guide/serverless-ha.adoc

@@ -8,7 +8,7 @@ toc::[]
 
 To use event-driven architecture on your cluster, install Knative Eventing. You can create Knative components such as event sources, brokers, and channels and then use them to send events to applications or external systems.
 
-After you install the {ServerlessOperatorName}, install Knative Eventing by using the {product-title} web console. You can install Knative Eventing by using the default settings or configure more advanced settings in the `KnativeEventing` custom resource (CR).
+After you install the {ServerlessOperatorName}, you can install Knative Eventing by using the default settings, or configure more advanced settings in the `KnativeEventing` custom resource (CR). For more information about configuration options for the `KnativeEventing` CR, see xref:../../serverless/admin_guide/serverless-configuration.adoc#serverless-configuration[Global configuration].
 
 include::modules/serverless-install-eventing-web-console.adoc[leveloffset=+1]
 include::modules/serverless-install-eventing-yaml.adoc[leveloffset=+1]

serverless/install/installing-knative-eventing.adoc

@@ -8,11 +8,10 @@ toc::[]
 
 Installing Knative Serving allows you to create Knative services and functions on your cluster. It also allows you to use additional functionality such as autoscaling and networking options for your applications.
 
-After you install the {ServerlessOperatorName}, you can install Knative Serving by using the default settings, or configure more advanced settings in the `KnativeServing` custom resource (CR). For more information about configuration options for the `KnativeServing` CR, see xref:../../serverless/install/installing-knative-serving.adoc#knative-serving-advanced-config_installing-knative-serving[Advanced configuration options].
+After you install the {ServerlessOperatorName}, you can install Knative Serving by using the default settings, or configure more advanced settings in the `KnativeServing` custom resource (CR). For more information about configuration options for the `KnativeServing` CR, see xref:../../serverless/admin_guide/serverless-configuration.adoc#serverless-configuration[Global configuration].
 
 include::modules/serverless-install-serving-web-console.adoc[leveloffset=+1]
 include::modules/serverless-install-serving-yaml.adoc[leveloffset=+1]
-include::modules/knative-serving-advanced-config.adoc[leveloffset=+1]
 
 [id="next-steps_installing-knative-serving"]
 == Next steps