AWS.ImageBuilder reference

CancelImageCreation

Source: src/AWS/ImageBuilder/CancelImageCreation.ts

Runtime binding for imagebuilder:CancelImageCreation.

Cancels an in-flight image build (only valid for builds in a non-terminal state). Build versions are created dynamically by pipeline runs, so this is an account-level binding: pass the imageBuildVersionArn returned by StartImagePipelineExecution. The idempotency clientToken is generated automatically. Provide the implementation with Effect.provide(AWS.ImageBuilder.CancelImageCreationHttp).

CancelImageCreation: Running Builds

// init — account-level binding, no resource argument
const cancelBuild = yield* AWS.ImageBuilder.CancelImageCreation();

// runtime
yield* cancelBuild({ imageBuildVersionArn });

Component

Source: src/AWS/ImageBuilder/Component.ts

An EC2 Image Builder component — a YAML document that defines the build, validation, and test steps applied to an instance during image creation.

Components are immutable versions: every property except tags replaces the component. Bump semanticVersion when changing the document.

Component: Creating a Component

const component = yield* ImageBuilder.Component("Setup", {
  platform: "Linux",
  semanticVersion: "1.0.0",
  data: [
    "name: setup",
    "description: install packages",
    "schemaVersion: 1.2",
    "phases:",
    "  - name: build",
    "    steps:",
    "      - name: install",
    "        action: ExecuteBash",
    "        inputs:",
    "          commands:",
    "            - dnf install -y htop",
].join("\n"),
});

Component: Using in an Image Recipe

const recipe = yield* ImageBuilder.ImageRecipe("Recipe", {
  parentImage: "arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x",
  components: [{ componentArn: component.componentBuildVersionArn }],
});

DeleteImage

Source: src/AWS/ImageBuilder/DeleteImage.ts

Runtime binding for imagebuilder:DeleteImage.

Deletes an image build version record (it does NOT deregister the EC2 AMIs or delete the ECR container images the build produced — clean those up separately). Useful for pruning failed or cancelled builds at runtime. Account-level binding: pass the build version’s ARN. Provide the implementation with Effect.provide(AWS.ImageBuilder.DeleteImageHttp).

DeleteImage: Running Builds

// init — account-level binding, no resource argument
const deleteImage = yield* AWS.ImageBuilder.DeleteImage();

// runtime
yield* deleteImage({ imageBuildVersionArn });

DistributionConfiguration

Source: src/AWS/ImageBuilder/DistributionConfiguration.ts

An EC2 Image Builder distribution configuration — defines where and how the output AMIs (or containers) of a pipeline are distributed across regions and accounts.

DistributionConfiguration: Creating a Distribution Configuration

const distribution = yield* ImageBuilder.DistributionConfiguration("Dist", {
  distributions: [{
    region: "us-west-2",
    amiDistributionConfiguration: {
      name: "my-app-{{ imagebuilder:buildDate }}",
      amiTags: { project: "my-app" },
    },
  }],
});

DistributionConfiguration: Using in a Pipeline

const pipeline = yield* ImageBuilder.ImagePipeline("Pipeline", {
  imageRecipeArn: recipe.imageRecipeArn,
  infrastructureConfigurationArn: infra.infrastructureConfigurationArn,
  distributionConfigurationArn: distribution.distributionConfigurationArn,
});

GetImage

Source: src/AWS/ImageBuilder/GetImage.ts

Runtime binding for imagebuilder:GetImage.

Reads an image build version by ARN — its state (BUILDING, AVAILABLE, CANCELLED, FAILED, …) and the AMIs/containers it produced. Build versions are created dynamically by pipeline runs, so this is an account-level binding: pass the imageBuildVersionArn returned by StartImagePipelineExecution or found via ListImagePipelineImages. Provide the implementation with Effect.provide(AWS.ImageBuilder.GetImageHttp).

GetImage: Observing Builds

// init — account-level binding, no resource argument
const getImage = yield* AWS.ImageBuilder.GetImage();

// runtime
const { image } = yield* getImage({ imageBuildVersionArn });
yield* Effect.log(`build is ${image?.state?.status}`);

GetImagePipeline

Source: src/AWS/ImageBuilder/GetImagePipeline.ts

Runtime binding for imagebuilder:GetImagePipeline.

Reads the bound ImagePipeline’s current configuration and state — schedule, status, recipe/infrastructure wiring, and the timestamps of the latest and next scheduled runs. The pipeline’s ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.ImageBuilder.GetImagePipelineHttp).

GetImagePipeline: Observing Pipelines

// init — bind the operation to the pipeline
const getPipeline = yield* AWS.ImageBuilder.GetImagePipeline(pipeline);

