mirror of https://github.com/knative/docs.git
Commit API spec and design doc (#444)
Initial copy/commit of Elafros API design doc, chunked into sections. Also includes initial definitions of Elafros personas. Still TODO: - Appendices A-E, which cover extended use cases.
This commit is contained in:
Evan Anderson
GitHub
parent
31c72e9a24
commit
4ee69f36ed
|
|
@ -0,0 +1,96 @@
|
|||
# Elafros Personas
|
||||
|
||||
When discussing user actions, it is often helpful to [define specific
|
||||
user roles](https://en.wikipedia.org/wiki/Persona_(user_experience)) who
|
||||
might want to do the action.
|
||||
|
||||
|
||||
## Elafros Compute
|
||||
|
||||
### Developer Personas
|
||||
|
||||
The developer personas are software engineers looking to build and run
|
||||
a stateless application without concern about the underlying
|
||||
infrastructure.
|
||||
|
||||
* Hobbyist
|
||||
* Backend SWE
|
||||
* Full stack SWE
|
||||
* SRE
|
||||
|
||||
User stories:
|
||||
* Deploy some code
|
||||
* Update environment
|
||||
* Roll back the last change
|
||||
* Debug an error in code
|
||||
* Monitor my application
|
||||
|
||||
### Operator Personas
|
||||
|
||||
* Hobbyist / Contributor
|
||||
* Cluster administrator
|
||||
* Security Engineer / Auditor
|
||||
* Capacity Planner
|
||||
|
||||
User stories:
|
||||
* Create an Elafros cluster
|
||||
* Apply policy / RBAC
|
||||
* Control or charge back for resource usage
|
||||
* Choose logging or monitoring plugins
|
||||
|
||||
|
||||
## Elafros Build
|
||||
|
||||
We expect the build components of Elafros to be useful on their own,
|
||||
as well as in conjunction with the compute components.
|
||||
|
||||
### Developer
|
||||
|
||||
User stories:
|
||||
* Start a build
|
||||
* Read build logs
|
||||
|
||||
### Language operator / contributor
|
||||
|
||||
User stories:
|
||||
* Create a build image / build pack
|
||||
|
||||
|
||||
## Elafros Events
|
||||
|
||||
Event generation and consumption is a core part of the serverless
|
||||
(particularly function as a service) computing model. Event generation
|
||||
and dispatch enables decoupling of event producers from consumers.
|
||||
|
||||
## Event consumer (developer)
|
||||
|
||||
User stories:
|
||||
* Determine what event sources are available
|
||||
* Trigger my service when certain events happen (event binding)
|
||||
* Filter events from a provider
|
||||
|
||||
## Event producer
|
||||
|
||||
User stories:
|
||||
* Publish events
|
||||
* Control who can bind events
|
||||
|
||||
|
||||
## Contributors
|
||||
|
||||
Contributors are an important part of the Elafros project. As such, we
|
||||
will also consider how various infrastructure encourages and enables
|
||||
contributors to the project, as well as the impact on end-users.
|
||||
|
||||
* Hobbyist or newcomer
|
||||
* Motivated user
|
||||
* Corporate (employed) maintainer
|
||||
* Consultant
|
||||
|
||||
User stories:
|
||||
* Check out the code
|
||||
* Build and run the code
|
||||
* Run tests
|
||||
* View test status
|
||||
* Run performance tests
|
||||
|
||||
|
|
@ -0,0 +1,322 @@
|
|||
# Error Conditions and Reporting
|
||||
|
||||
Elafros uses the standard Kubernetes API pattern for reporting
|
||||
configuration errors and current state of the system by writing the
|
||||
report in the `status` section. There are two mechanisms commonly used
|
||||
in status:
|
||||
|
||||
* conditions represent true/false statements about the current state
|
||||
of the resource.
|
||||
|
||||
* other fields may provide status on the most recently retrieved state
|
||||
of the system as it relates to the resource (example: number of
|
||||
replicas or traffic assignments).
|
||||
|
||||
Both of these mechanisms often include additional data from the
|
||||
controller such as `observedGeneration` (to determine whether the
|
||||
controller has seen the latest updates to the spec). Example user and
|
||||
system error scenarios are included below along with how the status is
|
||||
presented to CLI and UI tools via the API.
|
||||
|
||||
* [Revision failed to become Ready](#revision-failed-to-become-ready)
|
||||
* [Build failed](#build-failed)
|
||||
* [Revision not found by Route](#revision-not-found-by-route)
|
||||
* [Configuration not found by Route](#configuration-not-found-by-route)
|
||||
* [Latest Revision of a Configuration deleted](#latest-revision-of-a-configuration-deleted)
|
||||
* [Resource exhausted while creating a revision](#resource-exhausted-while-creating-a-revision)
|
||||
* [Deployment progressing slowly/stuck](#deployment-progressing-slowly-stuck)
|
||||
* [Traffic shift progressing slowly/stuck](#traffic-shift-progressing-slowly-stuck)
|
||||
* [Container image not present in repository](#container-image-not-present-in-repository)
|
||||
* [Container image fails at startup on Revision](#container-image-fails-at-startup-on-revision)
|
||||
|
||||
|
||||
## Revision failed to become Ready
|
||||
|
||||
If the latest Revision fails to become `Ready` for any reason within some reasonable
|
||||
timeframe, the Configuration should signal this
|
||||
with the `LatestRevisionReady` status, copying the reason and the message
|
||||
from the `Ready` condition on the Revision.
|
||||
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
latestReadyRevisionName: abc
|
||||
latestCreatedRevisionName: bcd # Hasn't become "Ready"
|
||||
conditions:
|
||||
- type: LatestRevisionReady
|
||||
status: False
|
||||
reason: ContainerMissing
|
||||
message: "Unable to start because container is missing and build failed."
|
||||
```
|
||||
|
||||
|
||||
## Build failed
|
||||
|
||||
If the Build steps failed while creating a Revision, you can examine
|
||||
the `Failed` condition on the Build or the `BuildFailed` condition on
|
||||
the Revision (which copies the value from the build referenced by
|
||||
`spec.buildName`). In addition, the Build resource (but not the
|
||||
Revision) should have a status field to link to the log output of the
|
||||
build.
|
||||
|
||||
```http
|
||||
GET /apis/build.dev/v1alpha1/namespaces/default/builds/build-1acub3
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
# Link to log stream; could be ELK or Stackdriver, for example
|
||||
buildLogsLink: "http://logging.infra.mycompany.com/...?filter=..."
|
||||
conditions:
|
||||
- type: Failed
|
||||
status: True
|
||||
reason: BuildStepFailed # could also be SourceMissing, etc
|
||||
# reason is a short status, message provides error details
|
||||
message: "Step XYZ failed with error message: $LASTLOGLINE"
|
||||
```
|
||||
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/abc
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: False
|
||||
reason: ContainerMissing
|
||||
message: "Unable to start because container is missing and build failed."
|
||||
- type: BuildFailed
|
||||
status: True
|
||||
reason: BuildStepFailed
|
||||
# reason is a short status, message provides error details
|
||||
message: "Step XYZ failed with error message: $LASTLOGLINE"
|
||||
```
|
||||
|
||||
|
||||
## Revision not found by Route
|
||||
|
||||
If a Revision is referenced in the Route's `spec.rollout.traffic`, the
|
||||
corresponding entry in the `status.traffic` list will be set to "Not
|
||||
found", and the `TrafficDropped` condition will be marked as True,
|
||||
with a reason of `RevisionMissing`.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/routes/abc
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
traffic:
|
||||
- revisionName: abc
|
||||
name: current
|
||||
percent: 100
|
||||
- revisionName: "Not found"
|
||||
name: next
|
||||
percent: 0
|
||||
conditions:
|
||||
- type: RolloutInProgress
|
||||
status: False
|
||||
- type: TrafficDropped
|
||||
status: True
|
||||
reason: RevisionMissing
|
||||
# reason is a short status, message provides error details
|
||||
message: "Revision 'qyzz' referenced in rollout.traffic not found"
|
||||
```
|
||||
|
||||
|
||||
## Configuration not found by Route
|
||||
|
||||
If a Route references the `latestReadyRevisionName` of a Configuration
|
||||
and the Configuration cannot be found, the corresponding entry in
|
||||
`status.traffic` list will be set to "Not found", and the
|
||||
`TrafficDropped` condition will be marked as True with a reason of
|
||||
`ConfigurationMissing`.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/routes/abc
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
traffic:
|
||||
- revisionName: "Not found"
|
||||
percent: 100
|
||||
conditions:
|
||||
- type: RolloutInProgress
|
||||
status: False
|
||||
- type: TrafficDropped
|
||||
status: True
|
||||
reason: ConfigurationMissing
|
||||
# reason is a short status, message provides error details
|
||||
message: "Revision 'my-service' referenced in rollout.traffic not found"
|
||||
```
|
||||
|
||||
|
||||
## Latest Revision of a Configuration deleted
|
||||
|
||||
If the most recent (or most recently ready) Revision is deleted, the
|
||||
Configuration will clear the `latestReadyRevisionName`. If the
|
||||
Configuration is referenced by a Route, the Route will set the
|
||||
`TrafficDropped` condition with reason `RevisionMissing`, as above.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/configurations/my-service
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
metadata:
|
||||
generation: 1234 # only updated when spec changes
|
||||
...
|
||||
spec:
|
||||
...
|
||||
status:
|
||||
latestCreatedRevision: abc
|
||||
conditions:
|
||||
- type: LatestRevisionReady
|
||||
status: False
|
||||
reason: RevisionMissing
|
||||
message: "The latest Revision appears to have been deleted."
|
||||
observedGeneration: 1234
|
||||
```
|
||||
|
||||
|
||||
## Resource exhausted while creating a revision
|
||||
|
||||
Since a Revision is only metadata, the Revision will be created, but
|
||||
will have a condition indicating the underlying failure, possibly
|
||||
indicating the failed underlying resource. In a multitenant
|
||||
environment, the customer might not have have access or visibility
|
||||
into the underlying resources in the hosting environment.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/abc
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: False
|
||||
reason: NoDeployment
|
||||
message: "The controller could not create a deployment named ela-abc-e13ac."
|
||||
```
|
||||
|
||||
|
||||
## Deployment progressing slowly/stuck
|
||||
|
||||
See
|
||||
[the kubernetes documentation for how this is handled for Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#failed-deployment). For
|
||||
Revisions, we will start by assuming a single timeout for deployment
|
||||
(rather than configurable), and report that the Revision was not
|
||||
Ready, with a reason `ProgressDeadlineExceeded`. Note that we will
|
||||
only report `ProgressDeadlineExceeded` if we could not determine
|
||||
another reason (such as quota failures, missing build, or container
|
||||
execution failures).
|
||||
|
||||
Kubernetes controllers will continue attempting to make progress
|
||||
(possibly at a less-aggressive rate) when they encounter a case where
|
||||
the desired status cannot match the actual status, so if the
|
||||
underlying deployment is slow, it might eventually finish after
|
||||
reporting `ProgressDeadlineExceeded`.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/abc
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: False
|
||||
reason: ProgressDeadlineExceeded
|
||||
message: "Unable to create pods for more than 120 seconds."
|
||||
```
|
||||
|
||||
|
||||
## Traffic shift progressing slowly/stuck
|
||||
|
||||
Similar to deployment slowness, if the transfer of traffic (either via
|
||||
gradual or abrupt rollout) takes longer than a certain timeout to
|
||||
complete/update, the `RolloutInProgress` condition will remain at
|
||||
True, but the reason will be set to `ProgressDeadlineExceeded`.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/routes/abc
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
traffic:
|
||||
- revisionName: abc
|
||||
percent: 75
|
||||
- revisionName: def
|
||||
percent: 25
|
||||
conditions:
|
||||
- type: RolloutInProgress
|
||||
status: True
|
||||
reason: ProgressDeadlineExceeded
|
||||
# reason is a short status, message provides error details
|
||||
message: "Unable to update traffic split for more than 120 seconds."
|
||||
```
|
||||
|
||||
|
||||
## Container image not present in repository
|
||||
|
||||
Revisions might be created while a Build is still creating the
|
||||
container image or uploading it to the repository. If the build is
|
||||
being performed by a CRD in the cluster, the spec.buildName attribute
|
||||
will be set (and see the [Build failed](#build-failed) example). In
|
||||
other cases when the build is not supplied, the container image
|
||||
referenced might not be present in the registry (either because of a
|
||||
typo or because it was deleted). In this case, the Ready condition
|
||||
will be set to False with a reason of ContainerMissing. This condition
|
||||
could be corrected if the image becomes available at a later time. We
|
||||
can also make a defensive copy of the container image to avoid this
|
||||
error due to deleted source container.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/abc
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: False
|
||||
reason: ContainerMissing
|
||||
message: "Unable to fetch image 'gcr.io/...': <literal error>"
|
||||
- type: Failed
|
||||
status: True
|
||||
reason: ContainerMissing
|
||||
message: "Unable to fetch image 'gcr.io/...': <literal error>"
|
||||
```
|
||||
|
||||
|
||||
## Container image fails at startup on Revision
|
||||
|
||||
Particularly for development cases with interpreted languages like
|
||||
Node or Python, syntax errors or the like might only be caught at
|
||||
container startup time. For this reason, implementations may choose to
|
||||
start a single copy of the container on deployment, before making the
|
||||
container Ready. If the initial container fails to start, the `Ready`
|
||||
condition will be set to False and the reason will be set to
|
||||
`ExitCode:%d` with the exit code of the application, and the last line
|
||||
of output in the message. Additionally, the Revision will include a
|
||||
`logsUrl` which provides the address of an endpoint which can be used to
|
||||
fetch the logs for the failed process.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/abc
|
||||
```
|
||||
```yaml
|
||||
...
|
||||
status:
|
||||
logUrl: "http://logging.infra.mycompany.com/...?filter=revision=abc&..."
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: False
|
||||
reason: ExitCode:127
|
||||
message: "Container failed with: SyntaxError: Unexpected identifier"
|
||||
```
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
|
|
@ -0,0 +1,22 @@
|
|||
The goal of the Elafros project is to provide a common toolkit and API
|
||||
framework for serverless workloads.
|
||||
|
||||
We define serverless workloads as computing workloads that are:
|
||||
|
||||
* Stateless
|
||||
* Amenable to the process scale-out model
|
||||
* Primarily driven by application level (L7 -- HTTP, for example)
|
||||
request traffic
|
||||
|
||||
While Kubernetes provides basic primitives like Deployment, Service,
|
||||
and Ingress in support of this model, our experience suggests that a
|
||||
more compact and richer opinionated model has substantial benefit for
|
||||
developers. In particular, by standardizing on higher-level primitives
|
||||
which perform substantial amounts of automation of common
|
||||
infrastructure, it should be possible to build consistent toolkits
|
||||
that provide a richer experience than updating yaml files with
|
||||
`kubectl`.
|
||||
|
||||
The Elafros APIs consist of Compute API (these documents),
|
||||
[Build API](https://github.com/elafros/build) and
|
||||
[Eventing API](https://github.com/elafros/eventing).
|
||||
|
|
@ -0,0 +1,929 @@
|
|||
# Sample API Usage
|
||||
|
||||
Following are several normative sample scenarios utilizing the Elafros
|
||||
API. These scenarios are arranged to provide a flavor of the API and
|
||||
building from the smallest, most frequent operations.
|
||||
|
||||
Examples in this section illustrate:
|
||||
|
||||
* [Automatic rollout of a new Revision to an existing Service with a
|
||||
pre-built container](#1--automatic-rollout-of-a-new-revision-to-existing-service---pre-built-container)
|
||||
* [Creating a first route to deploy a first revision from a pre-built
|
||||
container](#2--creating-route-and-deploying-first-revision---pre-built-container)
|
||||
* [Configuration changes and manual rollout
|
||||
options](#3--manual-rollout-of-a-new-revision---config-change-only)
|
||||
* [Creating a revision from source](#4--deploy-a-revision-from-source)
|
||||
* [Creating a function from source](#5--deploy-a-function)
|
||||
|
||||
Note that these API operations are identical for both app and function
|
||||
based services. (to see the full resource definitions, see the
|
||||
[Resource YAML Definitions](spec.md)).
|
||||
|
||||
CLI samples are for illustrative purposes, and not intended to
|
||||
represent final CLI design.
|
||||
|
||||
## 1) Automatic rollout of a new Revision to existing Service - pre-built container
|
||||
|
||||
**_Scenario_**: User deploys a new revision to an existing service
|
||||
with a new container image, rolling out automatically to 100%
|
||||
|
||||
```
|
||||
$ elafros deploy --service my-service
|
||||
Deploying app to service [my-service]:
|
||||
✓ Starting
|
||||
✓ Promoting
|
||||
Done.
|
||||
Deployed to https://my-service.default.mydomain.com
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
|
||||
* Update the Configuration with the config change
|
||||
|
||||
**Results:**
|
||||
|
||||
* A new Revision is created, and automatically rolled out to 100% once
|
||||
ready
|
||||
|
||||
|
||||
|
||||
|
||||
After the initial Route and Configuration have been created (which is
|
||||
shown in the [second example](TODO)), the typical
|
||||
interaction is to update the revision configuration, resulting in the
|
||||
creation of a new revision, which will be automatically rolled out by
|
||||
the route. Revision configuration updates can be handled as either a
|
||||
PUT or PATCH operation:
|
||||
|
||||
* Optimistic concurrency controls for PUT operations in a
|
||||
read/modify/write routine work as expected in kubernetes.
|
||||
|
||||
* PATCH semantics should work as expected in kubernetes, but may have
|
||||
some limitations imposed by CRDs at the moment.
|
||||
|
||||
In this and following examples PATCH is used. Revisions can be built
|
||||
from source, which results in a container image, or by directly
|
||||
supplying a pre-built container, which this first scenario
|
||||
illustrates. The example demonstrates the PATCH issued by the client,
|
||||
followed by several GET calls to illustrate each step in the
|
||||
reconciliation process as the system materializes the new revision,
|
||||
and begins shifting traffic from the old revision to the new revision.
|
||||
|
||||
The client PATCHes the configuration's template revision with just the
|
||||
new container image, inheriting previous configuration from the
|
||||
configuration:
|
||||
|
||||
```http
|
||||
PATCH /apis/elafros.dev/v1alpha1/namespaces/default/configurations/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-service # by convention, same name as the service
|
||||
spec:
|
||||
revisionTemplate: # template for building Revision
|
||||
spec:
|
||||
container:
|
||||
image: gcr.io/... # new image
|
||||
```
|
||||
|
||||
The update to the Configuration triggers a new revision being created,
|
||||
and the Configuration is updated to reflect the new Revision:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/configurations/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-service
|
||||
generation: 1235
|
||||
...
|
||||
|
||||
spec:
|
||||
... # same as before, except new container.image
|
||||
status:
|
||||
latestReadyRevisionName: abc
|
||||
latestCreatedRevisionName: def # new revision created, but not ready yet
|
||||
observedGeneration: 1235
|
||||
```
|
||||
|
||||
The newly created revision has the same config as the previous
|
||||
revision, but different code. Note the generation label reflects the
|
||||
new generation of the configuration (1235), indicating the provenance
|
||||
of the revision:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/def
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Revision
|
||||
metadata:
|
||||
name: def
|
||||
labels:
|
||||
elafros.dev/configuration: my-service
|
||||
elafros.dev/configurationGeneration: 1235
|
||||
...
|
||||
spec:
|
||||
container: # k8s core.v1.Container
|
||||
image: gcr.io/... # new container
|
||||
# same config as previous revision
|
||||
env:
|
||||
- name: FOO
|
||||
value: bar
|
||||
- name: HELLO
|
||||
value: blurg
|
||||
...
|
||||
status:
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: True
|
||||
```
|
||||
|
||||
When the new revision is Ready, i.e. underlying resources are
|
||||
materialized and ready to serve, the configuration updates its
|
||||
`status.latestReadyRevisionName` status to reflect the new
|
||||
revision. The route, which is configured to automatically rollout new
|
||||
revisions from the configuration, watches the configuration and is
|
||||
notified of the `latestReadyRevisionName`, and begins migrating traffic
|
||||
to it. During reconciliation, traffic may be routed to both existing
|
||||
revision `abc` and new revision `def`:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
...
|
||||
spec:
|
||||
rollout:
|
||||
traffic:
|
||||
- configurationName: my-service
|
||||
percent: 100
|
||||
|
||||
status:
|
||||
# domain:
|
||||
# oss: my-service.namespace.mydomain.com
|
||||
domain: my-service.namespace.mydomain.com
|
||||
# percentages add to 100
|
||||
traffic: # in status, all configurationName refs are dereferenced
|
||||
- revisionName: abc
|
||||
percent: 75
|
||||
- revisionName: def
|
||||
percent: 25
|
||||
conditions:
|
||||
- type: RolloutComplete
|
||||
status: False
|
||||
```
|
||||
|
||||
And once reconciled, revision def serves 100% of the traffic :
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
...
|
||||
spec:
|
||||
rollout:
|
||||
traffic:
|
||||
- configurationName: my-service
|
||||
percent: 100
|
||||
status:
|
||||
domain: my-service.default.mydomain.com
|
||||
traffic:
|
||||
- revisionName: def
|
||||
percent: 100
|
||||
conditions:
|
||||
- type: RolloutComplete
|
||||
status: True
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
## 2) Creating Route and deploying first Revision - pre-built container
|
||||
|
||||
**Scenario**: User creates a new Route and deploys their first
|
||||
Revision based on a pre-built container
|
||||
|
||||
```
|
||||
$ elafros deploy --service my-service --region us-central1
|
||||
✓ Creating service [my-service] in region [us-central1]
|
||||
Deploying app to service [my-service]:
|
||||
✓ Uploading [=================]
|
||||
✓ Starting
|
||||
✓ Promoting
|
||||
Done.
|
||||
Deployed to https://my-service.default.mydomain.com
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
|
||||
* Create a new Configuration and a Route that references a that
|
||||
configuration.
|
||||
|
||||
**Results**:
|
||||
|
||||
* A new Configuration is created, and generates a new Revision based
|
||||
on the configuration
|
||||
|
||||
* A new Route is created, referencing the configuration
|
||||
|
||||
* The route begins serving traffic to the revision that was created by
|
||||
the configuration
|
||||
|
||||
|
||||
|
||||
|
||||
The previous example assumed an existing Route and Configuration to
|
||||
illustrate the common scenario of updating the configuration to deploy
|
||||
a new revision to the service.
|
||||
|
||||
In this getting started example, deploying a first Revision is
|
||||
accomplished by creating a new Configuration (which will generate a
|
||||
new Revision) and creating a new Route referring to that
|
||||
configuration. Note that these two steps can occur in either order, or
|
||||
in parallel.
|
||||
|
||||
A Route can either refer directly to a Revision, or to the latest
|
||||
ready revision of a Configuration, as this example illustrates. This
|
||||
is the most straightforward scenario that many Elafros customers are
|
||||
expected to use, and is consistent with the experience of deploying
|
||||
code that is rolled out immediately.
|
||||
|
||||
The example shows the POST calls issued by the client, followed by
|
||||
several GET calls to illustrate each step in the reconciliation
|
||||
process as the system materializes and begins routing traffic to the
|
||||
revision.
|
||||
|
||||
The client creates the route and configuration, which by convention
|
||||
share the same name:
|
||||
|
||||
```http
|
||||
POST /apis/elafros.dev/v1alpha1/namespaces/default/routes
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
spec:
|
||||
rollout:
|
||||
traffic:
|
||||
- configurationName: my-service # named reference to Configuration
|
||||
percent: 100 # automatically activate new Revisions from the configuration
|
||||
```
|
||||
|
||||
```http
|
||||
POST /apis/elafros.dev/v1alpha1/namespaces/default/configurations
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-service # By convention (not req'd), same name as the service.
|
||||
# This will also be set as the "elafros.dev/configuration"
|
||||
# label on the created Revision.
|
||||
spec:
|
||||
revisionTemplate: # template for building Revision
|
||||
metadata: ...
|
||||
spec:
|
||||
container: # k8s core.v1.Container
|
||||
image: gcr.io/...
|
||||
env:
|
||||
- name: FOO
|
||||
value: bar
|
||||
- name: HELLO
|
||||
value: world
|
||||
...
|
||||
```
|
||||
|
||||
Upon the creation of the configuration, the system will create a new
|
||||
Revision, generating its name, and applying the spec and metadata from
|
||||
the configuration, as well as new metadata labels:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/abc
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Revision
|
||||
metadata:
|
||||
name: abc # generated name
|
||||
labels:
|
||||
# name and generation of the configuration that created the revision
|
||||
elafros.dev/configuration: my-service
|
||||
elafros.dev/configurationGeneration: 1234
|
||||
... # uid, resourceVersion, creationTimestamp, generation, selfLink, etc
|
||||
spec:
|
||||
... # spec from the configuration
|
||||
status:
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: False
|
||||
message: "Starting Instances"
|
||||
```
|
||||
|
||||
Immediately after the revision is created, i.e. before underlying
|
||||
resources have been fully materialized, the configuration is updated
|
||||
with latestCreatedRevisionName:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/configurations/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-service
|
||||
generation: 1234
|
||||
... # uid, resourceVersion, creationTimestamp, selfLink, etc
|
||||
spec:
|
||||
... # same as before
|
||||
status:
|
||||
# latest created revision, may not have materialized yet
|
||||
latestCreatedRevisionName: abc
|
||||
observedGeneration: 1234
|
||||
```
|
||||
|
||||
The configuration watches the revision, and when the revision is
|
||||
updated as Ready (to serve), the latestReadyRevisionName is updated:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/configurations/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-service
|
||||
generation: 1234
|
||||
...
|
||||
spec:
|
||||
... # same as before
|
||||
status:
|
||||
# the latest created and ready to serve. Watched by service
|
||||
latestReadyRevisionName: abc
|
||||
# latest created revision
|
||||
latestCreatedRevisionName: abc
|
||||
observedGeneration: 1234
|
||||
```
|
||||
|
||||
The route, which watches the configuration `my-service`, observes the
|
||||
change to `latestReadyRevisionName` and begins routing traffic to the
|
||||
new revision `abc`, addressable as
|
||||
`my-service.default.mydomain.com`. Once reconciled:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
generation: 2145
|
||||
...
|
||||
spec:
|
||||
rollout:
|
||||
traffic:
|
||||
- configurationName: my-service
|
||||
percent: 100
|
||||
|
||||
status:
|
||||
domain: my-service.default.mydomain.com
|
||||
|
||||
traffic: # in status, all configurationName refs are dereferenced to latest revision
|
||||
- revisionName: abc # latestReadyRevisionName from configurationName in spec
|
||||
percent: 100
|
||||
|
||||
conditions:
|
||||
- type: RolloutComplete
|
||||
status: True
|
||||
|
||||
observedGeneration: 2145
|
||||
```
|
||||
|
||||
|
||||
## 3) Manual rollout of a new Revision - config change only
|
||||
|
||||
**_Scenario_**: User updates configuration with new configuration (env
|
||||
var change) to an existing service, tests the revision, then
|
||||
proceeds with a manually controlled rollout to 100%
|
||||
|
||||
```
|
||||
$ elafros rollout strategy manual
|
||||
|
||||
$ elafros deploy --service my-service --env HELLO="blurg"
|
||||
[...]
|
||||
|
||||
$ elafros revisions list --service my-service
|
||||
Name Traffic Id Date Deployer Git SHA
|
||||
next 0% v3 2018-01-19 12:16 user1 a6f92d1
|
||||
current 100% v2 2018-01-18 20:34 user1 a6f92d1
|
||||
v1 2018-01-17 10:32 user1 33643fc
|
||||
|
||||
$ elafros rollout next percent 5
|
||||
[...]
|
||||
$ elafros rollout next percent 50
|
||||
[...]
|
||||
$ elafros rollout finish
|
||||
[...]
|
||||
|
||||
$ elafros revisions list --service my-service
|
||||
Name Traffic Id Date Deployer Git SHA
|
||||
current,next 100% v3 2018-01-19 12:16 user1 a6f92d1
|
||||
v2 2018-01-18 20:34 user1 a6f92d1
|
||||
v1 2018-01-17 10:32 user1 33643fc
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
|
||||
* Update the Route to pin the current revision
|
||||
|
||||
* Update the Configuration with the new configuration (env var)
|
||||
|
||||
* Update the Route to address the new Revision
|
||||
|
||||
* After testing the new revision through the named subdomain, proceed
|
||||
with the rollout, incrementally increasing traffic to 100%
|
||||
|
||||
**Results:**
|
||||
|
||||
* The system creates the new revision from the configuration,
|
||||
addressable at next.my-service... (by convention), but traffic is
|
||||
not routed to it until the percentage is manually ramped up. Upon
|
||||
completing the rollout, the next revision is now the current
|
||||
revision
|
||||
|
||||
|
||||
|
||||
|
||||
In the previous examples, the route referenced a Configuration for
|
||||
automatic rollouts of new Revisions. While this pattern is useful for
|
||||
many scenarios such as functions-as-a-service and simple development
|
||||
flows, the Route can also reference Revisions directly to "pin"
|
||||
traffic to specific revisions, which is suitable for manually
|
||||
controlling rollouts, i.e. testing a new revision prior to serving
|
||||
traffic. (Note: see [Appendix B](complex_examples.md) for a
|
||||
semi-automatic variation of manual rollouts).
|
||||
|
||||
The client updates the route to pin the current revision:
|
||||
|
||||
```http
|
||||
PATCH /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
spec:
|
||||
rollout:
|
||||
traffic:
|
||||
- revisionName: def # pin a specific revision, i.e. the current one
|
||||
percent: 100
|
||||
```
|
||||
|
||||
As in the previous example, the configuration is updated to trigger
|
||||
the creation of a new revision, in this case updating the container
|
||||
image but keeping the same config:
|
||||
|
||||
```http
|
||||
PATCH /apis/elafros.dev/v1alpha1/namespaces/default/configurations/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-service
|
||||
spec:
|
||||
revisionTemplate:
|
||||
spec:
|
||||
container:
|
||||
env: # k8s-style strategic merge patch, updating a single list value
|
||||
- name: HELLO
|
||||
value: blurg # changed value
|
||||
```
|
||||
|
||||
A new revision `ghi` is created that has the same code as the previous
|
||||
revision `def`, but different config:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/ghi
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Revision
|
||||
metadata:
|
||||
name: ghi
|
||||
...
|
||||
spec:
|
||||
container:
|
||||
image: gcr.io/... # same container as previous revision abc
|
||||
env:
|
||||
- name: FOO
|
||||
value: bar
|
||||
- name: HELLO
|
||||
value: blurg # changed value
|
||||
...
|
||||
status:
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: True
|
||||
```
|
||||
|
||||
Even when ready, the new revision does not automatically start serving
|
||||
traffic, as the route was pinned to revision `def`.
|
||||
|
||||
Update the route to make the existing revision serving traffic
|
||||
addressable through subdomain `current`, and referencing the new
|
||||
revision at 0% traffic but making it addressable through subdomain
|
||||
`next`:
|
||||
|
||||
```http
|
||||
PATCH /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
spec:
|
||||
rollout:
|
||||
traffic:
|
||||
- revisionName: def
|
||||
name: current # addressable as current.my-service.default.mydomain.com
|
||||
percent: 100
|
||||
- revisionName: ghi
|
||||
name: next # addressable as next.my-service.default.mydomain.com
|
||||
percent: 0 # no traffic yet
|
||||
```
|
||||
|
||||
In this state, the route makes both revisions addressable with
|
||||
subdomains `current` and `next` (once the revision `ghi` has a status of
|
||||
Ready), but traffic has not shifted to next yet. Also note that while
|
||||
the names current/next have semantic meaning, they are convention
|
||||
only; blue/green, or any other subdomain names could be configured.
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
...
|
||||
spec:
|
||||
... # unchanged
|
||||
status:
|
||||
domain: my-service.default.mydomain.com
|
||||
traffic:
|
||||
- revisionName: def
|
||||
name: current # addressable as current.my-service.default.mydomain.com
|
||||
percent: 100
|
||||
- revisionName: ghi
|
||||
name: next # addressable as next.my-service.default.mydomain.com
|
||||
percent: 0
|
||||
conditions:
|
||||
- type: RolloutComplete
|
||||
status: True
|
||||
...
|
||||
```
|
||||
|
||||
After testing the new revision at
|
||||
`next.my-service.default.mydomain.com`, it can be rolled out to 100%
|
||||
(either directly, or through several increments, with the split
|
||||
totaling 100%):
|
||||
|
||||
```http
|
||||
PATCH /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
spec:
|
||||
rollout:
|
||||
Traffic: # percentages must total 100%
|
||||
- revisionName: def
|
||||
name: current
|
||||
percent: 0
|
||||
- revisionName: ghi
|
||||
name: next
|
||||
percent: 100 # migrate traffic fully to the next revision
|
||||
```
|
||||
|
||||
After reconciliation, all traffic has been shifted to the new version:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
...
|
||||
spec:
|
||||
... # unchanged
|
||||
status:
|
||||
domain: my-service.default.mydomain.com
|
||||
traffic:
|
||||
- revisionName: def
|
||||
name: current
|
||||
percent: 0
|
||||
- revisionName: ghi
|
||||
name: next
|
||||
percent: 100
|
||||
conditions:
|
||||
- type: RolloutComplete
|
||||
status: True
|
||||
...
|
||||
```
|
||||
|
||||
By convention, the final step when completing the rollout is to update
|
||||
`current` to reflect the new revision. `next` can either be removed, or
|
||||
left addressing the same revision as current so that
|
||||
`next.my-service.default.mydomain.com` is always addressable.
|
||||
|
||||
```http
|
||||
PATCH /apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
spec:
|
||||
rollout:
|
||||
traffic:
|
||||
- revisionName: ghi # update for the next rollout, current = next
|
||||
name: current
|
||||
percent: 100
|
||||
- revisionName: ghi # optional: leave next as also referring to ghi
|
||||
name: next
|
||||
percent: 0
|
||||
```
|
||||
|
||||
|
||||
## 4) Deploy a Revision from source
|
||||
|
||||
**Scenario**: User deploys a revision to an existing service from
|
||||
source rather than a pre-built container
|
||||
|
||||
```
|
||||
$ elafros deploy --service my-service
|
||||
Deploying app to service [my-service]:
|
||||
✓ Uploading [=================]
|
||||
✓ Detected [node-8-9-4] runtime
|
||||
✓ Building
|
||||
✓ Starting
|
||||
✓ Promoting
|
||||
Done.
|
||||
Deployed to https://my-service.default.mydomain.com
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
|
||||
* Create/Update a Configuration, inlining build details.
|
||||
|
||||
**Results**:
|
||||
|
||||
* The Configuration is created/updated, which generates a container
|
||||
build and a new revision based on the template, and can be rolled
|
||||
out per earlier examples
|
||||
|
||||
|
||||
|
||||
|
||||
Previous examples demonstrated configurations created with pre-built
|
||||
containers. Revisions can also be created by providing build
|
||||
information to the configuration, which results in a container image
|
||||
built by the system. The build information is supplied by inlining the
|
||||
BuildSpec of a Build resource in the Configuration. This describes:
|
||||
|
||||
* **What** to build (`build.source`): Source can be provided as an
|
||||
archive, manifest file, or repository.
|
||||
|
||||
* **How** to build (`build.template`): a
|
||||
[BuildTemplate](https://github.com/elafros/build) is referenced,
|
||||
which describes how to build the container via a builder with
|
||||
arguments to the build process.
|
||||
|
||||
* **Where** to publish (`build.template.arguments`): Image registry
|
||||
url and other information specific to this build invocation.
|
||||
|
||||
The client creates the configuration inlining a build spec for an
|
||||
archive based source build, and referencing a nodejs build template:
|
||||
|
||||
```http
|
||||
POST /apis/elafros.dev/v1alpha1/namespaces/default/configurations
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-service
|
||||
spec:
|
||||
build: # build.dev/v1alpha1.BuildTemplateSpec
|
||||
source:
|
||||
# oneof git|gcs|custom:
|
||||
git:
|
||||
url: https://...
|
||||
commit: ...
|
||||
template: # defines build template
|
||||
name: nodejs_8_9_4 # builder name
|
||||
namespace: build-templates
|
||||
arguments:
|
||||
- name: _IMAGE
|
||||
value: gcr.io/... # destination for image
|
||||
|
||||
revisionTemplate: # template for building Revision
|
||||
metadata: ...
|
||||
spec:
|
||||
container: # k8s core.v1.Container
|
||||
image: gcr.io/... # Promise of a future build. Same as supplied in
|
||||
# build.template.arguments[_IMAGE]
|
||||
env: # Updated environment variables to go live with new source.
|
||||
- name: FOO
|
||||
value: bar
|
||||
- name: HELLO
|
||||
value: world
|
||||
```
|
||||
|
||||
Note the `revisionTemplate.spec.container.image` above is supplied
|
||||
with the destination of the build. This enables one-step changes to
|
||||
both config and source code. If the build step were responsible for
|
||||
updating the `revisionTemplate.spec.container.image` at the completion
|
||||
of the build, an update to both source and config could result in the
|
||||
creation of two Revisions, one with the config change, and the other
|
||||
with the new code deployment. It is expected that Revision will wait
|
||||
for the `buildName` to be complete and the
|
||||
`revisionTemplate.spec.container.image` to be live before marking the
|
||||
Revision as "ready".
|
||||
|
||||
Upon creating/updating the configuration's build field, the system
|
||||
creates a new revision. The configuration controller will initiate a
|
||||
build, populating the revision’s buildName with a reference to the
|
||||
underlying Build resource. Via status updates which the revision
|
||||
controller observes through the build reference, the high-level state
|
||||
of the build is mirrored into conditions in the Revision’s status:
|
||||
|
||||
```http
|
||||
GET /apis/elafros.dev/v1alpha1/namespaces/default/revisions/abc
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Revision
|
||||
metadata:
|
||||
name: abc
|
||||
labels:
|
||||
elafros.dev/configuration: my-service
|
||||
elafros.dev/configurationGeneration: 1234
|
||||
...
|
||||
spec:
|
||||
# name of the build.dev/v1alpha1.Build, if built from source.
|
||||
# Set by Configuration.
|
||||
buildName: ...
|
||||
|
||||
# spec from the configuration, with container.image containing the
|
||||
# newly built container
|
||||
container: # k8s core.v1.Container
|
||||
image: gcr.io/...
|
||||
env:
|
||||
- name: FOO
|
||||
value: bar
|
||||
- name: HELLO
|
||||
value: world
|
||||
status:
|
||||
# This is a copy of metadata from the container image or grafeas, indicating
|
||||
# the provenance of the revision, annotated on the container
|
||||
imageSource:
|
||||
archive|manifest|repository: ...
|
||||
context: ...
|
||||
conditions:
|
||||
- type: Ready
|
||||
status: True
|
||||
- type: BuildComplete
|
||||
status: True
|
||||
# other conditions indicating build failure details, if applicable
|
||||
```
|
||||
|
||||
Rollout operations in the route are identical to the pre-built
|
||||
container examples.
|
||||
|
||||
Also analogous is updating the configuration to create a new
|
||||
revision - in this case, updated source would be provided to the
|
||||
configuration's inlined build spec, which would initiate a new
|
||||
container build, and the creation of a new revision.
|
||||
|
||||
|
||||
## 5) Deploy a Function
|
||||
|
||||
**Scenario**: User deploys a new function revision to an existing service
|
||||
|
||||
```
|
||||
$ elafros deploy --function index --service my-function
|
||||
Deploying function to service [my-function]:
|
||||
✓ Uploading [=================]
|
||||
✓ Detected [node-8-9-4] runtime
|
||||
✓ Building
|
||||
✓ Starting
|
||||
✓ Promoting
|
||||
Done.
|
||||
Deployed to https://my-function.default.mydomain.com
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
|
||||
* Create/Update a Configuration, additionally specifying function details.
|
||||
|
||||
**Results**:
|
||||
|
||||
* The Configuration is created/updated, which generates a new revision
|
||||
based on the template build and spec which can be rolled out per
|
||||
previous examples
|
||||
|
||||
|
||||
|
||||
|
||||
Previous examples illustrated creating and deploying revisions in the
|
||||
context of apps. Functions are created and deployed in the same
|
||||
manner (in particular, as containers which respond to HTTP). In the
|
||||
build phase of the deployment, additional function metadata may be
|
||||
taken into account in order to wrap the supplied code in a functions
|
||||
framework.
|
||||
|
||||
Functions are configured with a language-specific entryPoint. The
|
||||
entryPoint may be provided as an argument to the build template, if
|
||||
language-native autodetection is insufficient. By convention, a type
|
||||
metadata label may also be added that designates revisions as a
|
||||
function, supporting listing revisions by type; there is no change to
|
||||
the system behavior based on type.
|
||||
|
||||
Note that a function may be connected to one or more event sources via
|
||||
Bindings in the Eventing API; the binding of events to functions is
|
||||
not a core function of the compute API.
|
||||
|
||||
Creating the configuration with build and function metadata:
|
||||
|
||||
```http
|
||||
POST /apis/elafros.dev/v1alpha1/namespaces/default/configurations
|
||||
```
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-function
|
||||
spec:
|
||||
build: # build.dev/v1alpha1.BuildTemplateSpec
|
||||
source:
|
||||
# oneof git|gcs|custom
|
||||
git:
|
||||
url: https://...
|
||||
commit: ...
|
||||
template: # defines build template
|
||||
name: go_1_9_fn # function builder
|
||||
namespace: build-templates
|
||||
arguments:
|
||||
- name: _IMAGE
|
||||
value: gcr.io/... # destination for image
|
||||
- name: _ENTRY_POINT
|
||||
value: index # language dependent, function-only entrypoint
|
||||
|
||||
revisionTemplate: # template for building Revision
|
||||
metadata:
|
||||
labels:
|
||||
# One-of "function" or "app", convention for CLI/UI clients to list/select
|
||||
elafros.dev/type: "function"
|
||||
spec:
|
||||
container: # k8s core.v1.Container
|
||||
image: gcr.io/... # Promise of a future build. Same as supplied in
|
||||
# build.template.arguments[_IMAGE]
|
||||
env:
|
||||
- name: FOO
|
||||
value: bar
|
||||
- name: HELLO
|
||||
value: world
|
||||
|
||||
# serializes requests for function. Default value for functions
|
||||
concurrencyModel: SingleThreaded
|
||||
# max time allowed to respond to request
|
||||
timeoutSeconds: 20
|
||||
```
|
||||
|
||||
Upon creating or updating the configuration, a new Revision is created
|
||||
per the previous examples. Rollout operations are also identical to
|
||||
the previous examples.
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
# Resource Types
|
||||
|
||||
The primary resources in the Elafros API are Routes, Revisions, and Configurations:
|
||||
|
||||
* 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.
|
||||
|
||||
|
||||
|
||||
## 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 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**.
|
||||
|
||||
## 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](https://github.com/elafros/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.
|
||||
|
||||
|
||||
# Orchestration
|
||||
|
||||
The system will be configured to not allow customer mutations to
|
||||
Revisions. Instead, the creation of immutable Revisions through a
|
||||
Configuration 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
|
||||
* the ability to rollback to a known good configuration
|
||||
|
||||
In the conventional single live revision scenario, a route has a
|
||||
single configuration with the same name as the route. Update
|
||||
operations on the configuration 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.
|
||||
|
||||
When creating an initial route and performing the first deployment,
|
||||
the two operations of creating a Route and an associated Configuration
|
||||
can be done in parallel, which streamlines the use case of deploying
|
||||
code initially from a button. The
|
||||
[sample API usage](normative_examples.md) section illustrates
|
||||
conventional usage of the API.
|
||||
|
|
@ -0,0 +1,263 @@
|
|||
## Resource Paths
|
||||
|
||||
Resource paths in the Elafros API have the following standard k8s form:
|
||||
|
||||
```
|
||||
/apis/{apiGroup}/{apiVersion}/namespaces/{metadata.namespace}/{kind}/{metadata.name}
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
/apis/elafros.dev/v1alpha1/namespaces/default/routes/my-service
|
||||
```
|
||||
|
||||
It is expected that each Route will provide a name within a
|
||||
cluster-wide DNS name. While no particular URL scheme is mandated
|
||||
(consult the `domain` property of the Route for the authoritative
|
||||
mapping), a common implementation would be to use the kubernetes
|
||||
namespace mechanism to produce a URL like the following:
|
||||
|
||||
```
|
||||
[$revisionname].$route.$namespace.<common elafros cluster suffix>
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
prod.my-service.default.mydomain.com
|
||||
```
|
||||
|
||||
|
||||
# Resource YAML Definitions
|
||||
|
||||
YAMLs for the Elafros API resources are described below, describing the
|
||||
basic k8s structure: metadata, spec and status, along with comments on
|
||||
specific fields.
|
||||
|
||||
## Route
|
||||
|
||||
For a high-level description of Routes,
|
||||
[see the overview](overview.md#route).
|
||||
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Route
|
||||
metadata:
|
||||
name: my-service
|
||||
namespace: default
|
||||
labels:
|
||||
elafros.dev/type: ... # +optional convention: function|app
|
||||
|
||||
# system generated meta
|
||||
uid: ...
|
||||
resourceVersion: ... # used for optimistic concurrency control
|
||||
creationTimestamp: ...
|
||||
generation: ... # updated only when spec changes; used by observedGeneration
|
||||
selfLink: ...
|
||||
...
|
||||
spec:
|
||||
traffic:
|
||||
# list of oneof configurationName | revisionName.
|
||||
# configurationName watches configurations to address latest latestReadyRevisionName
|
||||
# revisionName pins a specific revision
|
||||
- configurationName: ...
|
||||
name: ... # +optional. Access as {name}.${status.domain},
|
||||
# e.g. oss: current.my-service.default.mydomain.com
|
||||
percent: 100 # list percentages must add to 100. 0 is a valid list value
|
||||
- ...
|
||||
|
||||
status:
|
||||
# domain: The hostname used to access the default (traffic-split)
|
||||
# route. Typically, this will be composed of the name and namespace
|
||||
# along with a cluster-specific prefix (here, mydomain.com).
|
||||
domain: my-service.default.mydomain.com
|
||||
|
||||
traffic:
|
||||
# current rollout status list. configurationName references
|
||||
# are dereferenced to latest revision
|
||||
- revisionName: ... # latestReadyRevisionName from a configurationName in spec
|
||||
name: ...
|
||||
percent: ... # percentages add to 100. 0 is a valid list value
|
||||
- ...
|
||||
|
||||
conditions: # See also the [error conditions documentation](errors.md)
|
||||
- type: RolloutComplete
|
||||
status: True
|
||||
- type: TrafficDropped
|
||||
status: False
|
||||
- ...
|
||||
|
||||
observedGeneration: ... # last generation being reconciled
|
||||
```
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
For a high-level description of Configurations,
|
||||
[see the overview](overview.md#configuration).
|
||||
|
||||
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Configuration
|
||||
metadata:
|
||||
name: my-service
|
||||
namespace: default
|
||||
|
||||
# system generated meta
|
||||
uid: ...
|
||||
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
|
||||
build: # This is a build.dev/v1alpha1.BuildTemplateSpec
|
||||
source:
|
||||
# oneof git|gcs|custom:
|
||||
|
||||
# +optional.
|
||||
git:
|
||||
url: https://github.com/jrandom/myrepo
|
||||
commit: deadbeef # Or branch, tag, ref
|
||||
|
||||
# +optional. A zip archive or a manifest file in Google Cloud
|
||||
# Storage. A manifest file is a file containing a list of file
|
||||
# paths, backing URLs, and sha checksums. Manifest may be a more
|
||||
# efficient mechanism for a client to perform partial upload.
|
||||
gcs:
|
||||
location: https://...
|
||||
type: 'archive' # Or 'manifest'
|
||||
|
||||
# +optional. Custom specifies a container which will be run as
|
||||
# the first build step to fetch the source.
|
||||
custom: # is a core.v1.Container
|
||||
image: gcr.io/cloud-builders/git:latest
|
||||
args: [ "clone", "https://...", "other-place" ]
|
||||
|
||||
template: # build template reference and arguments.
|
||||
name: go_1_9_fn # builder name. Functions may have custom builders
|
||||
namespace: build-templates
|
||||
arguments:
|
||||
- name: _IMAGE
|
||||
value: gcr.io/... # destination for image
|
||||
- name: _ENTRY_POINT
|
||||
value: index # if function, language dependent entrypoint
|
||||
|
||||
revisionTemplate: # template for building Revision
|
||||
metadata: ...
|
||||
labels:
|
||||
elafros.dev/type: "function" # One of "function" or "app"
|
||||
spec: # elafros.RevisionTemplateSpec. Copied to a new revision
|
||||
|
||||
# +optional. if rolling back, the client may set this to the
|
||||
# previous revision's build to avoid triggering a rebuild
|
||||
buildName: ...
|
||||
|
||||
# is a core.v1.Container; some fields not allowed, such as resources, ports
|
||||
container:
|
||||
# image either provided as pre-built container, or built by Elafros from
|
||||
# source. When built by elafros, set to the same as build template, e.g.
|
||||
# build.template.arguments[_IMAGE], as the "promise" of a future build.
|
||||
# If buildName is provided, it is expected that this image will be
|
||||
# present when the referenced build is complete.
|
||||
image: gcr.io/...
|
||||
command: ['run']
|
||||
args: []
|
||||
env:
|
||||
# list of environment vars
|
||||
- name: FOO
|
||||
value: bar
|
||||
- name: HELLO
|
||||
value: world
|
||||
- ...
|
||||
livenessProbe: ... # Optional
|
||||
readinessProbe: ... # Optional
|
||||
|
||||
# +optional concurrency strategy. SingleThreaded default value for functions
|
||||
concurrencyModel: SingleThreaded
|
||||
# +optional. max time the instance is allowed for responding to a request
|
||||
timeoutSeconds: ...
|
||||
serviceAccountName: ... # Name of the service account the code should run as.
|
||||
|
||||
status:
|
||||
# the latest created and ready to serve. Watched by route
|
||||
latestReadyRevisionName: abc
|
||||
# latest created revision, may still be in the process of being materialized
|
||||
latestCreatedRevisionName: def
|
||||
conditions: # See also the [error conditions documentation](errors.md)
|
||||
- type: LatestRevisionReady
|
||||
status: False
|
||||
reason: ContainerMissing
|
||||
message: "Unable to start because container is missing and build failed."
|
||||
observedGeneration: ... # last generation being reconciled
|
||||
```
|
||||
|
||||
|
||||
## Revision
|
||||
|
||||
For a high-level description of Revisions,
|
||||
[see the overview](overview.md#revision).
|
||||
|
||||
```yaml
|
||||
apiVersion: elafros.dev/v1alpha1
|
||||
kind: Revision
|
||||
metadata:
|
||||
name: myservice-a1e34 # system generated
|
||||
namespace: default
|
||||
labels:
|
||||
elafros.dev/configuration: ... # to list configurations/revisions by service
|
||||
elafros.dev/configurationGeneration: ... # generation of configuration that created this Revision
|
||||
elafros.dev/type: "function" # convention, one of "function" or "app"
|
||||
# system generated meta
|
||||
uid: ...
|
||||
resourceVersion: ... # used for optimistic concurrency control
|
||||
creationTimestamp: ...
|
||||
generation: ...
|
||||
selfLink: ...
|
||||
...
|
||||
|
||||
# spec populated by Configuration
|
||||
spec:
|
||||
# +optional. name of the build.dev/v1alpha1.Build if built from source
|
||||
buildName: ...
|
||||
|
||||
container: # core.v1.Container
|
||||
image: gcr.io/...
|
||||
command: ['run']
|
||||
args: []
|
||||
env: # list of environment vars
|
||||
- name: FOO
|
||||
value: bar
|
||||
- name: HELLO
|
||||
value: world
|
||||
- ...
|
||||
livenessProbe: ... # Optional
|
||||
readinessProbe: ... # Optional
|
||||
concurrencyModel: ...
|
||||
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.
|
||||
imageSource:
|
||||
git|gcs: ...
|
||||
conditions: # See also the documentation in errors.md
|
||||
- type: Ready
|
||||
status: False
|
||||
message: "Starting Instances"
|
||||
# if built from source:
|
||||
- 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