SRVCOM-1728: Updating serverless applications section to meet new Jupiter reqs

abrennan89 · abrennan89 · commit 87adf72752ff · 2022-04-05T14:55:23.000-05:00
diff --git a/modules/creating-serverless-apps-kn.adoc b/modules/creating-serverless-apps-kn.adoc
@@ -7,7 +7,7 @@
 [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.
+Using the `kn` CLI to create serverless applications provides a more streamlined and intuitive user interface over modifying YAML files directly. You can use the `kn service create` command to create a basic serverless application using the `kn` CLI.
 
 .Prerequisites
 
diff --git a/modules/creating-serverless-apps-yaml.adoc b/modules/creating-serverless-apps-yaml.adoc
@@ -6,10 +6,14 @@
 [id="creating-serverless-apps-yaml_{context}"]
 = Creating serverless applications using YAML
 
-To create a serverless application by using YAML, you must create a YAML file that defines a `Service` object, then apply it by using `oc apply`.
+Creating Knative resources by using YAML files uses a declarative API, which enables you to describe applications declaratively and in a reproducible manner. To create a serverless application by using YAML, you must create a YAML file that defines a Knative `Service` object, then apply it by using `oc apply`.
+
+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.
 
 .Prerequisites
 
+* {ServerlessOperatorName} and Knative Serving are installed on your cluster.
+* 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}.
 * Install the OpenShift CLI (`oc`).
 
 .Procedure
@@ -38,5 +42,3 @@ 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.
diff --git a/modules/interacting-serverless-apps-http2-gRPC.adoc b/modules/interacting-serverless-apps-http2-gRPC.adoc
@@ -6,12 +6,7 @@
 [id="interacting-serverless-apps-http2-gRPC_{context}"]
 = Interacting with a serverless application using HTTP2 and gRPC
 
-{ServerlessProductName} supports only insecure or edge-terminated routes.
-
-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.
+{ServerlessProductName} supports only insecure or edge-terminated routes. 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.
 
 [IMPORTANT]
 ====
@@ -30,7 +25,9 @@ spec:
 
 .Prerequisites
 
+* {ServerlessOperatorName} and Knative Serving are installed on your cluster.
 * Install the OpenShift CLI (`oc`).
+* You have created a Knative service.
 
 .Procedure
 
diff --git a/modules/kn-service-apply.adoc b/modules/kn-service-apply.adoc
@@ -1,6 +1,5 @@
 // Module included in the following assemblies:
 //
-// * serverless/develop/serverless-applications.adoc
 // * serverless/reference/kn-serving-ref.adoc
 
 :_content-type: REFERENCE
diff --git a/modules/kn-service-describe.adoc b/modules/kn-service-describe.adoc
@@ -1,6 +1,5 @@
 // Module included in the following assemblies:
 //
-// * serverless/develop/serverless-applications.adoc
 // * serverless/reference/kn-serving-ref.adoc
 
 :_content-type: REFERENCE
diff --git a/modules/kn-service-offline-about.adoc b/modules/kn-service-offline-about.adoc
@@ -1,18 +1,18 @@
 // Module included in the following assemblies:
 //
-// * serverless/cli_reference/kn-offline-services.adoc
-// * serverless/develop/serverless-applications.adoc
+// * serverless/reference/kn-serving-ref.adoc
 
 :_content-type: CONCEPT
 [id="kn-service-offline-about_{context}"]
-= About offline mode
+= About the Knative CLI offline mode
 
-Normally, when you execute `kn service` commands, the changes immediately propagate to the cluster. However, as an alternative, you can execute `kn service` commands in offline mode:
+When you execute `kn service` commands, the changes immediately propagate to the cluster. However, as an alternative, you can execute `kn service` commands in offline mode. When you create a service in offline mode, no changes happen on the cluster, and instead the service descriptor file is created on your local machine.
 
-. When you create a service in offline mode, no changes happen on the cluster. Instead, the only thing that happens is the creation of the service descriptor file on your local machine.
-. After the descriptor file is created, you can manually modify it and track it in a version control system.
+:FeatureName: The offline mode of the Knative CLI
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+After the descriptor file is created, you can manually modify it and track it in a version control system. You can also propagate changes to the cluster by using the `kn service create -f`, `kn service apply -f`, or `oc apply -f` commands on the descriptor files.
 // Once `update` works, add it here and make it into a list
-. Finally, you can propagate changes to the cluster by using the `kn service create -f`, `kn service apply -f`, or `oc apply -f` commands on the descriptor files.
 
 The offline mode has several uses:
 
