diff --git a/config/nav.yml b/config/nav.yml index d899455ad76..a95333fa9b6 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -5,6 +5,12 @@ nav: # Home page ############################################################################### - Home: index.md +############################################################################### + # Concepts +############################################################################### + - Concepts: + - Overview: concepts/README.md + - Duck types: concepts/duck-typing.md ############################################################################### # Getting started ############################################################################### @@ -242,9 +248,8 @@ nav: - Eventing code samples: samples/eventing.md # Reference docs - Reference: - - Concepts: - - Duck types: reference/concepts/duck-typing.md - Security: reference/security/README.md + - Release notes: reference/relnotes/README.md - Contributing: - Welcome to the Knative community: contributing/README.md - Contribute to Knative: contributing/contributing.md diff --git a/config/redirects.yml b/config/redirects.yml index 0cbeb91372f..7f6db950235 100644 --- a/config/redirects.yml +++ b/config/redirects.yml @@ -1,6 +1,7 @@ plugins: redirects: redirect_maps: + reference/concepts/duck-typing.md: concepts/duck-typing.md reference/client/README.md: client/README.md reference/api/eventing-api.md: eventing/reference/eventing-api.md reference/api/serving-api.md: serving/reference/serving-api.md @@ -66,7 +67,7 @@ plugins: community/meetup.md: contributing/contributing.md community/samples.md: https://github.com/knative/docs/tree/main/code-samples/community concepts/overview.md: index.md - developer/concepts/duck-typing.md: reference/concepts/duck-typing.md + developer/concepts/duck-typing.md: concepts/duck-typing.md developer/eventing/event-delivery.md: eventing/event-delivery.md developer/eventing/sinks/README.md: eventing/sinks/README.md developer/eventing/sinks/kafka-sink.md: eventing/sinks/kafka-sink.md diff --git a/docs/concepts/README.md b/docs/concepts/README.md new file mode 100644 index 00000000000..bd9bd6d4ebd --- /dev/null +++ b/docs/concepts/README.md @@ -0,0 +1,15 @@ +# Concepts + +The documentation in this section explains commonly referenced Knative concepts and abstractions, and helps to provide you with a better understanding of how Knative works. + +## What is Knative? + +Knative is a platform-agnostic solution for running [serverless](https://en.wikipedia.org/wiki/Serverless_computing){target=_blank} deployments. + +## Knative Serving + +--8<-- "about-serving.md" + +## Knative Eventing + +--8<-- "about-eventing.md" diff --git a/docs/reference/concepts/duck-typing.md b/docs/concepts/duck-typing.md similarity index 100% rename from docs/reference/concepts/duck-typing.md rename to docs/concepts/duck-typing.md diff --git a/docs/eventing/README.md b/docs/eventing/README.md index 629d7813282..da6cdcdf907 100644 --- a/docs/eventing/README.md +++ b/docs/eventing/README.md @@ -1,17 +1,11 @@ # Knative Eventing -Knative Eventing is a collection of APIs that enable you to use an [event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture) with your applications. +--8<-- "about-eventing.md" -You can use these APIs to create components that route events from event producers to event consumers, or _sinks_, that receive events. Sinks can also be configured to respond to HTTP requests by sending a response event. - -Knative Eventing uses standard HTTP POST requests to send and receive events between event producers and sinks. These events conform to the [CloudEvents specifications](https://cloudevents.io/), which enables creating, parsing, sending, and receiving events in any programming language. - -In a Knative Eventing deployment, event [Sources](../eventing/sources/README.md) are the primary event producers. Examples of [sinks](../eventing/sinks/README.md) include [Brokers](../eventing/broker/README.md), [Channels](../eventing/channels/README.md), and [Services](../serving/services/README.md). +In a Knative Eventing deployment, event [Sources](../eventing/sources/README.md){target=_blank} are the primary event producers. Examples of [sinks](../eventing/sinks/README.md){target=_blank} include [Brokers](../eventing/broker/README.md){target=_blank}, [Channels](../eventing/channels/README.md){target=_blank}, and [Services](../serving/services/README.md){target=_blank}. ## Common use cases -Knative Eventing components are loosely coupled, and can be developed and deployed independently of each other. Any producer can generate events before there are active event consumers that are listening for those events. Any event consumer can express interest in a class of events before there are producers that are creating those events. - Examples of supported Knative Eventing use cases: - Publish an event without creating a consumer. You can send events to a broker as an HTTP POST, and use binding to decouple the destination configuration from your application that produces events. @@ -19,7 +13,7 @@ Examples of supported Knative Eventing use cases: - Consume an event without creating a publisher. You can use a trigger to consume events from a broker based on event attributes. The application receives events as an HTTP POST. !!! tip - Multiple event producers and sinks can be used together to create more advanced [Knative Eventing flows](flows/README.md) to solve complex use cases. + Multiple event producers and sinks can be used together to create more advanced [Knative Eventing flows](flows/README.md){target=_blank} to solve complex use cases. ## Eventing examples diff --git a/docs/eventing/sources/apiserversource/getting-started.md b/docs/eventing/sources/apiserversource/getting-started.md index 0f56f36efb7..eb00b3465e6 100644 --- a/docs/eventing/sources/apiserversource/getting-started.md +++ b/docs/eventing/sources/apiserversource/getting-started.md @@ -224,7 +224,7 @@ command: - `` is the name of the namespace that you created in step 1 earlier. - `` is the name of the ServiceAccount that you created in step 2 earlier. - `` is either `Resource` or `Reference`. If set to `Resource`, the event payload contains the entire resource that the event is for. If set to `Reference`, the event payload only contains a reference to the resource that the event is for. The default is `Reference`. - - `` is any supported [Addressable](../../../reference/concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`. + - `` is any supported Addressable object that you want to use as a sink, for example, a `Service` or `Deployment`. - `` is the name of your sink. For more information about the fields you can configure for the ApiServerSource object, see [ApiServerSource reference](reference.md). diff --git a/docs/eventing/sources/ping-source/README.md b/docs/eventing/sources/ping-source/README.md index b99cb4da789..64634cd025c 100644 --- a/docs/eventing/sources/ping-source/README.md +++ b/docs/eventing/sources/ping-source/README.md @@ -150,7 +150,7 @@ during the verification step in this procedure. - `` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute. - `` is the media type of the data you want to send, for example, `application/json`. - `` is the data you want to send. This data must be represented as text, not binary. For example, a JSON object such as `{"message": "Hello world!"}`. - - `` is any supported [Addressable](../../../reference/concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, `Service` or `Deployment`. + - `` is any supported Addressable object that you want to use as a sink, for example, a `Service` or `Deployment`. - `` is the name of your sink, for example, `event-display`. For more information about the fields you can configure for the PingSource object, see [PingSource reference](reference.md). @@ -191,7 +191,7 @@ during the verification step in this procedure. - `` is a cron expression for the schedule for the PingSource to send events, for example, `*/1 * * * *` sends an event every minute. - `` is the media type of the data you want to send, for example, `application/json`. - `` is the base64 encoded binary data that you want to send, for example, `ZGF0YQ==`. - - `` is any supported [Addressable](../../../reference/concepts/duck-typing.md#addressable) object that you want to use as a sink, for example, a Kubernetes Service. + - `` is any supported Addressable object that you want to use as a sink, for example, a Kubernetes Service. - `` is the name of your sink, for example, `event-display`. For more information about the fields you can configure for the PingSource object, see [PingSource reference](reference.md). diff --git a/docs/serving/README.md b/docs/serving/README.md index a8dabb0c4f0..bcbb861a4cd 100644 --- a/docs/serving/README.md +++ b/docs/serving/README.md @@ -1,6 +1,10 @@ # Knative Serving -Knative Serving provides components that enable: +--8<-- "about-serving.md" + +## Common use cases + +Examples of supported Knative Serving use cases: - Rapid deployment of serverless containers. - Autoscaling, including scaling pods down to zero. @@ -13,38 +17,6 @@ Knative Serving supports both HTTP and [HTTPS](using-a-tls-cert.md) networking p You can install Knative Serving via the methods listed on the [installation page](../install/README.md). -## Serving resources - -Knative Serving defines a set of objects as Kubernetes Custom Resource -Definitions (CRDs). These objects are used to define and control how your -serverless workload behaves on the cluster: - -- [Service](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#service): - The `service.serving.knative.dev` resource automatically manages the whole - lifecycle of your workload. It controls the creation of other objects to - ensure that your app has a route, a configuration, and a new revision for each - update of the service. Service can be defined to always route traffic to the - latest revision or to a pinned revision. -- [Route](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#route): - The `route.serving.knative.dev` resource maps a network endpoint to one or - more revisions. You can manage the traffic in several ways, including - fractional traffic and named routes. -- [Configuration](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#configuration): - The `configuration.serving.knative.dev` resource maintains the desired state - for your deployment. It provides a clean separation between code and - configuration and follows the Twelve-Factor App methodology. Modifying a - configuration creates a new revision. -- [Revision](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#revision): - 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 useful. Knative - Serving Revisions can be automatically scaled up and down according to - incoming traffic. See - [Configuring the Autoscaler](autoscaling/README.md) for more - information. - -![Diagram that displays how the Serving resources coordinate with each other.](https://github.com/knative/serving/raw/main/docs/spec/images/object_model.png) - ## Getting Started To get started with Serving, check out one of the [hello world](../samples/serving.md) @@ -55,8 +27,6 @@ With the `Service` resource, a deployed service will automatically have a matching route and configuration created. Each time the `Service` is updated, a new revision is created. -For more information on the resources and their interactions, see the [Resource Types Overview](https://github.com/knative/specs/blob/main/specs/serving/overview.md) in the Knative Serving repository. - ## More samples and demos - [Knative Serving code samples](../samples/serving.md) diff --git a/docs/snippets/about-eventing.md b/docs/snippets/about-eventing.md new file mode 100644 index 00000000000..7baf320d703 --- /dev/null +++ b/docs/snippets/about-eventing.md @@ -0,0 +1,9 @@ + +Knative Eventing is a collection of APIs that enable you to use an [event-driven architecture](https://en.wikipedia.org/wiki/Event-driven_architecture){target=_blank} with your applications. You can use these APIs to create components that route events from event producers to event consumers, known as sinks, that receive events. Sinks can also be configured to respond to HTTP requests by sending a response event. + +Knative Eventing uses standard HTTP POST requests to send and receive events between event producers and sinks. These events conform to the [CloudEvents specifications](https://cloudevents.io/){target=_blank}, which enables creating, parsing, sending, and receiving events in any programming language. + +Knative Eventing components are loosely coupled, and can be developed and deployed independently of each other. Any producer can generate events before there are active event consumers that are listening for those events. Any event consumer can express interest in a class of events before there are producers that are creating those events. diff --git a/docs/snippets/about-serving.md b/docs/snippets/about-serving.md new file mode 100644 index 00000000000..26be2d3b3fd --- /dev/null +++ b/docs/snippets/about-serving.md @@ -0,0 +1,38 @@ + +Knative Serving defines a set of objects as Kubernetes Custom Resource +Definitions (CRDs). These resources are used to define and control how your +serverless workload behaves on the cluster. + +The primary Knative Serving resources are Services, Routes, Configurations, and Revisions: + +![Diagram that displays how the Serving resources coordinate with each other.](https://github.com/knative/serving/raw/main/docs/spec/images/object_model.png) + +- [Service](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#service){target=_blank}: + The `service.serving.knative.dev` resource automatically manages the whole + lifecycle of your workload. It controls the creation of other objects to + ensure that your app has a route, a configuration, and a new revision for each + update of the service. Service can be defined to always route traffic to the + latest revision or to a pinned revision. + +- [Route](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#route){target=_blank}: + The `route.serving.knative.dev` resource maps a network endpoint to one or + more revisions. You can manage the traffic in several ways, including + fractional traffic and named routes. + +- [Configuration](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#configuration){target=_blank}: + The `configuration.serving.knative.dev` resource maintains the desired state + for your deployment. It provides a clean separation between code and + configuration and follows the Twelve-Factor App methodology. Modifying a + configuration creates a new revision. + +- [Revision](https://github.com/knative/specs/blob/main/specs/serving/knative-api-specification-1.0.md#revision){target=_blank}: + 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 useful. Knative + Serving Revisions can be automatically scaled up and down according to + incoming traffic. + +For more information on the resources and their interactions, see the [Resource Types Overview](https://github.com/knative/specs/blob/main/specs/serving/overview.md){target=_blank} in the `serving` Github repository.