diff --git a/images/knative-service-architecture.png b/images/knative-service-architecture.png index fcd4f72826..4d171664ee 100644 Binary files a/images/knative-service-architecture.png and b/images/knative-service-architecture.png differ diff --git a/modules/creating-serverless-apps-kn.adoc b/modules/creating-serverless-apps-kn.adoc index 50c6d414df..9109b6c8f4 100644 --- a/modules/creating-serverless-apps-kn.adoc +++ b/modules/creating-serverless-apps-kn.adoc @@ -1,3 +1,7 @@ +// 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 @@ -5,6 +9,7 @@ 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 --image --env + .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 index c5fbb70669..e637d1eedc 100644 --- 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 ---- -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 index da4b19b795..cc59cf1b9c 100644 --- 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 index 51117defb7..77e14af242 100644 --- 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 index 235e405239..1824b14c73 100644 --- 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 index 1ed1fa2a1a..d2e91c9137 100644 --- 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 index d6579f9bcd..ee3a6ecc63 100644 --- 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 index 7abf310ac8..18d99bad48 100644 --- 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 index c1571c2914..24dd0232d2 100644 --- 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 index 39a3351370..acae69ad72 100644 --- 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 index 054c9ef1bb..69643bc005 100644 --- 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 index b1239a1e1a..79308c5ab7 100644 --- 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 index d60d749a5b..3f417a82ff 100644 --- 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 index c276f86b62..3e46a8791e 100644 --- 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 index 07b1ba3c13..7996afca0b 100644 --- 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 index 29ae0fb44f..0bf66337e2 100644 --- 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 index 1d4fc25aef..add8702c37 100644 --- 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 index 4cf8bab731..0889a9dfbf 100644 --- 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 index 3fe6a534c3..38e5bdc83c 100644 --- 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 index 0565438c96..00cd38acd2 100644 --- 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 index 5e0a84decc..e635c1f0c5 100644 --- 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 index 68ff0a2036..c5afd300e8 100644 --- 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 index cd47c2d0e0..2b8c4f4d64 100644 --- 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]