diff --git a/modules/kn-service-offline-create.adoc b/modules/kn-service-offline-create.adoc
@@ -1,16 +1,21 @@
 // Module included in the following assemblies:
 //
-// * serverless/cli_reference/kn-offline-services.adoc
+// * serverless/reference/kn-serving-ref.adoc
 // * serverless/develop/serverless-applications.adoc
 
 :_content-type: PROCEDURE
 [id="creating-an-offline-service_{context}"]
 = Creating a service using offline mode
 
+You can execute `kn service` commands in offline mode, so that no changes happen on the cluster, and instead the service descriptor file is created on your local machine. After the descriptor file is created, you can modify the file before propagating changes to the cluster.
+
+:FeatureName: The offline mode of the Knative CLI
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
 .Prerequisites
 
 * {ServerlessOperatorName} and Knative Serving are installed on your cluster.
-* You have installed the `kn` CLI.
+* You have installed the Knative (`kn`) CLI.
 
 .Procedure
 
diff --git a/modules/kn-service-update.adoc b/modules/kn-service-update.adoc
@@ -1,6 +1,5 @@
 // Module included in the following assemblies:
 //
-// * serverless/develop/serverless-applications.adoc
 // * serverless/reference/kn-serving-ref.adoc
 
 :_content-type: REFERENCE
diff --git a/modules/serverless-https-redirect-service.adoc b/modules/serverless-https-redirect-service.adoc
@@ -6,7 +6,8 @@
 [id="serverless-https-redirect-service_{context}"]
 = HTTPS redirection per service
 
-You can enable or disable HTTPS redirection for a service by configuring the `networking.knative.dev/httpOption` annotation, as shown in the following example:
+// need better details from eng team about use case to update this topic
+You can enable or disable HTTPS redirection for a service by configuring the `networking.knative.dev/httpOption` annotation. The following example shows how you can use this annotation in a Knative `Service` YAML object:
 
 [source,yaml]
 ----
diff --git a/modules/serverless-kn-container.adoc b/modules/serverless-kn-container.adoc
@@ -1,13 +1,14 @@
 // Module included in the following assemblies:
 //
-// * 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.
+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}"]
diff --git a/modules/serverless-services-network-policies.adoc b/modules/serverless-services-network-policies.adoc
@@ -6,9 +6,7 @@
 [id="serverless-services-network-policies_{context}"]
 = Enabling communication with Knative applications on a cluster with restrictive network policies
 
-If you are using a cluster that multiple users have access to, your cluster might use network policies to control which pods, services, and namespaces can communicate with each other over the network.
-
-If your cluster uses restrictive network policies, it is possible that Knative system pods are not able to access your Knative application. For example, if your namespace has the following network policy, which denies all requests, Knative system pods cannot access your Knative application:
+If you are using a cluster that multiple users have access to, your cluster might use network policies to control which pods, services, and namespaces can communicate with each other over the network. If your cluster uses restrictive network policies, it is possible that Knative system pods are not able to access your Knative application. For example, if your namespace has the following network policy, which denies all requests, Knative system pods cannot access your Knative application:
 
 .Example NetworkPolicy object that denies all requests to the namespace
 [source,yaml]
@@ -35,6 +33,7 @@ If you do not want to allow access to your Knative application from all namespac
 .Prerequisites
 
 * Install the OpenShift CLI (`oc`).
+* {ServerlessOperatorName} and Knative Serving are installed on your cluster.
 
 .Procedure
 
diff --git a/modules/verifying-serverless-app-deployment.adoc b/modules/verifying-serverless-app-deployment.adoc
@@ -6,12 +6,13 @@
 [id="verifying-serverless-app-deployment_{context}"]
 = Verifying your serverless application deployment
 
-To verify that your serverless application has been deployed successfully, you must get the application URL created by Knative, and then send a request to that URL and observe the output.
+To verify that your serverless application has been deployed successfully, you must get the application URL created by Knative, and then send a request to that URL and observe the output. {ServerlessProductName} supports the use of both HTTP and HTTPS URLs, however the output from `oc get ksvc` always prints URLs using the `http://` format.
 
-[NOTE]
-====
-{ServerlessProductName} supports the use of both HTTP and HTTPS URLs, however the output from `oc get ksvc` will always print URLs using the `http://` format.
-====
+.Prerequisites
+
+* {ServerlessOperatorName} and Knative Serving are installed on your cluster.
+* You have installed the `oc` CLI.
+* You have created a Knative service.
 
 .Prerequisites
 
