Skip to content

Commit a950bec

Browse files
rh-maxrh-max
committed
Add Serving transport encryption docs
1 parent 5323620 commit a950bec

14 files changed

+541
-73
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -132,8 +132,6 @@ Topics:
132132
File: init-containers
133133
- Name: Resolving image tags to digests
134134
File: resolving-image-tags-to-digests
135-
- Name: Configuring TLS authentication
136-
File: serverless-config-tls
137135
- Name: Configuring Kourier
138136
File: configuring-kourier
139137
- Name: Restrictive network policies
@@ -142,6 +140,8 @@ Topics:
142140
File: debugging-serverless-applications
143141
- Name: Kourier and Istio ingresses
144142
File: kourier-and-istio-ingresses
143+
- Name: Serving transport encryption
144+
File: serving-transport-encryption
145145
- Name: Traffic splitting
146146
Dir: traffic-splitting
147147
Topics:

‎about/serverless-release-notes.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ include::modules/serverless-rn-1-25-0.adoc[leveloffset=+1]
8383
8484
[role="_additional-resources"]
8585
.Additional resources for {ocp-product-title}
86-
* xref:../knative-serving/config-applications/serverless-config-tls.adoc#serverless-config-tls[Configuring TLS authentication]
86+
* xref:../knative-serving/serving-transport-encryption.adoc#serving-transport-encryption-setting-up[Serving transport encryption]
8787
8888
include::modules/serverless-rn-1-24-0.adoc[leveloffset=+1]
8989
include::modules/serverless-rn-1-23-0.adoc[leveloffset=+1]

‎knative-serving/config-applications/serverless-config-tls.adoc

Lines changed: 0 additions & 26 deletions
This file was deleted.

‎knative-serving/serving-transport-encryption.adoc

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
include::_attributes/common-attributes.adoc[]
3+
[id="serving-transport-encryption"]
4+
= Serving transport encryption
5+
:context: serving-transport-encryption
6+
7+
toc::[]
8+
9+
You can enable {ServerlessProductName} Serving transport encryption to allow transporting data over secured and encrypted HTTPS connections using TLS.
10+
11+
:FeatureName: {ServerlessProductName} Serving transport encryption
12+
include::snippets/technology-preview.adoc[leveloffset=+2]
13+
14+
[IMPORTANT]
15+
====
16+
Serving Transport Encryption is only available for Kourier as an ingress layer. For {SMProductName}, use the service mesh mTLS capabilities to ensure encrypted traffic.
17+
====
18+
19+
include::modules/serving-transport-encryption-overview.adoc[leveloffset=+1]
20+
include::modules/serving-transport-encryption-choice-of-a-certificate-issuer.adoc[leveloffset=+1]
21+
22+
[id="serving-transport-encryption-setting-up_{context}"]
23+
== Setting up OpenShift Serverless transport encryption
24+
25+
.Prerequisites
26+
27+
* You have access to an {ocp-product-title} account with cluster administrator access.
28+
* Install the {oc-first}.
29+
* Install the {cert-manager-operator}.
30+
* Install the {ServerlessOperatorName}.
31+
32+
[IMPORTANT]
33+
====
34+
If you install the {ServerlessOperatorName} before installing the {cert-manager-operator}, you must restart the controller and activator deployments in the `knative-serving` namespace. Failure to restart these deployments prevents Knative from creating the necessary `cert-manager` resources, which results in pending Knative Services and prevents enabling the Knative Serving `cert-manager` integration.
35+
====
36+
37+
include::modules/serving-transport-encryption-configuring-selfsigned-clusterissuer.adoc[leveloffset=+2]
38+
include::modules/serving-transport-encryption-creating-a-clusterissuer-to-be-used-by-serving.adoc[leveloffset=+2]
39+
include::modules/serving-transport-encryption-configuring.adoc[leveloffset=+2]
40+
41+
include::modules/serving-transport-encryption-trust-configuration.adoc[leveloffset=+1]
42+
include::modules/serving-transport-encryption-ensuring-seamless-ca-rotation.adoc[leveloffset=+1]
43+
include::modules/serving-transport-encryption-verifying.adoc[leveloffset=+1]

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ $ oc create secret tls <tls_secret_name> --cert=<path_to_certificate_file> --key
3535
$ oc label secret <tls_secret_name> networking.internal.knative.dev/certificate-uid="<id>"
3636
----
3737
+
38-
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+
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.
3939
+
4040
[NOTE]
4141
====

