Custom Workflows

The execution role comes first

Custom workflows always require an execution role — the role Image Builder itself assumes to run the workflows. Without one, create-image/create-image-pipeline rejects the request: An execution role is required to provide workflows. The EC2ImageBuilderExecutionPolicy managed policy covers the baseline permissions:

This is not the build role from creating-images.md step 3 (that one lives on the build instance); the execution role is assumed by the Image Builder service.

Define and attach workflows

Start from an Amazon-managed workflow document rather than writing one from scratch — aws imagebuilder get-workflow returns the YAML in the data field. The document shape (steps chain via $.stepOutputs):

Like components, create-workflow accepts --dry-run to validate the document without creating anything — a valid document returns DryRunOperationException (“Request would have succeeded”), an invalid one returns the actual validation error. Create your version, then attach it to the build along with the execution role:

• Workflow types are BUILD, TEST, and DISTRIBUTION. A distribution workflow is an optional override — without one, the attached distribution configuration still runs; the Amazon-managed distribute-image and distribute-container are the starting points. The Amazon-managed defaults are arn:aws:imagebuilder:${region}:aws:workflow/build/build-image/x.x.x and .../workflow/test/test-image/x.x.x, and Amazon-managed variants exist too (e.g. build-image-with-update-ssm-agent) — browse with aws imagebuilder list-workflows --owner Amazon.
• The same --workflows + --execution-role pair works on create-image-pipeline.
• Workflows can pause for approval or external automation with a WaitForAction step, which does its own wiring: it publishes an EC2 Image Builder Workflow Step Waiting event to the default EventBridge bus, and can invoke a Lambda function asynchronously (lambdaFunctionName, with an optional JSON payload). The invocation carries the waiting step’s execution id, so the function can run its checks and act directly; whatever responds — automation or an operator — resumes or stops the build with send-workflow-step-action --action RESUME|STOP (pause default 3 days, maximum 7; the call’s reason surfaces as the step’s reason output). Lambda invocation needs lambda:InvokeFunction on the execution role, scoped to the invoked function’s ARN.
• An ExecuteStateMachine step starts an AWS Step Functions state machine (stateMachineArn, optional JSON input) and waits for it to complete — the direct integration for compliance validation or certification flows. The execution role needs states:StartExecution and states:DescribeExecution, scoped to the state machine and its executions.
• A RunCommand step runs an SSM command document against the build instance (documentName, parameters, and instanceId.$ chained from the launch step) — the hook for hardening, scanning, or setup logic that lives in SSM documents rather than components.
• If a custom-workflow build finishes AVAILABLE but the “output” AMI is just the parent AMI (possibly owned by another account): the build likely attached only a TEST workflow — without a BUILD workflow, no new AMI is created.
• Each step action’s inputs, outputs, timeouts, and IAM requirements are in the supported step actions documentation (opens in a new tab); the broader document schema and workflow management are in the image workflows documentation (opens in a new tab).