Merge pull request #37123 from abrennan89/SRVKS-820

abrennan89 · web-flow · commit d6ec4a279eea · 2021-10-20T09:46:35.000-05:00
SRVKS-812 + SRVKS-813 + SRVKS-820: Update domainmapping docs and add deprecation notes
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -3193,6 +3193,18 @@ Topics:
     # HA
   - Name: High availability on OpenShift Serverless
     File: serverless-ha
+# Security
+- Name: Security
+  Dir: security
+  Topics:
+  - Name: Configuring JSON Web Token authentication for Knative services
+    File: serverless-ossm-with-kourier-jwt
+  - Name: Configuring a custom domain for a Knative service
+    File: serverless-custom-domains
+  - Name: Configuring TLS for a custom domain using Kourier
+    File: serverless-ossm-tls-with-kourier
+  - Name: Using a custom TLS certificate for domain mapping
+    File: serverless-custom-tls-cert-domain-mapping
 #
 # TODO: Add developer guide
 #
@@ -3216,14 +3228,6 @@ Topics:
   # Tracing
   - Name: Tracing requests using Jaeger
     File: serverless-tracing
-    # JWT using kourier
-  - Name: Configuring JSON Web Token authentication for Knative services
-    File: serverless-ossm-with-kourier-jwt
-    # Custom domains
-  - Name: Configuring a custom domain for a Knative service
-    File: serverless-custom-domains
-  - Name: Configuring TLS for a custom domain
-    File: serverless-ossm-tls-with-kourier
     # Routes
   - Name: Configuring routes for Knative services
     File: serverless-configuring-routes
diff --git a/modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc b/modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc
@@ -31,7 +31,8 @@ spec:
 ...
 ----
 <1> Add the `sidecar.istio.io/inject="true"` annotation.
-<2> Optional: Add the `sidecar.istio.io/rewriteAppHTTPProbers="true"` annotation if you have enabled JSON Web Token (JWT) authentication.
+<2> You must set the annotation `sidecar.istio.io/rewriteAppHTTPProbers: "true"` in your Knative service as {ServerlessProductName} versions 1.14.0 and higher use an HTTP probe as the readiness probe for Knative services by default.
+
 . Apply your `Service` resource YAML file:
 +
 [source,terminal]
diff --git a/modules/serverless-ossm-setup.adoc b/modules/serverless-ossm-setup.adoc
@@ -36,12 +36,14 @@ spec:
 ====
 This list of namespaces must include the `knative-serving` namespace.
 ====
+
 . Apply the `ServiceMeshMemberRoll` resource:
 +
 [source,terminal]
 ----
 $ oc apply -f <filename>
 ----
+
 . Create the necessary gateways so that {ProductShortName} can accept traffic:
 +
 .Example `knative-local-gateway` object using HTTP
@@ -123,12 +125,14 @@ spec:
         mode: SIMPLE
         credentialName: <wildcard_certs>
 ----
+
 . Apply the `Gateway` resources:
 +
 [source,terminal]
 ----
 $ oc apply -f <filename>
 ----
+
 . Install Knative Serving by creating the following `KnativeServing` custom resource definition (CRD), which also enables the Istio integration:
 +
 [source,yaml]
@@ -154,12 +158,14 @@ spec:
 ----
 <1> Enables Istio integration.
 <2> Enables sidecar injection for Knative Serving data plane pods.
+
 . Apply the `KnativeServing` resource:
 +
 [source,terminal]
 ----
 $ oc apply -f <filename>
 ----
+
 . Create a Knative Service that has sidecar injection enabled and uses a pass-through route:
 +
 [source,yaml]
@@ -184,6 +190,7 @@ spec:
 <1> A namespace that is part of the Service Mesh member roll.
 <2> Instructs Knative Serving to generate an {product-title} pass-through enabled route, so that the certificates you have generated are served through the ingress gateway directly.
 <3> Injects {ProductShortName} sidecars into the Knative service pods.
+
 . Apply the `Service` resource:
 +
 [source,terminal]
