mirror of https://github.com/knative/docs.git
Update the API spec and overview to reflect ServingState intent. (#657)
* Update the API spec and overview to reflect ServingState intent. I've reworded the description of a Revision in the overview docs to capture some of the key lifecycle stages a revision may be in. I also found the existing wording confusing, since it talked about "history", which is more a property of configuration that is enabled by retirement, and I think the new wording better captures this. I've updated the specification to include `servingState`, clarify where fields aren't available (pointing to issues), and tweak assorted cosmetic things (e.g. trailing whitespace). Fixes: https://github.com/elafros/elafros/issues/644 * Clarify that blocking Revision creation is NYI (link to issue). * Various code review updated from @evankanderson and @grantr.
This commit is contained in:
Matt Moore
Google Prow Robot
parent
c366b41f51
commit
c885768008
|
|
@ -29,12 +29,18 @@ or all backing revisions.
|
|||
## Revision
|
||||
|
||||
**Revision** is an immutable snapshot of code and configuration. A
|
||||
revision can be created from a pre-built container image or built from
|
||||
source. While there is a history of previous revisions, only those
|
||||
currently referenced by a Route are addressable or routable. Older
|
||||
inactive revisions need not be backed by underlying resources, they
|
||||
exist only as the revision metadata in storage. Revisions are created
|
||||
by updates to a **Configuration**.
|
||||
revision references a container image, and optionally a build that is
|
||||
responsible for materializing that container image from source.
|
||||
Revisions are created by updates to a **Configuration**.
|
||||
|
||||
Revisions that are not addressable via a Route will be *retired*
|
||||
and all underlying K8s resources will be deleted. This provides a
|
||||
lightweight history of the revisions a configuration has produced
|
||||
over time, and enables users to easily rollback to a prior revision.
|
||||
|
||||
Revisions that are addressable via a Route will have resource
|
||||
utilization proportional to the load they are under.
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
|
|
@ -53,18 +59,18 @@ and makes both the most recently created and most recently *ready*
|
|||
|
||||
# Orchestration
|
||||
|
||||
The system will be configured to not allow customer mutations to
|
||||
Revisions. Instead, the creation of immutable Revisions through a
|
||||
Configuration provides:
|
||||
The system will be configured to disallow users from creating
|
||||
([NYI](https://github.com/elafros/elafros/issues/664)) or changing
|
||||
Revisions. Instead, Revisions are created indirectly when a Configuration
|
||||
is created or updated. This provides:
|
||||
|
||||
* a single referenceable resource for the route to perform automated
|
||||
rollouts
|
||||
* a single resource that can be watched to see a history of all the
|
||||
revisions created
|
||||
* (but doesn’t mandate) PATCH semantics for new revisions to be done
|
||||
on the server, minimizing read-modify-write implemented across
|
||||
multiple clients, which could result in optimistic concurrency
|
||||
errors
|
||||
* PATCH semantics for revisions implemented server-side, minimizing
|
||||
read-modify-write implemented across multiple clients, which could result
|
||||
in optimistic concurrency errors
|
||||
* the ability to rollback to a known good configuration
|
||||
|
||||
In the conventional single live revision scenario, a route has a
|
||||
|
|
|
|||
54
spec/spec.md
54
spec/spec.md
|
|
@ -51,10 +51,10 @@ metadata:
|
|||
|
||||
# system generated meta
|
||||
uid: ...
|
||||
resourceVersion: ... # used for optimistic concurrency control
|
||||
creationTimestamp: ...
|
||||
generation: ... # updated only when spec changes; used by observedGeneration
|
||||
selfLink: ...
|
||||
resourceVersion: ... # used for optimistic concurrency control
|
||||
creationTimestamp: ...
|
||||
generation: ... # updated only when spec changes; used by observedGeneration
|
||||
selfLink: ...
|
||||
...
|
||||
spec:
|
||||
traffic:
|
||||
|
|
@ -107,10 +107,10 @@ metadata:
|
|||
|
||||
# system generated meta
|
||||
uid: ...
|
||||
resourceVersion: ... # used for optimistic concurrency control
|
||||
creationTimestamp: ...
|
||||
generation: ... # updated only when spec changes; used by observedGeneration
|
||||
selfLink: ...
|
||||
resourceVersion: ... # used for optimistic concurrency control
|
||||
creationTimestamp: ...
|
||||
generation: ... # updated only when spec changes; used by observedGeneration
|
||||
selfLink: ...
|
||||
...
|
||||
spec:
|
||||
# +optional. composable Build spec, if omitted provide image directly
|
||||
|
|
@ -214,10 +214,10 @@ metadata:
|
|||
elafros.dev/configurationGeneration: ... # generation of configuration that created this Revision
|
||||
# system generated meta
|
||||
uid: ...
|
||||
resourceVersion: ... # used for optimistic concurrency control
|
||||
creationTimestamp: ...
|
||||
generation: ...
|
||||
selfLink: ...
|
||||
resourceVersion: ... # used for optimistic concurrency control
|
||||
creationTimestamp: ...
|
||||
generation: ...
|
||||
selfLink: ...
|
||||
...
|
||||
|
||||
# spec populated by Configuration
|
||||
|
|
@ -225,7 +225,9 @@ spec:
|
|||
# +optional. name of the build.dev/v1alpha1.Build if built from source
|
||||
buildName: ...
|
||||
|
||||
container: # core.v1.Container
|
||||
container: # corev1.Container
|
||||
# We disallow the following fields from corev1.Container:
|
||||
# name, resources, ports, and volumeMounts
|
||||
image: gcr.io/...
|
||||
command: ['run']
|
||||
args: []
|
||||
|
|
@ -237,25 +239,43 @@ spec:
|
|||
- ...
|
||||
livenessProbe: ... # Optional
|
||||
readinessProbe: ... # Optional
|
||||
|
||||
# Name of the service account the code should run as.
|
||||
serviceAccountName: ...
|
||||
|
||||
# The Revision's level of readiness for receiving traffic.
|
||||
# This may not be specified at creation (defaults to Active),
|
||||
# and is used by the controllers and activator to enable
|
||||
# scaling to/from 0.
|
||||
servingState: Active | Reserve | Retired
|
||||
|
||||
# NYI: https://github.com/elafros/elafros/issues/456
|
||||
# Some function or server frameworks or application code may be written to
|
||||
# expect that each request will be granted a single-tenant process to run
|
||||
# (i.e. that the request code is run single-threaded).
|
||||
concurrencyModel: ...
|
||||
|
||||
# NYI: https://github.com/elafros/elafros/issues/457
|
||||
# Many higher-level systems impose a per-request response deadline.
|
||||
timeoutSeconds: ...
|
||||
serviceAccountName: ... # Name of the service account the code should run as.
|
||||
...
|
||||
|
||||
status:
|
||||
# This is a copy of metadata from the container image or grafeas,
|
||||
# indicating the provenance of the revision. This is based on the
|
||||
# container image, but may need further clarification.
|
||||
# container image, but may need further clarification.
|
||||
imageSource:
|
||||
git|gcs: ...
|
||||
|
||||
conditions: # See also the documentation in errors.md
|
||||
- type: Ready
|
||||
status: False
|
||||
message: "Starting Instances"
|
||||
# if built from source:
|
||||
# If spec.buildName is provided
|
||||
- type: BuildComplete
|
||||
status: True
|
||||
# other conditions indicating build failure, if applicable
|
||||
- ...
|
||||
|
||||
# URL for accessing the logs generated by this revision. Note that logs
|
||||
# may still be access controlled separately from access to the API object.
|
||||
logUrl: "logging.infra.mycompany.com/...?filter=revision=myservice-a1e34&..."
|
||||
|
|
|
|||
Loading…
Reference in New Issue