Skip to main content

image_builders

Creates, updates, deletes, gets or lists an image_builders resource.

Overview​

Nameimage_builders
TypeResource
Idaws.appstream.image_builders

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
access_endpointsarrayThe list of virtual private cloud (VPC) interface endpoint objects. Administrators can connect to the image builder only through the specified endpoints.
appstream_agent_versionstringThe version of the WorkSpaces Applications agent that is currently being used by the image builder.
arnstringThe ARN for the image builder. (pattern: <code>^arn:aws(?:-cn|-iso-b|-iso|-us-gov)?:[A-Za-z0-9][A-Za-z0-9_/.-]{0,62}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9][A-Za-z0-9:_/+=,@.\-]{0,1023}$</code>)
created_timestring (date-time)The time stamp when the image builder was created.
descriptionstringThe description to display.
disable_imdsv1booleanIndicates whether Instance Metadata Service Version 1 (IMDSv1) is disabled for the image builder.
display_namestringThe image builder name to display.
domain_join_infoobjectThe name of the directory and organizational unit (OU) to use to join the image builder to a Microsoft Active Directory domain.
enable_default_internet_accessbooleanEnables or disables default internet access for the image builder.
iam_role_arnstringThe ARN of the IAM role that is applied to the image builder. To assume a role, the image builder calls the AWS Security Token Service (STS) AssumeRole API operation and passes the ARN of the role to use. The operation creates a new session with temporary credentials. WorkSpaces Applications retrieves the temporary credentials and creates the appstream_machine_role credential profile on the instance. For more information, see Using an IAM Role to Grant Permissions to Applications and Scripts Running on WorkSpaces Applications Streaming Instances in the Amazon WorkSpaces Applications Administration Guide. (pattern: <code>^arn:aws(?:-cn|-iso-b|-iso|-us-gov)?:[A-Za-z0-9][A-Za-z0-9_/.-]{0,62}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9][A-Za-z0-9:_/+=,@.\-]{0,1023}$</code>)
image_arnstringThe ARN of the image from which this builder was created. (pattern: <code>^arn:aws(?:-cn|-iso-b|-iso|-us-gov)?:[A-Za-z0-9][A-Za-z0-9_/.-]{0,62}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9_/.-]{0,63}:[A-Za-z0-9][A-Za-z0-9:_/+=,@.\-]{0,1023}$</code>)
image_builder_errorsarrayThe image builder errors.
instance_typestringThe instance type for the image builder. The following instance types are available: stream.standard.small stream.standard.medium stream.standard.large stream.compute.large stream.compute.xlarge stream.compute.2xlarge stream.compute.4xlarge stream.compute.8xlarge stream.memory.large stream.memory.xlarge stream.memory.2xlarge stream.memory.4xlarge stream.memory.8xlarge stream.memory.z1d.large stream.memory.z1d.xlarge stream.memory.z1d.2xlarge stream.memory.z1d.3xlarge stream.memory.z1d.6xlarge stream.memory.z1d.12xlarge stream.graphics.g4dn.xlarge stream.graphics.g4dn.2xlarge stream.graphics.g4dn.4xlarge stream.graphics.g4dn.8xlarge stream.graphics.g4dn.12xlarge stream.graphics.g4dn.16xlarge stream.graphics.g5.xlarge stream.graphics.g5.2xlarge stream.graphics.g5.4xlarge stream.graphics.g5.8xlarge stream.graphics.g5.16xlarge stream.graphics.g5.12xlarge stream.graphics.g5.24xlarge stream.graphics.g6.xlarge stream.graphics.g6.2xlarge stream.graphics.g6.4xlarge stream.graphics.g6.8xlarge stream.graphics.g6.16xlarge stream.graphics.g6.12xlarge stream.graphics.g6.24xlarge stream.graphics.gr6.4xlarge stream.graphics.gr6.8xlarge stream.graphics.g6f.large stream.graphics.g6f.xlarge stream.graphics.g6f.2xlarge stream.graphics.g6f.4xlarge stream.graphics.gr6f.4xlarge
latest_appstream_agent_versionstringIndicates whether the image builder is using the latest WorkSpaces Applications agent version or not. (TRUE, FALSE)
namestringThe name of the image builder.
network_access_configurationobjectDescribes the network details of the fleet or image builder instance.
platformstringThe operating system platform of the image builder. (WINDOWS, WINDOWS_SERVER_2016, WINDOWS_SERVER_2019, WINDOWS_SERVER_2022, WINDOWS_SERVER_2025, AMAZON_LINUX2, RHEL8, ROCKY_LINUX8, UBUNTU_PRO_2404)
root_volume_configobjectThe current configuration of the root volume for the image builder, including the storage size in GB.
statestringThe state of the image builder. (PENDING, UPDATING_AGENT, RUNNING, STOPPING, STOPPED, REBOOTING, SNAPSHOTTING, DELETING, FAILED, UPDATING, PENDING_QUALIFICATION, PENDING_SYNCING_APPS, SYNCING_APPS, PENDING_IMAGE_IMPORT)
state_change_reasonobjectThe reason why the last state change occurred.
vpc_configobjectThe VPC configuration of the image builder.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_image_buildersselectregionRetrieves a list that describes one or more specified image builders, if the image builder names are provided. Otherwise, all image builders in the account are described.
create_image_builderinsertregion, InstanceTypeCreates an image builder. An image builder is a virtual machine that is used to create an image. The initial state of the builder is PENDING. When it is ready, the state is RUNNING.
create_image_builder_streaming_urlinsertregionCreates a URL to start an image builder streaming session.
associate_software_to_image_builderupdateregion, ImageBuilderName, SoftwareNamesAssociates license included application(s) with an existing image builder instance.
delete_image_builderdeleteregionDeletes the specified image builder and releases the capacity.
disassociate_software_from_image_builderexecregion, ImageBuilderName, SoftwareNamesRemoves license included application(s) association(s) from an image builder instance.
start_software_deployment_to_image_builderexecregion, ImageBuilderNameInitiates license included applications deployment to an image builder instance.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Retrieves a list that describes one or more specified image builders, if the image builder names are provided. Otherwise, all image builders in the account are described.