diff --git a/serverless/admin_guide/serverless-ossm-setup.adoc b/serverless/admin_guide/serverless-ossm-setup.adoc
@@ -28,7 +28,7 @@ To complete and verify these procedures in your deployment, you need either a ce
 
 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 on xref:../../serverless/knative_serving/serverless-custom-domains.adoc#serverless-create-domain-mapping_serverless-custom-domains[Creating a custom domain mapping].
+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/serverlesss-ossm-external-certs.adoc[leveloffset=+2]
 include::modules/serverless-ossm-setup.adoc[leveloffset=+2]
diff --git a/serverless/security/serverless-custom-domains.adoc b/serverless/security/serverless-custom-domains.adoc
@@ -9,16 +9,8 @@ toc::[]
 
 Knative services are automatically assigned a default domain name based on your cluster configuration. For example, `<service_name>.<namespace>.example.com`.
 
-You can customize the domain for your Knative service by using one of the following methods:
+You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service, by creating a `DomainMapping` resource for the service. You can also create multiple `DomainMapping` resources to map multiple domains and subdomains to a single service.
 
-* Configure the service as a private service and create the required {ProductShortName} resources.
-+
-[IMPORTANT]
-====
-This method of configuring custom domains is only supported for clusters that have Kourier enabled. If you want to configure custom domains using only {ServerlessProductName} with {ProductShortName}, without Kourier enabled, use the `DomainMapping` resources method instead.
-====
-* Map a custom domain name that you own to a Knative service by creating a `DomainMapping` resource for the service. You can also create multiple `DomainMapping` resources to map multiple domains and subdomains to a single service.
-+
 [IMPORTANT]
 ====
 You can use `DomainMapping` resources to map custom domains either with or without Kourier enabled in your cluster, however TLS is not supported in clusters that have both Kourier and domain mapping enabled.
@@ -30,8 +22,24 @@ include::modules/serverless-create-domain-mapping-kn.adoc[leveloffset=+1]
 [id="serverless-custom-domains-private-services"]
 == Configuring custom domains for private Knative services
 
+:FeatureName: Configuring custom domains for private Knative services
+
+[IMPORTANT]
+====
+{FeatureName} is a deprecated feature. Deprecated functionality is still included in {product-title} and continues to be supported; however, it will be removed in a future release of this product and is not recommended for new deployments.
+
+Refer to xref:../../serverless/security/serverless-custom-domains.adoc#serverless-create-domain-mapping_serverless-custom-domains[Creating a custom domain mapping] for the latest documentation.
+====
+
+:!FeatureName:
+
 You can configure a custom domain for an existing Knative service by completing the following procedures.
 
+[IMPORTANT]
+====
+This method of configuring custom domains is only supported for clusters that have Kourier enabled. If you want to configure custom domains using only {ServerlessProductName} with {ProductShortName}, without Kourier enabled, use the `DomainMapping` resources method instead.
+====
+
 .Prerequisites
 
 * The {ServerlessOperatorName} and Knative Serving are installed on your {product-title} cluster.