// runtime
const { imagePipeline } = yield* getPipeline();
yield* Effect.log(
  `${imagePipeline?.name}: ${imagePipeline?.status}, last run ${imagePipeline?.dateLastRun}`,
);

GetWorkflowExecution

Source: src/AWS/ImageBuilder/GetWorkflowExecution.ts

Runtime binding for imagebuilder:GetWorkflowExecution.

Reads the runtime state of one workflow execution (a build/test/distribute workflow run within an image build) — its status, step counts, and timing. Workflow executions are created dynamically by builds, so this is an account-level binding: pass an id from ListWorkflowExecutions. Provide the implementation with Effect.provide(AWS.ImageBuilder.GetWorkflowExecutionHttp).

GetWorkflowExecution: Workflow Monitoring

// init — account-level binding, no resource argument
const getWorkflowExecution = yield* AWS.ImageBuilder.GetWorkflowExecution();

// runtime
const execution = yield* getWorkflowExecution({ workflowExecutionId });
yield* Effect.log(`${execution.type} workflow is ${execution.status}`);

GetWorkflowStepExecution

Source: src/AWS/ImageBuilder/GetWorkflowStepExecution.ts

Runtime binding for imagebuilder:GetWorkflowStepExecution.

Reads the runtime state of one workflow step — its action, status, rollback status, inputs/outputs, and message. Step executions are created dynamically by builds, so this is an account-level binding: pass an id from ListWorkflowStepExecutions or ListWaitingWorkflowSteps. Provide the implementation with Effect.provide(AWS.ImageBuilder.GetWorkflowStepExecutionHttp).

GetWorkflowStepExecution: Workflow Monitoring

// init — account-level binding, no resource argument
const getWorkflowStepExecution =
  yield* AWS.ImageBuilder.GetWorkflowStepExecution();

// runtime
const step = yield* getWorkflowStepExecution({ stepExecutionId });
yield* Effect.log(`step ${step.name} is ${step.status}`);

ImagePipeline

Source: src/AWS/ImageBuilder/ImagePipeline.ts

An EC2 Image Builder image pipeline — wires a recipe to an infrastructure configuration (and optionally a distribution configuration) and automates image builds on a schedule or on demand.

Creating the pipeline does not start a build; builds start on the configured schedule or when explicitly invoked.

ImagePipeline: Creating an Image Pipeline

Manual-Only Pipeline

const pipeline = yield* ImageBuilder.ImagePipeline("Pipeline", {
  imageRecipeArn: recipe.imageRecipeArn,
  infrastructureConfigurationArn: infra.infrastructureConfigurationArn,
  status: "DISABLED",
});

Scheduled Pipeline with Distribution

const pipeline = yield* ImageBuilder.ImagePipeline("Nightly", {
  imageRecipeArn: recipe.imageRecipeArn,
  infrastructureConfigurationArn: infra.infrastructureConfigurationArn,
  distributionConfigurationArn: distribution.distributionConfigurationArn,
  schedule: {
    scheduleExpression: "cron(0 9 * * ? *)",
    pipelineExecutionStartCondition:
      "EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE",
  },
});

ImageRecipe

Source: src/AWS/ImageBuilder/ImageRecipe.ts

An EC2 Image Builder image recipe — the blueprint that combines a parent image with an ordered list of components to produce a new AMI.

Recipes are immutable versions: every property except tags replaces the recipe. Bump semanticVersion when changing the definition.

ImageRecipe: Creating an Image Recipe

const recipe = yield* ImageBuilder.ImageRecipe("Recipe", {
  parentImage: "arn:aws:imagebuilder:us-west-2:aws:image/amazon-linux-2023-x86/x.x.x",
  semanticVersion: "1.0.0",
  components: [{ componentArn: component.componentBuildVersionArn }],
});

ImageRecipe: Using in a Pipeline

const pipeline = yield* ImageBuilder.ImagePipeline("Pipeline", {
  imageRecipeArn: recipe.imageRecipeArn,
  infrastructureConfigurationArn: infra.infrastructureConfigurationArn,
});

InfrastructureConfiguration

Source: src/AWS/ImageBuilder/InfrastructureConfiguration.ts

An EC2 Image Builder infrastructure configuration — the environment (instance profile, instance types, network, logging) in which images are built and tested.

InfrastructureConfiguration: Creating an Infrastructure Configuration

