hosts

Creates, updates, deletes, gets or lists a hosts resource.

Overview

Name	hosts
Type	Resource
Id	aws.ec2.hosts

Fields

The following fields are returned by SELECT queries:

describe_hosts

Name	Datatype	Description
allocation_time	string	The time that the Dedicated Host was allocated.
allows_multiple_instance_types	string	Indicates whether the Dedicated Host supports multiple instance types of the same instance family. If the value is on, the Dedicated Host supports multiple instance types in the instance family. If the value is off, the Dedicated Host supports a single instance type only.
asset_id	string	The ID of the Outpost hardware asset on which the Dedicated Host is allocated.
auto_placement	string	Whether auto-placement is on or off.
availability_zone	string	The Availability Zone of the Dedicated Host.
availability_zone_id	string	The ID of the Availability Zone in which the Dedicated Host is allocated.
available_capacity	string	Information about the instances running on the Dedicated Host.
client_token	string	Unique, case-sensitive identifier that you provide to ensure the idempotency of the request. For more information, see Ensuring Idempotency.
cpu_options	string	The CPU options for the Dedicated Host, including AMD Secure Encrypted Virtualization-Secure Nested Paging (AMD SEV-SNP) settings.
host_id	string	The ID of the Dedicated Host.
host_maintenance	string	Indicates whether host maintenance is enabled or disabled for the Dedicated Host.
host_properties	string	The hardware specifications of the Dedicated Host.
host_recovery	string	Indicates whether host recovery is enabled or disabled for the Dedicated Host.
host_reservation_id	string	The reservation ID of the Dedicated Host. This returns a null response if the Dedicated Host doesn't have an associated reservation.
instances	string	The IDs and instance type that are currently running on the Dedicated Host.
member_of_service_linked_resource_group	boolean	Indicates whether the Dedicated Host is in a host resource group. If memberOfServiceLinkedResourceGroup is true, the host is in a host resource group; otherwise, it is not.
outpost_arn	string	The Amazon Resource Name (ARN) of the Amazon Web Services Outpost on which the Dedicated Host is allocated.
owner_id	string	The ID of the Amazon Web Services account that owns the Dedicated Host.
release_time	string	The time that the Dedicated Host was released.
state	string	The Dedicated Host's state.
tags	string	Any tags assigned to the Dedicated Host.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_hosts	select	region	HostId, NextToken, MaxResults, Filter	Describes the specified Dedicated Hosts or all your Dedicated Hosts. The results describe only the Dedicated Hosts in the Region you're currently using. All listed instances consume capacity on your Dedicated Host. Dedicated Hosts that have recently been released are listed with the state released.
modify_hosts	update	HostId, region	HostRecovery, InstanceType, InstanceFamily, HostMaintenance, AutoPlacement	Modify the auto-placement setting of a Dedicated Host. When auto-placement is enabled, any instances that you launch with a tenancy of host but without a specific host ID are placed onto any available Dedicated Host in your account that has auto-placement enabled. When auto-placement is disabled, you need to provide a host ID to have the instance launch onto a specific host. If no host ID is provided, the instance is launched onto a suitable host with auto-placement enabled. You can also use this API action to modify a Dedicated Host to support either multiple instance types in an instance family, or to support a specific instance type only.
allocate_hosts	update	region	InstanceFamily, TagSpecification, HostRecovery, OutpostArn, HostMaintenance, AssetId, AvailabilityZoneId, CpuOptions, AutoPlacement, ClientToken, InstanceType, Quantity, AvailabilityZone	Allocates a Dedicated Host to your account. At a minimum, specify the supported instance type or instance family, the Availability Zone in which to allocate the host, and the number of hosts to allocate.
release_hosts	exec	HostId, region		When you no longer want to use an On-Demand Dedicated Host it can be released. On-Demand billing is stopped and the host goes into released state. The host ID of Dedicated Hosts that have been released can no longer be specified in another request, for example, to modify the host. You must stop or terminate all instances on a host before it can be released. When Dedicated Hosts are released, it may take some time for them to stop counting toward your limit and you may receive capacity errors when trying to allocate new Dedicated Hosts. Wait a few minutes and then try again. Released hosts still appear in a DescribeHosts response.

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.

