docs/spec/overview.md

Resource Types

The primary resources in the Elafros API are Routes, Revisions, Configurations, and Services:

• A Route provides a named endpoint and a mechanism for routing traffic to

• Revisions, which are immutable snapshots of code + config, created by a

• Configuration, which acts as a stream of environments for Revisions.

• Service acts as a top-level container for managing the set of Routes and Configurations which implement a network service.

Route

Route provides a network endpoint for a user's service (which consists of a series of software and configuration Revisions over time). A kubernetes namespace can have multiple routes. The route provides a long-lived, stable, named, HTTP-addressable endpoint that is backed by one or more Revisions. The default configuration is for the route to automatically route traffic to the latest revision created by a Configuration. For more complex scenarios, the API supports splitting traffic on a percentage basis, and CI tools could maintain multiple configurations for a single route (e.g. "golden path" and “experiments”) or reference multiple revisions directly to pin revisions during an incremental rollout and n-way traffic split. The route can optionally assign addressable subdomains to any or all backing revisions.

Revision

Revision is an immutable snapshot of code and configuration. A 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

A Configuration describes the desired latest Revision state, and creates and tracks the status of Revisions as the desired state is updated. A configuration might include instructions on how to transform a source package (either git repo or archive) into a container by referencing a Build, or might simply reference a container image and associated execution metadata needed by the Revision. On updates to a Configuration, a new build and/or deployment (creating a Revision) may be performed; the Configuration's controller will track the status of created Revisions and makes both the most recently created and most recently ready (i.e. healthy) Revision available in the status section.

Service

A Service encapsulates a set of Routes and Configurations which together provide a software component. Service exists to provide a singular abstraction which can be access controlled, reasoned about, and which encapsulates software lifecycle decisions such as rollout policy and team resource ownership. Service acts only as an orchestrator of the underlying Routes and Configurations (much as a kubernetes Deployment orchestrates ReplicaSets), and its usage is optional but recommended.

Orchestration

The system will be configured to disallow users from creating (NYI) 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
• 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 service creates both a route and a configuration with the same name as the service. Update operations on the service enable scenarios such as:

• "Push code, keep config": Specifying a new revision with updated source, inheriting configuration such as env vars from the configuration.
• "Update config, keep code": Specifying a new revision as just a change to configuration, such as updating an env variable, inheriting all other configuration and source/image.
• "Execute a manual rollout": Updating the service when in pinned rollout mode allows manual testing of a revision before making it live.

Using a Service object to orchestrate the creation a both route and configuration allows deployment of code (e.g. from a github button) to avoid needing to reason about sequencing and failure modes of parallel resource creation. The sample API usage section illustrates conventional usage of the API.