const role = yield* IAM.Role("BuilderRole", {
  assumeRolePolicyDocument: {
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: { Service: "ec2.amazonaws.com" },
      Action: ["sts:AssumeRole"],
    }],
  },
  managedPolicyArns: [
    "arn:aws:iam::aws:policy/EC2InstanceProfileForImageBuilder",
    "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore",
  ],
});
const profile = yield* IAM.InstanceProfile("BuilderProfile", {
  roleName: role.roleName,
});
const infra = yield* ImageBuilder.InfrastructureConfiguration("Infra", {
  instanceProfileName: profile.instanceProfileName,
  instanceTypes: ["t3.micro"],
  terminateInstanceOnFailure: true,
});

ListImageBuildVersions

Source: src/AWS/ImageBuilder/ListImageBuildVersions.ts

Runtime binding for imagebuilder:ListImageBuildVersions.

Lists the build versions of an image version (…:image/{name}/{version}), newest first — each entry reports its state, so a function can find the latest AVAILABLE build of an image. Image versions are created dynamically by pipeline runs, so this is an account-level binding. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListImageBuildVersionsHttp).

ListImageBuildVersions: Observing Builds

// init — account-level binding, no resource argument
const listImageBuildVersions =
  yield* AWS.ImageBuilder.ListImageBuildVersions();

// runtime
const { imageSummaryList } = yield* listImageBuildVersions({
  imageVersionArn,
});

ListImagePackages

Source: src/AWS/ImageBuilder/ListImagePackages.ts

Runtime binding for imagebuilder:ListImagePackages.

Lists the OS packages that Systems Manager Inventory recorded inside an image at build time (only available once the build is AVAILABLE). Build versions are created dynamically by pipeline runs, so this is an account-level binding. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListImagePackagesHttp).

ListImagePackages: Observing Builds

// init — account-level binding, no resource argument
const listImagePackages = yield* AWS.ImageBuilder.ListImagePackages();

// runtime
const { imagePackageList } = yield* listImagePackages({
  imageBuildVersionArn,
});

ListImagePipelineImages

Source: src/AWS/ImageBuilder/ListImagePipelineImages.ts

Runtime binding for imagebuilder:ListImagePipelineImages.

Enumerates the image build versions the bound ImagePipeline has produced — the building block of a “latest AMI from this pipeline” lookup or a build-history dashboard. The pipeline’s ARN is injected from the binding. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListImagePipelineImagesHttp).

ListImagePipelineImages: Observing Pipelines

// init — bind the operation to the pipeline
const listBuilds = yield* AWS.ImageBuilder.ListImagePipelineImages(
  pipeline,
);

// runtime
const { imageSummaryList } = yield* listBuilds();
const available = (imageSummaryList ?? []).filter(
  (image) => image.state?.status === "AVAILABLE",
);

ListImages

Source: src/AWS/ImageBuilder/ListImages.ts

Runtime binding for imagebuilder:ListImages.

Enumerates the image versions you have access to (owned, shared, or Amazon-managed) — e.g. to discover the latest parent image version. Newly created images can take up to two minutes to appear. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListImagesHttp).

ListImages: Observing Builds

// init — account-level binding, no resource argument
const listImages = yield* AWS.ImageBuilder.ListImages();

// runtime
const { imageVersionList } = yield* listImages({ owner: "Self" });
yield* Effect.log(`account has ${imageVersionList?.length ?? 0} images`);

ListImageScanFindingAggregations

Source: src/AWS/ImageBuilder/ListImageScanFindingAggregations.ts

Runtime binding for imagebuilder:ListImageScanFindingAggregations.

Returns Amazon Inspector finding counts grouped by severity — for the whole account, or grouped by one key (imagePipelineArn, imageBuildVersionArn, accountId, vulnerabilityId) when a filter is supplied. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListImageScanFindingAggregationsHttp).

ListImageScanFindingAggregations: Scan Findings

// init — account-level binding, no resource argument
const listImageScanFindingAggregations =
  yield* AWS.ImageBuilder.ListImageScanFindingAggregations();

// runtime
const { responses } = yield* listImageScanFindingAggregations({
  filter: { name: "imagePipelineArn", values: [pipelineArn] },
});

ListImageScanFindings

Source: src/AWS/ImageBuilder/ListImageScanFindings.ts

Runtime binding for imagebuilder:ListImageScanFindings.

Lists Amazon Inspector scan findings for images in the account (populated when a pipeline has imageScanningConfiguration enabled). Filter by imageBuildVersionArn or imagePipelineArn to narrow to one build or pipeline. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListImageScanFindingsHttp).

ListImageScanFindings: Scan Findings

// init — account-level binding, no resource argument
const listImageScanFindings =
  yield* AWS.ImageBuilder.ListImageScanFindings();

