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.