‎modules/serverless-enabling-tls-internal-traffic.adoc

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎modules/serving-transport-encryption-choice-of-a-certificate-issuer.adoc

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * knative-serving/serving-transport-encryption.adoc
4+
:_mod-docs-content-type: CONCEPT
5+
[id="serving-transport-encryption-choice-of-a-certificate-issuer_{context}"]
6+
= Choice of a certificate issuer
7+
8+
Issuers refer to `cert-manager` issuers and cluster issuers. They represent certificate authorities (CAs) that can generate signed certificates by honoring certificate signing requests. For more information, see link:https://cert-manager.io/docs/concepts/issuer/[cert-manager documentation on issuers].
9+
10+
Depending on the encryption features that you use, {ServerlessProductName} requires your certificate issuer to be able to sign certain certificates. To identify your certificate issuer, refer to the link:https://cert-manager.io/docs/configuration/issuers/[list of cert-manager integrations], which contains examples for the following:
11+
12+
* A custom CA stored in a Kubernetes secret
13+
* HTTP-01 challenges
14+
* DNS-01 challenges
15+
* Self-signed issuers
16+
17+
[id="serving-transport-encryption-compatible-certificate-issuers_{context}"]
18+
== Compatible certificate issuers
19+
20+
Not all issuer types work for each Knative Serving encryption feature.
21+
22+
* For cluster-local encryption, the issuer must be able to sign certificates for the following cluster-local domain types:
23+
+
24+
--
25+
** `myapp.<namespace>`
26+
** `myapp.<namespace>.svc`
27+
** `myapp.<namespace>.svc.cluster.local`
28+
--
29+
+
30+
As the CA usually is not within the cluster, verification using the Automated Certificate Management Environment (ACME) protocol (DNS01/HTTP01) is not possible. You can use an issuer that allows creating these certificates, such as the `cert-manager` CA issuer.
31+
32+
* For system-internal encryption, the issuer must be able to sign certificates with the following Subject Alternative Names (SANs):
33+
+
34+
--
35+
** `kn-routing`
36+
** names of format `kn-user-<namespace>`, where `<namespace>` is a namespace where Knative Services are created
37+
** `data-plane.knative.dev`
38+
--
39+
+
40+
Knative requires these SANs to verify connections between the internal components. Because this is not possible using the ACME protocol (DNS01/HTTP01), you must configure an issuer that allows creating these certificates, for example, `cert-manager` CA issuer.

‎modules/serving-transport-encryption-configuring-selfsigned-clusterissuer.adoc

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * knative-serving/serving-transport-encryption.adoc
4+
:_content-type: PROCEDURE
5+
[id="serving-transport-encryption-configuring-selfsigned-clusterissuer_{context}"]
6+
= Configuring a SelfSigned cluster issuer
7+
8+
The following procedure uses a `SelfSigned` issuer as the root certificate. For information about the implications and limitations of this method, see the link:https://cert-manager.io/docs/configuration/selfsigned/[SelfSigned cert-manager documentation].
9+
10+
If you manage your own company-specific Private Key Infrastructure (PKI), use the CA issuer. For more information, see link:https://cert-manager.io/docs/configuration/ca/[cert-manager documentation on CA issuers].
11+
12+
.Procedure
13+
14+
. Create a `SelfSigned` `ClusterIssuer` custom resource (CR):
15+
+
16+
.Example ClusterIssuer CR
17+
[source,yaml]
18+
----
19+
apiVersion: cert-manager.io/v1
20+
kind: ClusterIssuer
21+
metadata:
22+
name: knative-serving-selfsigned-issuer
23+
spec:
24+
selfSigned: {}
25+
----
26+
27+
. Apply the `ClusterIssuer` CR by running the following command:
28+
+
29+
[source,terminal]
30+
----
31+
$ oc apply -f <filename>
32+
----
33+
34+
. Create a root certificate that refers to the `ClusterIssuer` CR:
35+
+
36+
.Example root certificate
37+
[source,yaml]
38+
----
39+
apiVersion: cert-manager.io/v1
40+
kind: Certificate
41+
metadata:
42+
name: knative-serving-selfsigned-ca
43+
namespace: cert-manager <1>
44+
spec:
45+
secretName: knative-serving-ca <2>
46+
47+
isCA: true
48+
commonName: selfsigned-ca
49+
privateKey:
50+
algorithm: ECDSA
51+
size: 256
52+
53+
issuerRef:
54+
name: knative-serving-selfsigned-issuer
55+
kind: ClusterIssuer
56+
group: cert-manager.io
57+
----
58+
<1> The {cert-manager-operator} namespace, `cert-manager` by default.
59+
<2> Secret name later used for the `ClusterIssuer` CR for Knative Serving.
60+
61+
. Apply the `Certificate` CR by running the following command:
62+
+
63+
[source,terminal]
64+
----
65+
$ oc apply -f <filename>
66+
----
67+

