pipeline

ordered stages that apply steps to hosts

A pipeline is an ordered list of stages. Each stage applies its steps to a set of hosts.

Files

A pipeline is a file in pipelines/, such as pipelines/site.yaml, or a key in pipelines of winch.yaml. winch plan site and winch apply site run it.

One stage or many

Most pipelines run the same steps on every host. Such a pipeline holds the steps directly. It is one stage with the name of the pipeline. A pipeline whose hosts have different roles, or that must finish on some hosts before it starts on others, has stages.

Order

Stages run in order. A stage starts when the previous stage finished on all its hosts. Inside a stage, each host runs its steps in order, without waiting for other hosts. A stage that matches no host is skipped. --stages runs only some stages, and --hosts only some hosts.

Steps of a stage

A step in a stage can use a module directly. It cannot use template, source, or the key of repo: those read the files of a recipe.

Failures

A failed host takes no part in later stages. The other hosts go on. A new run is the resume: steps that already succeeded check as ok.

Keys

pipeline.stages

list of maps

Stages in run order. A stage starts when the previous stage finished on all its hosts. A pipeline with stages has no other key.

pipeline.stages.name

string, required

Unique in the pipeline. It follows the rule of host names. --stages selects stages by name.

pipeline.stages.hosts

string, default all

Host pattern. Run winch doc inventory for the patterns.

pipeline.stages.parallelism

integer

Maximum hosts at the same time. Hosts start in inventory order. The next host starts when a host finishes the stage and its health gate passes. A failure stops new hosts from starting. Running hosts finish the stage.

pipeline.stages.health

map

Check after a host changed in the stage. The gate runs on a host after it finishes the stage, when the stage has a change on that host. The plan marks it with * and does not run it. A gate that fails stays pending on the host, and the next apply runs it.

pipeline.stages.health.command

string, required

Must exit 0. winch runs it on the host once per second until it exits 0, then keeps running it for stable seconds. A failed run starts the wait again. An exit of 126 or 127, when sh cannot find or run the command, fails the gate at once.

pipeline.stages.health.stable

integer, default 0

Seconds the command keeps passing. It is less than timeout.

pipeline.stages.health.timeout

integer, default 60

Seconds the gate has to pass. Then the host fails, and the error shows the end of the last output.

pipeline.stages.steps

list of steps, required

Recipe steps and module steps, in order.

pipeline.stages.handlers

map of lists of steps

Handlers of the stage, as in a recipe. A module step of the stage notifies them.

pipeline.hosts

string, default all

Host pattern of a pipeline without stages. Run winch doc inventory for the patterns.

pipeline.parallelism

integer

Maximum hosts at the same time. Hosts start in inventory order. The next host starts when a host finishes the stage and its health gate passes. A failure stops new hosts from starting. Running hosts finish the stage.

pipeline.health

map

Check after a host changed in the stage. The gate runs on a host after it finishes the stage, when the stage has a change on that host. The plan marks it with * and does not run it. A gate that fails stays pending on the host, and the next apply runs it.

pipeline.health.command

string, required

Must exit 0. winch runs it on the host once per second until it exits 0, then keeps running it for stable seconds. A failed run starts the wait again. An exit of 126 or 127, when sh cannot find or run the command, fails the gate at once.

pipeline.health.stable

integer, default 0

Seconds the command keeps passing. It is less than timeout.

pipeline.health.timeout

integer, default 60

Seconds the gate has to pass. Then the host fails, and the error shows the end of the last output.

pipeline.steps

list of steps

Steps of a pipeline without stages: recipe steps and module steps, in order.

pipeline.handlers

map of lists of steps

Handlers of a pipeline without stages, as in a recipe. A module step of the stage notifies them.

Example

# pipelines/site.yaml
stages:
  - name: base
    hosts: all
    parallelism: 1
    steps:
      - timezone:
          name: Etc/UTC
  - name: web
    hosts: web
    health:
      command: systemctl is-active nginx
      stable: 10
      timeout: 120
    steps:
      - recipe: nginx

# winch.yaml
name: acme
inventories:
  production:
    hosts:
      web1.acme.com: {}
      web2.acme.com: {}
    groups:
      web:
        hosts: [web1.acme.com, web2.acme.com]
recipes:
  nginx:
    steps:
      - pkg:
          name: nginx