SRVCOM-1664: ensure that docs have right context attribute

abrennan89 · abrennan89 · commit 9d6e9c215a6a · 2022-02-08T09:58:21.000-06:00
diff --git a/images/knative-service-architecture.png b/images/knative-service-architecture.png
diff --git a/modules/creating-serverless-apps-kn.adoc b/modules/creating-serverless-apps-kn.adoc
@@ -1,10 +1,15 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-applications.adoc
+
 :_content-type: PROCEDURE
 [id="creating-serverless-apps-kn_{context}"]
 = Creating serverless applications by using the Knative CLI
 
 The following procedure describes how you can create a basic serverless application using the `kn` CLI.
 
 .Prerequisites
+
 * {ServerlessOperatorName} and Knative Serving are installed on your cluster.
 * You have installed the `kn` CLI.
 
@@ -19,7 +24,6 @@ $ kn service create <service-name> --image <image> --env <key=value>
 +
 .Example command
 [source,terminal]
-[source,terminal]
 ----
 $ kn service create event-display \
     --image quay.io/openshift-knative/knative-eventing-sources-event-display:latest
diff --git a/modules/creating-serverless-apps-yaml.adoc b/modules/creating-serverless-apps-yaml.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// serverless/knative_serving/serverless-applications.adoc
+// * serverless/develop/serverless-applications.adoc
 
 :_content-type: PROCEDURE
 [id="creating-serverless-apps-yaml_{context}"]
@@ -35,5 +35,4 @@ spec:
 $ oc apply -f <filename>
 ----
 
-After the service is created and the application is deployed, Knative creates an immutable revision for this version of the application.
-Knative also performs network programming to create a route, ingress, service, and load balancer for your application and automatically scales your pods up and down based on traffic, including inactive pods.
+After the service is created and the application is deployed, Knative creates an immutable revision for this version of the application. Knative also performs network programming to create a route, ingress, service, and load balancer for your application and automatically scales your pods up and down based on traffic, including inactive pods.
diff --git a/modules/interacting-serverless-apps-http2-gRPC.adoc b/modules/interacting-serverless-apps-http2-gRPC.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// serverless/knative_serving/serverless-applications.adoc
+// serverless/develop/serverless-applications.adoc
 
 :_content-type: PROCEDURE
 [id="interacting-serverless-apps-http2-gRPC_{context}"]
@@ -11,68 +11,59 @@
 Insecure or edge-terminated routes do not support HTTP2 on {product-title}.
 These routes also do not support gRPC because gRPC is transported by HTTP2.
 
-If you use these protocols in your application, you must call the application using the ingress gateway directly.
-To do this you must find the ingress gateway's public address and the application's specific host.
+If you use these protocols in your application, you must call the application using the ingress gateway directly. To do this you must find the ingress gateway's public address and the application's specific host.
 
-// FIXME: Uncomment for Serverless 1.19.0
-// [IMPORTANT]
-// ====
-// This method needs to expose Kourier Gateway using the `LoadBalancer` service type. You can configure this by adding the following YAML to your `KnativeServing` custom resource definition (CRD):
+[IMPORTANT]
+====
+This method needs to expose Kourier Gateway using the `LoadBalancer` service type. You can configure this by adding the following YAML to your `KnativeServing` custom resource definition (CRD):
 
-// [source,yaml]
-// ----
-// ...
-// spec:
-//   ingress:
-//     kourier:
-//       service-type: LoadBalancer
-// ...
-// ----
-// ====
+[source,yaml]
+----
+...
+spec:
+  ingress:
+    kourier:
+      service-type: LoadBalancer
+...
+----
+====
 
 .Procedure
 
 . Find the application host. See the instructions in _Verifying your serverless application deployment_.
+
 . Find the ingress gateway's public address:
 +
-
 [source,terminal]
 ----
 $ oc -n knative-serving-ingress get svc kourier
 ----
-
 +
 .Example output
 +
-
 [source,terminal]
 ----
 NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP                                                             PORT(S)                                                                                                                                      AGE
 kourier   LoadBalancer   172.30.51.103   a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com   80:31380/TCP,443:31390/TCP   67m
 ----
