Release¶
A Release contains all the information required for Shipper to run a particular version of an application.
To aid both the human and other users in finding resources related to a particular Release object, the following labels are expected to be present in a newly created Release and propagated to all of its related objects (both in the management and application clusters):
- shipper-app
- The name of the Application object owning the Release.
- shipper-release
- The name of the Release object.
Example¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 | apiVersion: shipper.booking.com/v1alpha1
kind: Release
metadata:
name: reviews-api-deadbeef-1
spec:
targetStep: 2
environment:
chart:
name: reviews-api
version: 0.0.1
repoUrl: https://charts.example.com
clusterRequirements:
capabilities:
- gpu
- high-memory-nodes
regions:
- name: us-east1
strategy:
steps:
- name: staging
capacity:
incumbent: 100
contender: 1
traffic:
incumbent: 100
contender: 0
- name: canary
capacity:
incumbent: 10
contender: 90
traffic:
incumbent: 10
contender: 90
- name: full on
capacity:
incumbent: 0
contender: 100
traffic:
incumbent: 0
contender: 100
values:
replicaCount: 2
status:
achievedStep:
name: full on
step: 2
conditions:
- lastTransitionTime: 2018-12-06T13:43:15Z
status: "True"
type: Complete
- lastTransitionTime: 2018-12-06T12:43:09Z
status: "True"
type: Scheduled
strategy:
conditions:
- lastTransitionTime: 2018-12-06T17:48:41Z
status: "True"
step: 2
type: ContenderAchievedCapacity
- lastTransitionTime: 2018-12-06T12:43:46Z
status: "True"
step: 2
type: ContenderAchievedInstallation
- lastTransitionTime: 2018-12-06T13:42:15Z
status: "True"
step: 2
type: ContenderAchievedTraffic
- lastTransitionTime: 2018-12-06T13:43:15Z
status: "True"
step: 2
type: IncumbentAchievedCapacity
- lastTransitionTime: 2018-12-06T13:42:45Z
status: "True"
step: 2
type: IncumbentAchievedTraffic
state:
waitingForCapacity: "False"
waitingForCommand: "False"
waitingForInstallation: "False"
waitingForTraffic: "False"
|
Spec¶
.spec.targetStep
¶
targetStep defines which strategy step this Release should be trying to complete. It is the primary interface for users to advance or retreat a given rollout.
.spec.environment
¶
The environment contains all the information required for an application to be deployed with Shipper.
Important
Roll-forwards and roll-backs have no difference from Shipper’s
perspective, so a roll-back can be performed simply by replacing an
Application’s .spec.template
field with the .spec.environment
field of the Release you want to roll-back to.
.spec.environment.chart
¶
1 2 3 4 | chart:
name: reviews-api
version: 0.0.1
repoUrl: https://charts.example.com
|
The environment chart key defines the Helm Chart that contains the Kubernetes object
templates for this Release. name
, version
, and repoUrl
are all
required. repoUrl
is the Helm Chart repository that Shipper should
download the chart from.
Note
Shipper will cache this chart version internally after fetching it, just
like pullPolicy: IfNotPresent
for Docker images in Kubernetes. This
protects against chart repository outages. However, it means that if you
need to change your chart, you need to tag it with a different version.
.spec.environment.clusterRequirements
¶
1 2 3 4 5 6 | clusterRequirements:
capabilities:
- gpu
- high-memory-nodes
regions:
- name: us-east1
|
The environment clusterRequirements key specifies what kinds of clusters this Release can be scheduled to. It is required.
clusterRequirements.capabilities
is a list of capability names this
Release requires. They should match capabilities specified in Cluster objects exactly. This may be left empty
if the Release has no required capabilities.
clusterRequirements.regions
is a list of regions this Release must run in. It is required.
.spec.environment.strategy
¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | strategy:
steps:
- name: staging
capacity:
incumbent: 100
contender: 1
traffic:
incumbent: 100
contender: 0
- name: canary
capacity:
incumbent: 10
contender: 90
traffic:
incumbent: 10
contender: 90
- name: full on
capacity:
incumbent: 0
contender: 100
traffic:
incumbent: 0
contender: 100
|
The environment strategy is a required field that specifies the rollout strategy to be used when deploying the Release.
.spec.environment.strategy.steps
contains a list of steps that must be
executed in order to complete a release. A step should have the follwing keys:
Key | Description |
---|---|
.name |
The step name, meant for human users. For example, staging , canary or full on . |
.capacity.incumbent |
The percentage of replicas, from the total number of required replicas the incumbent Release (previous release) should have at this step. |
.capacity.contender |
The percentage of replicas, from the total number of required replicas the contender Release (latest release) should have at this step. |
.traffic.incumbent |
The weight the incumbent Release has when load balancing traffic through all Release objects of the given Application. |
.traffic.contender |
The weight the contender Release has when load balancing traffic through all Release objects of the given Application. |
.spec.environment.values
¶
The environment values key provides parameters for the Helm Chart templates. It is
exactly equivalent to a values.yaml
file provided to the helm install -f
values.yaml
invocation. Like values.yaml
it is technically optional, but
almost all rollouts are likely to include some dynamic values for the chart,
like the image tag.
Almost all Charts will expect some values like replicaCount
,
image.repository
, and image.tag
.
Status¶
.status.achievedStep
¶
achievedStep indicates which strategy step was most recently completed.
.status.conditions
¶
All conditions contain five fields: lastTransitionTime
, status
, type
,
reason
, and message
. Typically reason
and message
are omitted in the
expected case, and populated in the error or unexpected case.
type: Blocked
¶
This condition indicates whether a Release is blocked by a rollout block or not.
type: Complete
¶
This condition indicates whether a Release has finished its strategy, and should be considered complete.
type: Scheduled
¶
This condition indicates whether the clusterRequirements
were satisfied and
a concrete set of clusters selected for this Release.
type: StrategyExecuted
¶
This condition indicates whether a Release has achieved a strategy step. This means the installation, capacity and traffic specified in the .spec.environment.strategy step were achieved.
.status.strategy
¶
This section contains information on the progression of the strategy.
.status.strategy.conditions
¶
These conditions represent the precise state of the strategy: for each of the incumbent and contender, whether they have converged on the state defined by the given strategy step.
.status.strategy.state
¶
The state keys are intended to make it easier to interpret the strategy
conditions by summarizing into a high level conclusion: what is Shipper waiting
for right now? If it is waitingForCommand: "True"
then the rollout is
awaiting a change to .spec.targetStep
to proceed. If any other key is
True
, then Shipper is still working to achieve the desired state.