Merge pull request #47635 from abrennan89/securityabstracts

abrennan89 · web-flow · commit e9a16177ce40 · 2022-07-18T10:35:56.000-05:00
[SRVCOM-1832]: Update abstracts for Jupiter requirements
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -3508,8 +3508,6 @@ Topics:
     File: serverless-ossm-with-kourier-jwt
   - Name: Configuring a custom domain for a Knative service
     File: serverless-custom-domains
-  - Name: Using a custom TLS certificate for domain mapping
-    File: serverless-custom-tls-cert-domain-mapping
 # Functions
 - Name: Functions
   Dir: functions
diff --git a/_topic_maps/_topic_map_osd.yml b/_topic_maps/_topic_map_osd.yml
@@ -311,8 +311,6 @@ Topics:
     File: serverless-ossm-with-kourier-jwt
   - Name: Configuring a custom domain for a Knative service
     File: serverless-custom-domains
-  - Name: Using a custom TLS certificate for domain mapping
-    File: serverless-custom-tls-cert-domain-mapping
 - Name: Functions
   Dir: functions
   Topics:
diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml
@@ -422,8 +422,6 @@ Topics:
     File: serverless-ossm-with-kourier-jwt
   - Name: Configuring a custom domain for a Knative service
     File: serverless-custom-domains
-  - Name: Using a custom TLS certificate for domain mapping
-    File: serverless-custom-tls-cert-domain-mapping
 - Name: Functions
   Dir: functions
   Topics:
diff --git a/modules/serverless-create-domain-mapping-kn.adoc b/modules/serverless-create-domain-mapping-kn.adoc
@@ -7,11 +7,7 @@
 [id="serverless-create-domain-mapping-kn_{context}"]
 = Creating a custom domain mapping by using the Knative CLI
 
-You can use the `kn` CLI to create a `DomainMapping` custom resource (CR) that maps to an Addressable target CR, such as a Knative service or a Knative route.
-
-The `--ref` flag specifies an Addressable target CR for domain mapping.
-
-If a prefix is not provided when using the `--ref` flag, it is assumed that the target is a Knative service in the current namespace. The examples in the following procedure show the prefixes for mapping to a Knative service or a Knative route.
+You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service. You can use the Knative (`kn`) CLI to create a `DomainMapping` custom resource (CR) that maps to an Addressable target CR, such as a Knative service or a Knative route.
 
 .Prerequisites
 
@@ -39,6 +35,10 @@ $ kn domain create <domain_mapping_name> --ref <target_name>
 ----
 $ kn domain create example.com --ref example-service
 ----
++
+The `--ref` flag specifies an Addressable target CR for domain mapping.
++
+If a prefix is not provided when using the `--ref` flag, it is assumed that the target is a Knative service in the current namespace.
 
 * Map a domain to a Knative service in a specified namespace:
 +
diff --git a/modules/serverless-create-domain-mapping.adoc b/modules/serverless-create-domain-mapping.adoc
@@ -6,7 +6,7 @@
 [id="serverless-create-domain-mapping_{context}"]
 = Creating a custom domain mapping
 
-To map a custom domain name to a custom resource (CR), you must create a `DomainMapping` CR that maps to an Addressable target CR, such as a Knative service or a Knative route.
+You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service. To map a custom domain name to a custom resource (CR), you must create a `DomainMapping` CR that maps to an Addressable target CR, such as a Knative service or a Knative route.
 
 .Prerequisites
 
diff --git a/modules/serverless-domain-mapping-custom-tls-cert.adoc b/modules/serverless-domain-mapping-custom-tls-cert.adoc
@@ -1,12 +1,12 @@
 // Module included in the following assemblies:
 //
-// * serverless/security/serverless-custom-tls-cert-domain-mapping.adoc
+// * serverless/security/serverless-custom-domains.adoc
 
 :_content-type: PROCEDURE
 [id="serverless-domain-mapping-custom-tls-cert_{context}"]
