6.2. Pipelines

Pipelines are defined as a series of operators, or execution stages. Operators are defined as a container and a set of services the operator can make use of. Let’s take a look at a few examples.

Let’s take a look at a simple example.

# Simple "hello world" pipeline definition example.
api-version: 0.3.0
name: hello-world
operators:
  - name: whalesay
    # The container property is the heart of the operator. Container images
    # contain the executable code which defines what the operator does.
    container:
      # The image container::property is the only required property in an
      # operator's definition. Without it, there is literally nothing to do.
      image: clara/examples/whalesay
      tag: latest
      command: ['sh', '-c', 'whalesay', 'hello world!']

Above is your first look at a Clara Deploy SDK pipeline definition. Pipeline definitions use YAML as their domain specific language (DSL). YAML is widely used and supported, and most text editors and IDE support it without any need for third-party plug-ins. Each line of the definition declares a property, and the indention at the beginning of the line determines the scope of the property.

Read Ansible’s YAML Basics for more information regarding YAML and a decent guide on how to read and write it.

Now, let’s look closer at the definition itself and how Clara Deploy SDK interprets it. The first line of the definition is a comment. Comments begin with the hash (also known as number sign, pound sign, and/or octothorpe) character, and end with a new line character. Comments are ignored by Clara Deploy SDK’s definition interpreter, but are a great way to convey useful information to human readers of the definition (most often yourself months after the fact).

The second line contains the api-version that the definition is expecting to be executed by. Including the api-version allows Clara Deploy SDK’s definition interpreter to make smart choices when handling definitions defined against other versions of Clara Deploy SDK, including applying rules defined by that version of the API. When api-version is not specified, Clara Deploy SDK’s definition interpreter assumes the current version is intended, regardless of the actual version the definition was created with.

The third line declares the definition’s name. Intended primarily for human use, (it is easier to discuss “the hello world pipeline” than it is to discuss “pipeline 9a16fd80-3f52-489b-b333-1aa553605024”), the value is still expected to be unique to all other names declared in the definition.

The fourth line declares the set of operators that compose the pipeline. The operators property is a list, which can be infered by the first line of an entry beginning with a - character.