Create a YAML workflow document

The YAML format definition document configures input, output, and workflow steps for the build, test, and distribution stages of the image creation process. The same document format applies to all three workflow types. You can start from templates that include standardized steps, or you can start from scratch to define your own workflow. Whether you use a template or start from scratch, you can customize the workflow to fit your needs.

Structure of a YAML workflow document

The following sections describe the structure of the YAML workflow document that Image Builder uses to perform image build, test, and distribution actions.

Workflow document identification

Uniquely identifies the workflow. This section can include the following attributes.

Example

---
name: sample-test-image
description: Workflow for a sample image, with extra configuration options exposed through workflow parameters.
schemaVersion: 1.0

Workflow document input parameters

This part of the workflow document defines input parameters that the caller can specify. If you do not have any parameters, you can leave this section out. If you do specify parameters, each parameter can include the following attributes.

You can define up to 25 parameters in a workflow document. Each parameter value can contain up to 1,024 characters. A parameter must use one of four supported data types: string, integer, boolean, or stringList. If you do not specify a default value for a parameter, you must provide the parameter value at runtime.

Example

Specify the parameter in the workflow document.

parameters:
  - name: waitForActionAtEnd
    type: boolean
    default: true
    description: "Wait for an external action at the end of the workflow"

Use the parameter value in the workflow document.

$.parameters.waitForActionAtEnd

Workflow document steps

Specifies up to 15 step actions for the workflow. Steps run in the order that they're defined within the workflow document. In case of failure, a rollback runs in reverse order, starting with the step that failed, and working backward through prior steps.

Each step can refer to the output of any prior step actions. This is known as chaining, or referencing. To refer to output from a prior step action, you can use a JSONPath selector. For example:

$.stepOutputs.step-name.output-name

For more information, see Use dynamic variables in your workflow document.

Each step can include the following attributes.

Example

steps:
  - name: LaunchTestInstance
    action: LaunchInstance
    onFailure: Abort
    inputs:
      waitFor: "ssmAgent"

  - name: ApplyTestComponents
    action: ExecuteComponents
    onFailure: Abort
    inputs:
      instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"

  - name: TerminateTestInstance
    action: TerminateInstance
    onFailure: Continue
    inputs:
      instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"

  - name: WaitForActionAtEnd
    action: WaitForAction
    if:
      booleanEquals: true
      value: "$.parameters.waitForActionAtEnd"

Workflow document outputs

Defines outputs for the workflow. Each output is a key value pair that specifies the name of the output and the value. You can use outputs to export data at runtime that subsequent workflows can use. This section is optional.

You can define up to 25 outputs in a workflow document. Each output name must be unique across all of the workflows that you include in your pipeline. A later workflow can then reference an output by name with $.workflowOutputs.name.

Each output that you define includes the following attributes.

Example

Create an output image ID for the workflow document with step output from the createProdImage step.

outputs:
  - name: 'outputImageId'
    value: '$.stepOutputs.createProdImage.imageId'

Refer to the workflow output in the next workflow.

$.workflowOutputs.outputImageId