-= Adding a custom TLS certificate to a DomainMapping CR
+= Securing a service with a custom domain by using a TLS certificate
 
-You can add an existing TLS certificate with a `DomainMapping` custom resource (CR) to secure the mapped service.
+After you have configured a custom domain for a Knative service, you can use a TLS certificate to secure the mapped service. To do this, you must create a Kubernetes TLS secret, and then update the `DomainMapping` CR to use the TLS secret that you have created.
 
 .Prerequisites
 
@@ -27,7 +27,7 @@ You can add an existing TLS certificate with a `DomainMapping` custom resource (
 $ 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:
+. Update the `DomainMapping` CR to use the TLS secret that you have created:
 +
 [source,yaml]
 ----
diff --git a/modules/serverless-domain-mapping-odc-admin.adoc b/modules/serverless-domain-mapping-odc-admin.adoc
@@ -6,6 +6,8 @@
 [id="serverless-domain-mapping-odc-admin_{context}"]
 = Mapping a custom domain to a service by using the Administrator perspective
 
+include::snippets/serverless-domain-mapping.adoc[]
+
 ifdef::openshift-enterprise[]
 If you have cluster administrator permissions, you can create a `DomainMapping` custom resource (CR) by using the *Administrator* perspective in the {product-title} web console.
 endif::[]
diff --git a/modules/serverless-domain-mapping-odc-developer.adoc b/modules/serverless-domain-mapping-odc-developer.adoc
@@ -6,7 +6,7 @@
 [id="serverless-domain-mapping-odc-developer_{context}"]
 = Mapping a custom domain to a service by using the Developer perspective
 
-You can use the *Developer* perspective of the {product-title} web console to map a `DomainMapping` custom resource (CR) to a Knative service.
+You can customize the domain for your Knative service by mapping a custom domain name that you own to a Knative service. You can use the *Developer* perspective of the {product-title} web console to map a `DomainMapping` custom resource (CR) to a Knative service.
 
 .Prerequisites
 
diff --git a/modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc b/modules/serverless-ossm-enable-sidecar-injection-with-kourier.adoc
diff --git a/modules/serverless-ossm-v1x-jwt.adoc b/modules/serverless-ossm-v1x-jwt.adoc
@@ -6,16 +6,52 @@
 [id="serverless-ossm-v1x-jwt_{context}"]
 = Using JSON Web Token authentication with {SMProductShortName} 1.x and {ServerlessProductName}
 
-You can use the following procedure to enable using JSON Web Token authentication with {SMProductShortName} 1.x and {ServerlessProductName}.
+You can use JSON Web Token (JWT) authentication with Knative services by using {SMProductShortName} 1.x and {ServerlessProductName}. To do this, you must create a policy in the application namespace that is a member of the `ServiceMeshMemberRoll` object. You must also enable sidecar injection for the service.
+
+[IMPORTANT]
+====
+Adding sidecar injection to pods in system namespaces, such as `knative-serving` and `knative-serving-ingress`, is not supported when Kourier is enabled.
+
+ifdef::openshift-enterprise[]
+If you require sidecar injection for pods in these namespaces, see the {ServerlessProductName} documentation on _Integrating {SMProductShortName} with {ServerlessProductName} natively_.
+endif::[]
+====
 
 .Prerequisites
 
-* You have installed the {ServerlessOperatorName} and Knative Serving.
+* You have installed the {ServerlessOperatorName}, Knative Serving, and {SMProductName} on your cluster.
 * 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}.
 
 .Procedure
 