‎modules/serving-transport-encryption-configuring.adoc

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * knative-serving/serving-transport-encryption.adoc
4+
:_content-type: PROCEDURE
5+
[id="serving-transport-encryption-configuring_{context}"]
6+
= Configuring transport encryption
7+
8+
Configuring transport encryption consists of two parts:
9+
10+
. Specifying the `ClusterIssuer` issuer to use:
11+
12+
** `clusterLocalIssuerRef`: issuer for cluster-local-domain certificates used for ingress.
13+
14+
** `systemInternalIssuerRef`: issuer for certificates for system-internal-tls certificates used by Knative internal components.
15+
16+
. Specifying transport encryption features to use:
17+
18+
** `cluster-local-domain-tls`: Enables the transport encryption feature for cluster-local domains
19+
20+
** `system-internal-tls`: Enables the transport encryption feature for OpenShift Serverless Serving internal components.
21+
22+
.Procedure
23+
24+
. Enable transport encryption in the `KnativeServing` resource:
25+
+
26+
[source,yaml]
27+
----
28+
apiVersion: operator.knative.dev/v1beta1
29+
kind: KnativeServing
30+
metadata:
31+
name: knative-serving
32+
namespace: knative-serving
33+
spec:
34+
...
35+
config:
36+
certmanager:
37+
clusterLocalIssuerRef: |
38+
kind: ClusterIssuer
39+
name: knative-serving-ca-issuer <1>
40+
systemInternalIssuerRef: |
41+
kind: ClusterIssuer
42+
name: knative-serving-ca-issuer <2>
43+
network:
44+
cluster-local-domain-tls: Enabled <3>
45+
system-internal-tls: Enabled <4>
46+
----
47+
<1> Define the cluster issuer for each feature. The same or individual cluster issuers can be used.
48+
<2> Define the cluster issuer.
49+
<3> Enable the `cluster-local-domain-tls` feature. This and other features can be enabled or disabled individually.
50+
<4> Enable the `system-internal-tls` feature.
51+
52+
. Apply the `KnativeServing` resource by running the following command:
53+
+
54+
[source,terminal]
55+
----
56+
$ oc apply -f <filename>
57+
----
58+
59+
. Optionally, change the `defaultCertificate` value in the Ingress Controller:
60+
+
61+
[source,yaml]
62+
----
63+
apiVersion: operator.openshift.io/v1
64+
kind: IngressController
65+
...
66+
spec:
67+
defaultCertificate:
68+
name: ca-ingress-cert
69+
----
70+
71+
. If you changed the `defaultCertificate` value, you must specify the custom certificate name in the `openshift-ingress-default-certificate` field in the `KnativeServing` custom resource.
72+
+
73+
For example, if the custom certificate name is `ca-ingress-cert`, add the following configuration:
74+
+
75+
[source,yaml]
76+
----
77+
...
78+
spec:
79+
config:
80+
network:
81+
system-internal-tls: Enabled
82+
openshift-ingress-default-certificate: "ca-ingress-cert"
83+
...
84+
----
85+
86+
. If you enabled `cluster-local-domain-tls` or `system-internal-tls`, restart the Controller component by running the following command.
87+
+
88+
[IMPORTANT]
89+
====
90+
When either the `cluster-local-domain-tls` or the `system-internal-tls` feature is enabled, you must restart the Controller component to enable the Knative Serving `cert-manager` integration.
91+
====
92+
+
93+
[source,terminal]
94+
----
95+
$ oc rollout restart deploy/controller -n knative-serving
96+
----
97+
98+
. If you enabled `system-internal-tls`, restart the Activator component by running the following command.
99+
+
100+
[IMPORTANT]
101+
====
102+
When the `system-internal-tls` feature is activated, you must restart the Activator component to reconfigure its internal web server, as this is not possible during runtime.
103+
====
104+
+
105+
[source,terminal]
106+
----
107+
$ oc rollout restart deploy/activator -n knative-serving
108+
----

0 commit comments

Comments
 (0)