diff --git a/serverless/develop/serverless-applications.adoc b/serverless/develop/serverless-applications.adoc
@@ -6,9 +6,9 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-To deploy a serverless application using {ServerlessProductName}, you must create a _Knative service_. Knative services are Kubernetes services, defined by a route and a configuration, and contained in a YAML file.
+Serverless applications are created and deployed as Kubernetes services, defined by a route and a configuration, and contained in a YAML file. To deploy a serverless application using {ServerlessProductName}, you must create a Knative `Service` object.
 
-.Example Knative service YAML
+.Example Knative `Service` object YAML file
 [source,yaml]
 ----
 apiVersion: serving.knative.dev/v1
@@ -25,43 +25,29 @@ spec:
             - name: RESPONSE <4>
               value: "Hello Serverless!"
 ----
-
 <1> The name of the application.
 <2> The namespace the application uses.
 <3> The image of the application.
 <4> The environment variable printed out by the sample application.
 
-[id="serverless-applications-create"]
-== Creating serverless applications
-
 You can create a serverless application by using one of the following methods:
 
-ifdef::openshift-enterprise[]
-* Create a Knative service from the {product-title} web console. See the documentation about xref:../../applications/creating_applications/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating applications using the Developer perspective].
-endif::[]
-
-ifdef::openshift-dedicated[]
 * Create a Knative service from the {product-title} web console.
++
+ifdef::openshift-enterprise[]
+See xref:../../applications/creating_applications/odc-creating-applications-using-developer-perspective.adoc#odc-creating-applications-using-developer-perspective[Creating applications using the Developer perspective] for more information.
 endif::[]
-// TODO: remove conditional once Applications docs are available in OSD
-
-* Create a Knative service using the `kn` CLI.
-* Create and apply a YAML file.
+* Create a Knative service by using the `kn` CLI.
+* Create and apply a Knative `Service` object as a YAML file, by using the `oc` CLI.
 
 // create service using CLI
-include::modules/creating-serverless-apps-kn.adoc[leveloffset=+2]
+include::modules/creating-serverless-apps-kn.adoc[leveloffset=+1]
 
-include::modules/serverless-kn-container.adoc[leveloffset=+3]
+// offline mode
+include::modules/kn-service-offline-create.adoc[leveloffset=+1]
 
 // create service using YAML
-include::modules/creating-serverless-apps-yaml.adoc[leveloffset=+2]
-
-// Update services
-include::modules/kn-service-update.adoc[leveloffset=+1]
-// kn service apply
-include::modules/kn-service-apply.adoc[leveloffset=+1]
-// describe services
-include::modules/kn-service-describe.adoc[leveloffset=+1]
+include::modules/creating-serverless-apps-yaml.adoc[leveloffset=+1]
 
 include::modules/verifying-serverless-app-deployment.adoc[leveloffset=+1]
 include::modules/interacting-serverless-apps-http2-gRPC.adoc[leveloffset=+1]
@@ -71,20 +57,14 @@ ifdef::openshift-enterprise[]
 // Using Knative services w/ restrictive NetworkPolicies
 include::modules/serverless-services-network-policies.adoc[leveloffset=+1]
 endif::[]
+// should maybe move to admin guide? asked serving team
 
 // HTTPS redirection
 include::modules/serverless-https-redirect-service.adoc[leveloffset=+1]
-
-[id="serverless-applications-kn-offline-mode"]
-== Using kn CLI in offline mode
-
-:FeatureName: The offline mode of the kn CLI
-include::snippets/technology-preview.adoc[leveloffset=+1]
-
-include::modules/kn-service-offline-about.adoc[leveloffset=+2]
-include::modules/kn-service-offline-create.adoc[leveloffset=+2]
+// asked serving team why a user would need this for abstract rewrite, waiting for details
 
 [id="additional-resources_serverless-applications"]
 [role="_additional-resources"]
 == Additional resources
+* xref:../../serverless/reference/kn-serving-ref.adoc#kn-serving-ref[Knative Serving CLI commands]
 * xref:../../serverless/security/serverless-ossm-with-kourier-jwt.adoc#serverless-ossm-with-kourier-jwt[Configuring JSON Web Token authentication for Knative services]
diff --git a/serverless/reference/kn-serving-ref.adoc b/serverless/reference/kn-serving-ref.adoc
@@ -18,6 +18,10 @@ include::modules/kn-service-update.adoc[leveloffset=+2]
 include::modules/kn-service-apply.adoc[leveloffset=+2]
 include::modules/kn-service-describe.adoc[leveloffset=+2]
 
+// offline mode
+include::modules/kn-service-offline-about.adoc[leveloffset=+1]
+include::modules/kn-service-offline-create.adoc[leveloffset=+2]
+
 [id="kn-serving-ref-kn-container"]
 == kn container commands
 