+. Add the `sidecar.istio.io/inject="true"` annotation to your service:
++
+.Example service
+[source,yaml]
+----
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: <service_name>
+spec:
+  template:
+    metadata:
+      annotations:
+        sidecar.istio.io/inject: "true" <1>
+        sidecar.istio.io/rewriteAppHTTPProbers: "true" <2>
+...
+----
+<1> Add the `sidecar.istio.io/inject="true"` annotation.
+<2> You must set the annotation `sidecar.istio.io/rewriteAppHTTPProbers: "true"` in your Knative service, because {ServerlessProductName} versions 1.14.0 and higher use an HTTP probe as the readiness probe for Knative services by default.
+
+. Apply the `Service` resource:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----
+
 . Create a policy in a serverless application namespace which is a member in the `ServiceMeshMemberRoll` object, that only allows requests with valid JSON Web Tokens (JWT):
 +
 [IMPORTANT]
@@ -43,6 +79,7 @@ spec:
 ----
 <1> The path on your application to collect metrics by system pod.
 <2> The path on your application to probe by system pod.
+
 . Apply the `Policy` resource:
 +
 [source,terminal]
@@ -64,6 +101,7 @@ $ curl http://hello-example-default.apps.mycluster.example.com/
 ----
 Origin authentication failed.
 ----
+
 . Verify the request with a valid JWT.
 .. Get the valid JWT token:
 +
diff --git a/modules/serverless-ossm-v2x-jwt.adoc b/modules/serverless-ossm-v2x-jwt.adoc
@@ -6,16 +6,52 @@
 [id="serverless-ossm-v2x-jwt_{context}"]
 = Using JSON Web Token authentication with {SMProductShortName} 2.x and {ServerlessProductName}
 
-You can use the following procedure to enable using JSON Web Token authentication with {SMProductShortName} 2.x and {ServerlessProductName}.
+You can use JSON Web Token (JWT) authentication with Knative services by using {SMProductShortName} 2.x and {ServerlessProductName}. To do this, you must create authentication requests and policies in the application namespace that is a member of the `ServiceMeshMemberRoll` object. You must also enable sidecar injection for the service.
+
+[IMPORTANT]
+====
+Adding sidecar injection to pods in system namespaces, such as `knative-serving` and `knative-serving-ingress`, is not supported when Kourier is enabled.
+
+ifdef::openshift-enterprise[]
+If you require sidecar injection for pods in these namespaces, see the {ServerlessProductName} documentation on _Integrating {SMProductShortName} with {ServerlessProductName} natively_.
+endif::[]
+====
 
 .Prerequisites
 
-* You have installed the {ServerlessOperatorName} and Knative Serving.
+* You have installed the {ServerlessOperatorName}, Knative Serving, and {SMProductName} on your cluster.
 * 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}.
 
 .Procedure
 
+. Add the `sidecar.istio.io/inject="true"` annotation to your service:
++
+.Example service
+[source,yaml]
+----
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: <service_name>
+spec:
+  template:
+    metadata:
+      annotations:
+        sidecar.istio.io/inject: "true" <1>
+        sidecar.istio.io/rewriteAppHTTPProbers: "true" <2>
+...
+----
+<1> Add the `sidecar.istio.io/inject="true"` annotation.
+<2> You must set the annotation `sidecar.istio.io/rewriteAppHTTPProbers: "true"` in your Knative service, because {ServerlessProductName} versions 1.14.0 and higher use an HTTP probe as the readiness probe for Knative services by default.
+
+. Apply the `Service` resource:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----
+
 . Create a `RequestAuthentication` resource in each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object:
 +
 [source,yaml]
@@ -30,12 +66,14 @@ spec:
   - issuer: testing@secure.istio.io
     jwksUri: https://raw.githubusercontent.com/istio/istio/release-1.8/security/tools/jwt/samples/jwks.json
 ----
+
 . Apply the `RequestAuthentication` resource:
 +
 [source,terminal]
 ----
 $ oc apply -f <filename>
 ----
+
 . Allow access to the `RequestAuthenticaton` resource from system pods for each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, by creating the following `AuthorizationPolicy` resource:
 +
 [source,yaml]
