Merge pull request #58234 from rh-max/srvls-secret-filtering

[SRVKS-947] Srvls secret filtering

Author: stevsmit

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

@@ -35,11 +35,11 @@ To work around this issue, enable mTLS by deploying `PeerAuthentication` instead
 $ 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:
+. Add the `networking.internal.knative.dev/certificate-uid: <id>`` label to the Kubernetes TLS secret:
 +
-[source,yaml]
+[source,terminal]
 ----
-“networking.internal.knative.dev/certificate-uid": “<value>”
+$ oc label secret <tls_secret_name> networking.internal.knative.dev/certificate-uid="<id>"
 ----
 +
 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.

modules/serverless-ossm-secret-filtering.adoc renamed to modules/serverless-ossm-secret-filtering-net-istio.adoc

@@ -3,11 +3,16 @@
 // * /serverless/integrations/serverless-ossm-setup.adoc
 
 :_content-type: PROCEDURE
-[id="serverless-ossm-secret-filtering_{context}"]
-= Improving memory usage by using secret filtering for {SMProductShortName}
+[id="serverless-ossm-secret-filtering-net-istio_{context}"]
+= Improving net-istio 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).
 
+[IMPORTANT]
+====
+If you enable secret filtering, all of your secrets need to be labeled with  `networking.internal.knative.dev/certificate-uid: "<id>"`. Otherwise, Knative Serving does not detect them, which leads to failures. You must label both new and existing secrets.
+====
+
 .Prerequisites
 
 ifdef::openshift-enterprise[]
@@ -52,3 +57,8 @@ spec:
       name: autoscaler
 ----
 <1> Adding this annotation injects an environment variable, `ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID=true`, to the `net-istio` controller pod.
++
+[NOTE]
+====
+This annotation is ignored if you set a different value by overriding deployments.
+====

modules/serverless-ossm-secret-filtering-net-kourier.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * /serverless/knative-serving/config-custom-domains/domain-mapping-custom-tls-cert.adoc
+
+:_content-type: PROCEDURE
+[id="serverless-ossm-secret-filtering-net-kourier_{context}"]
+= Improving net-kourier memory usage by using secret filtering
+
+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-kourier` ingress controller to fail on large clusters due to memory leaking. However, a filtering mechanism is available for the Knative `net-kourier` ingress controller, which enables the controller to only fetch Knative related secrets. You can enable this mechanism by setting an environment variable to the `KnativeServing` custom resource (CR).
+
+[IMPORTANT]
+====
+If you enable secret filtering, all of your secrets need to be labeled with  `networking.internal.knative.dev/certificate-uid: "<id>"`. Otherwise, Knative Serving does not detect them, which leads to failures. You must label both new and existing secrets.
+====
+
+.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::[]
+
+* A project that you created or that you have roles and permissions for to create applications and other workloads in {product-title}.
+* Install the {ServerlessOperatorName} and Knative Serving.
+* Install the OpenShift CLI (`oc`).
+
+.Procedure
+
+* Set the `ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID` variable to `true` for `net-kourier-controller` in the `KnativeServing` CR:
++
+.Example KnativeServing CR
+[source,yaml]
+----
+apiVersion: operator.knative.dev/v1beta1
+kind: KnativeServing
+metadata:
+ name: knative-serving
+ namespace: knative-serving
+spec:
+ deployments:
+   - env:
+     - container: controller
+       envVars:
+       - name: ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID
+         value: 'true'
+     name: net-kourier-controller
+----

modules/serverless-rn-1-28-0.adoc

@@ -38,7 +38,9 @@
 +
 With {ServerlessProductName} 1.28, the {ServerlessOperatorName} allows injecting the environment variable `ENABLE_SECRET_INFORMER_FILTERING_BY_CERT_UID` for both `net-istio` and `net-kourier`.
 +
-To prevent problems when upgrading from {ServerlessProductName} 1.28 to some future version, users must annotate their secrets with `networking.internal.knative.dev/certificate-uid:some_cuid`.
+If you enable secret filtering, all of your secrets need to be labeled with  `networking.internal.knative.dev/certificate-uid: "<id>"`. Otherwise, Knative Serving does not detect them, which leads to failures. You must label both new and existing secrets.
++
+In one of the following {ServerlessProductName} releases, secret filtering will become enabled by default. To prevent failures, label your secrets in advance.
 
 [id="known-issues-1-28-0_{context}"]
 == Known issues

serverless/integrations/serverless-ossm-setup.adoc

@@ -30,4 +30,4 @@ 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]
+include::modules/serverless-ossm-secret-filtering-net-istio.adoc[leveloffset=+1]

serverless/knative-serving/config-custom-domains/domain-mapping-custom-tls-cert.adoc

@@ -5,4 +5,4 @@ include::_attributes/common-attributes.adoc[]
 :context: domain-mapping-custom-tls-cert
 
 include::modules/serverless-domain-mapping-custom-tls-cert.adoc[leveloffset=+1]
-
+include::modules/serverless-ossm-secret-filtering-net-kourier.adoc[leveloffset=+1]