From 00bbbb0fd3979d3d09c50e6773297b8abd7d6f88 Mon Sep 17 00:00:00 2001 From: abrennan Date: Fri, 17 Jul 2020 11:28:05 -0500 Subject: [PATCH] [WIP] Adding Serverless architecture section --- _topic_map.yml | 14 ++++--- modules/knative-eventing-workflows.adoc | 14 ------- modules/serverless-components.adoc | 29 -------------- modules/serverless-serving-resources.adoc | 17 --------- .../container_security/security-build.adoc | 2 +- serverless/architecture/images | 1 + serverless/architecture/modules | 1 + .../serverless-event-architecture.adoc | 38 +++++++++++++++++++ .../serverless-serving-architecture.adoc | 32 ++++++++++++++++ .../event_sources/knative-event-sources.adoc | 11 ++++-- .../serverless-knative-eventing.adoc | 26 ------------- .../serverless-knative-serving.adoc | 23 ----------- serverless/serverless-getting-started.adoc | 13 ++++--- 13 files changed, 96 insertions(+), 125 deletions(-) delete mode 100644 modules/knative-eventing-workflows.adoc delete mode 100644 modules/serverless-components.adoc delete mode 100644 modules/serverless-serving-resources.adoc create mode 120000 serverless/architecture/images create mode 120000 serverless/architecture/modules create mode 100644 serverless/architecture/serverless-event-architecture.adoc create mode 100644 serverless/architecture/serverless-serving-architecture.adoc delete mode 100644 serverless/knative_eventing/serverless-knative-eventing.adoc delete mode 100644 serverless/knative_serving/serverless-knative-serving.adoc diff --git a/_topic_map.yml b/_topic_map.yml index aa904ba587..6068a0c506 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2293,8 +2293,16 @@ Topics: # Support - Name: Support File: serverless-support +# Architecture +- Name: Architecture + Dir: architecture + Topics: + - Name: Knative Serving + File: serverless-serving-architecture + - Name: Knative Eventing + File: serverless-event-architecture # Intro / getting started -- Name: Getting started with OpenShift Serverless +- Name: Getting started File: serverless-getting-started # Installing OpenShift Serverless - Name: Installing OpenShift Serverless @@ -2327,8 +2335,6 @@ Topics: - Name: Knative Serving Dir: knative_serving Topics: - - Name: How Knative Serving works - File: serverless-knative-serving # Knative services - Name: Using kn to complete Serving tasks File: serving-kn-commands @@ -2342,8 +2348,6 @@ Topics: - Name: Knative Eventing Dir: knative_eventing Topics: - - Name: How Knative Eventing works - File: serverless-knative-eventing # Brokers - Name: Using the broker File: serverless-using-brokers diff --git a/modules/knative-eventing-workflows.adoc b/modules/knative-eventing-workflows.adoc deleted file mode 100644 index 79a290f9e3..0000000000 --- a/modules/knative-eventing-workflows.adoc +++ /dev/null @@ -1,14 +0,0 @@ -// Module included in the following assemblies: -// -// * applications/application_life_cycle_management/odc-knative-event-sources.adoc -// * serverless/knative_eventing/serverless-knative-eventing.adoc - -[id="knative-eventing-workflows_{context}"] -= Knative Eventing workflows - -In a Knative Eventing workflow, event producers send information to an _event source_ about changes to system state. Examples of event producers include a Kafka cluster or the Kubernetes API server. - -An _event source_ is a resource object, which is the link between an event producer and a _sink_, or consumer, that receives those events. - -Examples of sinks are Knative services and channels. Events can also be sent to a _broker_, where they can be filtered using _triggers_ before being sent to a sink. -Using the broker and trigger together enables an event delivery mechanism that hides the details of event routing from the event producer and event consumer. diff --git a/modules/serverless-components.adoc b/modules/serverless-components.adoc deleted file mode 100644 index 76c0db5964..0000000000 --- a/modules/serverless-components.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module is included in the following assemblies: -// -// serverless/serverless-getting-started.adoc - -[id="serverless-components_{context}"] -= {ServerlessProductName} components - -This section describes the components of {ServerlessProductName}. - -[id="serverless-components-serving_{context}"] -== Knative Serving - -Knative Serving on {product-title} builds on Kubernetes and Kourier to support deploying and managing serverless applications. - -It creates a set of Kubernetes custom resource definitions (CRDs) that are used to define and control the behavior of serverless workloads on an {product-title} cluster. - -These CRDs are building blocks to address complex use cases, for example: - -* Rapidly deploying serverless containers. -* Automatically scaling pods. -* Viewing point-in-time snapshots of deployed code and configurations. - -[id="serverless-components-eventing_{context}"] -== Knative Eventing - -Knative Eventing on {product-title} enables developers to more easily declare how components of their system communicate, using an event-driven architecture for serverless applications. -Event-driven architecture is based on the concept of decoupled relationships between event producers and event consumers. - -For more information about event-driven architecture, see link:https://www.redhat.com/en/topics/integration/what-is-event-driven-architecture[What is event-driven architecture?] diff --git a/modules/serverless-serving-resources.adoc b/modules/serverless-serving-resources.adoc deleted file mode 100644 index 8aff0dc188..0000000000 --- a/modules/serverless-serving-resources.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// Module included in the following assemblies: -// -// * /knative_serving/serverless-knative-serving.adoc - -[id="serverless-serving-resources_{context}"] -= Knative Serving resources - -The resources described in this section are required for Knative Serving to be configured and run correctly. - -Knative service resource:: The `service.serving.knative.dev` resource automatically manages the whole lifecycle of a serverless workload on a cluster. It controls the creation of other objects to ensure that an app has a route, a configuration, and a new revision for each update of the service. Services can be defined to always route traffic to the latest revision or to a pinned revision. - -Knative route resource:: The `route.serving.knative.dev` resource maps a network endpoint to one or more Knative revisions. You can manage the traffic in several ways, including fractional traffic and named routes. - -Knative configuration resource:: The `configuration.serving.knative.dev` resource maintains the required state for your deployment. Modifying a configuration creates a new revision. - -Knative revision resource:: The `revision.serving.knative.dev` resource is a point-in-time snapshot of the code and configuration for each modification made to the workload. Revisions are immutable objects and can be retained for as long as needed. -Cluster administrators can modify the `revision.serving.knative.dev` resource to enable automatic scaling of Pods in your {product-title} cluster. diff --git a/security/container_security/security-build.adoc b/security/container_security/security-build.adoc index 4b788ba48c..f9136f49e8 100644 --- a/security/container_security/security-build.adoc +++ b/security/container_security/security-build.adoc @@ -30,6 +30,6 @@ include::modules/security-build-knative.adoc[leveloffset=+1] * xref:../../builds/creating-build-inputs.adoc#builds-input-secrets-configmaps_creating-build-inputs[Input Secrets and ConfigMaps] ifndef::openshift-origin[] * xref:../../architecture/cicd_gitops.adoc#cicd_gitops[The CI/CD methodology and practice] -* xref:../../serverless/knative_serving/serverless-knative-serving.adoc#serverless-knative-serving[How Knative Serving works] +* xref:../../serverless/architecture/serverless-serving-architecture.adoc#serverless-serving-architecture[Knative Serving architecture] endif::[] * xref:../../applications/application_life_cycle_management/odc-viewing-application-composition-using-topology-view.adoc#odc-viewing-application-composition-using-topology-view[Viewing application composition using the Topology view] diff --git a/serverless/architecture/images b/serverless/architecture/images new file mode 120000 index 0000000000..5e67573196 --- /dev/null +++ b/serverless/architecture/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/serverless/architecture/modules b/serverless/architecture/modules new file mode 120000 index 0000000000..464b823aca --- /dev/null +++ b/serverless/architecture/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/serverless/architecture/serverless-event-architecture.adoc b/serverless/architecture/serverless-event-architecture.adoc new file mode 100644 index 0000000000..6a542d96b1 --- /dev/null +++ b/serverless/architecture/serverless-event-architecture.adoc @@ -0,0 +1,38 @@ +include::modules/serverless-document-attributes.adoc[] +[id="serverless-event-architecture"] += Knative Eventing architecture +:context: serverless-event-architecture +include::modules/common-attributes.adoc[] + +toc::[] + +Knative Eventing on {product-title} enables developers to use an link:https://www.redhat.com/en/topics/integration/what-is-event-driven-architecture[event-driven architecture] with serverless applications. +An event-driven architecture is based on the concept of decoupled relationships between event producers that create events, and event _sinks_, or consumers, that receive them. + +Knative Eventing uses standard HTTP POST requests to send and receive events between event producers and consumers. +These events conform to the link:https://cloudevents.io[CloudEvents specifications], which enables creating, parsing, sending, and receiving events in any programming language. + +You can propagate an event from an xref:../event_sources/knative-event-sources.adoc#knative-event-sources[event source] to multiple event sinks by using: + +* xref:../knative_eventing/serverless-channels.adoc#serverless-channels[Channels] and Subscriptions, or +* xref:../knative_eventing/serverless-using-brokers.adoc#serverless-using-brokers[Brokers] and xref:../knative_eventing/serverless-kn-trigger.adoc#serverless-kn-trigger[Triggers]. +// TODO: Add subscription docs + +The Channel and Broker implementations manage delivery of events to event sinks, by using Subscriptions and Triggers. +Events are buffered if the destination sink is unavailable. +// For more information about creating an Event delivery system, see +// Add link to getting started or tutorial landing page for eventing +Knative Eventing supports the following scenarios: + +Publish an event without creating a consumer:: You can send events to a Broker as an HTTP POST, and use a SinkBinding to decouple the destination configuration from your application that is producing events. +Consume an event without creating a publisher:: You can use a Trigger to consume events from a Broker based on event attributes. Your application will receive events as an HTTP POST. +// Use Channels and Subscriptions to define complex message-passing topologies:: For simple pipelines, the Sequence automates construction of Channels and Subscriptions between each stage. +// Knative also supports some additional patterns such as Parallel fanout of events, and routing response events from both Channels and Brokers + +[id="serverless-event-architecture-sinks"] +== Event sinks + +To enable delivery to multiple types of sinks, Knative Eventing defines the following generic interfaces that can be implemented by multiple Kubernetes resources: + +Addressable objects:: Able to receive and acknowledge an Event delivered over HTTP to an address defined in the Event's `status.address.url` field. The Kubernetes Service object also satisfies the addressable interface. +Callable objects:: Able to receive an Event delivered over HTTP and transform it, returning 0 or 1 new Events in the HTTP response payload. These returned Events may be further processed in the same way that Events from an external event source are processed. diff --git a/serverless/architecture/serverless-serving-architecture.adoc b/serverless/architecture/serverless-serving-architecture.adoc new file mode 100644 index 0000000000..bff3dc733c --- /dev/null +++ b/serverless/architecture/serverless-serving-architecture.adoc @@ -0,0 +1,32 @@ +include::modules/serverless-document-attributes.adoc[] +[id="serverless-serving-architecture"] += Knative Serving architecture +:context: serverless-serving-architecture +include::modules/common-attributes.adoc[] + +toc::[] + +Knative Serving on {product-title} enables developers to write link:https://www.redhat.com/en/topics/cloud-native-apps[cloud-native applications] using link:https://www.redhat.com/en/topics/cloud-native-apps/what-is-serverless[serverless architecture]. +Serverless is a cloud computing model where application developers don't need to provision servers or manage scaling for their applications. These routine tasks are abstracted away by the platform, allowing developers to push code to production much faster than in traditional models. + +Knative Serving supports deploying and managing cloud-native applications by providing a set of objects as Kubernetes Custom Resource Definitions (CRDs) that define and control the behavior of serverless workloads on an {product-title} cluster. For more information about CRDs, see xref:../../operators/crds/crd-extending-api-with-crds.adoc#crd-extending-api-with-crds[Extending the Kubernetes API with Custom Resource Definitions]. + +Developers use these CRDs to create custom resource (CR) instances that can be used as building blocks to address complex use cases. For example: + +* Rapidly deploying serverless containers. +* Automatically scaling pods. +// TODO: Add other use cases, more advanced tutorials? + +For more information about CRs, see xref:../../operators/crds/crd-managing-resources-from-crds.adoc#crd-managing-resources-from-crds[Managing resources from Custom Resource Definitions]. + +[id="serverless-serving-architecture-custom-resources"] +== Knative Serving CRDs +// TODO: Request a good Serving arch diagram + +Service:: The `service.serving.knative.dev` CRD automatically manages the life cycle of your workload to ensure that the application is deployed and reachable through the network. It creates a Route, a Configuration, and a new Revision for each change to a user created Service, or custom resource. Most developer interactions in Knative are carried out by modifying Services. + +Revision:: The `revision.serving.knative.dev` CRD is a point-in-time snapshot of the code and configuration for each modification made to the workload. Revisions are immutable objects and can be retained for as long as necessary. + +Route:: The `route.serving.knative.dev` CRD maps a network endpoint to one or more Revisions. You can manage the traffic in several ways, including fractional traffic and named routes. + +Configuration:: The `configuration.serving.knative.dev` CRD maintains the desired state for your deployment. It provides a clean separation between code and configuration. Modifying a configuration creates a new Revision. diff --git a/serverless/event_sources/knative-event-sources.adoc b/serverless/event_sources/knative-event-sources.adoc index 8aeb7b4aea..f47f6b6001 100644 --- a/serverless/event_sources/knative-event-sources.adoc +++ b/serverless/event_sources/knative-event-sources.adoc @@ -5,16 +5,16 @@ include::modules/common-attributes.adoc[] :context: knative-event-sources toc::[] -An _event source_ is a resource object that acts as a link between an event producer and a _sink_. A sink can be a Knative service, channel or broker that receives events from an event source. +An _event source_ is an object that links an event producer with an event _sink_, or consumer. A sink can be a Knative Service, Channel, or Broker that receives events from an event source. Currently, {ServerlessProductName} supports the following event source types: ApiServerSource:: Connects a sink to the Kubernetes API server. PingSource:: Periodically sends ping events with a constant payload. It can be used as a timer. -SinkBinding is also supported, which allows you to connect core Kubernetes resources such as `Deployment`, `Job`, or `StatefulSet` with a sink. +xref:../../serverless/knative_eventing/serverless-sinkbinding.adoc#serverless-sinkbinding[SinkBinding] is also supported, which allows you to connect core Kubernetes resources such as Deployment, Job, or StatefulSet with a sink. -You can create and manage Knative event sources using the Developer perspective, the `kn` CLI, or by applying YAML files. +You can create and manage Knative event sources using the **Developer** perspective in the {product-title} web console, the `kn` CLI, or by applying YAML files. .Prerequisites @@ -22,10 +22,13 @@ You can create and manage Knative event sources using the Developer perspective, * Event sources need a service to use as an event _sink_. The sink is the service or application that events are sent to from the event source. // TODO: Create a better section about adding serverless apps/Knative services, group kn + dev console etc as I am doing now for event sources. This content should be reusable in Serverless and Dev Console docs. +[id="knative-event-sources-creating"] == Creating event sources * Create an xref:../../serverless/event_sources/serverless-apiserversource.adoc#serverless-apiserversource[ApiServerSource]. +* Create an xref:../../serverless/event_sources/serverless-pingsource.adoc#serverless-pingsource[PingSource]. // add others +[id="knative-event-sources-additional-resources"] == Additional resources -* For more information about eventing workflows using {ServerlessProductName}, see xref:../../serverless/knative_eventing/serverless-knative-eventing.adoc#serverless-knative-eventing[How Knative Eventing works]. +* For more information about eventing workflows using {ServerlessProductName}, see xref:../../serverless/architecture/serverless-event-architecture.adoc#serverless-event-architecture[Knative Eventing architecture]. diff --git a/serverless/knative_eventing/serverless-knative-eventing.adoc b/serverless/knative_eventing/serverless-knative-eventing.adoc deleted file mode 100644 index d8b375fb0c..0000000000 --- a/serverless/knative_eventing/serverless-knative-eventing.adoc +++ /dev/null @@ -1,26 +0,0 @@ -[id="serverless-knative-eventing"] -= How Knative Eventing works -include::modules/common-attributes.adoc[] -include::modules/serverless-document-attributes.adoc[] -:context: serverless-knative-eventing - -:FeatureName: Knative Eventing -include::modules/technology-preview.adoc[leveloffset=+1] - -toc::[] - -Knative Eventing on {product-title} enables developers to more easily declare how components of their system communicate, using an event-driven architecture for serverless applications. - -Event-driven architecture is based on the concept of decoupled relationships between event producers and event consumers. - -For more information about event-driven architecture, see link:https://www.redhat.com/en/topics/integration/what-is-event-driven-architecture[What is event-driven architecture?] - -include::modules/knative-eventing-workflows.adoc[leveloffset=+1] - -== Additional resources - -* For more information about event sources, see xref:../event_sources/knative-event-sources.adoc#knative-event-sources[Getting started with event sources]. -* For more information about brokers, see xref:../knative_eventing/serverless-using-brokers.adoc#serverless-using-brokers[Using brokers]. -* For more information about triggers, see xref:../knative_eventing/serverless-kn-trigger.adoc#serverless-kn-trigger[Using triggers]. -* For more information about channels, see xref:../knative_eventing/serverless-channels.adoc#serverless-channels[Using channels]. -// TODO: Add subscription docs diff --git a/serverless/knative_serving/serverless-knative-serving.adoc b/serverless/knative_serving/serverless-knative-serving.adoc deleted file mode 100644 index b39b7b99a9..0000000000 --- a/serverless/knative_serving/serverless-knative-serving.adoc +++ /dev/null @@ -1,23 +0,0 @@ -[id="serverless-knative-serving"] -= How Knative Serving works -include::modules/common-attributes.adoc[] -include::modules/serverless-document-attributes.adoc[] -:context: serverless-knative-serving - -toc::[] - -Knative Serving on {product-title} builds on Kubernetes and Kourier to support deploying and managing serverless applications. - -It creates a set of Kubernetes custom resource definitions (CRDs) that are used to define and control the behavior of serverless workloads on an {product-title} cluster. - -These CRDs are building blocks to address complex use cases, for example: - -* Rapidly deploying serverless containers. -* Automatically scaling pods. -* Viewing point-in-time snapshots of deployed code and configurations. - -include::modules/serverless-serving-resources.adoc[leveloffset=+1] -include::modules/serverless-apps-intro.adoc[leveloffset=+1] - -== Next steps -* Create a serverless application. For more information, see the documentation on xref:../../serverless/serving-creating-managing-apps.adoc#serving-creating-managing-apps[Creating and managing serverless applications]. diff --git a/serverless/serverless-getting-started.adoc b/serverless/serverless-getting-started.adoc index 87282d3208..4b12ccd035 100644 --- a/serverless/serverless-getting-started.adoc +++ b/serverless/serverless-getting-started.adoc @@ -8,7 +8,7 @@ toc::[] {ServerlessProductName} simplifies the process of delivering code from development into production by reducing the need for infrastructure set up or back-end development by developers. -[id="how-it-works_{context}"] +[id="serverless-getting-started-how-it-works"] == How {ServerlessProductName} works Developers on {ServerlessProductName} can use the provided Kubernetes native APIs, as well as familiar languages and frameworks, to deploy applications and container workloads. @@ -17,16 +17,17 @@ Developers on {ServerlessProductName} can use the provided Kubernetes native API {ServerlessProductName} is based on the open source Knative project, which provides portability and consistency across hybrid and multi-cloud environments by enabling an enterprise-grade serverless platform. -[id="serverless-supported-configs_{context}"] +[id="serverless-getting-started-supported-configs"] == Supported Configurations -The set of supported features, configurations, and integrations for {ServerlessProductName} (current and past versions) are available at the link:https://access.redhat.com/articles/4912821[Supported Configurations page]. - -include::modules/serverless-components.adoc[leveloffset=+1] +The set of supported features, configurations, and integrations for {ServerlessProductName}, current and past versions, are available at the link:https://access.redhat.com/articles/4912821[Supported Configurations page]. :FeatureName: Knative Eventing include::modules/technology-preview.adoc[leveloffset=+2] +[id="serverless-getting-started-next-steps"] == Next steps -* Install the xref:../serverless/installing_serverless/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessOperatorName}] on your {product-title} cluster to get started with serverless applications. + +* Install the xref:../serverless/installing_serverless/installing-openshift-serverless.adoc#installing-openshift-serverless[{ServerlessOperatorName}] on your {product-title} cluster to get started. * View the xref:../serverless/serverless-release-notes.adoc#serverless-release-notes[{ServerlessProductName} release notes]. +* Create an application by following the documentation on xref:../serverless/serving-creating-managing-apps.adoc#serving-creating-managing-apps[Creating and managing serverless applications].