// runtime
const { findings } = yield* listImageScanFindings({
  filters: [{ name: "imagePipelineArn", values: [pipelineArn] }],
});

ListWaitingWorkflowSteps

Source: src/AWS/ImageBuilder/ListWaitingWorkflowSteps.ts

Runtime binding for imagebuilder:ListWaitingWorkflowSteps.

Lists every workflow step in the account that is paused on WAIT_FOR_ACTION — the work queue for an approval function, which then resumes or stops each build with SendWorkflowStepAction. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListWaitingWorkflowStepsHttp).

ListWaitingWorkflowSteps: Workflow Monitoring

// init — account-level binding, no resource argument
const listWaitingWorkflowSteps =
  yield* AWS.ImageBuilder.ListWaitingWorkflowSteps();

// runtime
const { steps } = yield* listWaitingWorkflowSteps();

ListWorkflowExecutions

Source: src/AWS/ImageBuilder/ListWorkflowExecutions.ts

Runtime binding for imagebuilder:ListWorkflowExecutions.

Enumerates the build/test/distribution workflow runs of an image build version — the drill-down view of what a build is currently doing (each entry reports the workflow’s status and step counts). Account-level binding: pass the imageBuildVersionArn. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListWorkflowExecutionsHttp).

ListWorkflowExecutions: Observing Builds

// init — account-level binding, no resource argument
const listWorkflowExecutions =
  yield* AWS.ImageBuilder.ListWorkflowExecutions();

// runtime
const { workflowExecutions } = yield* listWorkflowExecutions({
  imageBuildVersionArn,
});
for (const execution of workflowExecutions ?? []) {
  yield* Effect.log(`${execution.type}: ${execution.status}`);
}

ListWorkflowStepExecutions

Source: src/AWS/ImageBuilder/ListWorkflowStepExecutions.ts

Runtime binding for imagebuilder:ListWorkflowStepExecutions.

Lists the steps of one workflow execution with their runtime status — drill-down from ListWorkflowExecutions. Provide the implementation with Effect.provide(AWS.ImageBuilder.ListWorkflowStepExecutionsHttp).

ListWorkflowStepExecutions: Workflow Monitoring

// init — account-level binding, no resource argument
const listWorkflowStepExecutions =
  yield* AWS.ImageBuilder.ListWorkflowStepExecutions();

// runtime
const { steps } = yield* listWorkflowStepExecutions({
  workflowExecutionId,
});

RetryImage

Source: src/AWS/ImageBuilder/RetryImage.ts

Runtime binding for imagebuilder:RetryImage.

Retries a failed image build in place (same build version ARN) — pair it with consumeImageEvents to automatically retry transient build failures. The idempotency clientToken is generated automatically. Provide the implementation with Effect.provide(AWS.ImageBuilder.RetryImageHttp).

RetryImage: Running Builds

// init — account-level binding, no resource argument
const retryImage = yield* AWS.ImageBuilder.RetryImage();

// runtime
yield* retryImage({ imageBuildVersionArn });

SendWorkflowStepAction

Source: src/AWS/ImageBuilder/SendWorkflowStepAction.ts

Runtime binding for imagebuilder:SendWorkflowStepAction.

Resumes or stops an image build that is paused on a WaitForAction workflow step — the approval half of a human/automated gate (find pending steps with ListWaitingWorkflowSteps). The idempotency clientToken is generated automatically. Provide the implementation with Effect.provide(AWS.ImageBuilder.SendWorkflowStepActionHttp).

SendWorkflowStepAction: Workflow Monitoring

// init — account-level binding, no resource argument
const sendWorkflowStepAction =
  yield* AWS.ImageBuilder.SendWorkflowStepAction();

// runtime
yield* sendWorkflowStepAction({
  stepExecutionId,
  imageBuildVersionArn,
  action: "RESUME",
  reason: "approved by review function",
});

StartImagePipelineExecution

Source: src/AWS/ImageBuilder/StartImagePipelineExecution.ts

Runtime binding for imagebuilder:StartImagePipelineExecution.

Manually kicks off a build of the bound ImagePipeline — the pipeline’s ARN is injected and the idempotency clientToken is generated automatically. Returns the imageBuildVersionArn of the image being created, for use with GetImage / CancelImageCreation. Provide the implementation with Effect.provide(AWS.ImageBuilder.StartImagePipelineExecutionHttp).

StartImagePipelineExecution: Running Builds

// init — bind the operation to the pipeline
const startBuild = yield* AWS.ImageBuilder.StartImagePipelineExecution(
  pipeline,
);

// runtime
const { imageBuildVersionArn } = yield* startBuild();
yield* Effect.log(`building ${imageBuildVersionArn}`);