Name	Datatype	Description
HostId	array	The IDs of the Dedicated Hosts to release.
region	string	AWS region (default: us-east-1)
AssetId	array	The IDs of the Outpost hardware assets on which to allocate the Dedicated Hosts. Targeting specific hardware assets on an Outpost can help to minimize latency between your workloads. This parameter is supported only if you specify OutpostArn. If you are allocating the Dedicated Hosts in a Region, omit this parameter. If you specify this parameter, you can omit Quantity. In this case, Amazon EC2 allocates a Dedicated Host on each specified hardware asset. If you specify both AssetIds and Quantity, then the value for Quantity must be equal to the number of asset IDs specified.
AutoPlacement	string	Indicates whether the host accepts any untargeted instance launches that match its instance type configuration, or if it only accepts Host tenancy instance launches that specify its unique host ID. For more information, see Understanding auto-placement and affinity in the Amazon EC2 User Guide. Default: off
AvailabilityZone	string	The Availability Zone in which to allocate the Dedicated Host.
AvailabilityZoneId	string	The ID of the Availability Zone.
ClientToken	string	Unique, case-sensitive identifier that you provide to ensure the idempotency of the request. For more information, see Ensuring Idempotency.
CpuOptions	object	The CPU configuration options to apply to the Dedicated Host.
Filter	array	The filters. auto-placement - Whether auto-placement is enabled or disabled (on | off). availability-zone - The Availability Zone of the host. client-token - The idempotency token that you provided when you allocated the host. host-reservation-id - The ID of the reservation assigned to this host. instance-type - The instance type size that the Dedicated Host is configured to support. state - The allocation state of the Dedicated Host (available | under-assessment | permanent-failure | released | released-permanent-failure). tag-key - The key of a tag assigned to the resource. Use this filter to find all resources assigned a tag with a specific key, regardless of the tag value.
HostId	array	The IDs of the Dedicated Hosts. The IDs are used for targeted instance launches.
HostMaintenance	string	Indicates whether to enable or disable host maintenance for the Dedicated Host. For more information, see Host maintenance in the Amazon EC2 User Guide.
HostRecovery	string	Indicates whether to enable or disable host recovery for the Dedicated Host. Host recovery is disabled by default. For more information, see Host recovery in the Amazon EC2 User Guide. Default: off
InstanceFamily	string	Specifies the instance family to be supported by the Dedicated Hosts. If you specify an instance family, the Dedicated Hosts support multiple instance types within that instance family. If you want the Dedicated Hosts to support a specific instance type only, omit this parameter and specify InstanceType instead. You cannot specify InstanceFamily and InstanceType in the same request.
InstanceType	string	Specifies the instance type to be supported by the Dedicated Hosts. If you specify an instance type, the Dedicated Hosts support instances of the specified instance type only. If you want the Dedicated Hosts to support multiple instance types in a specific instance family, omit this parameter and specify InstanceFamily instead. You cannot specify InstanceType and InstanceFamily in the same request.
MaxResults	integer	The maximum number of results to return for the request in a single page. The remaining results can be seen by sending another request with the returned nextToken value. This value can be between 5 and 500. If maxResults is given a larger value than 500, you receive an error. You cannot specify this parameter and the host IDs parameter in the same request.
NextToken	string	The token to use to retrieve the next page of results.
OutpostArn	string	The Amazon Resource Name (ARN) of the Amazon Web Services Outpost on which to allocate the Dedicated Host. If you specify OutpostArn, you can optionally specify AssetIds. If you are allocating the Dedicated Host in a Region, omit this parameter.
Quantity	integer	The number of Dedicated Hosts to allocate to your account with these parameters. If you are allocating the Dedicated Hosts on an Outpost, and you specify AssetIds, you can omit this parameter. In this case, Amazon EC2 allocates a Dedicated Host on each specified hardware asset. If you specify both AssetIds and Quantity, then the value that you specify for Quantity must be equal to the number of asset IDs specified.
TagSpecification	array	The tags to apply to the Dedicated Host during creation.