SELECT
access_endpoints,
appstream_agent_version,
arn,
created_time,
description,
disable_imdsv1,
display_name,
domain_join_info,
enable_default_internet_access,
iam_role_arn,
image_arn,
image_builder_errors,
instance_type,
latest_appstream_agent_version,
name,
network_access_configuration,
platform,
root_volume_config,
state,
state_change_reason,
vpc_config
FROM aws.appstream.image_builders
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Creates an image builder. An image builder is a virtual machine that is used to create an image. The initial state of the builder is PENDING. When it is ready, the state is RUNNING.

INSERT INTO aws.appstream.image_builders (
Name,
ImageName,
ImageArn,
InstanceType,
Description,
DisplayName,
VpcConfig,
IamRoleArn,
EnableDefaultInternetAccess,
DomainJoinInfo,
AppstreamAgentVersion,
Tags,
AccessEndpoints,
RootVolumeConfig,
SoftwaresToInstall,
SoftwaresToUninstall,
DisableIMDSV1,
region
)
SELECT 
'{{ Name }}',
'{{ ImageName }}',
'{{ ImageArn }}',
'{{ InstanceType }}' /* required */,
'{{ Description }}',
'{{ DisplayName }}',
'{{ VpcConfig }}',
'{{ IamRoleArn }}',
{{ EnableDefaultInternetAccess }},
'{{ DomainJoinInfo }}',
'{{ AppstreamAgentVersion }}',
'{{ Tags }}',
'{{ AccessEndpoints }}',
'{{ RootVolumeConfig }}',
'{{ SoftwaresToInstall }}',
'{{ SoftwaresToUninstall }}',
{{ DisableIMDSV1 }},
'{{ region }}'
RETURNING
image_builder
;

UPDATE examples​

Associates license included application(s) with an existing image builder instance.

UPDATE aws.appstream.image_builders
SET 
ImageBuilderName = '{{ ImageBuilderName }}',
SoftwareNames = '{{ SoftwareNames }}'
WHERE 
region = '{{ region }}' --required
AND ImageBuilderName = '{{ ImageBuilderName }}' --required
AND SoftwareNames = '{{ SoftwareNames }}' --required;

DELETE examples​

Deletes the specified image builder and releases the capacity.

DELETE FROM aws.appstream.image_builders
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Removes license included application(s) association(s) from an image builder instance.

EXEC aws.appstream.image_builders.disassociate_software_from_image_builder 
@region='{{ region }}' --required 
@@json=
'{
"ImageBuilderName": "{{ ImageBuilderName }}", 
"SoftwareNames": "{{ SoftwareNames }}"
}'
;
Last updated on