@@ -56,12 +94,14 @@ spec:
 ----
 <1> The path on your application to collect metrics by system pod.
 <2> The path on your application to probe by system pod.
+
 . Apply the `AuthorizationPolicy` resource:
 +
 [source,terminal]
 ----
 $ oc apply -f <filename>
 ----
+
 . For each serverless application namespace that is a member in the `ServiceMeshMemberRoll` object, create the following `AuthorizationPolicy` resource:
 +
 [source,yaml]
@@ -78,6 +118,7 @@ spec:
     - source:
        requestPrincipals: ["testing@secure.istio.io/testing@secure.istio.io"]
 ----
+
 . Apply the `AuthorizationPolicy` resource:
 +
 [source,terminal]
@@ -100,6 +141,7 @@ $ curl http://hello-example-1-default.apps.mycluster.example.com/
 ----
 RBAC: access denied
 ----
+
 . Verify the request with a valid JWT.
 .. Get the valid JWT token:
 +
diff --git a/serverless/admin_guide/serverless-admin-perspective.adoc b/serverless/admin_guide/serverless-admin-perspective.adoc
@@ -10,6 +10,8 @@ If you do not want to switch to the *Developer* perspective in the {product-titl
 
 // Create services as an admin
 include::modules/creating-serverless-apps-admin-console.adoc[leveloffset=+1]
+// domain mapping as an admin
+include::modules/serverless-domain-mapping-odc-admin.adoc[leveloffset=+1]
 // Event sources
 include::modules/serverless-creating-event-source-admin-web-console.adoc[leveloffset=+1]
 // Brokers
diff --git a/serverless/security/serverless-custom-domains.adoc b/serverless/security/serverless-custom-domains.adoc
@@ -6,19 +6,11 @@ include::_attributes/common-attributes.adoc[]
 
 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 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.
+include::snippets/serverless-domain-mapping.adoc[]
 
 include::modules/serverless-create-domain-mapping.adoc[leveloffset=+1]
 include::modules/serverless-create-domain-mapping-kn.adoc[leveloffset=+1]
+// ODC
+include::modules/serverless-domain-mapping-odc-developer.adoc[leveloffset=+1]
 
-// Using the web console
-
-[id="serverless-custom-domains-odc"]
-== Creating a custom domain mapping by using the web console
-
-You can use the *Administrator* or *Developer* perspective of the {product-title} web console to create a custom domain mapping for a Knative service.
-
-include::modules/serverless-domain-mapping-odc-admin.adoc[leveloffset=+2]
-include::modules/serverless-domain-mapping-odc-developer.adoc[leveloffset=+2]
+include::modules/serverless-domain-mapping-custom-tls-cert.adoc[leveloffset=+1]
diff --git a/serverless/security/serverless-custom-tls-cert-domain-mapping.adoc b/serverless/security/serverless-custom-tls-cert-domain-mapping.adoc
diff --git a/serverless/security/serverless-ossm-with-kourier-jwt.adoc b/serverless/security/serverless-ossm-with-kourier-jwt.adoc
@@ -6,8 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-After the {SMProductShortName} integration with {ServerlessProductName} and Kourier has been configured on your cluster, you can enable JSON Web Token (JWT) authentication for your Knative services.
+{ServerlessProductName} does not currently have user-defined authorization features. To add user-defined authorization to your deployment, you must integrate {ServerlessProductName} with {SMProductName}, and then configure JSON Web Token (JWT) authentication and sidecar injection for Knative services.
 
-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]
diff --git a/snippets/serverless-domain-mapping.adoc b/snippets/serverless-domain-mapping.adoc
@@ -0,0 +1,8 @@
+// Text snippet included in the following files
+//
+// * serverless/security/serverless-custom-domains.adoc
+// * modules/serverless-domain-mapping-odc-admin.adoc
+
+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 mapping a custom domain name that you own to a Knative service.
+
+You can do this 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.