SELECT examples

describe_hosts

Describes the specified Dedicated Hosts or all your Dedicated Hosts. The results describe only the Dedicated Hosts in the Region you're currently using. All listed instances consume capacity on your Dedicated Host. Dedicated Hosts that have recently been released are listed with the state released.

SELECT
allocation_time,
allows_multiple_instance_types,
asset_id,
auto_placement,
availability_zone,
availability_zone_id,
available_capacity,
client_token,
cpu_options,
host_id,
host_maintenance,
host_properties,
host_recovery,
host_reservation_id,
instances,
member_of_service_linked_resource_group,
outpost_arn,
owner_id,
release_time,
state,
tags
FROM aws.ec2.hosts
WHERE region = '{{ region }}' -- required
AND HostId = '{{ HostId }}'
AND NextToken = '{{ NextToken }}'
AND MaxResults = '{{ MaxResults }}'
AND Filter = '{{ Filter }}'
;

UPDATE examples

modify_hosts

Modify the auto-placement setting of a Dedicated Host. When auto-placement is enabled, any instances that you launch with a tenancy of host but without a specific host ID are placed onto any available Dedicated Host in your account that has auto-placement enabled. When auto-placement is disabled, you need to provide a host ID to have the instance launch onto a specific host. If no host ID is provided, the instance is launched onto a suitable host with auto-placement enabled. You can also use this API action to modify a Dedicated Host to support either multiple instance types in an instance family, or to support a specific instance type only.

UPDATE aws.ec2.hosts
SET 
-- No updatable properties
WHERE 
HostId = '{{ HostId }}' --required
AND region = '{{ region }}' --required
AND HostRecovery = '{{ HostRecovery}}'
AND InstanceType = '{{ InstanceType}}'
AND InstanceFamily = '{{ InstanceFamily}}'
AND HostMaintenance = '{{ HostMaintenance}}'
AND AutoPlacement = '{{ AutoPlacement}}'
RETURNING
successful,
unsuccessful;

allocate_hosts

Allocates a Dedicated Host to your account. At a minimum, specify the supported instance type or instance family, the Availability Zone in which to allocate the host, and the number of hosts to allocate.

UPDATE aws.ec2.hosts
SET 
-- No updatable properties
WHERE 
region = '{{ region }}' --required
AND InstanceFamily = '{{ InstanceFamily}}'
AND TagSpecification = '{{ TagSpecification}}'
AND HostRecovery = '{{ HostRecovery}}'
AND OutpostArn = '{{ OutpostArn}}'
AND HostMaintenance = '{{ HostMaintenance}}'
AND AssetId = '{{ AssetId}}'
AND AvailabilityZoneId = '{{ AvailabilityZoneId}}'
AND CpuOptions = '{{ CpuOptions}}'
AND AutoPlacement = '{{ AutoPlacement}}'
AND ClientToken = '{{ ClientToken}}'
AND InstanceType = '{{ InstanceType}}'
AND Quantity = '{{ Quantity}}'
AND AvailabilityZone = '{{ AvailabilityZone}}'
RETURNING
host_ids;

Lifecycle Methods

release_hosts

When you no longer want to use an On-Demand Dedicated Host it can be released. On-Demand billing is stopped and the host goes into released state. The host ID of Dedicated Hosts that have been released can no longer be specified in another request, for example, to modify the host. You must stop or terminate all instances on a host before it can be released. When Dedicated Hosts are released, it may take some time for them to stop counting toward your limit and you may receive capacity errors when trying to allocate new Dedicated Hosts. Wait a few minutes and then try again. Released hosts still appear in a DescribeHosts response.

EXEC aws.ec2.hosts.release_hosts 
@HostId='{{ HostId }}' --required, 
@region='{{ region }}' --required
;