Skip to content

Begins an ad-hoc state change for the specified image build version

Description

Begins an ad-hoc state change for the specified image build version. This is a one-time operation - if you schedule the update, it runs only once. If the request includes underlying resources, or schedules the update far enough in the future, Image Builder runs the update as an asynchronous lifecycle execution and returns its identifier. Otherwise, for target states other than DELETED, the state change applies immediately. If a request that starts a lifecycle execution arrives while the image already has one in progress, Image Builder rejects it.

Usage

imagebuilder_start_resource_state_update(resourceArn, state,
  executionRole, includeResources, exclusionRules, updateAt, clientToken)

Arguments

  • resourceArn

    [required] The Amazon Resource Name (ARN) of the image build version to update. The image must be in one of these terminal states: AVAILABLE, DEPRECATED, DISABLED, FAILED, or CANCELLED. Images with FAILED or CANCELLED status can transition only to DELETED.

  • state

    [required] Specifies the lifecycle action to take for this request. For AMI-based images, valid values are AVAILABLE, DEPRECATED, DISABLED, and DELETED. For container-based images, only DELETED is supported.

  • executionRole

    The name or Amazon Resource Name (ARN) of the IAM role that's used to update image state. You must provide this property together with includeResources. Neither is valid without the other.

  • includeResources

    Specifies which underlying resources to update, in addition to the Image Builder image resource itself. Snapshots and containers are only valid for the DELETED state. To set an image to DELETED, you must include its underlying resources. To delete only the Image Builder image record, use the delete_image operation instead.

  • exclusionRules

    Rules that Image Builder evaluates against each of the image's AMIs. Matching AMIs and their snapshots are skipped. Exclusion rules only take effect when the request includes AMIs. If the target state is DELETED and any resource was skipped, the Image Builder image resource itself is also retained. For the DEPRECATED and DISABLED target states, Image Builder updates the image resource's state regardless of exclusions.

  • updateAt

    The timestamp that indicates when resources are updated by a lifecycle action. This property is valid only when the target status is DEPRECATED, and the value must be a future time. If you don't specify a value, Image Builder begins the state update right away. For a scheduled deprecation, included AMIs get their EC2 deprecation time set immediately, and Image Builder schedules the image resource to transition to DEPRECATED at that time.

  • clientToken

    [required] A unique, case-sensitive identifier you provide to ensure that the operation runs no more than one time. If you retry a request with the same client token, Image Builder returns the original response without running the operation again. For more information, see Ensuring idempotency in the Amazon EC2 API Reference.

Value

A list with the following syntax:

list(
  lifecycleExecutionId = "string",
  resourceArn = "string"
)

Request syntax

svc$start_resource_state_update(
  resourceArn = "string",
  state = list(
    status = "AVAILABLE"|"DELETED"|"DEPRECATED"|"DISABLED"
  ),
  executionRole = "string",
  includeResources = list(
    amis = TRUE|FALSE,
    snapshots = TRUE|FALSE,
    containers = TRUE|FALSE
  ),
  exclusionRules = list(
    amis = list(
      isPublic = TRUE|FALSE,
      regions = list(
        "string"
      ),
      sharedAccounts = list(
        "string"
      ),
      lastLaunched = list(
        value = 123,
        unit = "DAYS"|"WEEKS"|"MONTHS"|"YEARS"
      ),
      tagMap = list(
        "string"
      )
    )
  ),
  updateAt = as.POSIXct(
    "2015-01-01"
  ),
  clientToken = "string"
)