AWS imagebuilder: Document retry attribute for Image Builder workflow steps
Summary
Adds documentation for a new `retry` attribute on workflow steps, including `maxAttempts` and `backoffSeconds` fields, retry semantics, per-attempt timeouts, and special behavior for LaunchInstance and ExecuteComponents steps, plus an example.
Security assessment
The change documents a reliability/retry feature for workflow steps. It notes that ExecuteComponents retries re-run components from the beginning without undoing prior changes, which is an operational caveat rather than a security control, so it is not security-related.
Evidence
+retry | Configures Image Builder to automatically run the step again if it fails. For more information, see Retry failed workflow steps. | Dict | No | No retries | The `retry` attribute contains the following fields:
Diff
diff --git a/imagebuilder/latest/userguide/image-workflow-create-document.md b/imagebuilder/latest/userguide/image-workflow-create-document.md index 265b5f090..d0147a230 100644 --- a//imagebuilder/latest/userguide/image-workflow-create-document.md +++ b//imagebuilder/latest/userguide/image-workflow-create-document.md @@ -122,0 +123,6 @@ onFailure | Configures the action to take if the step fails, as follows. +retry | Configures Image Builder to automatically run the step again if it fails. For more information, see Retry failed workflow steps. | Dict | No | No retries | The `retry` attribute contains the following fields: + + * `maxAttempts` (required) – The total number of times that the step can run, including the first attempt. Valid values: 1–10. + * `backoffSeconds` (optional) – The number of seconds that Image Builder waits before it starts each retry attempt. If you don't set a value, Image Builder waits 30 seconds. Valid values: 0–600. + + @@ -154,0 +161,48 @@ waitSeconds | The time, in seconds, for which the step execution will pause. | +#### Retry failed workflow steps + +By default, each step in a workflow runs one time. To have Image Builder automatically run a step again when it fails, add the `retry` attribute to the step. The `retry` attribute contains the following fields. + + * `maxAttempts` (required) – The total number of times that the step can run, including the first attempt. For example, if you set `maxAttempts` to `3` and every attempt fails, the step runs three times before Image Builder marks it as failed. Valid values: 1–10. + + * `backoffSeconds` (optional) – The number of seconds that Image Builder waits before it starts each retry attempt. If you don't set a value, Image Builder waits 30 seconds. To retry immediately, set the value to `0`. Valid values: 0–600. + + + + +Retries work as follows: + + * The `timeoutSeconds` value for the step applies to each attempt separately. The timeout clock restarts when a retry attempt starts. + + * If the step still fails after the final attempt, the `onFailure` behavior for the step applies. + + + + +Some step actions have additional retry behavior: + + * Before it retries a `LaunchInstance` step, Image Builder terminates the instance that the failed attempt launched. The retry attempt launches a new instance. + + * When it retries an `ExecuteComponents` step, Image Builder runs your components again from the beginning. It doesn't undo changes that a failed attempt already made on the instance. Before you configure retries for a step that runs components, make sure that your components can safely run more than once. + + + + +To see how many times a step ran, use the `GetWorkflowStepExecution` or `ListWorkflowStepExecutions` API operations. The response includes the `attemptNumber` and `maxAttempts` fields for the step. + +###### Note + +The `retry` attribute for a workflow step is separate from the `maxAttempts` field, which retries an individual step within a AWSTOE component document. For more information, see [Use the AWSTOE component document framework for custom components](./toe-use-documents.html). + +**Example** + + + steps: + - name: LaunchBuildInstance + action: LaunchInstance + onFailure: Abort + retry: + maxAttempts: 3 + backoffSeconds: 60 + inputs: + waitFor: "ssmAgent" +