Skip to content

Commit afd5d85

Browse files
abrennan89abrennan89
committed
[SRVKS-900] Improvements for ingress docs; add secret filtering docs
1 parent 240db73 commit afd5d85

File tree

5 files changed

+89
-29
lines changed

5 files changed

+89
-29
lines changed

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,20 @@ After you have configured a custom domain for a Knative service, you can use a T
2727
$ oc create secret tls <tls_secret_name> --cert=<path_to_certificate_file> --key=<path_to_key_file>
2828
----
2929

30+
. If you are using {SMProductName} as the ingress for your {ServerlessProductName} installation, label the Kubernetes TLS secret with the following:
31+
+
32+
[source,yaml]
33+
----
34+
“networking.internal.knative.dev/certificate-uid": “<value>”
35+
----
36+
+
37+
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.
38+
+
39+
[NOTE]
40+
====
41+
The {cert-manager-operator} is a Technology Preview feature. For more information, see the *Installing the {cert-manager-operator}* documentation.
42+
====
43+
3044
. Update the `DomainMapping` CR to use the TLS secret that you have created:
3145
+
3246
[source,yaml]

‎modules/serverless-ossm-secret-filtering.adoc

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * /serverless/admin_guide/serverless-ossm-setup.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="serverless-ossm-secret-filtering_{context}"]
7+
= Improving memory usage by using secret filtering for {SMProductShortName}
8+
9+
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).
10+
11+
.Prerequisites
12+
13+
ifdef::openshift-enterprise[]
14+
* You have access to an {product-title} account with cluster administrator access.
15+
endif::[]
16+
17+
ifdef::openshift-dedicated,openshift-rosa[]
18+
* You have access to an {product-title} account with cluster or dedicated administrator access.
19+
endif::[]
20+
21+
* 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}.
22+
* Install {SMProductName}. {ServerlessProductName} with {SMProductShortName} only is supported for use with {SMProductName} version 2.0.5 or later.
23+
* Install the {ServerlessOperatorName} and Knative Serving.
24+
* Install the OpenShift CLI (`oc`).
25+
26+
.Procedure
27+
28+
* Add the `serverless.openshift.io/enable-secret-informer-filtering` annotation to the `KnativeServing` CR:
29+
+
30+
.Example KnativeServing CR
31+
[source,yaml]
32+
----
33+
apiVersion: operator.knative.dev/v1alpha1
34+
kind: KnativeServing
35+
metadata:
36+
name: knative-serving
37+
namespace: knative-serving
38+
annotations:
39+
serverless.openshift.io/enable-secret-informer-filtering: "true" <1>
40+
spec:
41+
ingress:
42+
istio:
43+
enabled: true
44+
deployments:
45+
- annotations:
46+
sidecar.istio.io/inject: "true"
47+
sidecar.istio.io/rewriteAppHTTPProbers: "true"
48+
name: activator
49+
- annotations:
50+
sidecar.istio.io/inject: "true"
51+
sidecar.istio.io/rewriteAppHTTPProbers: "true"
52+
name: autoscaler
53+
----
54+
<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

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
[id="serverless-ossm-setup-with-kourier_{context}"]
77
= Integrating {SMProductShortName} with {ServerlessProductName} when Kourier is enabled
88

9+
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.
10+
911
.Prerequisites
1012

1113
ifdef::openshift-enterprise[]
@@ -16,10 +18,10 @@ ifdef::openshift-dedicated,openshift-rosa[]
1618
* You have access to an {product-title} account with cluster or dedicated administrator access.
1719
endif::[]
1820

19-
* Install the OpenShift CLI (`oc`).
2021
* 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}.
21-
* You have installed the {ServerlessOperatorName} and Knative Serving on your cluster.
22-
* You have installed {SMProductName}. {ServerlessProductName} with {SMProductShortName} and Kourier is supported for use with both {SMProductName} versions 1.x and 2.x.
22+
* Install the OpenShift CLI (`oc`).
23+
* Install the {ServerlessOperatorName} and Knative Serving on your cluster.
24+
* Install {SMProductName}. {ServerlessProductName} with {SMProductShortName} and Kourier is supported for use with both {SMProductName} versions 1.x and 2.x.
2325
2426
.Procedure
2527

‎modules/serverless-ossm-setup.adoc

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,10 @@
66
[id="serverless-ossm-setup_{context}"]
77
= Integrating {SMProductShortName} with {ServerlessProductName}
88

9-
You can integrate {SMProductShortName} with {ServerlessProductName} without using Kourier by completing the following procedure.
9+
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.
1010

1111
.Prerequisites
1212

13-
* You have installed {SMProductName}. {ServerlessProductName} with {SMProductShortName} only is supported for use with {SMProductName} version 2.0.5 or higher.
14-
1513
ifdef::openshift-enterprise[]
1614
* You have access to an {product-title} account with cluster administrator access.
1715
endif::[]
@@ -20,14 +18,10 @@ ifdef::openshift-dedicated,openshift-rosa[]
2018
* You have access to an {product-title} account with cluster or dedicated administrator access.
2119
endif::[]
2220

23-
* You have installed the {ServerlessOperatorName}.
24-
+
25-
[IMPORTANT]
26-
====
27-
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_.
28-
====
29-
* Install the OpenShift CLI (`oc`).
3021
* 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}.
22+
* Install {SMProductName}. {ServerlessProductName} with {SMProductShortName} only is supported for use with {SMProductName} version 2.0.5 or later.
23+
* Install the {ServerlessOperatorName}.
24+
* Install the OpenShift CLI (`oc`).
3125
3226
.Procedure
3327

‎serverless/admin_guide/serverless-ossm-setup.adoc

Lines changed: 12 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,32 +6,28 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

9-
Using {SMProductShortName} with {ServerlessProductName} enables developers to configure additional networking and routing options.
10-
11-
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.
9+
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.
1210

1311
[IMPORTANT]
1412
====
1513
{ServerlessProductName} only supports the use of {SMProductName} functionality that is explicitly documented in this guide, and does not support other undocumented features.
1614
====
1715

18-
// without kourier
19-
[id="serverless-ossm-setup-native"]
20-
== Integrating {SMProductShortName} with {ServerlessProductName} natively
21-
22-
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.
23-
24-
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.
16+
[id="prerequsites_serverless-ossm-setup"]
17+
== Prerequisites
2518

19+
* 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.
20+
+
2621
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.
2722

28-
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_.
29-
30-
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].
23+
* 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_.
3124

32-
include::modules/serverless-ossm-external-certs.adoc[leveloffset=+2]
33-
include::modules/serverless-ossm-setup.adoc[leveloffset=+2]
34-
include::modules/serverless-ossm-enabling-serving-metrics.adoc[leveloffset=+2]
25+
* 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].
3526

27+
include::modules/serverless-ossm-external-certs.adoc[leveloffset=+1]
28+
// without kourier
29+
include::modules/serverless-ossm-setup.adoc[leveloffset=+1]
30+
include::modules/serverless-ossm-enabling-serving-metrics.adoc[leveloffset=+1]
3631
// With kourier
3732
include::modules/serverless-ossm-setup-with-kourier.adoc[leveloffset=+1]
33+
include::modules/serverless-ossm-secret-filtering.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)