diff --git a/spec/overview.md b/spec/overview.md index f8bd77de8..edc05cd9e 100644 --- a/spec/overview.md +++ b/spec/overview.md @@ -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 diff --git a/spec/spec.md b/spec/spec.md index eac1124db..fdc38fe91 100644 --- a/spec/spec.md +++ b/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&..."