diff --git a/serverless/security/serverless-custom-tls-cert-domain-mapping.adoc b/serverless/security/serverless-custom-tls-cert-domain-mapping.adoc
@@ -0,0 +1,71 @@
+include::modules/serverless-document-attributes.adoc[]
+include::modules/ossm-document-attributes.adoc[]
+[id="serverless-custom-tls-cert-domain-mapping"]
+= Using a custom TLS certificate for domain mapping
+:context: serverless-custom-tls-cert-domain-mapping
+include::modules/common-attributes.adoc[]
+
+toc::[]
+
+You can use an existing TLS certificate with a `DomainMapping` custom resource (CR) to secure the mapped service.
+
+.Prerequisites
+
+* You have completed the steps in xref:../../serverless/security/serverless-custom-domains.adoc#serverless-custom-domains[Configuring a custom domain for a Knative service], and have a working `DomainMapping` CR.
+
+* You have a TLS certificate from your Certificate Authority provider, or a self-signed certificate.
+
+* You have obtained the `cert` and `key` files from your Certificate Authority provider, or a self-signed certificate.
+
+.Procedure
+
+. Create a Kubernetes TLS secret:
++
+[source,terminal]
+----
+$ oc create secret tls <tls_secret_name> --cert=<path_to_certificate_file> --key=<path_to_key_file>
+----
+
+. Update the `DomainMapping` CR to use the TLS secret you have created:
++
+[source,yaml]
+----
+apiVersion: serving.knative.dev/v1alpha1
+kind: DomainMapping
+metadata:
+  name: <domain_name>
+  namespace: <namespace>
+spec:
+  ref:
+    name: <service_name>
+    kind: Service
+    apiVersion: serving.knative.dev/v1
+# TLS block specifies the secret to be used
+  tls:
+    secretName: <tls_secret_name>
+----
+
+.Verification
+
+. Verify that the `DomainMapping` CR status is `True`, and that the `URL` column of the output shows the mapped domain with the scheme `https`:
++
+[source,terminal]
+----
+$ oc get domainmapping <domain_name>
+----
++
+.Example output
+[source,terminal]
+----
+NAME                      URL                               READY   REASON
+example.com               https://example.com               True
+----
+
+. Optional: If the service is exposed publicly, verify that it is available by running the following command:
++
+[source,terminal]
+----
+$ curl https://<domain_name>
+----
++
+If the certificate is self-signed, skip verification by adding the `-k` flag to the `curl` command.
diff --git a/serverless/security/serverless-ossm-tls-with-kourier.adoc b/serverless/security/serverless-ossm-tls-with-kourier.adoc
@@ -1,12 +1,18 @@
 include::modules/serverless-document-attributes.adoc[]
 include::modules/ossm-document-attributes.adoc[]
 [id="serverless-ossm-tls-with-kourier"]
-= Configuring Transport Layer Security for a custom domain using {ProductName} and Kourier
+= Configuring TLS for a custom domain using Kourier
 :context: serverless-ossm-tls
 include::modules/common-attributes.adoc[]
 
 toc::[]
 
+:FeatureName: Configuring TLS for a custom domain using Kourier
+
+include::modules/deprecated-feature.adoc[leveloffset=+1]
+
+:!FeatureName:
+
 You can create a Transport Layer Security (TLS) key and certificates for a custom domain and subdomain using {ProductName}.
 
 [IMPORTANT]
@@ -25,7 +31,7 @@ You can create a Transport Layer Security (TLS) key and certificates for a custo
 {ServerlessProductName} is compatible only with full implementations of either {ProductName} 1.x or 2.x. {ServerlessProductName} does not support custom usage of some 1.x resources and some 2.x resources in the same deployment. For example, upgrading to 2.x while still using the control plane `maistra.io/v1` spec is not supported.
 ====
 * Complete the configuration steps in xref:../../serverless/admin_guide/serverless-ossm-setup.adoc#serverless-ossm-setup-with-kourier_serverless-ossm-setup[Integrating {ProductShortName} and {ServerlessProductName} with Kourier enabled].
-* Configure a custom domain. See xref:../../serverless/knative_serving/serverless-custom-domains.adoc#serverless-custom-domains[Configuring a custom domain for a Knative service].
+* Configure a custom domain. See xref:../../serverless/security/serverless-custom-domains.adoc#serverless-custom-domains[Configuring a custom domain for a Knative service].
 * In this example, `openssl` is used to generate certificates, but you can use any certificate generation tool to create these.
 
 [IMPORTANT]
diff --git a/serverless/security/serverless-ossm-with-kourier-jwt.adoc b/serverless/security/serverless-ossm-with-kourier-jwt.adoc
@@ -9,11 +9,6 @@ toc::[]
 
 After the {ProductShortName} integration with {ServerlessProductName} and Kourier has been configured on your cluster, you can enable JSON Web Token (JWT) authentication for your Knative services.
 
-[IMPORTANT]
-====
-You must set the annotation `sidecar.istio.io/rewriteAppHTTPProbers: "true"` in your Knative service as {ServerlessProductName} versions 1.14.0 and higher use an HTTP probe as the readiness probe for Knative services by default.
-====
-
 include::modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc[leveloffset=+1]
 include::modules/serverless-ossm-v2x-jwt.adoc[leveloffset=+1]
 include::modules/serverless-ossm-v1x-jwt.adoc[leveloffset=+1]
