Service docs (#685)

* Initial checkin of Service docs (aka "Steve")

* Partial checkpoint on updating spec

* Add service to images

Adds Service to images

* Update the rest of examples

* Reorder errors to group logically into deployment and routing errors.

Introduce Service error documentation, and structure error blocks to show how Service aggregates errors from Route and Configuration.

* Address small comments from @vaikas-google and @mattmoor. Did not refactor service.pinned behavior.

docs/overview/elafros-api-objects.md

@@ -10,6 +10,9 @@
 * Route
   * Assigns traffic to Revisions (fractional scaling or by name).
   * Built using [Istio](https://istio.io/docs/).
+* Service
+  * Acts as a top-level controller to orchestrate Route and Configuration.
+  * Provides a simple entry point for UI and CLI tooling to achieve common behavior.
 * Build
   * Executes builds.
 

docs/overview/elafros-api-service.md

@@ -0,0 +1,12 @@
+# API Objects - Service
+
+* Orchestrates Routes and Configurations to support higher-level tooling.
+  * Configuration of code + inbound routing in a single API call.
+  * Definition of specific common rollout policies
+    * Automatic (latest) rollout
+    * Manual rollout
+    * Extensible for other rollout strategies which might be requested
+  * Provides a top-level resource for graphical UI to key off of.
+* Recommended starting point for Elafros use, as it provides "guide rails" to avoid unusual and non-idiomatic usage.
+  * Mirrors labels and annotations to the created objects.
+  * Advanced scenarios may require disconnecting the Service ownership of the created Route and Configuration.

docs/overview/elafros-code-layout-controller.md

@@ -1,6 +1,6 @@
 # Code layout - Controller
 
-* ./pkg/controller/{route,configuration,revision}/controller.go
-* sync_handler the main method for reconcile
+* `./pkg/controller/{configuration,revision,route,service}/controller.go`
+* `sync_handler` is the main method for reconcile
 * Other resource creation broken into their own files in those directories
-* Communicates information via [resource].status field
+* Communicates information via `[resource].status` field

docs/overview/elafros-code-layout-webhook.md

@@ -1,11 +1,11 @@
 # Code layout - Webhook
 
-* ./pkg/webhook/webhook.go
+* `./pkg/webhook/webhook.go`
   * All the generic mutations / validations
   * Serialization / deserialization
 * Calls into resource specific validation / mutation
-  * ./pkg/webhook/{route,revision,configuration}
+  * `./pkg/webhook/{configuration,revision,route,service}`
 * Mutations specified with an array of jsonpatch objects
-* ./pkg/webhook/certs.go
+* `./pkg/webhook/certs.go`
   * CA / Server cert 
 

docs/overview/index.md

@@ -7,6 +7,7 @@
   * [Configuration](./elafros-api-configuration.md)
   * [Revision](./elafros-api-revision.md)
   * [Route](./elafros-api-route.md)
+  * [Service](./elafros-api-service.md)
 * [Components](./elafros-components.md)
 * Code layout
   * [Resources](./elafros-code-layout-resources.md)