[ aws . ec2 ]

allocate-hosts

Description

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.

See also: AWS API Documentation

See ‘aws help’ for descriptions of global parameters.

Synopsis

  allocate-hosts
[--auto-placement <value>]
--availability-zone <value>
[--client-token <value>]
[--instance-type <value>]
[--instance-family <value>]
--quantity <value>
[--tag-specifications <value>]
[--host-recovery <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--cli-auto-prompt <value>]

Options

--auto-placement (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 Instance Placement and Host Affinity in the Amazon EC2 User Guide for Linux Instances .

Default: on

Possible values:

• on

• off

--availability-zone (string)

The Availability Zone in which to allocate the Dedicated Host.

--client-token (string)

Unique, case-sensitive identifier that you provide to ensure the idempotency of the request. For more information, see How to Ensure Idempotency .

--instance-type (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.

--instance-family (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.

--quantity (integer)

The number of Dedicated Hosts to allocate to your account with these parameters.

--tag-specifications (list)

The tags to apply to the Dedicated Host during creation.

(structure)

The tags to apply to a resource when the resource is being created.

ResourceType -> (string)

The type of resource to tag. Currently, the resource types that support tagging on creation are: capacity-reservation | client-vpn-endpoint | dedicated-host | dhcp-options | export-image-task | export-instance-task | fleet | fpga-image | host-reservation | import-image-task | import-snapshot-task | instance | internet-gateway | ipv4pool-ec2 | ipv6pool-ec2 | key-pair | launch-template | placement-group | prefix-list | natgateway | network-acl | security-group | spot-fleet-request | spot-instances-request | snapshot | subnet | traffic-mirror-filter | traffic-mirror-session | traffic-mirror-target | transit-gateway | transit-gateway-attachment | transit-gateway-route-table | volume |vpc | vpc-endpoint (for interface and gateway endpoints) | vpc-endpoint-service (for AWS PrivateLink) | vpc-flow-log .

To tag a resource after it has been created, see CreateTags .

Tags -> (list)

The tags to apply to the resource.

(structure)

Describes a tag.

Key -> (string)

The key of the tag.

Constraints: Tag keys are case-sensitive and accept a maximum of 127 Unicode characters. May not begin with aws: .

Value -> (string)

The value of the tag.

Constraints: Tag values are case-sensitive and accept a maximum of 255 Unicode characters.

Shorthand Syntax:

ResourceType=string,Tags=[{Key=string,Value=string},{Key=string,Value=string}] ...

JSON Syntax:

[
  {
    "ResourceType": "client-vpn-endpoint"|"customer-gateway"|"dedicated-host"|"dhcp-options"|"elastic-ip"|"elastic-gpu"|"export-image-task"|"export-instance-task"|"fleet"|"fpga-image"|"host-reservation"|"image"|"import-image-task"|"import-snapshot-task"|"instance"|"internet-gateway"|"key-pair"|"launch-template"|"local-gateway-route-table-vpc-association"|"natgateway"|"network-acl"|"network-interface"|"placement-group"|"reserved-instances"|"route-table"|"security-group"|"snapshot"|"spot-fleet-request"|"spot-instances-request"|"subnet"|"traffic-mirror-filter"|"traffic-mirror-session"|"traffic-mirror-target"|"transit-gateway"|"transit-gateway-attachment"|"transit-gateway-multicast-domain"|"transit-gateway-route-table"|"volume"|"vpc"|"vpc-peering-connection"|"vpn-connection"|"vpn-gateway"|"vpc-flow-log",
    "Tags": [
      {
        "Key": "string",
        "Value": "string"
      }
      ...
    ]
  }
  ...
]

--host-recovery (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 Elastic Compute Cloud User Guide .

Default: off

Possible values:

• on

• off

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

--cli-auto-prompt (boolean) Automatically prompt for CLI input parameters.

See ‘aws help’ for descriptions of global parameters.

Examples

Example 1: To allocate a Dedicated Host

The following allocate-hosts example allocates a single Dedicated Host in the eu-west-1a Availability Zone, onto which you can launch m5.large instances. By default, the Dedicated Host accepts only target instance launches, and does not support host recovery.

aws ec2 allocate-hosts \
    --instance-type m5.large \
    --availability-zone eu-west-1a \
    --quantity 1

Output:

{
    "HostIds": [
        "h-07879acf49EXAMPLE"
    ]
}

Example 2: To allocate a Dedicated Host with auto-placement and host recovery enabled

The following allocate-hosts example allocates a single Dedicated Host in the eu-west-1a Availability Zone with auto-placement and host recovery enabled.

aws ec2 allocate-hosts \
    --instance-type m5.large \
    --availability-zone eu-west-1a \
    --auto-placement on \
    --host-recovery on \
    --quantity 1

Output:

{
     "HostIds": [
         "h-07879acf49EXAMPLE"
     ]
}

Example 3: To allocate a Dedicated Host with tags

The following allocate-hosts example allocates a single Dedicated Host and applies a tag with a key named purpose and a value of production.

aws ec2 allocate-hosts \
    --instance-type m5.large \
    --availability-zone eu-west-1a \
    --quantity 1 \
    --tag-specifications 'ResourceType=dedicated-host,Tags={Key=purpose,Value=production}'

Output:

{
    "HostIds": [
        "h-07879acf49EXAMPLE"
    ]
}

For more information, see Allocating Dedicated Hosts in the Amazon Elastic Compute Cloud User Guide for Linux Instances.

Output

HostIds -> (list)

The ID of the allocated Dedicated Host. This is used to launch an instance onto a specific host.

(string)