-
 +
 The public address is surfaced in the `EXTERNAL-IP` field, and in this case is `a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com`.
 
 . Manually set the host header of your HTTP request to the application's host, but direct the request itself against the public address of the ingress gateway.
 +
-
 [source,terminal]
 ----
 $ curl -H "Host: hello-default.example.com" a83e86291bcdd11e993af02b7a65e514-33544245.us-east-1.elb.amazonaws.com
 ----
-
 +
 .Example output
 [source,terminal]
 ----
 Hello Serverless!
 ----
-
 +
 You can also make a gRPC request by setting the authority to the application's host, while directing the request against the ingress gateway directly:
 +
-
 [source,yaml]
 ----
 grpc.Dial(
@@ -81,7 +72,6 @@ grpc.Dial(
     grpc.WithInsecure(),
 )
 ----
-
 +
 [NOTE]
 ====
diff --git a/modules/kn-service-apply.adoc b/modules/kn-service-apply.adoc
@@ -1,3 +1,9 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-applications.adoc
+// * serverless/reference/kn-serving-ref.adoc
+
+:_content-type: REFERENCE
 [id="kn-service-apply_{context}"]
 = Applying service declarations
 
diff --git a/modules/kn-service-describe.adoc b/modules/kn-service-describe.adoc
@@ -1,3 +1,9 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-applications.adoc
+// * serverless/reference/kn-serving-ref.adoc
+
+:_content-type: REFERENCE
 [id="kn-service-describe_{context}"]
 = Describing serverless applications by using the Knative CLI
 
diff --git a/modules/kn-service-offline-about.adoc b/modules/kn-service-offline-about.adoc
@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
-// serverless/cli_reference/kn-offline-services.adoc
+// * serverless/cli_reference/kn-offline-services.adoc
+// * serverless/develop/serverless-applications.adoc
 
 :_content-type: CONCEPT
 [id="kn-service-offline-about_{context}"]
diff --git a/modules/kn-service-offline-create.adoc b/modules/kn-service-offline-create.adoc
@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
-// serverless/cli_reference/kn-offline-services.adoc
+// * serverless/cli_reference/kn-offline-services.adoc
+// * serverless/develop/serverless-applications.adoc
 
 :_content-type: PROCEDURE
 [id="creating-an-offline-service_{context}"]
diff --git a/modules/kn-service-update.adoc b/modules/kn-service-update.adoc
@@ -1,3 +1,9 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-applications.adoc
+// * serverless/reference/kn-serving-ref.adoc
+
+:_content-type: REFERENCE
 [id="kn-service-update_{context}"]
 = Updating serverless applications by using the Knative CLI
 
diff --git a/modules/odc-splitting-traffic-between-revisions-using-developer-perspective.adoc b/modules/odc-splitting-traffic-between-revisions-using-developer-perspective.adoc
@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-traffic-management.adoc
+
 :_content-type: PROCEDURE
 [id="odc-splitting-traffic-between-revisions-using-developer-perspective_{context}"]
 = Managing traffic between revisions by using the {product-title} web console
@@ -6,6 +10,11 @@ After you create a serverless application, the application is displayed in the *
 
 Any new change in the code or the service configuration creates a new revision, which is a snapshot of the code at a given time. For a service, you can manage the traffic between the revisions of the service by splitting and routing it to the different revisions as required.
 
+.Prerequisites
+
+* The {ServerlessOperatorName} and Knative Serving are installed on your cluster.
+* You have logged in to the {product-title} web console.
+
 .Procedure
 
 To split traffic between multiple revisions of an application in the *Topology* view:
diff --git a/modules/serverless-blue-green-deploy.adoc b/modules/serverless-blue-green-deploy.adoc
@@ -1,9 +1,17 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-traffic-management.adoc
+
 :_content-type: PROCEDURE
 [id="serverless-blue-green-deploy_{context}"]
 = Routing and managing traffic by using a blue-green deployment strategy
 
 You can safely reroute traffic from a production version of an app to a new version, by using a link:https://en.wikipedia.org/wiki/Blue-green_deployment[blue-green deployment strategy].
 
+.Prerequisites
+
+* The {ServerlessOperatorName} and Knative Serving are installed on the cluster.
+
 .Procedure
 
 . Create and deploy an app as a Knative service.
diff --git a/modules/serverless-custom-revision-urls.adoc b/modules/serverless-custom-revision-urls.adoc
@@ -1,3 +1,8 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-traffic-management.adoc
+
+:_content-type: REFERENCE
 [id="serverless-custom-revision-urls_{context}"]
 = Custom URLs for revisions
 
diff --git a/modules/serverless-https-redirect-service.adoc b/modules/serverless-https-redirect-service.adoc
@@ -1,7 +1,8 @@
 // Module is included in the following assemblies:
 //
-// * serverless/knative_serving/serverless-applications.adoc
+// * serverless/develop/serverless-applications.adoc
 
+:_content-type: REFERENCE
 [id="serverless-https-redirect-service_{context}"]
 = HTTPS redirection per service
 
diff --git a/modules/serverless-install-eventing-web-console.adoc b/modules/serverless-install-eventing-web-console.adoc
@@ -11,7 +11,7 @@ You can use the following procedure to install Knative Eventing by using the {pr
 .Prerequisites
 
 * You have access to an {product-title} account with cluster administrator access.
-* You have logged into the {product-title} web console.
+* You have logged in to the {product-title} web console.
 * You have installed the {ServerlessOperatorName}.
 
 .Procedure
diff --git a/modules/serverless-install-serving-web-console.adoc b/modules/serverless-install-serving-web-console.adoc
@@ -11,7 +11,7 @@ You can use the following procedure to install Knative Serving by using the {pro
 .Prerequisites
 
 * You have access to an {product-title} account with cluster administrator access.
-* You have logged into the {product-title} web console.
+* You have logged in to the {product-title} web console.
 * You have installed the {ServerlessOperatorName}.
 
 .Procedure
diff --git a/modules/serverless-install-web-console.adoc b/modules/serverless-install-web-console.adoc
@@ -11,7 +11,7 @@ This procedure describes how to install and subscribe to the {ServerlessOperator
 .Prerequisites
 
 * You have access to an {product-title} account with cluster administrator access.
-* You have logged into the {product-title} web console.
+* You have logged in to the {product-title} web console.
 
 .Procedure
 
diff --git a/modules/serverless-kn-container.adoc b/modules/serverless-kn-container.adoc
@@ -1,13 +1,15 @@
 // Module included in the following assemblies:
 //
-// * serverless/cli_tools/kn-serving-ref.adoc
-// * serverless/knative_serving/serverless-applications.adoc
+// * serverless/develop/serverless-applications.adoc
+// * serverless/reference/kn-serving-ref.adoc
 
+:_content-type: REFERENCE
 [id="serverless-kn-container_{context}"]
 = Knative client multi-container support
 
 You can use the `kn container add` command to print YAML container spec to standard output. This command is useful for multi-container use cases because it can be used along with other standard `kn` flags to create definitions. The `kn container add` command accepts all container-related flags that are supported for use with the `kn service create` command. The `kn container add` command can also be chained by using UNIX pipes (`|`) to create multiple container definitions at once.
 
+[discrete]
 [id="serverless-kn-container-examples_{context}"]
 == Example commands
 
diff --git a/modules/serverless-services-network-policies.adoc b/modules/serverless-services-network-policies.adoc
@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-applications.adoc
+
 :_content-type: PROCEDURE
 [id="serverless-services-network-policies_{context}"]
 = Enabling communication with Knative applications on a cluster with restrictive network policies
@@ -25,9 +29,8 @@ To allow access to your applications from Knative system pods, you must add a la
 ====
 A network policy that denies requests to non-Knative services on your cluster still prevents access to these services. However, by allowing access from Knative system namespaces to your Knative application, you are allowing access to your Knative application from all namespaces in the cluster.
 
-If you do not want to allow access to your Knative application from all namespaces on the cluster, you might want to use _JSON Web Token authentication for Knative services_ instead (see the _Knative Serving_ documentation). JSON Web Token authentication for Knative services requires Service Mesh.
+If you do not want to allow access to your Knative application from all namespaces on the cluster, you might want to use _JSON Web Token authentication for Knative services_ instead. JSON Web Token authentication for Knative services requires Service Mesh.
 ====
-// xrefs for modules would be nice here to link to the JWT docs
 
 .Procedure
 
@@ -82,4 +85,4 @@ spec:
   - Ingress
 ----
 <1> Provide a name for your network policy.
-<2> The namespace where your application (Knative service) exists.
+<2> The namespace where your application exists.
diff --git a/modules/serverless-traffic-management-kn.adoc b/modules/serverless-traffic-management-kn.adoc
@@ -1,3 +1,8 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-traffic-management.adoc
+
+:_content-type: REFERENCE
 [id="serverless-traffic-management-kn_{context}"]
 = Traffic management using the Knative CLI
 
diff --git a/modules/serverless-traffic-routing-examples.adoc b/modules/serverless-traffic-routing-examples.adoc
@@ -1,3 +1,8 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-traffic-management.adoc
+
+:_content-type: REFERENCE
 [id="serverless-traffic-routing-examples_{context}"]
 = Traffic routing examples
 
diff --git a/modules/serverless-workflow-traffic-splitting-flags.adoc b/modules/serverless-workflow-traffic-splitting-flags.adoc
@@ -1,3 +1,8 @@
+// Module included in the following assemblies:
+//
+// * serverless/develop/serverless-traffic-management.adoc
+
+:_content-type: REFERENCE
 [id="traffice-splitting-flags_{context}"]
 = Knative CLI traffic management flags
 
diff --git a/modules/verifying-serverless-app-deployment.adoc b/modules/verifying-serverless-app-deployment.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// serverless/knative_serving/serverless-applications.adoc
+// serverless/develop/serverless-applications.adoc
 
 :_content-type: PROCEDURE
 [id="verifying-serverless-app-deployment_{context}"]
diff --git a/serverless/develop/serverless-applications.adoc b/serverless/develop/serverless-applications.adoc
@@ -1,8 +1,8 @@
 :_content-type: ASSEMBLY
-include::modules/serverless-document-attributes.adoc[]
 [id="serverless-applications"]
 = Serverless applications
 include::modules/common-attributes.adoc[]
+include::modules/serverless-document-attributes.adoc[]
 :context: serverless-applications
 
 toc::[]
@@ -62,6 +62,10 @@ include::modules/interacting-serverless-apps-http2-gRPC.adoc[leveloffset=+1]
 // Using Knative services w/ restrictive NetworkPolicies
 include::modules/serverless-services-network-policies.adoc[leveloffset=+1]
 
+.Additional resources
+
+* See xref:../../serverless/security/serverless-ossm-with-kourier-jwt.adoc#serverless-ossm-with-kourier-jwt[Configuring JSON Web Token authentication for Knative services].
+
 // HTTPS redirection
 include::modules/serverless-https-redirect-service.adoc[leveloffset=+1]
 
diff --git a/serverless/develop/serverless-traffic-management.adoc b/serverless/develop/serverless-traffic-management.adoc
@@ -1,8 +1,8 @@
 :_content-type: ASSEMBLY
-include::modules/serverless-document-attributes.adoc[]
 [id="serverless-traffic-management"]
 = Traffic management
 include::modules/common-attributes.adoc[]
+include::modules/serverless-document-attributes.adoc[]
 :context: serverless-traffic-management
 
 toc::[]
@@ -13,7 +13,6 @@ A _revision_ is a point-in-time snapshot of the code and configuration for each
 You can manage traffic routing to different revisions of a Knative service by modifying the `traffic` spec of the service resource.
 
 image::knative-service-architecture.png[Knative service architecture]
-// placeholder image until we get a nice diagram to replace this
 
 // routing basics - YAML examples
 include::modules/serverless-traffic-routing-examples.adoc[leveloffset=+1]
