Home / Keptn v1 Docs / Release 0.19.x / Reference / Configurations / shipyard
The shipyard is configured in the shipyard.yaml file, which defines the activities to be performed for a Keptn project and the order in which those activities are executed.
Each project must have one, and only one, shipyard.yaml file which is passed to the keptn create project command.
Each shipyard contains one or more stages
, which can be given any name that is meaningful.
Examples are “development”, “hardening”, “production”, and “remediation”.
A stage
is a grouping of activities to be executed until the project is deployed and,
optionally, a “production” stage that defines remediation activities
that can be executed in response to issues detected on the production site.
Each stage
must have one or more sequences
, which can be given any name that is meaningful.
A sequence
defines the tasks
to be performed and, optionally, an event that triggers that sequence.
The following Synopsis shows all the constructions that are supported for a shipyard although most projects only use some of the constructions.
apiVersion: spec.keptn.sh/0.2.3
kind: "Shipyard"
metadata:
name: "shipyard-<project-name>"
spec:
stages:
- name: "<stagename-1>"
sequences:
- name: "delivery"
tasks:
- name: "deployment"
properties:
deploymentstrategy: "direct" | "blue_green_service" | "user_managed"
- name: "release"
- name: "hardening"
- name: "production"
sequences:
- name: "<delivery-sequence>"
triggeredOn:
- event: "<event>.finished"
tasks:
- name: "delivery"
- name: "remediation-sequence>"
triggeredOn:
-event: "<event>"
selector:
match:
evaluation.result: "<result>"
tasks:
- name: "get-action"
- name: "action"
- name: "evaluation"
triggeredAfter: "<timeframe>"
properties:
timeframe: "<xx>m"
Meta-data
apiVersion
: The version of the shipyard specification in the format: spec.keptn.sh/x.y.z
kind
: is Shipyard
metadata
:
name
: Unique name for this shipyard file
Typically, this is the string shipyard
followed by a dash and the project name;
for example, shipyard-sockshop
name
must start with a lowercase letter and include only lowercase alphanumeric characters and hyphens.name
has a maximum length of 200 characters;
This value is configurable with .Values.shipyardController.config.validation.projectNameMaxSize
.spec
: Consists of the property stages.
stages
: An array of stages, each of which has a name
and a sequence
of tasks
to executeStage
A stage is named for the particular activity to be performed,
such as development
, hardening
, staging
, or production
.
Each shipyard file must have at least one stage
.
The name of the stage becomes the name of the branch
in the upstream Git repository
and the Kubernetes namespace to which
services are deployed.
A stage can be given any meaningful name that conforms to the Kubernetes Object Names and IDs specification, meaning:
Contains only lowercase alphanumeric characters or -
.
Most especially, must not contain /
or %
.
Starts and ends with an alphanumeric character.
Contains at most 43 characters.
Kubernetes allows up to 63 character names (because of DNS limitations).
For continuous delivery, the helm-service
creates Helm releases
named <serviceName>-generated
, where <serviceName>
is the stage name..
Because “-generated” is 10 characters, the stage name can not be longer than 43 characters.
It is possible that larger values are allowed if you are not using the helm-service
but this has not been tested and is not guaranteed.
A stage has the properties:
name
: A unique name for the stage
such as development
, hardening
, staging
, or `production.sequences
: An array of sequences that define the tasks to be performed
and, optionally, the events that trigger each task.You can not add or delete stages in the shipyard file for an existing project although you can make other modifications.
Sequence
A sequence
is an ordered list of task
s that are triggered sequentially and are part of a stage
.
By default, a sequence is a standalone section that runs and finishes,
unless you specify the triggeredOn
property to form a chain of sequences.
Each stage
includes an implicit evaluation
sequence
with a single task that is also called evaluation
.
You can define your own evaluation
sequence with any set of tasks to override this default sequence
but each stage must have either an implicit or explicit evaluation
sequence.
Sequences that use the same service cannot be run in parallel. If you simultaneously trigger multiple sequences for the same service, they are queued to run sequentially. Sequences for different services can be run in parallel. This is possible when you have different automation projects or if you have multiple services within a project.
A sequence has the properties:
name
: A unique name for the sequence
tasks
: An array of tasks executed by the sequence in the declared order.
triggeredOn
(optional): An array of events that trigger the sequence.
This property can be used to trigger a sequence once another sequence has been finished,
essentially forming chains of sequences.
In addition to specifying the sequence whose completion should activate the trigger,
you can define a selector
that defines whether the sequence should be triggered
if the preceeding sequence has been executed successfuly, or had a failed
or warning
result.
For example, the following sequence with the name rollback
is only triggered
if the sequence delivery
in production had a result of failed
:
- name: rollback
triggeredOn:
- event: production.delivery.finished
selector:
match:
result: failed
It is also possible to refer to certain tasks within the preceeding sequence.
For example, if match
is changed to release.result: failed
,
the rollback
sequence is executed only if the task release
of the sequence delivery
has a result of failed
:
- name: rollback
triggeredOn:
- event: production.delivery.finished
selector:
match:
release.result: failed
If no selector
is specified, the sequence is triggered
only if the preceeding delivery
sequence has a result of pass
:
- name: rollback
triggeredOn:
- event: production.delivery.finished
Task
A single task
is the smallest executable unit and is contained in a sequences
block.
A task has the properties:
name
: A unique name for the tasktriggeredAfter
(optional): Wait time before the task is triggered.properties
(optional): Task properties as individual key:value
pairs.
These properties are properties that the actioning tool requires
and are consumed by the tool that executes the task.
Typically, properties are passed in at runtime using JSON data
rather than having the data hardcoded into the shipyard file.Keptn supports a set of opinionated tasks for declaring a delivery or remediation sequence. Additional tasks may be defined for the services you integrate.
In addition, the following two tasks are reserved although they are associated with specific services:
Each of these are discussed below.
action
Indicates that a remediation action should be executed by an action provider that is defined in a remediation configuration.
approval
Intercepts the task
sequence and waits for a user to approve or decline the open approval.
This task can be added, for example, before deploying an artifact into the next stage.
The approval strategy is defined based on the evaluation
result pass
and warning
.
The approval strategies for the evaluation results pass
and warning
can be set to:
automatic
: Task sequence continues without requesting approvalmanual
: Task sequence requests for approval before continuingSynopsis:
- name: approval
properties:
pass: automatic
warning: manual
This allows combinations as follows:
Evaluation result: pass | Evaluation result: warning | Behavior | |
---|---|---|---|
Skip approval task: | pass:automatic | warning:automatic | Regardless of the evaluation result, the approval task is skipped |
Depending on evaluation result: | pass:automatic | warning:manual | If the evaluation result is a warning, an approval is required |
Depending on evaluation result: | pass:manual | warning:automatic | If the evaluation result is a pass, an approval is required |
Mandatory approval task: | pass:manual | warning:manual | Regardless of the evaluation result, an approval is required |
By default, an automatic
approval strategy is used for the pass
and warning
evaluation results.
evaluation
Defines the quality evaluation that is executed to verify the quality of a deplyoment based on its SLOs/SLIs.
Every stage must include an evaluation
sequence.
If you do not define an evaluation
sequence for a stage,
an “implicit” evaluation
sequence with a single task that is also called evaluation
is used.
This default evaluation
sequence is overridden by any explicit evaluation
sequence
that you define for your project.
Use the optional triggeredAfter
parameter to specify when to trigger the evaluation.
Set the timeframe
property to specify the timespan to be evaluated.
For example, timeframe: 5m
says that the quality gate evaluation looks at the previous five minutes.
timeframe
must be specified but
you can specify the timeframe
as part of the JSON payload
and pass it in when you trigger the sequence using curl
rather than hard-coding it in the file.
This makes the timeframe value dynamic. For example:
{
"type": "sh.keptn.event.SomeStage.MySequence.triggered",
# Other fields removed for brevity
"data": {
"evaluation": {
"timeframe": "5m"
}
}
get-action
Extracts the desired remediation action from a remediation configuration.
release
Defines the releasing task that is executed after a successful deployment occurs. This task shifts production trafic towards the new deployment.
rollback
Defines the rollback task that is executed when a rollback is triggered.
remediation
Defines whether remediation actions are enabled or not.
For historical reasons and backward compatibility, the following tasks are reserved in Keptn although they are actually associated with services that run on the execution plane rather than on the control plane.
deployment
Defines the deployment strategy used to deploy a new version of a service.
This is part of helm-service, which assumes that Istio is installed on the cluster
unless the Job Executor Service is installed in the cluster.
The deployment strategy
is set to one of the following:
direct
: Deploys a new version of a service by replacing the old version of the service.blue_green_service
: Deploys a new version of a service next to the old one.
After a successful validation of this new version, it replaces the old one and is marked as stable.user_managed
: Deploys a new version of a service
by fetching the current Helm chart from the Git repo and updating appropriate values.This is discussed more in Deployment with Helm
test
Defines the test strategy used to validate a deployment with the jmeter-service.
The jmeter-service supports setting the teststrategy
to one of the following:
functional
: Test a deployment based on functional tests.performance
: Test a deployment based on performance/load tests.Task properties are a way to pass additional Key / Value metadata that actioning integration uses as part of it’s logic. In this case, the jmeter-service expects either teststrategy: functional
or teststrategy: performance
to be set. If you action the test
task with another service you may not need to set these details.
Failed tests result in an automatic rollback
of the latest deployment
when using a blue/green deployment strategy.
- name: test
properties:
teststrategy: functional | performance
For example, you may run functional
tests in a dev
stage
and performance
tests in a hardening
or `staging stage.
A shipyard is defined at the level of a project. This means that all services in a project share the same shipyard definition.
You can not add or delete stages in the shipyard file for an existing project although you can make other modifications. See Updating project’s shipyard for information about modifications that can be made to a shipyard file.
As a workaround, you can temporarily skip the execution of a particular stage by doing either of the following:
triggeredOn
attribute for the stage you want to skipapproval
step as the first task of the stage you want to skip
and then Deny
the approvalsThe See also section of this page references other pages in this documentation set that contain annotated examples for accomplishing various tasks.
Metadata
name field in the shipyard file.