Merge pull request #47036 from abrennan89/SRVKS-900

[SRVKS-926] Improvements for ingress docs; add secret filtering docs

Author: abrennan89

modules/serverless-domain-mapping-custom-tls-cert.adoc

@@ -27,6 +27,20 @@ After you have configured a custom domain for a Knative service, you can use a T
 $ oc create secret tls <tls_secret_name> --cert=<path_to_certificate_file> --key=<path_to_key_file>
 ----
 
+. If you are using {SMProductName} as the ingress for your {ServerlessProductName} installation, label the Kubernetes TLS secret with the following:
++
+[source,yaml]
+----
+“networking.internal.knative.dev/certificate-uid": “<value>”
+----
++
+If you are using a third-party secret provider such as cert-manager, you can configure your secret manager to label the Kubernetes TLS secret automatically. Cert-manager users can use the secret template offered to automatically generate secrets with the correct label. In this case, secret filtering is done based on the key only, but this value can carry useful information such as the certificate ID that the secret contains.
++
+[NOTE]
+====
+The {cert-manager-operator} is a Technology Preview feature. For more information, see the *Installing the {cert-manager-operator}* documentation.
+====
+
 . Update the `DomainMapping` CR to use the TLS secret that you have created:
 +
 [source,yaml]

modules/serverless-ossm-secret-filtering.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// * /serverless/admin_guide/serverless-ossm-setup.adoc
+
+:_content-type: PROCEDURE
+[id="serverless-ossm-secret-filtering_{context}"]
+= Improving memory usage by using secret filtering for {SMProductShortName}
+
+By default, the link:https://aly.arriqaaq.com/kubernetes-informers/[informers] implementation for the Kubernetes `client-go` library fetches all resources of a particular type. This can lead to a substantial overhead when many resources are available, which can cause the Knative `net-istio` ingress controller to fail on large clusters due to memory leaking. However, a filtering mechanism is available for the Knative `net-istio` ingress controller, which enables the controller to only fetch Knative related secrets. You can enable this mechanism by adding an annotation to the `KnativeServing` custom resource (CR).
+
+.Prerequisites
+
+ifdef::openshift-enterprise[]
+* You have access to an {product-title} account with cluster administrator access.
+endif::[]
+
+ifdef::openshift-dedicated,openshift-rosa[]
+* You have access to an {product-title} account with cluster or dedicated administrator access.
+endif::[]
+
+* You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
+* Install {SMProductName}. {ServerlessProductName} with {SMProductShortName} only is supported for use with {SMProductName} version 2.0.5 or later.
+* Install the {ServerlessOperatorName} and Knative Serving.
+* Install the OpenShift CLI (`oc`).
+
+.Procedure
+
+* Add the `serverless.openshift.io/enable-secret-informer-filtering` annotation to the `KnativeServing` CR:
++
+.Example KnativeServing CR
+[source,yaml]
+----
+apiVersion: operator.knative.dev/v1alpha1
+kind: KnativeServing
+metadata:
+  name: knative-serving
+  namespace: knative-serving
+  annotations:
+    serverless.openshift.io/enable-secret-informer-filtering: "true" <1>
+spec:
+  ingress:
+    istio:
+      enabled: true
+  deployments:
+    - annotations:
+        sidecar.istio.io/inject: "true"
+        sidecar.istio.io/rewriteAppHTTPProbers: "true"
+      name: activator
+    - annotations:
+        sidecar.istio.io/inject: "true"
+        sidecar.istio.io/rewriteAppHTTPProbers: "true"
+      name: autoscaler
+----
+<1> Adding this annotation injects an enviroment variable, `ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID=true`, to the `net-istio` controller pod.

modules/serverless-ossm-setup-with-kourier.adoc

@@ -6,6 +6,8 @@
 [id="serverless-ossm-setup-with-kourier_{context}"]
 = Integrating {SMProductShortName} with {ServerlessProductName} when Kourier is enabled
 
+You can use {SMProductShortName} with {ServerlessProductName} even if Kourier is already enabled. This procedure might be useful if you have already installed Knative Serving with Kourier enabled, but decide to add a {SMProductShortName} integration later.
+
 .Prerequisites
 
 ifdef::openshift-enterprise[]
@@ -16,10 +18,10 @@ ifdef::openshift-dedicated,openshift-rosa[]
 * You have access to an {product-title} account with cluster or dedicated administrator access.
 endif::[]
 
-* Install the OpenShift CLI (`oc`).
 * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
-* You have installed the {ServerlessOperatorName} and Knative Serving on your cluster.
-* You have installed {SMProductName}. {ServerlessProductName} with {SMProductShortName} and Kourier is supported for use with both {SMProductName} versions 1.x and 2.x.
+* Install the OpenShift CLI (`oc`).
+* Install the {ServerlessOperatorName} and Knative Serving on your cluster.
+* Install {SMProductName}. {ServerlessProductName} with {SMProductShortName} and Kourier is supported for use with both {SMProductName} versions 1.x and 2.x.
 
 .Procedure
 

modules/serverless-ossm-setup.adoc

@@ -6,12 +6,10 @@
 [id="serverless-ossm-setup_{context}"]
 = Integrating {SMProductShortName} with {ServerlessProductName}
 
