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.

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
+revision references a container image, and optionally a build that is
-source. While there is a history of previous revisions, only those
+responsible for materializing that container image from source.
-currently referenced by a Route are addressable or routable. Older
+Revisions are created by updates to a **Configuration**.
-inactive revisions need not be backed by underlying resources, they
+
-exist only as the revision metadata in storage. Revisions are created
+Revisions that are not addressable via a Route will be *retired*
-by updates to a **Configuration**.
+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
+The system will be configured to disallow users from creating
-Revisions. Instead, the creation of immutable Revisions through a
+([NYI](https://github.com/elafros/elafros/issues/664)) or changing
-Configuration provides:
+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
+* PATCH semantics for revisions implemented server-side, minimizing
-  on the server, minimizing read-modify-write implemented across
+  read-modify-write implemented across multiple clients, which could result
-  multiple clients, which could result in optimistic concurrency
+  in optimistic concurrency errors
-  errors
 * the ability to rollback to a known good configuration
 
 In the conventional single live revision scenario, a route has a

spec/spec.md

@@ -51,10 +51,10 @@ metadata:
  
   # system generated meta
   uid: ...
-  resourceVersion: ...  # used for optimistic concurrency control
+  resourceVersion: ...  # used for optimistic concurrency control
-  creationTimestamp: ... 
+  creationTimestamp: ...
-  generation: ...  # updated only when spec changes; used by observedGeneration
+  generation: ...  # updated only when spec changes; used by observedGeneration
-  selfLink: ...
+  selfLink: ...
   ...
 spec:
   traffic:
@@ -107,10 +107,10 @@ metadata:
   
   # system generated meta
   uid: ...
-  resourceVersion: ...  # used for optimistic concurrency control
+  resourceVersion: ...  # used for optimistic concurrency control
-  creationTimestamp: ...
+  creationTimestamp: ...
-  generation: ...  # updated only when spec changes; used by observedGeneration
+  generation: ...  # updated only when spec changes; used by observedGeneration
-  selfLink: ...
+  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
+  resourceVersion: ...  # used for optimistic concurrency control
-  creationTimestamp: ...
+  creationTimestamp: ...
-  generation: ... 
+  generation: ...
-  selfLink: ...
+  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&..."