From 772552dbb7da07b4571d49cad364fa3bce11a1db Mon Sep 17 00:00:00 2001 From: mattmoor-sockpuppet Date: Mon, 5 Aug 2019 07:15:55 -0700 Subject: [PATCH] Format markdown (#1647) Produced via: `prettier --write --prose-wrap=always $(find -name '*.md' | grep -v vendor | grep -v .github)` /assign @samodell --- docs/eventing/choice.md | 26 +- docs/eventing/samples/choice/README.md | 18 +- .../samples/choice/multiple-cases/README.md | 50 +- .../choice/mutual-exclusivity/README.md | 49 +- .../sequence-with-broker-trigger/README.md | 25 +- docs/serving/fluentd-requirements.md | 6 +- .../spec/knative-api-specification-1.0.md | 622 ++++++++++-------- docs/serving/using-a-tls-cert.md | 3 +- 8 files changed, 449 insertions(+), 350 deletions(-) diff --git a/docs/eventing/choice.md b/docs/eventing/choice.md index 78ed79a6e..5803aef3d 100644 --- a/docs/eventing/choice.md +++ b/docs/eventing/choice.md @@ -16,24 +16,26 @@ Choice creates `Channel`s and `Subscription`s under the hood. Choice has three parts for the Spec: -1. `cases` defines the list of `filter` and `subscriber` pairs, one per - branch, and optionally a `reply` object. For each branch: - 1. the `filter` is evaluated and when it returns an event the `subscriber` is executed. - Both `filter` and `subscriber` must be `Callable`. - 1. the event returned by the `subscriber` is sent to the branch `reply` object. When - the `reply` is empty, the event is sent to the `spec.reply` object (see below). -1. (optional) `channelTemplate` defines the Template which will be used to create - `Channel`s. -1. (optional) `reply` defines where the result of each branch is sent to when the branch does - not have its own `reply` object. +1. `cases` defines the list of `filter` and `subscriber` pairs, one per branch, + and optionally a `reply` object. For each branch: + 1. the `filter` is evaluated and when it returns an event the `subscriber` is + executed. Both `filter` and `subscriber` must be `Callable`. + 1. the event returned by the `subscriber` is sent to the branch `reply` + object. When the `reply` is empty, the event is sent to the `spec.reply` + object (see below). +1. (optional) `channelTemplate` defines the Template which will be used to + create `Channel`s. +1. (optional) `reply` defines where the result of each branch is sent to when + the branch does not have its own `reply` object. ### Choice Status Choice has three parts for the Status: 1. Conditions which detail the overall Status of the Choice object -1. IngressChannelStatus and CaseStatuses which convey the Status - of underlying `Channel` and `Subscription` resource that are created as part of this Choice. +1. IngressChannelStatus and CaseStatuses which convey the Status of underlying + `Channel` and `Subscription` resource that are created as part of this + Choice. 1. AddressStatus which is exposed so that Choice can be used where Addressable can be used. Sending to this address will target the `Channel` which is fronting this Choice (same as `IngressChannelStatus`). diff --git a/docs/eventing/samples/choice/README.md b/docs/eventing/samples/choice/README.md index c8825d9ef..67542771e 100644 --- a/docs/eventing/samples/choice/README.md +++ b/docs/eventing/samples/choice/README.md @@ -1,14 +1,16 @@ -The following examples will help you understand how to use Choice -to describe various flows. +The following examples will help you understand how to use Choice to describe +various flows. ## Prerequisites All examples require: -- A Kubernetes cluster with - - Knative Eventing v0.8+ - - Knative Service v0.8+ -All examples are using the [default channel template](../../channels/default-channels.md). +- A Kubernetes cluster with + - Knative Eventing v0.8+ + - Knative Service v0.8+ + +All examples are using the +[default channel template](../../channels/default-channels.md). ## Examples @@ -16,10 +18,10 @@ For each of these examples below, we'll use [`CronJobSource`](../cronjob-source/README.md) as the source of events. We also use simple -[functions](https://github.com/lionelvillard/knative-functions) to perform trivial filtering, transformation and routing of the incoming events. +[functions](https://github.com/lionelvillard/knative-functions) to perform +trivial filtering, transformation and routing of the incoming events. The examples are: - [Choice with multiple cases and global reply](./multiple-cases/README.md) - [Choice with mutually exclusive cases](./mutual-exclusivity/README.md) - diff --git a/docs/eventing/samples/choice/multiple-cases/README.md b/docs/eventing/samples/choice/multiple-cases/README.md index 3c7066c8d..4e5879a57 100644 --- a/docs/eventing/samples/choice/multiple-cases/README.md +++ b/docs/eventing/samples/choice/multiple-cases/README.md @@ -1,4 +1,5 @@ We are going to create a Choice with two cases: + - the first case accepts events with a time that is is even - the second case accepts events with a time that is is odd @@ -10,7 +11,8 @@ Please refer to the sample overview for the [prerequisites](../README.md). ### Create the Knative Services -Let's first create the filter and transformer services that we will use in our Choice. +Let's first create the filter and transformer services that we will use in our +Choice. ```yaml apiVersion: serving.knative.dev/v1alpha1 @@ -90,26 +92,26 @@ spec: apiVersion: messaging.knative.dev/v1alpha1 kind: InMemoryChannel cases: - - filter: - ref: - apiVersion: serving.knative.dev/v1alpha1 - kind: Service - name: even-filter - subscriber: - ref: - apiVersion: serving.knative.dev/v1alpha1 - kind: Service - name: even-transformer - - filter: - ref: - apiVersion: serving.knative.dev/v1alpha1 - kind: Service - name: odd-filter - subscriber: - ref: - apiVersion: serving.knative.dev/v1alpha1 - kind: Service - name: odd-transformer + - filter: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: even-filter + subscriber: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: even-transformer + - filter: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: odd-filter + subscriber: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: odd-transformer reply: apiVersion: serving.knative.dev/v1alpha1 kind: Service @@ -146,8 +148,8 @@ kubectl create -f ./cron-source.yaml ### Inspecting the results You can now see the final output by inspecting the logs of the event-display -pods. Note that since we set the `CronJobSource` to emit every minute, it -might take some time for the events to show up in the logs. +pods. Note that since we set the `CronJobSource` to emit every minute, it might +take some time for the events to show up in the logs. Let's look at the `event-display` log: @@ -184,4 +186,4 @@ Data, { "message": "this is odd!" } -``` \ No newline at end of file +``` diff --git a/docs/eventing/samples/choice/mutual-exclusivity/README.md b/docs/eventing/samples/choice/mutual-exclusivity/README.md index ba9b2ac37..666f950a2 100644 --- a/docs/eventing/samples/choice/mutual-exclusivity/README.md +++ b/docs/eventing/samples/choice/mutual-exclusivity/README.md @@ -1,8 +1,11 @@ -In this example, we are going to see how we can create a Choice -with mutually exclusive cases. +In this example, we are going to see how we can create a Choice with mutually +exclusive cases. -This example is the same as the [multiple cases example](../multiple-cases/README.md) except -that we are now going to rely on the Knative [switcher](https://github.com/lionelvillard/knative-functions#switcher) function to provide a soft mutual exclusivity guarantee. +This example is the same as the +[multiple cases example](../multiple-cases/README.md) except that we are now +going to rely on the Knative +[switcher](https://github.com/lionelvillard/knative-functions#switcher) function +to provide a soft mutual exclusivity guarantee. NOTE: this example has to be deployed in the default namespace. @@ -12,7 +15,8 @@ Please refer to the sample overview for the [prerequisites](../README.md). ### Create the Knative Services -Let's first create the switcher and transformer services that we will use in our Choice. +Let's first create the switcher and transformer services that we will use in our +Choice. ```yaml apiVersion: serving.knative.dev/v1alpha1 @@ -79,20 +83,20 @@ spec: apiVersion: messaging.knative.dev/v1alpha1 kind: InMemoryChannel cases: - - filter: - uri: "http://me-even-odd-switcher.default.svc.cluster.local/0" - subscriber: - ref: - apiVersion: serving.knative.dev/v1alpha1 - kind: Service - name: me-even-transformer - - filter: - uri: "http://me-even-odd-switcher.default.svc.cluster.local/1" - subscriber: - ref: - apiVersion: serving.knative.dev/v1alpha1 - kind: Service - name: me-odd-transformer + - filter: + uri: "http://me-even-odd-switcher.default.svc.cluster.local/0" + subscriber: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: me-even-transformer + - filter: + uri: "http://me-even-odd-switcher.default.svc.cluster.local/1" + subscriber: + ref: + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + name: me-odd-transformer reply: apiVersion: serving.knative.dev/v1alpha1 kind: Service @@ -128,9 +132,9 @@ kubectl create -f ./cron-source.yaml ### Inspecting the results -You can now see the final output by inspecting the logs of the `me-event-display` -pods. Note that since we set the `CronJobSource` to emit every minute, it -might take some time for the events to show up in the logs. +You can now see the final output by inspecting the logs of the +`me-event-display` pods. Note that since we set the `CronJobSource` to emit +every minute, it might take some time for the events to show up in the logs. Let's look at the `me-event-display` log: @@ -168,4 +172,3 @@ Data, "message": "this is odd!" } ``` - diff --git a/docs/eventing/samples/sequence/sequence-with-broker-trigger/README.md b/docs/eventing/samples/sequence/sequence-with-broker-trigger/README.md index 470a49d59..e38f3fb29 100644 --- a/docs/eventing/samples/sequence/sequence-with-broker-trigger/README.md +++ b/docs/eventing/samples/sequence/sequence-with-broker-trigger/README.md @@ -39,10 +39,10 @@ spec: template: spec: containers: - - image: us.gcr.io/probable-summer-223122/cmd-03315b715ae8f3e08e3a9378df706fbb@sha256:2656f39a7fcb6afd9fc79e7a4e215d14d651dc674f38020d1d18c6f04b220700 - env: - - name: STEP - value: "0" + - image: us.gcr.io/probable-summer-223122/cmd-03315b715ae8f3e08e3a9378df706fbb@sha256:2656f39a7fcb6afd9fc79e7a4e215d14d651dc674f38020d1d18c6f04b220700 + env: + - name: STEP + value: "0" --- apiVersion: serving.knative.dev/v1alpha1 @@ -53,10 +53,10 @@ spec: template: spec: containers: - - image: us.gcr.io/probable-summer-223122/cmd-03315b715ae8f3e08e3a9378df706fbb@sha256:2656f39a7fcb6afd9fc79e7a4e215d14d651dc674f38020d1d18c6f04b220700 - env: - - name: STEP - value: "1" + - image: us.gcr.io/probable-summer-223122/cmd-03315b715ae8f3e08e3a9378df706fbb@sha256:2656f39a7fcb6afd9fc79e7a4e215d14d651dc674f38020d1d18c6f04b220700 + env: + - name: STEP + value: "1" --- apiVersion: serving.knative.dev/v1alpha1 kind: Service @@ -66,12 +66,13 @@ spec: template: spec: containers: - - image: us.gcr.io/probable-summer-223122/cmd-03315b715ae8f3e08e3a9378df706fbb@sha256:2656f39a7fcb6afd9fc79e7a4e215d14d651dc674f38020d1d18c6f04b220700 - env: - - name: STEP - value: "2" + - image: us.gcr.io/probable-summer-223122/cmd-03315b715ae8f3e08e3a9378df706fbb@sha256:2656f39a7fcb6afd9fc79e7a4e215d14d651dc674f38020d1d18c6f04b220700 + env: + - name: STEP + value: "2" --- + ``` ```shell diff --git a/docs/serving/fluentd-requirements.md b/docs/serving/fluentd-requirements.md index 31e23c0a9..6e63a836e 100644 --- a/docs/serving/fluentd-requirements.md +++ b/docs/serving/fluentd-requirements.md @@ -48,8 +48,8 @@ Kubernetes cluster has access to. See [Setting Up A Logging Plugin](./setting-up-a-logging-plugin.md) for details. > **NOTE**: Operators must add the credentials file the Stackdriver agent needs -> to the Docker image if their Knative Serving is not built on a -> Google Cloud Platform-based cluster or if they want to send logs to another -> Google Cloud Platform project. See +> to the Docker image if their Knative Serving is not built on a Google Cloud +> Platform-based cluster or if they want to send logs to another Google Cloud +> Platform project. See > [here](https://cloud.google.com/logging/docs/agent/authorization) for more > information. diff --git a/docs/serving/spec/knative-api-specification-1.0.md b/docs/serving/spec/knative-api-specification-1.0.md index ba88ef042..09bc8c621 100644 --- a/docs/serving/spec/knative-api-specification-1.0.md +++ b/docs/serving/spec/knative-api-specification-1.0.md @@ -1,7 +1,7 @@ # Knative Serving API Specification -Authors: [argent@google.com](mailto:argent@google.com), [dangerd@google.com](mailto:dangerd@google.com) - +Authors: [argent@google.com](mailto:argent@google.com), +[dangerd@google.com](mailto:dangerd@google.com) @@ -44,41 +44,83 @@ APPROVED

# Abstract -The Knative serving platform provides common abstractions for managing request-driven, short-lived, stateless compute resources in the style of common FaaS and PaaS offerings. This document describes the structure, lifecycle and management of Knative resources in the context of the [Kubernetes Resource Model](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md). An understanding of the Kubernetes API interface and the capabilities of [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) is assumed. The Knative Serving API surface aims to support the following additional constraints beyond the general Kubernetes model: +The Knative serving platform provides common abstractions for managing +request-driven, short-lived, stateless compute resources in the style of common +FaaS and PaaS offerings. This document describes the structure, lifecycle and +management of Knative resources in the context of the +[Kubernetes Resource Model](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md). +An understanding of the Kubernetes API interface and the capabilities of +[Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +is assumed. The Knative Serving API surface aims to support the following +additional constraints beyond the general Kubernetes model: +- Client-side orchestration should not be required for common operations such as + deployment, rollback, or simple imperative updates ("change environment + variable X"). +- Both declarative (aka GitOps) and imperative (command-driven) management of + resources should be usable, though not on the same resources at the same time. + (I.e. one application may use a checked-in configuration which is + automatically pushed, while a different application may be pushed and updated + by hand with the authoritative state living on the server.) +- Developers can effectively use the Knative Serving stack without needing to + engage beyond the core Knative resource model. Conversely, platform operators + may restrict developers (e.g. via RBAC) to only be able to operate on the core + Knative Serving resources, and may provide additional abstractions to manage + platform-specific settings. +- The Knative Serving API may be deployed in a single-tenant or multi-tenant + environment; it is assumed that developers may not have access to multiple + namespaces or any cluster-level resources. +This document does not define the +[runtime contract (see this document)](https://github.com/knative/serving/blob/master/docs/runtime-contract.md) +nor prescribe specific implementations of supporting services such as access +control, observability, or resource management. -* Client-side orchestration should not be required for common operations such as deployment, rollback, or simple imperative updates ("change environment variable X"). -* Both declarative (aka GitOps) and imperative (command-driven) management of resources should be usable, though not on the same resources at the same time. (I.e. one application may use a checked-in configuration which is automatically pushed, while a different application may be pushed and updated by hand with the authoritative state living on the server.) -* Developers can effectively use the Knative Serving stack without needing to engage beyond the core Knative resource model. Conversely, platform operators may restrict developers (e.g. via RBAC) to only be able to operate on the core Knative Serving resources, and may provide additional abstractions to manage platform-specific settings. -* The Knative Serving API may be deployed in a single-tenant or multi-tenant environment; it is assumed that developers may not have access to multiple namespaces or any cluster-level resources. - -This document does not define the [runtime contract (see this document)](https://github.com/knative/serving/blob/master/docs/runtime-contract.md) nor prescribe specific implementations of supporting services such as access control, observability, or resource management. - -This document makes reference in a few places to different profiles for Knative Serving installations. A profile in this context is a set of operations, resources, and fields that are accessible to a developer interacting with a Knative installation. Currently, only a single (minimal) profile for Knative Serving is defined, but additional profiles may be defined in the future to standardize advanced functionality. A minimal profile is one that implements all of the "MUST", "MUST NOT", and "REQUIRED" conditions of this document. - +This document makes reference in a few places to different profiles for Knative +Serving installations. A profile in this context is a set of operations, +resources, and fields that are accessible to a developer interacting with a +Knative installation. Currently, only a single (minimal) profile for Knative +Serving is defined, but additional profiles may be defined in the future to +standardize advanced functionality. A minimal profile is one that implements all +of the "MUST", "MUST NOT", and "REQUIRED" conditions of this document. # Background -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). - -There is no formal specification of the Kubernetes API and Resource Model. This document assumes Kubernetes 1.13 behavior; this behavior will typically be supported by many future Kubernetes versions. Additionally, this document may reference specific core Kubernetes resources; these references may be illustrative (i.e. _an implementation on Kubernetes_) or descriptive (i.e. _this Kubernetes resource MUST be exposed_). References to these core Kubernetes resources will be annotated as either illustrative or descriptive. - -This document considers two users of a given Knative Serving environment, and is particularly concerned with the expectations of developers (and language and tooling developers, by extension) deploying applications to the environment. - - - -* **Developers** write code which is packaged into a container which is run on the Knative Serving cluster. - * **Language and tooling developers** typically write tools used by developers to package code into containers. As such, they are concerned that tooling which wraps developer code to produce resources which match the Knative API contract. -* **Operators** (also known as **platform providers**) provision the compute resources and manage the software configuration of Knative Serving and the underlying abstractions (for example: Linux, Kubernetes, Istio, etc). +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be +interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). +There is no formal specification of the Kubernetes API and Resource Model. This +document assumes Kubernetes 1.13 behavior; this behavior will typically be +supported by many future Kubernetes versions. Additionally, this document may +reference specific core Kubernetes resources; these references may be +illustrative (i.e. _an implementation on Kubernetes_) or descriptive (i.e. _this +Kubernetes resource MUST be exposed_). References to these core Kubernetes +resources will be annotated as either illustrative or descriptive. +This document considers two users of a given Knative Serving environment, and is +particularly concerned with the expectations of developers (and language and +tooling developers, by extension) deploying applications to the environment. +- **Developers** write code which is packaged into a container which is run on + the Knative Serving cluster. + - **Language and tooling developers** typically write tools used by developers + to package code into containers. As such, they are concerned that tooling + which wraps developer code to produce resources which match the Knative API + contract. +- **Operators** (also known as **platform providers**) provision the compute + resources and manage the software configuration of Knative Serving and the + underlying abstractions (for example: Linux, Kubernetes, Istio, etc). # RBAC Profile -In order to validate the controls described in [Resource Overview](#resource-overview), the following Kubernetes RBAC profile may be applied in a Kubernetes cluster. This Kubernetes RBAC is an illustrative example of the minimal profile rather than a requirement. This Role should be sufficient to develop, deploy, and manage a set of serving applications within a single namespace. Knative Conformance tests against "MUST", "MUST NOT", and "REQUIRED" conditions are expected to pass when using this profile: - +In order to validate the controls described in +[Resource Overview](#resource-overview), the following Kubernetes RBAC profile +may be applied in a Kubernetes cluster. This Kubernetes RBAC is an illustrative +example of the minimal profile rather than a requirement. This Role should be +sufficient to develop, deploy, and manage a set of serving applications within a +single namespace. Knative Conformance tests against "MUST", "MUST NOT", and +"REQUIRED" conditions are expected to pass when using this profile: ```yaml apiVersion: rbac.authorization.k8s.io/v1 @@ -86,25 +128,34 @@ kind: Role metadata: name: knative-developer rules: -- apiGroups: ["serving.knative.dev"] - resources: ["services"] - verbs: ["get", "list", "create", "update", "delete"] -- apiGroups: ["serving.knative.dev"] - resources: ["configurations", "routes", "revisions"] - verbs: ["get", "list"] + - apiGroups: ["serving.knative.dev"] + resources: ["services"] + verbs: ["get", "list", "create", "update", "delete"] + - apiGroups: ["serving.knative.dev"] + resources: ["configurations", "routes", "revisions"] + verbs: ["get", "list"] ``` - - # Resource Overview -The Knative Serving API provides a set of [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) to manage stateless request-triggered (i.e. on-demand) autoscaled containers. Knative Serving assumes the use of HTTP (including HTTP/2 and layered protocols such as [gRPC](https://grpc.io/)) as a request transport. In addition to low-level scaling and routing objects, Knative Serving provides a high-level Service object to reduce the cognitive overhead for application developers – the Service object should provide sufficient controls to cover most of application deployment scenarios (by frequency). - +The Knative Serving API provides a set of +[Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +to manage stateless request-triggered (i.e. on-demand) autoscaled containers. +Knative Serving assumes the use of HTTP (including HTTP/2 and layered protocols +such as [gRPC](https://grpc.io/)) as a request transport. In addition to +low-level scaling and routing objects, Knative Serving provides a high-level +Service object to reduce the cognitive overhead for application developers – the +Service object should provide sufficient controls to cover most of application +deployment scenarios (by frequency). ## Service -The Knative Service represents an instantiation of a single serverless container environment (e.g. a microservice) over time. As such, a Service includes both a network address by which the Service may be reached as well as the application code and configuration needed to run the Service. The following table details which operations must be made available to a developer accessing a Knative Service using a minimal profile: - +The Knative Service represents an instantiation of a single serverless container +environment (e.g. a microservice) over time. As such, a Service includes both a +network address by which the Service may be reached as well as the application +code and configuration needed to run the Service. The following table details +which operations must be made available to a developer accessing a Knative +Service using a minimal profile:
@@ -163,17 +214,29 @@ The Knative Service represents an instantiation of a single serverless container
- -^ Kubernetes only allows JSON merge patch for CRD types. It is recommended that if allowed, at least JSON Merge patch be made available. [JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) - +^ Kubernetes only allows JSON merge patch for CRD types. It is recommended that +if allowed, at least JSON Merge patch be made available. +[JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) ## Revision -The Knative Revision represents a stateless, autoscaling snapshot-in-time of application code and configuration. Revisions enable progressive rollout and rollback of application changes by changing the HTTP routing between Service names and Revision instances. As such, Revisions are generally immutable, except where they may reference mutable core Kubernetes resources such as ConfigMaps and Secrets. Revisions can also be mutated by changes in Revision defaults. Changes to defaults that mutate Revisions are generally syntactic and not semantic. +The Knative Revision represents a stateless, autoscaling snapshot-in-time of +application code and configuration. Revisions enable progressive rollout and +rollback of application changes by changing the HTTP routing between Service +names and Revision instances. As such, Revisions are generally immutable, except +where they may reference mutable core Kubernetes resources such as ConfigMaps +and Secrets. Revisions can also be mutated by changes in Revision defaults. +Changes to defaults that mutate Revisions are generally syntactic and not +semantic. -Developers MUST NOT be able to create Revisions or update Revision `spec` directly; Revisions MUST be created in response to updates to a Configuration `spec`. It is RECOMMENDED that developers are able to force the deletion of Revisions to both handle the possibility of leaked resources as well as for removal of known-bad Revisions to avoid future errors in managing the service. +Developers MUST NOT be able to create Revisions or update Revision `spec` +directly; Revisions MUST be created in response to updates to a Configuration +`spec`. It is RECOMMENDED that developers are able to force the deletion of +Revisions to both handle the possibility of leaked resources as well as for +removal of known-bad Revisions to avoid future errors in managing the service. -The following table details which operations must be made available to a developer accessing a Knative Revision using a minimal profile: +The following table details which operations must be made available to a +developer accessing a Knative Revision using a minimal profile: @@ -232,18 +295,25 @@ The following table details which operations must be made available to a develop
- -^ Kubernetes only allows JSON merge patch for CRD types. It is recommended that if allowed, at least JSON Merge patch be made available. [JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) - +^ Kubernetes only allows JSON merge patch for CRD types. It is recommended that +if allowed, at least JSON Merge patch be made available. +[JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) ## Route -The Knative Route represents the current HTTP request routing state against a set of Revisions. To enable progressive rollout of serverless applications, a Route supports percentage-based request distribution across multiple application code and configuration states (Revisions). +The Knative Route represents the current HTTP request routing state against a +set of Revisions. To enable progressive rollout of serverless applications, a +Route supports percentage-based request distribution across multiple application +code and configuration states (Revisions). -Routes which are owned (controlled) by a Service SHOULD NOT be updated by developers; any changes will be reset by the Service controller. - -The table below details which operations must be made available to a developer accessing a Knative Route using a minimal profile. For any non-minimal profile, the POST, PUT, or DELETE operations MUST be enabled as a group. This ensures that the developer has the ability to control the complete lifecycle of the object from create through deletion. +Routes which are owned (controlled) by a Service SHOULD NOT be updated by +developers; any changes will be reset by the Service controller. +The table below details which operations must be made available to a developer +accessing a Knative Route using a minimal profile. For any non-minimal profile, +the POST, PUT, or DELETE operations MUST be enabled as a group. This ensures +that the developer has the ability to control the complete lifecycle of the +object from create through deletion. @@ -302,18 +372,27 @@ The table below details which operations must be made available to a developer a
- -^ Kubernetes only allows JSON merge patch for CRD types. It is recommended that if allowed, at least JSON Merge patch be made available. [JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) - +^ Kubernetes only allows JSON merge patch for CRD types. It is recommended that +if allowed, at least JSON Merge patch be made available. +[JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) ## Configuration -The Knative Configuration represents the desired future state (after deployments complete) of a single autoscaled container application and configuration. The Configuration provides a template for creating Revisions as the desired state of the application changes. +The Knative Configuration represents the desired future state (after deployments +complete) of a single autoscaled container application and configuration. The +Configuration provides a template for creating Revisions as the desired state of +the application changes. -Configurations which are owned (controlled) by a Service SHOULD NOT be updated by developers; any changes will be reset by the Service controller. These changes MAY still generate side effects such as the creation of additional Revisions. - -The table below details which operations must be made available to a developer accessing a Knative Configuration using a minimal profile. For any advanced profile, the POST, PUT, or DELETE operations MUST be enabled as a group. This ensures that the developer has the ability to control the complete lifecycle of the object from create through deletion. +Configurations which are owned (controlled) by a Service SHOULD NOT be updated +by developers; any changes will be reset by the Service controller. These +changes MAY still generate side effects such as the creation of additional +Revisions. +The table below details which operations must be made available to a developer +accessing a Knative Configuration using a minimal profile. For any advanced +profile, the POST, PUT, or DELETE operations MUST be enabled as a group. This +ensures that the developer has the ability to control the complete lifecycle of +the object from create through deletion. @@ -372,14 +451,19 @@ The table below details which operations must be made available to a developer a
- -^ Kubernetes only allows JSON merge patch for CRD types. It is recommended that if allowed, at least JSON Merge patch be made available. [JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) - +^ Kubernetes only allows JSON merge patch for CRD types. It is recommended that +if allowed, at least JSON Merge patch be made available. +[JSON Merge Patch Spec (RFC 7386)](https://tools.ietf.org/html/rfc7386) # Error Signalling -The Knative API uses the [Kubernetes Conditions convention](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) to communicate errors and problems to the user. Each user-visible resource described in Resource Overview MUST have a `conditions` field in `status`, which must be a list of `Condition` objects of the following form (note that the actual API object types may be named `FooCondition` to allow better code generation and disambiguation between similar fields in the same `apiGroup`): - +The Knative API uses the +[Kubernetes Conditions convention](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties) +to communicate errors and problems to the user. Each user-visible resource +described in Resource Overview MUST have a `conditions` field in `status`, which +must be a list of `Condition` objects of the following form (note that the +actual API object types may be named `FooCondition` to allow better code +generation and disambiguation between similar fields in the same `apiGroup`): @@ -466,116 +550,213 @@ This is the primary key of the Conditions list when viewed as a map.
+Additionally, the resource's `status.conditions` field MUST be managed as +follows to enable clients (particularly user interfaces) to present useful +diagnostic and error message to the user. In the following section, conditions +are referred to by their `type` (aka the string value of the `type` field on the +Condition). -Additionally, the resource's `status.conditions` field MUST be managed as follows to enable clients (particularly user interfaces) to present useful diagnostic and error message to the user. In the following section, conditions are referred to by their `type` (aka the string value of the `type` field on the Condition). +1. Each resource MUST have either a `Ready` condition (for ongoing systems) or + `Succeeded` condition (for resources that run to completion) with + `severity=""`, which MUST use the `True`, `False`, and `Unknown` status + values as follows: - - -1. Each resource MUST have either a `Ready` condition (for ongoing systems) or `Succeeded` condition (for resources that run to completion) with `severity=""`, which MUST use the `True`, `False`, and `Unknown` status values as follows: 1. `False` MUST indicate a failure condition. - 1. `Unknown` SHOULD indicate that reconciliation is not yet complete and success or failure is not yet determined. - 1. `True` SHOULD indicate that the application is fully reconciled and operating correctly. + 1. `Unknown` SHOULD indicate that reconciliation is not yet complete and + success or failure is not yet determined. + 1. `True` SHOULD indicate that the application is fully reconciled and + operating correctly. - `Unknown` and `True` are specified as SHOULD rather than MUST requirements because there may be errors which prevent serving which cannot be determined by the API stack (e.g. DNS record configuration in certain environments). Implementations are expected to treat these as "MUST" for factors within the control of the implementation. + `Unknown` and `True` are specified as SHOULD rather than MUST requirements + because there may be errors which prevent serving which cannot be determined + by the API stack (e.g. DNS record configuration in certain environments). + Implementations are expected to treat these as "MUST" for factors within the + control of the implementation. + +1. For non-`Ready` conditions, any conditions with `severity=""` (aka "Error + conditions") must be aggregated into the "Ready" condition as follows: -1. For non-`Ready` conditions, any conditions with `severity=""` (aka "Error conditions") must be aggregated into the "Ready" condition as follows: 1. If the condition is `False`, `Ready` MUST be `False`. 1. If the condition is `Unknown`, `Ready` MUST be `False` or `Unknown`. - 1. If the condition is `True`, `Ready` may be any of `True`, `False`, or `Unknown`. + 1. If the condition is `True`, `Ready` may be any of `True`, `False`, or + `Unknown`. - Implementations MAY choose to report that `Ready` is `False` or `Unknown` even if all Error conditions report a status of `True` (i.e. there may be additional hidden implementation conditions which feed into the `Ready` condition which are not reported.) + Implementations MAY choose to report that `Ready` is `False` or `Unknown` + even if all Error conditions report a status of `True` (i.e. there may be + additional hidden implementation conditions which feed into the `Ready` + condition which are not reported.) -1. Non-`Ready` conditions with non-error severity MAY be surfaced by the implementation. Examples of `Warning` or `Info` conditions could include: missing health check definitions, scale-to-zero status, or non-fatal capacity limits. - -Conditions type names should be chosen to describe positive conditions where `True` means that the condition has been satisfied. Some conditions may be transient (for example, `ResourcesAllocated` might change between `True` and `False` as an application scales to and from zero). It is RECOMMENDED that transient conditions be indicated with a `severity="Info"`. +1. Non-`Ready` conditions with non-error severity MAY be surfaced by the + implementation. Examples of `Warning` or `Info` conditions could include: + missing health check definitions, scale-to-zero status, or non-fatal + capacity limits. +Conditions type names should be chosen to describe positive conditions where +`True` means that the condition has been satisfied. Some conditions may be +transient (for example, `ResourcesAllocated` might change between `True` and +`False` as an application scales to and from zero). It is RECOMMENDED that +transient conditions be indicated with a `severity="Info"`. # Resource Lifecycle -Revisions are created by updates to the `spec` of Configuration resources, which own the Revision lifecycle. Similarly, Service resources create and own (control) Routes and Configurations. In some profiles, Route and Configuration may be directly created without creating an owning Service; this is considered an advanced environment, as it exposes more concepts and higher-cardinality relationships to the developer. - -This section describes the rules by which the different resources interact. The general Kubernetes model is that of [continuous reconciliation across eventually-consistent resources](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/principles.md#control-logic). +Revisions are created by updates to the `spec` of Configuration resources, which +own the Revision lifecycle. Similarly, Service resources create and own +(control) Routes and Configurations. In some profiles, Route and Configuration +may be directly created without creating an owning Service; this is considered +an advanced environment, as it exposes more concepts and higher-cardinality +relationships to the developer. +This section describes the rules by which the different resources interact. The +general Kubernetes model is that of +[continuous reconciliation across eventually-consistent resources](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/principles.md#control-logic). ### Ownership -In several of the following sections, resources are said to "own" another resource. Ownership indicates that the owned resource is being managed by the owning resource and MUST be recorded using an [OwnerReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#ownerreference-v1-meta) in `metadata.ownerReferences` on the owned resource with `controller` set to `True` and `uid` set to the UID of the owning resource. +In several of the following sections, resources are said to "own" another +resource. Ownership indicates that the owned resource is being managed by the +owning resource and MUST be recorded using an +[OwnerReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#ownerreference-v1-meta) +in `metadata.ownerReferences` on the owned resource with `controller` set to +`True` and `uid` set to the UID of the owning resource. -If the owning resource determines an ownership conflict and does not hold an OwnerReference, the owning resource SHOULD NOT modify the resource, and SHOULD signal the conflict with an error Condition. - -Deleting an owning resource MUST trigger deletion of all owned resources; this deletion MAY be immediate or eventually consistent. This process can be implemented using [Kubernetes cascading deletion](https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/#controlling-how-the-garbage-collector-deletes-dependents). +If the owning resource determines an ownership conflict and does not hold an +OwnerReference, the owning resource SHOULD NOT modify the resource, and SHOULD +signal the conflict with an error Condition. +Deleting an owning resource MUST trigger deletion of all owned resources; this +deletion MAY be immediate or eventually consistent. This process can be +implemented using +[Kubernetes cascading deletion](https://kubernetes.io/docs/concepts/workloads/controllers/garbage-collection/#controlling-how-the-garbage-collector-deletes-dependents). ## Service -When a Service is created, it MUST create and own a Configuration and Route with the same name as the Service. Updates to `spec`, `metadata.labels`, and `metadata.annotations` of the Service MUST be copied to the appropriate Configuration or Route, as follows: +When a Service is created, it MUST create and own a Configuration and Route with +the same name as the Service. Updates to `spec`, `metadata.labels`, and +`metadata.annotations` of the Service MUST be copied to the appropriate +Configuration or Route, as follows: +- `metadata` changes MUST be copied to both Configuration and Route. +- In addition, the `serving.knative.dev/service` label on the Route and + Configuration MUST be set to the name of the Service. +- Additional `labels` and `annotations` on the Configuration and Route not + specified above MUST be removed. +- See the documentation of `spec` in the + [detailed resource fields section](#detailed-resources--v1beta1) for the + mapping of specific `spec` fields to the corresponding fields in Configuration + and Route. - -* `metadata` changes MUST be copied to both Configuration and Route. -* In addition, the `serving.knative.dev/service` label on the Route and Configuration MUST be set to the name of the Service. -* Additional `labels` and `annotations` on the Configuration and Route not specified above MUST be removed. -* See the documentation of `spec` in the [detailed resource fields section](#detailed-resources--v1beta1) for the mapping of specific `spec` fields to the corresponding fields in Configuration and Route. - -Similarly, the Service MUST update its `status` fields based on the corresponding `status` of its owned Route and Configuration. The Service MUST include conditions of `ConfigurationsReady` and `RoutesReady` in addition to the generic `Ready` condition; other conditions MAY also be present. - +Similarly, the Service MUST update its `status` fields based on the +corresponding `status` of its owned Route and Configuration. The Service MUST +include conditions of `ConfigurationsReady` and `RoutesReady` in addition to the +generic `Ready` condition; other conditions MAY also be present. ## Configuration -When a Configuration is created or its `spec` updated, the following steps MUST be taken to create a new Revision (on creation, the previous state for all fields is an empty value): +When a Configuration is created or its `spec` updated, the following steps MUST +be taken to create a new Revision (on creation, the previous state for all +fields is an empty value): +- If the `spec.template` field has changed from the previous state, a new owned + Revision MUST be created. If the Revision name is not provided by the user + through the `spec.template.metadata.name` field, it MUST be system generated. + The system generated name should be treated opaquely as no semantics are + defined. The values of `spec.template.metadata` and `spec.template.spec` MUST + be copied to the newly created Revision. If the Revision cannot be created, + the Configuration MUST signal that the Configuration is not `Ready`. +- `metadata.labels` and `metadata.annotations` from the Configuration MUST NOT + be copied to the newly-created Revision. - -* If the `spec.template` field has changed from the previous state, a new owned Revision MUST be created. If the Revision name is not provided by the user through the `spec.template.metadata.name` field, it MUST be system generated. The system generated name should be treated opaquely as no semantics are defined. The values of `spec.template.metadata` and `spec.template.spec` MUST be copied to the newly created Revision. If the Revision cannot be created, the Configuration MUST signal that the Configuration is not `Ready`. -* `metadata.labels` and `metadata.annotations` from the Configuration MUST NOT be copied to the newly-created Revision. - -Configuration MUST track the status of owned Revisions in order of creation, and report the name of the most recently created Revision in `status.latestCreatedRevisionName` and the name of the most recently created Revision where the `Ready` Condition is `True` in `status.latestReadyRevisionName`. These fields MAY be used by client software and Route objects to determine the status of the Configuration and the best target Revision for requests. - +Configuration MUST track the status of owned Revisions in order of creation, and +report the name of the most recently created Revision in +`status.latestCreatedRevisionName` and the name of the most recently created +Revision where the `Ready` Condition is `True` in +`status.latestReadyRevisionName`. These fields MAY be used by client software +and Route objects to determine the status of the Configuration and the best +target Revision for requests. ## Revision -A Revision is automatically scaled by the underlying infrastructure; a Revision with no referencing Routes MAY be automatically scaled to zero instances and backing resources collected. Additionally, Revisions which are older than the oldest live Revision (referenced by at least one Route or latest for the Configuration) MAY be automatically deleted by the system. - +A Revision is automatically scaled by the underlying infrastructure; a Revision +with no referencing Routes MAY be automatically scaled to zero instances and +backing resources collected. Additionally, Revisions which are older than the +oldest live Revision (referenced by at least one Route or latest for the +Configuration) MAY be automatically deleted by the system. ## Route -Route does not directly own any Knative resources, but may refer to multiple Revisions which will receive incoming requests either directly or through a reference to a Configuration's `status.latestReadyRevisionName` field. In these cases, the Route MAY use a `serving.knative.dev/route` label to indicate that a Configuration or Revision is currently referenced by the Route. This label or other mechanisms MAY be used to prevent user deletion of Revisions referenced by a Route. - +Route does not directly own any Knative resources, but may refer to multiple +Revisions which will receive incoming requests either directly or through a +reference to a Configuration's `status.latestReadyRevisionName` field. In these +cases, the Route MAY use a `serving.knative.dev/route` label to indicate that a +Configuration or Revision is currently referenced by the Route. This label or +other mechanisms MAY be used to prevent user deletion of Revisions referenced by +a Route. # Request Routing -Knative uses fractional host-based HTTP routing to deliver requests to autoscaled instances. Knative Routes specify request routing from HTTP virtual hosts ([Host-header](https://tools.ietf.org/html/rfc7230#section-5.4) based routing) to fractional assignments to Revisions. The following semantics apply to Knative request routing: - - - -* Each [HTTP/1.1 request](https://tools.ietf.org/html/rfc7230#section-6.3) MUST be treated as a separate "request" using the following semantics. -* If supported by the Knative installation, each [HTTP/2 stream](https://tools.ietf.org/html/rfc7540#section-5) MUST be treated as a separate "request" using the following semantics. Note that this maps naturally for [HTTP requests over HTTP/2](https://tools.ietf.org/html/rfc7540#section-8.1), but is also well-defined for other applications like [gRPC](https://grpc.io/). -* DNS Hostnames allocated to Routes MUST be unique. -* DNS Hostnames allocated to Routes SHOULD resolve. [Wildcard DNS records](https://tools.ietf.org/html/rfc4592) associated with a domain assigned to the namespace are the RECOMMENDED implementation. -* Requests to a specific Host MUST be dispatched to Revision instances in accordance with the weights specified in the Route, even if the number of container instances per Revision does not match the weights specified in the Route. -* When a selected Revision does not have available instances, the routing infrastructure MUST hold (delay) requests until an available instance is ready, scheduling a new container instance if needed. This is sometimes referred to as a "cold start". -* Requests which cause a new container instance to be created ("cold start") SHOULD be sent to the initially selected Revision, rather than to a different Revision. -* Multiple simultaneous or subsequent requests from a single client (even over the same TCP connection) MAY be dispatched to different instances or different Revisions (traffic routing MUST NOT be "sticky" in a way which violates the weight distributions). Developers SHOULD NOT assume that subsequent requests from the same client will reach the same application instance. +Knative uses fractional host-based HTTP routing to deliver requests to +autoscaled instances. Knative Routes specify request routing from HTTP virtual +hosts ([Host-header](https://tools.ietf.org/html/rfc7230#section-5.4) based +routing) to fractional assignments to Revisions. The following semantics apply +to Knative request routing: +- Each [HTTP/1.1 request](https://tools.ietf.org/html/rfc7230#section-6.3) MUST + be treated as a separate "request" using the following semantics. +- If supported by the Knative installation, each + [HTTP/2 stream](https://tools.ietf.org/html/rfc7540#section-5) MUST be treated + as a separate "request" using the following semantics. Note that this maps + naturally for + [HTTP requests over HTTP/2](https://tools.ietf.org/html/rfc7540#section-8.1), + but is also well-defined for other applications like [gRPC](https://grpc.io/). +- DNS Hostnames allocated to Routes MUST be unique. +- DNS Hostnames allocated to Routes SHOULD resolve. + [Wildcard DNS records](https://tools.ietf.org/html/rfc4592) associated with a + domain assigned to the namespace are the RECOMMENDED implementation. +- Requests to a specific Host MUST be dispatched to Revision instances in + accordance with the weights specified in the Route, even if the number of + container instances per Revision does not match the weights specified in the + Route. +- When a selected Revision does not have available instances, the routing + infrastructure MUST hold (delay) requests until an available instance is + ready, scheduling a new container instance if needed. This is sometimes + referred to as a "cold start". +- Requests which cause a new container instance to be created ("cold start") + SHOULD be sent to the initially selected Revision, rather than to a different + Revision. +- Multiple simultaneous or subsequent requests from a single client (even over + the same TCP connection) MAY be dispatched to different instances or different + Revisions (traffic routing MUST NOT be "sticky" in a way which violates the + weight distributions). Developers SHOULD NOT assume that subsequent requests + from the same client will reach the same application instance. # Detailed Resources – v1beta1 -The following schema defines a set of REQUIRED or RECOMMENDED resource fields on the Knative resource types. Whether a field is REQUIRED or RECOMMENDED is denoted in the "Schema Requirement" column. Additional `spec` and `status` fields MAY be provided by particular implementations, however it is expected that most extension will be accomplished via the `metadata.labels` and `metadata.annotations` fields, as Knative implementations MAY validate supplied resources against these fields and refuse resources which specify unknown fields. Knative implementations MUST NOT require `spec` fields outside this implementation; to do so would break interoperability between such implementations and implementations which implement validation of field names. - +The following schema defines a set of REQUIRED or RECOMMENDED resource fields on +the Knative resource types. Whether a field is REQUIRED or RECOMMENDED is +denoted in the "Schema Requirement" column. Additional `spec` and `status` +fields MAY be provided by particular implementations, however it is expected +that most extension will be accomplished via the `metadata.labels` and +`metadata.annotations` fields, as Knative implementations MAY validate supplied +resources against these fields and refuse resources which specify unknown +fields. Knative implementations MUST NOT require `spec` fields outside this +implementation; to do so would break interoperability between such +implementations and implementations which implement validation of field names. ## Service - ### Metadata: -Standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#objectmeta-v1-meta) resource. - -Service `labels` and `annotations` MUST be copied to the `labels` and `annotations` on the owned Configuration and Route. Additionally, the owned Configuration and Route MUST have the `serving.knative.dev/service` label set to the name of the Service. +Standard Kubernetes +[meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#objectmeta-v1-meta) +resource. +Service `labels` and `annotations` MUST be copied to the `labels` and +`annotations` on the owned Configuration and Route. Additionally, the owned +Configuration and Route MUST have the `serving.knative.dev/service` label set to +the name of the Service. ### Spec: -
Field Name @@ -615,11 +796,8 @@ Service `labels` and `annotations` MUST be copied to the `labels` and `annotatio
- - ### Status: - - @@ -707,21 +886,25 @@ Service `labels` and `annotations` MUST be copied to the `labels` and `annotatio
FieldName @@ -665,10 +843,11 @@ Service `labels` and `annotations` MUST be copied to the `labels` and `annotatio
address An implementation of the + An implementation of the +Addressable contract (an object with a +url string). -Addressable contract (an object with a url string). A duck-typed interface for loading the delivery address of the destination, copied from the owned Route. The URL provided in address MAY only be internally-routable.
- - ## Configuration - ### Metadata: -Standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#objectmeta-v1-meta) resource. - -Configuration `labels` and `annotations` MUST NOT be copied to the `labels` and `annotations` on newly-created Revisions. Configuration metadata MUST NOT be continuously copied to existing Revisions, which should remain immutable after creation. Additionally, the newly-created Revision MUST have the `serving.knative.dev/configuration` label set to the name of the Configuration. The Revision MUST also have the `serving.knative.dev/configurationGeneration` label set to the Configuration's `metadata.generation` from which this Revision was created. +Standard Kubernetes +[meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#objectmeta-v1-meta) +resource. +Configuration `labels` and `annotations` MUST NOT be copied to the `labels` and +`annotations` on newly-created Revisions. Configuration metadata MUST NOT be +continuously copied to existing Revisions, which should remain immutable after +creation. Additionally, the newly-created Revision MUST have the +`serving.knative.dev/configuration` label set to the name of the Configuration. +The Revision MUST also have the `serving.knative.dev/configurationGeneration` +label set to the Configuration's `metadata.generation` from which this Revision +was created. ### Spec: - -
FieldName @@ -738,26 +921,21 @@ Configuration `labels` and `annotations` MUST NOT be copied to the `labels` and +RevisionTemplateSpec
(Required) -RevisionTemplateSpec -
-(Required) 		A template for the current desired application state. Changes to template will cause a new Revision to be created - + A template for the current desired application state. Changes to template will cause a new Revision to be created as defined in the lifecycle section. + REQUIRED
- - ### Status: - @@ -814,19 +992,16 @@ Configuration `labels` and `annotations` MUST NOT be copied to the `labels` and
FieldName @@ -774,8 +952,8 @@ Configuration `labels` and `annotations` MUST NOT be copied to the `labels` and - See Error Signalling + Used for signalling errors, see link. Condition of type Ready MUST be present.
- - ## Route - ### Metadata: -Standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#objectmeta-v1-meta) resource. - +Standard Kubernetes +[meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#objectmeta-v1-meta) +resource. ### Spec: -
FieldName @@ -852,11 +1027,8 @@ Standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/ge
- - ### Status: - @@ -923,19 +1095,16 @@ Standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/ge
FieldName @@ -873,8 +1045,8 @@ Standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/ge - See Error Signalling + Used for signalling errors, see link. Conditions of types Ready MUST be present. `AllTrafficAssigned`, `IngressReady`, and `CertificateProvisioned` MAY be present.
- - ## Revision - ### Metadata: -Standard Kubernetes [meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#objectmeta-v1-meta) resource. - +Standard Kubernetes +[meta.v1/ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#objectmeta-v1-meta) +resource. ### Spec: - @@ -1020,11 +1190,8 @@ See
FieldName @@ -998,10 +1167,11 @@ Default: 0 The maximum number of concurrent requests being handled by a single instance of containers[0]. The default value is 0, which means that the system decides.

-See +See +Request Routing for more details on what +constitutes a request. -Request Routing for more details on what constitutes a request.

REQUIRED
- - ### Status: - @@ -1071,16 +1238,16 @@ See
FieldName @@ -1041,8 +1208,8 @@ See - See Error Signalling + Used for signalling errors, see link. Conditions of type Ready MUST be present. Conditions of type Active, ContainerHealthy, ResourcesAvailable MAY be present.
- - # Detailed Resource Types - v1beta1 -Although `container,` `volumes,` and types that they reference are based upon core Kubernetes objects, there are additional limitations applied to ensure that created containers can statelessly autoscale. The set of fields that have been determined to be compatible with statelessly scaling are detailed below. Restrictions to the values of the field are noted in the Description column. - +Although `container,` `volumes,` and types that they reference are based upon +core Kubernetes objects, there are additional limitations applied to ensure that +created containers can statelessly autoscale. The set of fields that have been +determined to be compatible with statelessly scaling are detailed below. +Restrictions to the values of the field are noted in the Description column. ## TrafficTarget - - @@ -1154,10 +1321,12 @@ Min: 0
Max: 100 - @@ -1176,11 +1345,8 @@ All percent values in traffic MUST sum to 100.
FieldName @@ -1111,10 +1278,10 @@ Although `container,` `volumes,` and types that they reference are based upon co

(Optional)

ConfigurationName of a configuration to whose latest Revision we will send this portion of traffic. Tracks latestReadyRevisionName for the Configuration. This field is never set in status, only in spec. This is mutually exclusive with revisionName. This field is disallowed when used in - + ConfigurationName of a configuration to whose latest Revision we will send this portion of traffic. Tracks latestReadyRevisionName for the Configuration. This field is never set in status, only in spec. This is mutually exclusive with revisionName. This field is disallowed when used in ServiceSpec. + REQUIRED The + The +percentage of requests which should be allocated from +the main Route domain name to the specified revisionName or +configurationName. -percentage of requests which should be allocated from the main Route domain name to the specified revisionName or configurationName.

All percent values in traffic MUST sum to 100.

- - ## RevisionTemplateSpec - @@ -1210,8 +1376,8 @@ All percent values in traffic MUST sum to 100. @@ -1220,11 +1386,8 @@ All percent values in traffic MUST sum to 100.
FieldName @@ -1197,8 +1363,8 @@ All percent values in traffic MUST sum to 100. - RevisionMetadata + The requested metadata for the Revision. - RevisionSpec + The requested spec for the Revision.
- - ## Container -
FieldName @@ -1438,11 +1601,8 @@ Max: 1
- - ## EnvVar -
FieldName @@ -1493,11 +1653,8 @@ Max: 1
- - ## EnvVarSource -
FieldName @@ -1537,11 +1694,8 @@ Max: 1
- - ## ConfigMapKeySelector -
FieldName @@ -1585,11 +1739,8 @@ Max: 1
- - ## SecretKeySelector -
FieldName @@ -1633,11 +1784,8 @@ Max: 1
- - ## Probe - @@ -1677,8 +1825,8 @@ Max: 1 @@ -1710,8 +1858,8 @@ Max: 1 @@ -1730,11 +1878,8 @@ Max: 1
FieldName @@ -1654,8 +1802,8 @@ Max: 1 - ExecAction + As specified in Kubernetes core/v1.Probe. - HTTPGetAction + As specified in Kubernetes core/v1.Probe. - TCPSocketAction + As specified in Kubernetes core/v1.Probe.
- - ## EnvFromSource - @@ -1774,8 +1919,8 @@ Max: 1 @@ -1784,11 +1929,8 @@ Max: 1
FieldName @@ -1751,8 +1896,8 @@ Max: 1 - ConfigMapEnvSource + As specified in Kubernetes core/v1.EnvFromSource. - SecretEnvSource + As specified in Kubernetes core/v1.EnvFromSource.
- - ## ExecAction -
FieldName @@ -1814,11 +1956,8 @@ Max: 1
- - ## HTTPGetAction - @@ -1875,11 +2014,8 @@ Max: 1
FieldName @@ -1845,8 +1984,8 @@ Max: 1 - HTTPHeader + As specified in Kubernetes core/v1.HTTPGetAction.
- - ## TCPSocketAction -
FieldName @@ -1903,11 +2039,8 @@ Max: 1
- - ## HTTPHeader -
FieldName @@ -1941,11 +2074,8 @@ Max: 1
- - ## ContainerPort -
FieldName @@ -1993,11 +2123,8 @@ Max: 1
- - ## ConfigMapEnvSource -
FieldName @@ -2031,11 +2158,8 @@ Max: 1
- - ## SecretEnvSource -
FieldName @@ -2069,11 +2193,8 @@ Max: 1
- - ## ResourceRequirements -
FieldName @@ -2107,11 +2228,8 @@ Max: 1
- - ## SecurityContext -
FieldName @@ -2135,11 +2253,8 @@ Max: 1
- - ## VolumeMount -
FieldName @@ -2193,11 +2308,8 @@ Max: 1
- - ## Volume - @@ -2227,8 +2339,8 @@ Max: 1 @@ -2240,8 +2352,8 @@ Max: 1 @@ -2250,11 +2362,8 @@ Max: 1
FieldName @@ -2214,8 +2326,8 @@ Max: 1 - ConfigMapVolumeSource + As specified in Kubernetes core/v1.Volume. - SecretVolumeSource + As specified in Kubernetes core/v1.Volume. - ProjectedVolumeSource + As specified in Kubernetes core/v1.Volume.
- - ## ConfigMapVolumeSource -
FieldName @@ -2308,11 +2417,8 @@ Max: 1
- - ## SecretVolumeSource -
FieldName @@ -2366,11 +2472,8 @@ Max: 1
- - ## ProjectedVolumeSource -
FieldName @@ -2404,11 +2507,8 @@ Max: 1
- - ## KeyToPath -
FieldName @@ -2452,11 +2552,8 @@ Max: 1
- - ## VolumeProjection - @@ -2486,8 +2583,8 @@ Max: 1 @@ -2496,11 +2593,8 @@ Max: 1
FieldName @@ -2473,8 +2570,8 @@ Max: 1 - ConfigMapProjection + As specified in Kubernetes core/v1.VolumeProjection. - SecretProjection + As specified in Kubernetes core/v1.VolumeProjection.
- - ## ConfigMapProjection -
FieldName @@ -2544,11 +2638,8 @@ Max: 1
- - ## SecretProjection -
FieldName @@ -2592,11 +2683,8 @@ Max: 1
- - ## [Addressable](https://github.com/knative/pkg/blob/master/apis/duck/v1beta1/addressable_types.go) (Interface) -
FieldName diff --git a/docs/serving/using-a-tls-cert.md b/docs/serving/using-a-tls-cert.md index 4ac37be20..133ff4ccc 100644 --- a/docs/serving/using-a-tls-cert.md +++ b/docs/serving/using-a-tls-cert.md @@ -78,7 +78,8 @@ If you need a new TLS certificate, you can choose to use one of the following tools to obtain a certificate from Let's Encrypt: - Setup Certbot to manually obtain Let's Encrypt certificates -- Setup cert-manager to either manually obtain a certificate, or to automatically provision certificates +- Setup cert-manager to either manually obtain a certificate, or to + automatically provision certificates This page covers details for both of the above options.