2026/01/20 - Amazon Workspaces Instances - 3 updated api methods
Changes Added billing configuration support for WorkSpaces Instances with monthly and hourly billing modes, including new filtering capabilities for instance type searches.
{'BillingConfiguration': {'BillingMode': 'MONTHLY | HOURLY'}}
Launches a new WorkSpace Instance with specified configuration parameters, enabling programmatic workspace deployment.
See also: AWS API Documentation
Request Syntax
client.create_workspace_instance(
ClientToken='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
],
ManagedInstance={
'BlockDeviceMappings': [
{
'DeviceName': 'string',
'Ebs': {
'VolumeType': 'standard'|'io1'|'io2'|'gp2'|'sc1'|'st1'|'gp3',
'Encrypted': True|False,
'KmsKeyId': 'string',
'Iops': 123,
'Throughput': 123,
'VolumeSize': 123
},
'NoDevice': 'string',
'VirtualName': 'string'
},
],
'CapacityReservationSpecification': {
'CapacityReservationPreference': 'capacity-reservations-only'|'open'|'none',
'CapacityReservationTarget': {
'CapacityReservationId': 'string',
'CapacityReservationResourceGroupArn': 'string'
}
},
'CpuOptions': {
'AmdSevSnp': 'enabled'|'disabled',
'CoreCount': 123,
'ThreadsPerCore': 123
},
'CreditSpecification': {
'CpuCredits': 'standard'|'unlimited'
},
'DisableApiStop': True|False,
'EbsOptimized': True|False,
'EnablePrimaryIpv6': True|False,
'EnclaveOptions': {
'Enabled': True|False
},
'HibernationOptions': {
'Configured': True|False
},
'IamInstanceProfile': {
'Arn': 'string',
'Name': 'string'
},
'ImageId': 'string',
'InstanceMarketOptions': {
'MarketType': 'spot'|'capacity-block',
'SpotOptions': {
'BlockDurationMinutes': 123,
'InstanceInterruptionBehavior': 'hibernate'|'stop',
'MaxPrice': 'string',
'SpotInstanceType': 'one-time'|'persistent',
'ValidUntilUtc': datetime(2015, 1, 1)
}
},
'InstanceType': 'string',
'Ipv6Addresses': [
{
'Ipv6Address': 'string',
'IsPrimaryIpv6': True|False
},
],
'Ipv6AddressCount': 123,
'KernelId': 'string',
'KeyName': 'string',
'LicenseSpecifications': [
{
'LicenseConfigurationArn': 'string'
},
],
'MaintenanceOptions': {
'AutoRecovery': 'disabled'|'default'
},
'MetadataOptions': {
'HttpEndpoint': 'enabled'|'disabled',
'HttpProtocolIpv6': 'enabled'|'disabled',
'HttpPutResponseHopLimit': 123,
'HttpTokens': 'optional'|'required',
'InstanceMetadataTags': 'enabled'|'disabled'
},
'Monitoring': {
'Enabled': True|False
},
'NetworkInterfaces': [
{
'AssociateCarrierIpAddress': True|False,
'AssociatePublicIpAddress': True|False,
'ConnectionTrackingSpecification': {
'TcpEstablishedTimeout': 123,
'UdpStreamTimeout': 123,
'UdpTimeout': 123
},
'Description': 'string',
'DeviceIndex': 123,
'EnaSrdSpecification': {
'EnaSrdEnabled': True|False,
'EnaSrdUdpSpecification': {
'EnaSrdUdpEnabled': True|False
}
},
'InterfaceType': 'interface'|'efa'|'efa-only',
'Ipv4Prefixes': [
{
'Ipv4Prefix': 'string'
},
],
'Ipv4PrefixCount': 123,
'Ipv6AddressCount': 123,
'Ipv6Addresses': [
{
'Ipv6Address': 'string',
'IsPrimaryIpv6': True|False
},
],
'Ipv6Prefixes': [
{
'Ipv6Prefix': 'string'
},
],
'Ipv6PrefixCount': 123,
'NetworkCardIndex': 123,
'NetworkInterfaceId': 'string',
'PrimaryIpv6': True|False,
'PrivateIpAddress': 'string',
'PrivateIpAddresses': [
{
'Primary': True|False,
'PrivateIpAddress': 'string'
},
],
'SecondaryPrivateIpAddressCount': 123,
'Groups': [
'string',
],
'SubnetId': 'string'
},
],
'NetworkPerformanceOptions': {
'BandwidthWeighting': 'default'|'vpc-1'|'ebs-1'
},
'Placement': {
'Affinity': 'string',
'AvailabilityZone': 'string',
'GroupId': 'string',
'GroupName': 'string',
'HostId': 'string',
'HostResourceGroupArn': 'string',
'PartitionNumber': 123,
'Tenancy': 'default'|'dedicated'|'host'
},
'PrivateDnsNameOptions': {
'HostnameType': 'ip-name'|'resource-name',
'EnableResourceNameDnsARecord': True|False,
'EnableResourceNameDnsAAAARecord': True|False
},
'PrivateIpAddress': 'string',
'RamdiskId': 'string',
'SecurityGroupIds': [
'string',
],
'SecurityGroups': [
'string',
],
'SubnetId': 'string',
'TagSpecifications': [
{
'ResourceType': 'instance'|'volume'|'spot-instances-request'|'network-interface',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
'UserData': 'string'
},
BillingConfiguration={
'BillingMode': 'MONTHLY'|'HOURLY'
}
)
string
Unique token to ensure idempotent instance creation, preventing duplicate workspace launches.
This field is autopopulated if not provided.
list
Optional metadata tags for categorizing and managing WorkSpaces Instances.
(dict) --
Represents a key-value metadata tag.
Key (string) --
Unique identifier for the tag.
Value (string) --
Value associated with the tag key.
dict
[REQUIRED]
Comprehensive configuration settings for the WorkSpaces Instance, including network, compute, and storage parameters.
BlockDeviceMappings (list) --
Configures block device mappings for storage.
(dict) --
Defines device mapping for WorkSpace Instance storage.
DeviceName (string) --
Name of the device for storage mapping.
Ebs (dict) --
EBS volume configuration for the device.
VolumeType (string) --
Type of EBS volume (e.g., gp2, io1).
Encrypted (boolean) --
Indicates if the volume is encrypted.
KmsKeyId (string) --
KMS key used for volume encryption.
Iops (integer) --
Input/output operations per second for the volume.
Throughput (integer) --
Volume data transfer rate.
VolumeSize (integer) --
Size of the EBS volume in gigabytes.
NoDevice (string) --
Indicates device should not be mapped.
VirtualName (string) --
Virtual device name for ephemeral storage.
CapacityReservationSpecification (dict) --
Specifies capacity reservation preferences.
CapacityReservationPreference (string) --
Preference for using capacity reservation.
CapacityReservationTarget (dict) --
Specific capacity reservation target.
CapacityReservationId (string) --
Unique identifier for the capacity reservation.
CapacityReservationResourceGroupArn (string) --
ARN of the capacity reservation resource group.
CpuOptions (dict) --
Configures CPU-specific settings.
AmdSevSnp (string) --
AMD Secure Encrypted Virtualization configuration.
CoreCount (integer) --
Number of CPU cores to allocate.
ThreadsPerCore (integer) --
Number of threads per CPU core.
CreditSpecification (dict) --
Defines CPU credit configuration for burstable instances.
CpuCredits (string) --
CPU credit specification mode.
DisableApiStop (boolean) --
Prevents API-initiated instance stop.
EbsOptimized (boolean) --
Enables optimized EBS performance.
EnablePrimaryIpv6 (boolean) --
Enables primary IPv6 address configuration.
EnclaveOptions (dict) --
Configures AWS Nitro Enclave settings.
Enabled (boolean) --
Enables or disables AWS Nitro Enclaves for enhanced security.
HibernationOptions (dict) --
Configures instance hibernation capabilities.
Configured (boolean) --
Enables or disables instance hibernation capability.
IamInstanceProfile (dict) --
Specifies IAM instance profile configuration.
Arn (string) --
Amazon Resource Name (ARN) of the IAM instance profile.
Name (string) --
Name of the IAM instance profile.
ImageId (string) --
Identifies the Amazon Machine Image (AMI) for the instance.
InstanceMarketOptions (dict) --
Configures marketplace-specific deployment options.
MarketType (string) --
Specifies the type of marketplace for instance deployment.
SpotOptions (dict) --
Configuration options for spot instance deployment.
BlockDurationMinutes (integer) --
Duration of spot instance block reservation.
InstanceInterruptionBehavior (string) --
Specifies behavior when spot instance is interrupted.
MaxPrice (string) --
Maximum hourly price for spot instance.
SpotInstanceType (string) --
Defines the type of spot instance request.
ValidUntilUtc (datetime) --
Timestamp until which spot instance request is valid.
InstanceType (string) --
Specifies the WorkSpace Instance type.
Ipv6Addresses (list) --
Configures specific IPv6 addresses.
(dict) --
Represents an IPv6 address configuration for a WorkSpace Instance.
Ipv6Address (string) --
Specific IPv6 address assigned to the instance.
IsPrimaryIpv6 (boolean) --
Indicates if this is the primary IPv6 address for the instance.
Ipv6AddressCount (integer) --
Specifies number of IPv6 addresses to assign.
KernelId (string) --
Identifies the kernel for the instance.
KeyName (string) --
Specifies the key pair for instance access.
LicenseSpecifications (list) --
Configures license-related settings.
(dict) --
Specifies license configuration for WorkSpace Instance.
LicenseConfigurationArn (string) --
ARN of the license configuration for the WorkSpace Instance.
MaintenanceOptions (dict) --
Defines automatic maintenance settings.
AutoRecovery (string) --
Enables or disables automatic instance recovery.
MetadataOptions (dict) --
Configures instance metadata service settings.
HttpEndpoint (string) --
Enables or disables HTTP endpoint for instance metadata.
HttpProtocolIpv6 (string) --
Configures IPv6 support for instance metadata HTTP protocol.
HttpPutResponseHopLimit (integer) --
Sets maximum number of network hops for metadata PUT responses.
HttpTokens (string) --
Configures token requirement for instance metadata retrieval.
InstanceMetadataTags (string) --
Enables or disables instance metadata tags retrieval.
Monitoring (dict) --
Enables or disables detailed instance monitoring.
Enabled (boolean) --
Enables or disables detailed instance monitoring.
NetworkInterfaces (list) --
Configures network interface settings.
(dict) --
Defines network interface configuration for WorkSpace Instance.
AssociateCarrierIpAddress (boolean) --
Enables carrier IP address association.
AssociatePublicIpAddress (boolean) --
Enables public IP address assignment.
ConnectionTrackingSpecification (dict) --
Configures network connection tracking parameters.
TcpEstablishedTimeout (integer) --
Timeout for established TCP connections.
UdpStreamTimeout (integer) --
Timeout for UDP stream connections.
UdpTimeout (integer) --
General timeout for UDP connections.
Description (string) --
Descriptive text for the network interface.
DeviceIndex (integer) --
Unique index for the network interface.
EnaSrdSpecification (dict) --
Configures Elastic Network Adapter Scalable Reliable Datagram settings.
EnaSrdEnabled (boolean) --
Enables or disables ENA SRD for network performance.
EnaSrdUdpSpecification (dict) --
Configures UDP-specific ENA SRD settings.
EnaSrdUdpEnabled (boolean) --
Enables or disables ENA SRD for UDP traffic.
InterfaceType (string) --
Specifies the type of network interface.
Ipv4Prefixes (list) --
IPv4 prefix configurations for the interface.
(dict) --
Specifies IPv4 prefix configuration for network interfaces.
Ipv4Prefix (string) --
Specific IPv4 prefix for network interface configuration.
Ipv4PrefixCount (integer) --
Number of IPv4 prefixes to assign.
Ipv6AddressCount (integer) --
Number of IPv6 addresses to assign.
Ipv6Addresses (list) --
Specific IPv6 addresses for the interface.
(dict) --
Represents an IPv6 address configuration for a WorkSpace Instance.
Ipv6Address (string) --
Specific IPv6 address assigned to the instance.
IsPrimaryIpv6 (boolean) --
Indicates if this is the primary IPv6 address for the instance.
Ipv6Prefixes (list) --
IPv6 prefix configurations for the interface.
(dict) --
Specifies IPv6 prefix configuration for network interfaces.
Ipv6Prefix (string) --
Specific IPv6 prefix for network interface configuration.
Ipv6PrefixCount (integer) --
Number of IPv6 prefixes to assign.
NetworkCardIndex (integer) --
Index of the network card for multiple network interfaces.
NetworkInterfaceId (string) --
Unique identifier for the network interface.
PrimaryIpv6 (boolean) --
Indicates the primary IPv6 configuration.
PrivateIpAddress (string) --
Primary private IP address for the interface.
PrivateIpAddresses (list) --
List of private IP addresses for the interface.
(dict) --
Defines private IP address configuration for network interface.
Primary (boolean) --
Indicates if this is the primary private IP address.
PrivateIpAddress (string) --
Specific private IP address for the network interface.
SecondaryPrivateIpAddressCount (integer) --
Number of additional private IP addresses to assign.
Groups (list) --
Security groups associated with the network interface.
(string) --
SubnetId (string) --
Subnet identifier for the network interface.
NetworkPerformanceOptions (dict) --
Defines network performance configuration.
BandwidthWeighting (string) --
Defines bandwidth allocation strategy for network interfaces.
Placement (dict) --
Specifies instance placement preferences.
Affinity (string) --
Specifies host affinity for dedicated instances.
AvailabilityZone (string) --
Identifies the specific AWS availability zone.
GroupId (string) --
Unique identifier for placement group.
GroupName (string) --
Name of the placement group.
HostId (string) --
Identifies the specific dedicated host.
HostResourceGroupArn (string) --
ARN of the host resource group.
PartitionNumber (integer) --
Specifies partition number for partition placement groups.
Tenancy (string) --
Defines instance tenancy configuration.
PrivateDnsNameOptions (dict) --
Configures private DNS name settings.
HostnameType (string) --
Specifies the type of hostname configuration.
EnableResourceNameDnsARecord (boolean) --
Enables DNS A record for resource name resolution.
EnableResourceNameDnsAAAARecord (boolean) --
Enables DNS AAAA record for resource name resolution.
PrivateIpAddress (string) --
Specifies the primary private IP address.
RamdiskId (string) --
Identifies the ramdisk for the instance.
SecurityGroupIds (list) --
Specifies security group identifiers.
(string) --
SecurityGroups (list) --
Configures security group settings.
(string) --
SubnetId (string) --
Identifies the subnet for the instance.
TagSpecifications (list) --
Configures resource tagging specifications.
(dict) --
Defines tagging configuration for a resource.
ResourceType (string) --
Type of resource being tagged.
Tags (list) --
Collection of tags for the specified resource.
(dict) --
Represents a key-value metadata tag.
Key (string) --
Unique identifier for the tag.
Value (string) --
Value associated with the tag key.
UserData (string) --
Provides custom initialization data for the instance.
dict
Optional billing configuration for the WorkSpace Instance. Allows customers to specify their preferred billing mode when creating a new instance. Defaults to hourly billing if not specified.
BillingMode (string) -- [REQUIRED]
Specifies the billing mode for WorkSpace Instances. MONTHLY provides fixed monthly rates for predictable budgeting, while HOURLY enables pay-per-second billing for actual usage.
dict
Response Syntax
{
'WorkspaceInstanceId': 'string'
}
Response Structure
(dict) --
Returns the unique identifier for the newly created WorkSpaces Instance.
WorkspaceInstanceId (string) --
Unique identifier assigned to the newly created WorkSpaces Instance.
{'BillingConfiguration': {'BillingMode': 'MONTHLY | HOURLY'}}
Retrieves detailed information about a specific WorkSpace Instance.
See also: AWS API Documentation
Request Syntax
client.get_workspace_instance(
WorkspaceInstanceId='string'
)
string
[REQUIRED]
Unique identifier of the WorkSpace Instance to retrieve.
dict
Response Syntax
{
'WorkspaceInstanceErrors': [
{
'ErrorCode': 'string',
'ErrorMessage': 'string'
},
],
'EC2InstanceErrors': [
{
'EC2ErrorCode': 'string',
'EC2ExceptionType': 'string',
'EC2ErrorMessage': 'string'
},
],
'ProvisionState': 'ALLOCATING'|'ALLOCATED'|'DEALLOCATING'|'DEALLOCATED'|'ERROR_ALLOCATING'|'ERROR_DEALLOCATING',
'WorkspaceInstanceId': 'string',
'EC2ManagedInstance': {
'InstanceId': 'string'
},
'BillingConfiguration': {
'BillingMode': 'MONTHLY'|'HOURLY'
}
}
Response Structure
(dict) --
Provides comprehensive details about the requested WorkSpaces Instance.
WorkspaceInstanceErrors (list) --
Captures any errors specific to the WorkSpace Instance lifecycle.
(dict) --
Captures errors specific to WorkSpace Instance operations.
ErrorCode (string) --
Unique error code for the WorkSpace Instance error.
ErrorMessage (string) --
Detailed description of the WorkSpace Instance error.
EC2InstanceErrors (list) --
Includes any underlying EC2 instance errors encountered.
(dict) --
Captures detailed error information for EC2 instance operations.
EC2ErrorCode (string) --
Unique error code identifying the specific EC2 instance error.
EC2ExceptionType (string) --
Type of exception encountered during EC2 instance operation.
EC2ErrorMessage (string) --
Detailed description of the EC2 instance error.
ProvisionState (string) --
Current provisioning state of the WorkSpaces Instance.
WorkspaceInstanceId (string) --
Unique identifier of the retrieved WorkSpaces Instance.
EC2ManagedInstance (dict) --
Details of the associated EC2 managed instance.
InstanceId (string) --
Unique identifier of the managed EC2 instance.
BillingConfiguration (dict) --
Returns the current billing configuration for the WorkSpace Instance, indicating the active billing mode.
BillingMode (string) --
Specifies the billing mode for WorkSpace Instances. MONTHLY provides fixed monthly rates for predictable budgeting, while HOURLY enables pay-per-second billing for actual usage.
{'InstanceConfigurationFilter': {'BillingMode': 'MONTHLY | HOURLY',
'PlatformType': 'Windows | Windows BYOL | '
'Linux/UNIX | Ubuntu Pro '
'Linux | Red Hat Enterprise '
'Linux | Red Hat BYOL Linux | '
'SUSE Linux',
'Tenancy': 'SHARED | DEDICATED'}}
Response {'InstanceTypes': {'SupportedInstanceConfigurations': [{'BillingMode': 'MONTHLY '
'| '
'HOURLY',
'PlatformType': 'Windows '
'| '
'Windows '
'BYOL '
'| '
'Linux/UNIX '
'| '
'Ubuntu '
'Pro '
'Linux '
'| Red '
'Hat '
'Enterprise '
'Linux '
'| Red '
'Hat '
'BYOL '
'Linux '
'| '
'SUSE '
'Linux',
'Tenancy': 'SHARED | '
'DEDICATED'}]}}
Retrieves a list of instance types supported by Amazon WorkSpaces Instances, enabling precise workspace infrastructure configuration.
See also: AWS API Documentation
Request Syntax
client.list_instance_types(
MaxResults=123,
NextToken='string',
InstanceConfigurationFilter={
'BillingMode': 'MONTHLY'|'HOURLY',
'PlatformType': 'Windows'|'Windows BYOL'|'Linux/UNIX'|'Ubuntu Pro Linux'|'Red Hat Enterprise Linux'|'Red Hat BYOL Linux'|'SUSE Linux',
'Tenancy': 'SHARED'|'DEDICATED'
}
)
integer
Maximum number of instance types to return in a single API call. Enables pagination of instance type results.
string
Pagination token for retrieving subsequent pages of instance type results.
dict
Optional filter to narrow instance type results based on configuration requirements. Only returns instance types that support the specified combination of tenancy, platform type, and billing mode.
BillingMode (string) -- [REQUIRED]
Filters WorkSpace Instance types based on supported billing modes. Allows customers to search for instance types that support their preferred billing model, such as HOURLY or MONTHLY billing.
PlatformType (string) -- [REQUIRED]
Filters WorkSpace Instance types by operating system platform. Allows customers to find instances that support their desired OS, such as Windows, Linux/UNIX, Ubuntu Pro, RHEL, or SUSE.
Tenancy (string) -- [REQUIRED]
Filters WorkSpace Instance types by tenancy model. Allows customers to find instances that match their tenancy requirements, such as SHARED or DEDICATED.
dict
Response Syntax
{
'InstanceTypes': [
{
'InstanceType': 'string',
'SupportedInstanceConfigurations': [
{
'BillingMode': 'MONTHLY'|'HOURLY',
'PlatformType': 'Windows'|'Windows BYOL'|'Linux/UNIX'|'Ubuntu Pro Linux'|'Red Hat Enterprise Linux'|'Red Hat BYOL Linux'|'SUSE Linux',
'Tenancy': 'SHARED'|'DEDICATED'
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Contains the list of instance types supported by WorkSpaces Instances.
InstanceTypes (list) --
Collection of supported instance types for WorkSpaces Instances.
(dict) --
Provides details about a specific WorkSpace Instance type.
InstanceType (string) --
Unique identifier for the WorkSpace Instance type.
SupportedInstanceConfigurations (list) --
Lists all valid combinations of tenancy, platform type, and billing mode supported for the specific WorkSpace Instance type. Contains the complete set of configuration options available for this instance type.
(dict) --
Represents a single valid configuration combination that an instance type supports, combining tenancy, platform type, and billing mode into one complete configuration specification.
BillingMode (string) --
Specifies the billing mode supported in this configuration combination.
PlatformType (string) --
Specifies the operating system platform supported in this configuration combination.
Tenancy (string) --
Specifies the tenancy model supported in this configuration combination.
NextToken (string) --
Token for retrieving additional instance types if the result set is paginated.