-You can integrate {SMProductShortName} with {ServerlessProductName} without using Kourier by completing the following procedure.
+You can integrate {SMProductShortName} with {ServerlessProductName} without using Kourier as the default ingress. To do this, do not install the Knative Serving component before completing the following procedure. There are additional steps required when creating the `KnativeServing` custom resource defintion (CRD) to integrate Knative Serving with {SMProductShortName}, which are not covered in the general Knative Serving installation procedure. This procedure might be useful if you want to integrate {SMProductShortName} as the default and only ingress for your {ServerlessProductName} installation.
 
 .Prerequisites
 
-* You have installed {SMProductName}. {ServerlessProductName} with {SMProductShortName} only is supported for use with {SMProductName} version 2.0.5 or higher.
-
 ifdef::openshift-enterprise[]
 * You have access to an {product-title} account with cluster administrator access.
 endif::[]
@@ -20,14 +18,10 @@ ifdef::openshift-dedicated,openshift-rosa[]
 * You have access to an {product-title} account with cluster or dedicated administrator access.
 endif::[]
 
-* You have installed the {ServerlessOperatorName}.
-+
-[IMPORTANT]
-====
-Do not install the Knative Serving component before completing the following procedures. There are additional steps required when creating the `KnativeServing` custom resource defintion (CRD) to integrate Knative Serving with {SMProductShortName}, which are not covered in the general Knative Serving installation procedure of the _Administration guide_.
-====
-* Install the OpenShift CLI (`oc`).
 * You have created a project or have access to a project with the appropriate roles and permissions to create applications and other workloads in {product-title}.
+* Install {SMProductName}. {ServerlessProductName} with {SMProductShortName} only is supported for use with {SMProductName} version 2.0.5 or later.
+* Install the {ServerlessOperatorName}.
+* Install the OpenShift CLI (`oc`).
 
 .Procedure
 

serverless/admin_guide/serverless-ossm-setup.adoc

@@ -6,32 +6,28 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Using {SMProductShortName} with {ServerlessProductName} enables developers to configure additional networking and routing options.
-
-The {ServerlessOperatorName} provides Kourier as the default ingress for Knative. However, you can use {SMProductShortName} with {ServerlessProductName} whether Kourier is enabled or not. Integrating with Kourier disabled allows you to configure additional networking and routing options that the Kourier ingress does not support.
+The {ServerlessOperatorName} provides Kourier as the default ingress for Knative. However, you can use {SMProductShortName} with {ServerlessProductName} whether Kourier is enabled or not. Integrating with Kourier disabled allows you to configure additional networking and routing options that the Kourier ingress does not support, such as mTLS functionality.
 
 [IMPORTANT]
 ====
 {ServerlessProductName} only supports the use of {SMProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features.
 ====
 
-// without kourier
-[id="serverless-ossm-setup-native"]
-== Integrating {SMProductShortName} with {ServerlessProductName} natively
-
-Integrating {SMProductShortName} with {ServerlessProductName} natively, without Kourier, allows you to use additional networking and routing options that are not supported by the default Kourier ingress, such as mTLS functionality.
-
-The examples in the following procedures use the domain `example.com`. The example certificate for this domain is used as a certificate authority (CA) that signs the subdomain certificate.
+[id="prerequsites_serverless-ossm-setup"]
+== Prerequisites
 
+* The examples in the following procedures use the domain `example.com`. The example certificate for this domain is used as a certificate authority (CA) that signs the subdomain certificate.
++
 To complete and verify these procedures in your deployment, you need either a certificate signed by a widely trusted public CA or a CA provided by your organization. Example commands must be adjusted according to your domain, subdomain, and CA.
 
-You must configure the wildcard certificate to match the domain of your {product-title} cluster. For example, if your {product-title} console address is `https://console-openshift-console.apps.openshift.example.com`, you must configure the wildcard certificate so that the domain is `*.apps.openshift.example.com`. For more information about configuring wildcard certificates, see the following topic about _Creating a certificate to encrypt incoming external traffic_.
-
-If you want to use any domain name, including those which are not subdomains of the default {product-title} cluster domain, you must set up domain mapping for those domains. For more information, see the {ServerlessProductName} documentation about xref:../../serverless/security/serverless-custom-domains.adoc#serverless-create-domain-mapping_serverless-custom-domains[Creating a custom domain mapping].
+* You must configure the wildcard certificate to match the domain of your {product-title} cluster. For example, if your {product-title} console address is `https://console-openshift-console.apps.openshift.example.com`, you must configure the wildcard certificate so that the domain is `*.apps.openshift.example.com`. For more information about configuring wildcard certificates, see the following topic about _Creating a certificate to encrypt incoming external traffic_.
 
-include::modules/serverless-ossm-external-certs.adoc[leveloffset=+2]
-include::modules/serverless-ossm-setup.adoc[leveloffset=+2]
-include::modules/serverless-ossm-enabling-serving-metrics.adoc[leveloffset=+2]
+* If you want to use any domain name, including those which are not subdomains of the default {product-title} cluster domain, you must set up domain mapping for those domains. For more information, see the {ServerlessProductName} documentation about xref:../../serverless/security/serverless-custom-domains.adoc#serverless-create-domain-mapping_serverless-custom-domains[Creating a custom domain mapping].
 
+include::modules/serverless-ossm-external-certs.adoc[leveloffset=+1]
+// without kourier
+include::modules/serverless-ossm-setup.adoc[leveloffset=+1]
+include::modules/serverless-ossm-enabling-serving-metrics.adoc[leveloffset=+1]
 // With kourier
 include::modules/serverless-ossm-setup-with-kourier.adoc[leveloffset=+1]
+include::modules/serverless-ossm-secret-filtering.adoc[leveloffset=+1]