diff --git a/website/docs/cdktf/python/r/instance.html.markdown b/website/docs/cdktf/python/r/instance.html.markdown new file mode 100644 index 00000000000..0c17c25a439 --- /dev/null +++ b/website/docs/cdktf/python/r/instance.html.markdown @@ -0,0 +1,505 @@ +--- +subcategory: "EC2 (Elastic Compute Cloud)" +layout: "aws" +page_title: "AWS: aws_instance" +description: |- + Provides an EC2 instance resource. This allows instances to be created, updated, and deleted. Instances also support provisioning. +--- + + + +# Resource: aws_instance + +Provides an EC2 instance resource. This allows instances to be created, updated, and deleted. Instances also support [provisioning](https://www.terraform.io/docs/provisioners/index.html). + +## Example Usage + +### Basic example using AMI lookup + +```python +# Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +from constructs import Construct +from cdktf import Token, TerraformStack +# +# Provider bindings are generated by running `cdktf get`. +# See https://cdk.tf/provider-generation for more details. +# +from imports.aws.data_aws_ami import DataAwsAmi +from imports.aws.instance import Instance +class MyConvertedCode(TerraformStack): + def __init__(self, scope, name): + super().__init__(scope, name) + ubuntu = DataAwsAmi(self, "ubuntu", + filter=[DataAwsAmiFilter( + name="name", + values=["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"] + ), DataAwsAmiFilter( + name="virtualization-type", + values=["hvm"] + ) + ], + most_recent=True, + owners=["099720109477"] + ) + Instance(self, "web", + ami=Token.as_string(ubuntu.id), + instance_type="t3.micro", + tags={ + "Name": "HelloWorld" + } + ) +``` + +### Spot instance example + +```python +# Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +from constructs import Construct +from cdktf import Token, TerraformStack +# +# Provider bindings are generated by running `cdktf get`. +# See https://cdk.tf/provider-generation for more details. +# +from imports.aws.data_aws_ami import DataAwsAmi +from imports.aws.instance import Instance +class MyConvertedCode(TerraformStack): + def __init__(self, scope, name): + super().__init__(scope, name) + this_var = DataAwsAmi(self, "this", + filter=[DataAwsAmiFilter( + name="architecture", + values=["arm64"] + ), DataAwsAmiFilter( + name="name", + values=["al2023-ami-2023*"] + ) + ], + most_recent=True, + owners=["amazon"] + ) + aws_instance_this = Instance(self, "this_1", + ami=Token.as_string(this_var.id), + instance_market_options=InstanceInstanceMarketOptions( + spot_options=InstanceInstanceMarketOptionsSpotOptions( + max_price=Token.as_string(0.0031) + ) + ), + instance_type="t4g.nano", + tags={ + "Name": "test-spot" + } + ) + # This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match. + aws_instance_this.override_logical_id("this") +``` + +### Network and credit specification example + +```python +# Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +from constructs import Construct +from cdktf import TerraformStack +# +# Provider bindings are generated by running `cdktf get`. +# See https://cdk.tf/provider-generation for more details. +# +from imports.aws.instance import Instance +from imports.aws.network_interface import NetworkInterface +from imports.aws.subnet import Subnet +from imports.aws.vpc import Vpc +class MyConvertedCode(TerraformStack): + def __init__(self, scope, name): + super().__init__(scope, name) + my_vpc = Vpc(self, "my_vpc", + cidr_block="172.16.0.0/16", + tags={ + "Name": "tf-example" + } + ) + my_subnet = Subnet(self, "my_subnet", + availability_zone="us-west-2a", + cidr_block="172.16.10.0/24", + tags={ + "Name": "tf-example" + }, + vpc_id=my_vpc.id + ) + foo = NetworkInterface(self, "foo", + private_ips=["172.16.10.100"], + subnet_id=my_subnet.id, + tags={ + "Name": "primary_network_interface" + } + ) + aws_instance_foo = Instance(self, "foo_3", + ami="ami-005e54dee72cc1d00", + credit_specification=InstanceCreditSpecification( + cpu_credits="unlimited" + ), + instance_type="t2.micro", + network_interface=[InstanceNetworkInterface( + device_index=0, + network_interface_id=foo.id + ) + ] + ) + # This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match. + aws_instance_foo.override_logical_id("foo") +``` + +### CPU options example + +```python +# Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +from constructs import Construct +from cdktf import Token, TerraformStack +# +# Provider bindings are generated by running `cdktf get`. +# See https://cdk.tf/provider-generation for more details. +# +from imports.aws.data_aws_ami import DataAwsAmi +from imports.aws.instance import Instance +from imports.aws.subnet import Subnet +from imports.aws.vpc import Vpc +class MyConvertedCode(TerraformStack): + def __init__(self, scope, name): + super().__init__(scope, name) + example = Vpc(self, "example", + cidr_block="172.16.0.0/16", + tags={ + "Name": "tf-example" + } + ) + amzn_linux2023_ami = DataAwsAmi(self, "amzn-linux-2023-ami", + filter=[DataAwsAmiFilter( + name="name", + values=["al2023-ami-2023.*-x86_64"] + ) + ], + most_recent=True, + owners=["amazon"] + ) + aws_subnet_example = Subnet(self, "example_2", + availability_zone="us-east-2a", + cidr_block="172.16.10.0/24", + tags={ + "Name": "tf-example" + }, + vpc_id=example.id + ) + # This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match. + aws_subnet_example.override_logical_id("example") + aws_instance_example = Instance(self, "example_3", + ami=Token.as_string(amzn_linux2023_ami.id), + cpu_options=InstanceCpuOptions( + core_count=2, + threads_per_core=2 + ), + instance_type="c6a.2xlarge", + subnet_id=Token.as_string(aws_subnet_example.id), + tags={ + "Name": "tf-example" + } + ) + # This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match. + aws_instance_example.override_logical_id("example") +``` + +### Host resource group or Licence Manager registered AMI example + +A host resource group is a collection of Dedicated Hosts that you can manage as a single entity. As you launch instances, License Manager allocates the hosts and launches instances on them based on the settings that you configured. You can add existing Dedicated Hosts to a host resource group and take advantage of automated host management through License Manager. + +-> **NOTE:** A dedicated host is automatically associated with a License Manager host resource group if **Allocate hosts automatically** is enabled. Otherwise, use the `host_resource_group_arn` argument to explicitly associate the instance with the host resource group. + +```python +# Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +from constructs import Construct +from cdktf import TerraformStack +# +# Provider bindings are generated by running `cdktf get`. +# See https://cdk.tf/provider-generation for more details. +# +from imports.aws.instance import Instance +class MyConvertedCode(TerraformStack): + def __init__(self, scope, name): + super().__init__(scope, name) + Instance(self, "this", + ami="ami-0dcc1e21636832c5d", + host_resource_group_arn="arn:aws:resource-groups:us-west-2:012345678901:group/win-testhost", + instance_type="m5.large", + tenancy="host" + ) +``` + +## Argument Reference + +The following arguments are supported: + +* `ami` - (Optional) AMI to use for the instance. Required unless `launch_template` is specified and the Launch Template specifes an AMI. If an AMI is specified in the Launch Template, setting `ami` will override the AMI specified in the Launch Template. +* `associate_public_ip_address` - (Optional) Whether to associate a public IP address with an instance in a VPC. +* `availability_zone` - (Optional) AZ to start the instance in. + +* `capacity_reservation_specification` - (Optional) Describes an instance's Capacity Reservation targeting option. See [Capacity Reservation Specification](#capacity-reservation-specification) below for more details. + +-> **NOTE:** Changing `cpu_core_count` and/or `cpu_threads_per_core` will cause the resource to be destroyed and re-created. + +* `cpu_core_count` - (Optional, **Deprecated** use the `cpu_options` argument instead) Sets the number of CPU cores for an instance. This option is only supported on creation of instance type that support CPU Options [CPU Cores and Threads Per CPU Core Per Instance Type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#cpu-options-supported-instances-values) - specifying this option for unsupported instance types will return an error from the EC2 API. +* `cpu_options` - (Optional) The CPU options for the instance. See [CPU Options](#cpu-options) below for more details. +* `cpu_threads_per_core` - (Optional - has no effect unless `cpu_core_count` is also set, **Deprecated** use the `cpu_options` argument instead) If set to 1, hyperthreading is disabled on the launched instance. Defaults to 2 if not set. See [Optimizing CPU Options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) for more information. +* `credit_specification` - (Optional) Configuration block for customizing the credit specification of the instance. See [Credit Specification](#credit-specification) below for more details. Terraform will only perform drift detection of its value when present in a configuration. Removing this configuration on existing instances will only stop managing it. It will not change the configuration back to the default for the instance type. +* `disable_api_stop` - (Optional) If true, enables [EC2 Instance Stop Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html#Using_StopProtection). +* `disable_api_termination` - (Optional) If true, enables [EC2 Instance Termination Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingDisableAPITermination). +* `ebs_block_device` - (Optional) One or more configuration blocks with additional EBS block devices to attach to the instance. Block device configurations only apply on resource creation. See [Block Devices](#ebs-ephemeral-and-root-block-devices) below for details on attributes and drift detection. When accessing this as an attribute reference, it is a set of objects. +* `ebs_optimized` - (Optional) If true, the launched EC2 instance will be EBS-optimized. Note that if this is not set on an instance type that is optimized by default then this will show as disabled but if the instance type is optimized by default then there is no need to set this and there is no effect to disabling it. See the [EBS Optimized section](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html) of the AWS User Guide for more information. +* `enclave_options` - (Optional) Enable Nitro Enclaves on launched instances. See [Enclave Options](#enclave-options) below for more details. +* `ephemeral_block_device` - (Optional) One or more configuration blocks to customize Ephemeral (also known as "Instance Store") volumes on the instance. See [Block Devices](#ebs-ephemeral-and-root-block-devices) below for details. When accessing this as an attribute reference, it is a set of objects. +* `get_password_data` - (Optional) If true, wait for password data to become available and retrieve it. Useful for getting the administrator password for instances running Microsoft Windows. The password data is exported to the `password_data` attribute. See [GetPasswordData](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_GetPasswordData.html) for more information. +* `hibernation` - (Optional) If true, the launched EC2 instance will support hibernation. +* `host_id` - (Optional) ID of a dedicated host that the instance will be assigned to. Use when an instance is to be launched on a specific dedicated host. +* `host_resource_group_arn` - (Optional) ARN of the host resource group in which to launch the instances. If you specify an ARN, omit the `tenancy` parameter or set it to `host`. +* `iam_instance_profile` - (Optional) IAM Instance Profile to launch the instance with. Specified as the name of the Instance Profile. Ensure your credentials have the correct permission to assign the instance profile according to the [EC2 documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html#roles-usingrole-ec2instance-permissions), notably `iam:PassRole`. +* `instance_initiated_shutdown_behavior` - (Optional) Shutdown behavior for the instance. Amazon defaults this to `stop` for EBS-backed instances and `terminate` for instance-store instances. Cannot be set on instance-store instances. See [Shutdown Behavior](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingInstanceInitiatedShutdownBehavior) for more information. +* `instance_market_options` - (Optional) Describes the market (purchasing) option for the instances. See [Market Options](#market-options) below for details on attributes. +* `instance_type` - (Optional) Instance type to use for the instance. Required unless `launch_template` is specified and the Launch Template specifies an instance type. If an instance type is specified in the Launch Template, setting `instance_type` will override the instance type specified in the Launch Template. Updates to this field will trigger a stop/start of the EC2 instance. +* `ipv6_address_count`- (Optional) Number of IPv6 addresses to associate with the primary network interface. Amazon EC2 chooses the IPv6 addresses from the range of your subnet. +* `ipv6_addresses` - (Optional) Specify one or more IPv6 addresses from the range of the subnet to associate with the primary network interface +* `key_name` - (Optional) Key name of the Key Pair to use for the instance; which can be managed using [the `aws_key_pair` resource](key_pair.html). +* `launch_template` - (Optional) Specifies a Launch Template to configure the instance. Parameters configured on this resource will override the corresponding parameters in the Launch Template. See [Launch Template Specification](#launch-template-specification) below for more details. +* `maintenance_options` - (Optional) Maintenance and recovery options for the instance. See [Maintenance Options](#maintenance-options) below for more details. +* `metadata_options` - (Optional) Customize the metadata options of the instance. See [Metadata Options](#metadata-options) below for more details. +* `monitoring` - (Optional) If true, the launched EC2 instance will have detailed monitoring enabled. (Available since v0.6.0) +* `network_interface` - (Optional) Customize network interfaces to be attached at instance boot time. See [Network Interfaces](#network-interfaces) below for more details. +* `placement_group` - (Optional) Placement Group to start the instance in. +* `placement_partition_number` - (Optional) Number of the partition the instance is in. Valid only if [the `aws_placement_group` resource's](placement_group.html) `strategy` argument is set to `"partition"`. +* `private_dns_name_options` - (Optional) Options for the instance hostname. The default values are inherited from the subnet. See [Private DNS Name Options](#private-dns-name-options) below for more details. +* `private_ip` - (Optional) Private IP address to associate with the instance in a VPC. +* `root_block_device` - (Optional) Configuration block to customize details about the root block device of the instance. See [Block Devices](#ebs-ephemeral-and-root-block-devices) below for details. When accessing this as an attribute reference, it is a list containing one object. +* `secondary_private_ips` - (Optional) List of secondary private IPv4 addresses to assign to the instance's primary network interface (eth0) in a VPC. Can only be assigned to the primary network interface (eth0) attached at instance creation, not a pre-existing network interface i.e., referenced in a `network_interface` block. Refer to the [Elastic network interfaces documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html#AvailableIpPerENI) to see the maximum number of private IP addresses allowed per instance type. +* `security_groups` - (Optional, EC2-Classic and default VPC only) List of security group names to associate with. + +-> **NOTE:** If you are creating Instances in a VPC, use `vpc_security_group_ids` instead. + +* `source_dest_check` - (Optional) Controls if traffic is routed to the instance when the destination address does not match the instance. Used for NAT or VPNs. Defaults true. +* `subnet_id` - (Optional) VPC Subnet ID to launch in. +* `tags` - (Optional) Map of tags to assign to the resource. Note that these tags apply to the instance and not block storage devices. If configured with a provider [`default_tags` configuration block](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#default_tags-configuration-block) present, tags with matching keys will overwrite those defined at the provider-level. +* `tenancy` - (Optional) Tenancy of the instance (if the instance is running in a VPC). An instance with a tenancy of `dedicated` runs on single-tenant hardware. The `host` tenancy is not supported for the import-instance command. Valid values are `default`, `dedicated`, and `host`. +* `user_data` - (Optional) User data to provide when launching the instance. Do not pass gzip-compressed data via this argument; see `user_data_base64` instead. Updates to this field will trigger a stop/start of the EC2 instance by default. If the `user_data_replace_on_change` is set then updates to this field will trigger a destroy and recreate. +* `user_data_base64` - (Optional) Can be used instead of `user_data` to pass base64-encoded binary data directly. Use this instead of `user_data` whenever the value is not a valid UTF-8 string. For example, gzip-encoded user data must be base64-encoded and passed via this argument to avoid corruption. Updates to this field will trigger a stop/start of the EC2 instance by default. If the `user_data_replace_on_change` is set then updates to this field will trigger a destroy and recreate. +* `user_data_replace_on_change` - (Optional) When used in combination with `user_data` or `user_data_base64` will trigger a destroy and recreate when set to `true`. Defaults to `false` if not set. +* `volume_tags` - (Optional) Map of tags to assign, at instance-creation time, to root and EBS volumes. + +~> **NOTE:** Do not use `volume_tags` if you plan to manage block device tags outside the `aws_instance` configuration, such as using `tags` in an [`aws_ebs_volume`](/docs/providers/aws/r/ebs_volume.html) resource attached via [`aws_volume_attachment`](/docs/providers/aws/r/volume_attachment.html). Doing so will result in resource cycling and inconsistent behavior. + +* `vpc_security_group_ids` - (Optional, VPC only) List of security group IDs to associate with. + +### Capacity Reservation Specification + +~> **NOTE:** You can specify only one argument at a time. If you specify both `capacity_reservation_preference` and `capacity_reservation_target`, the request fails. Modifying `capacity_reservation_preference` or `capacity_reservation_target` in this block requires the instance to be in `stopped` state. + +Capacity reservation specification can be applied/modified to the EC2 Instance at creation time or when the instance is `stopped`. + +The `capacity_reservation_specification` block supports the following: + +* `capacity_reservation_preference` - (Optional) Indicates the instance's Capacity Reservation preferences. Can be `"open"` or `"none"`. (Default: `"open"`). +* `capacity_reservation_target` - (Optional) Information about the target Capacity Reservation. See [Capacity Reservation Target](#capacity-reservation-target) below for more details. + +For more information, see the documentation on [Capacity Reservations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/capacity-reservations-using.html). + +### Capacity Reservation Target + +~> **NOTE:** Modifying `capacity_reservation_id` in this block requires the instance to be in `stopped` state. + +Describes a target Capacity Reservation. + +This `capacity_reservation_target` block supports the following: + +* `capacity_reservation_id` - (Optional) ID of the Capacity Reservation in which to run the instance. +* `capacity_reservation_resource_group_arn` - (Optional) ARN of the Capacity Reservation resource group in which to run the instance. + +### CPU Options + +-> **NOTE:** Changing any of `amd_sev_snp`, `core_count`, `threads_per_core` will cause the resource to be destroyed and re-created. + +CPU options apply to the instance at launch time. + +The `cpu_options` block supports the following: + +* `amd_sev_snp` - (Optional) Indicates whether to enable the instance for AMD SEV-SNP. AMD SEV-SNP is supported with M6a, R6a, and C6a instance types only. Valid values are `enabled` and `disabled`. +* `core_count` - (Optional) Sets the number of CPU cores for an instance. This option is only supported on creation of instance type that support CPU Options [CPU Cores and Threads Per CPU Core Per Instance Type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#cpu-options-supported-instances-values) - specifying this option for unsupported instance types will return an error from the EC2 API. +* `threads_per_core` - (Optional - has no effect unless `core_count` is also set) If set to 1, hyperthreading is disabled on the launched instance. Defaults to 2 if not set. See [Optimizing CPU Options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) for more information. + +For more information, see the documentation on [Optimizing CPU options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html). + +### Credit Specification + +The `credit_specification` block supports the following: + +* `cpu_credits` - (Optional) Credit option for CPU usage. Valid values include `standard` or `unlimited`. T3 instances are launched as unlimited by default. T2 instances are launched as standard by default. + +### EBS, Ephemeral, and Root Block Devices + +Each of the `*_block_device` attributes control a portion of the EC2 Instance's "Block Device Mapping". For more information, see the [AWS Block Device Mapping documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html). + +The `root_block_device` block supports the following: + +* `delete_on_termination` - (Optional) Whether the volume should be destroyed on instance termination. Defaults to `true`. +* `encrypted` - (Optional) Whether to enable volume encryption. Defaults to `false`. Must be configured to perform drift detection. +* `iops` - (Optional) Amount of provisioned [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html). Only valid for volume_type of `io1`, `io2` or `gp3`. +* `kms_key_id` - (Optional) Amazon Resource Name (ARN) of the KMS Key to use when encrypting the volume. Must be configured to perform drift detection. +* `tags` - (Optional) Map of tags to assign to the device. +* `throughput` - (Optional) Throughput to provision for a volume in mebibytes per second (MiB/s). This is only valid for `volume_type` of `gp3`. +* `volume_size` - (Optional) Size of the volume in gibibytes (GiB). +* `volume_type` - (Optional) Type of volume. Valid values include `standard`, `gp2`, `gp3`, `io1`, `io2`, `sc1`, or `st1`. Defaults to `gp2`. + +Modifying the `encrypted` or `kms_key_id` settings of the `root_block_device` requires resource replacement. + +Each `ebs_block_device` block supports the following: + +* `delete_on_termination` - (Optional) Whether the volume should be destroyed on instance termination. Defaults to `true`. +* `device_name` - (Required) Name of the device to mount. +* `encrypted` - (Optional) Enables [EBS encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html) on the volume. Defaults to `false`. Cannot be used with `snapshot_id`. Must be configured to perform drift detection. +* `iops` - (Optional) Amount of provisioned [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html). Only valid for volume_type of `io1`, `io2` or `gp3`. +* `kms_key_id` - (Optional) Amazon Resource Name (ARN) of the KMS Key to use when encrypting the volume. Must be configured to perform drift detection. +* `snapshot_id` - (Optional) Snapshot ID to mount. +* `tags` - (Optional) Map of tags to assign to the device. +* `throughput` - (Optional) Throughput to provision for a volume in mebibytes per second (MiB/s). This is only valid for `volume_type` of `gp3`. +* `volume_size` - (Optional) Size of the volume in gibibytes (GiB). +* `volume_type` - (Optional) Type of volume. Valid values include `standard`, `gp2`, `gp3`, `io1`, `io2`, `sc1`, or `st1`. Defaults to `gp2`. + +~> **NOTE:** Currently, changes to the `ebs_block_device` configuration of _existing_ resources cannot be automatically detected by Terraform. To manage changes and attachments of an EBS block to an instance, use the `aws_ebs_volume` and `aws_volume_attachment` resources instead. If you use `ebs_block_device` on an `aws_instance`, Terraform will assume management over the full set of non-root EBS block devices for the instance, treating additional block devices as drift. For this reason, `ebs_block_device` cannot be mixed with external `aws_ebs_volume` and `aws_volume_attachment` resources for a given instance. + +Each `ephemeral_block_device` block supports the following: + +* `device_name` - Name of the block device to mount on the instance. +* `no_device` - (Optional) Suppresses the specified device included in the AMI's block device mapping. +* `virtual_name` - (Optional) [Instance Store Device Name](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#InstanceStoreDeviceNames) (e.g., `ephemeral0`). + +Each AWS Instance type has a different set of Instance Store block devices available for attachment. AWS [publishes a list](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#StorageOnInstanceTypes) of which ephemeral devices are available on each type. The devices are always identified by the `virtual_name` in the format `ephemeral{0..N}`. + +### Enclave Options + +-> **NOTE:** Changing `enabled` will cause the resource to be destroyed and re-created. + +Enclave options apply to the instance at boot time. + +The `enclave_options` block supports the following: + +* `enabled` - (Optional) Whether Nitro Enclaves will be enabled on the instance. Defaults to `false`. + +For more information, see the documentation on [Nitro Enclaves](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html). + +### Maintenance Options + +The `maintenance_options` block supports the following: + +* `auto_recovery` - (Optional) Automatic recovery behavior of the Instance. Can be `"default"` or `"disabled"`. See [Recover your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-recover.html) for more details. + +### Market Options + +The `instance_market_options` block supports the following: + +* `market_type` - (Optional) Type of market for the instance. Valid value is `spot`. Defaults to `spot`. +* `spot_options` - (Optional) Block to configure the options for Spot Instances. See [Spot Options](#spot-options) below for details on attributes. + +### Metadata Options + +Metadata options can be applied/modified to the EC2 Instance at any time. + +The `metadata_options` block supports the following: + +* `http_endpoint` - (Optional) Whether the metadata service is available. Valid values include `enabled` or `disabled`. Defaults to `enabled`. +* `http_put_response_hop_limit` - (Optional) Desired HTTP PUT response hop limit for instance metadata requests. The larger the number, the further instance metadata requests can travel. Valid values are integer from `1` to `64`. Defaults to `1`. +* `http_tokens` - (Optional) Whether or not the metadata service requires session tokens, also referred to as _Instance Metadata Service Version 2 (IMDSv2)_. Valid values include `optional` or `required`. Defaults to `optional`. +* `instance_metadata_tags` - (Optional) Enables or disables access to instance tags from the instance metadata service. Valid values include `enabled` or `disabled`. Defaults to `disabled`. + +For more information, see the documentation on the [Instance Metadata Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html). + +### Network Interfaces + +Each of the `network_interface` blocks attach a network interface to an EC2 Instance during boot time. However, because the network interface is attached at boot-time, replacing/modifying the network interface **WILL** trigger a recreation of the EC2 Instance. If you should need at any point to detach/modify/re-attach a network interface to the instance, use the `aws_network_interface` or `aws_network_interface_attachment` resources instead. + +The `network_interface` configuration block _does_, however, allow users to supply their own network interface to be used as the default network interface on an EC2 Instance, attached at `eth0`. + +Each `network_interface` block supports the following: + +* `delete_on_termination` - (Optional) Whether or not to delete the network interface on instance termination. Defaults to `false`. Currently, the only valid value is `false`, as this is only supported when creating new network interfaces when launching an instance. +* `device_index` - (Required) Integer index of the network interface attachment. Limited by instance type. +* `network_card_index` - (Optional) Integer index of the network card. Limited by instance type. The default index is `0`. +* `network_interface_id` - (Required) ID of the network interface to attach. + +### Private DNS Name Options + +The `private_dns_name_options` block supports the following: + +* `enable_resource_name_dns_aaaa_record` - Indicates whether to respond to DNS queries for instance hostnames with DNS AAAA records. +* `enable_resource_name_dns_a_record` - Indicates whether to respond to DNS queries for instance hostnames with DNS A records. +* `hostname_type` - Type of hostname for Amazon EC2 instances. For IPv4 only subnets, an instance DNS name must be based on the instance IPv4 address. For IPv6 native subnets, an instance DNS name must be based on the instance ID. For dual-stack subnets, you can specify whether DNS names use the instance IPv4 address or the instance ID. Valid values: `ip-name` and `resource-name`. + +### Spot Options + +The `spot_options` block supports the following: + +* `instance_interruption_behavior` - (Optional) The behavior when a Spot Instance is interrupted. Valid values include `hibernate`, `stop`, `terminate` . The default is `terminate`. +* `max_price` - (Optional) The maximum hourly price that you're willing to pay for a Spot Instance. +* `spot_instance_type` - (Optional) The Spot Instance request type. Valid values include `one-time`, `persistent`. Persistent Spot Instance requests are only supported when the instance interruption behavior is either hibernate or stop. The default is `one-time`. +* `valid_until` - (Optional) The end date of the request, in UTC format (YYYY-MM-DDTHH:MM:SSZ). Supported only for persistent requests. + +### Launch Template Specification + +-> **Note:** Launch Template parameters will be used only once during instance creation. If you want to update existing instance you need to change parameters +directly. Updating Launch Template specification will force a new instance. + +Any other instance parameters that you specify will override the same parameters in the launch template. + +The `launch_template` block supports the following: + +* `id` - ID of the launch template. Conflicts with `name`. +* `name` - Name of the launch template. Conflicts with `id`. +* `version` - Template version. Can be a specific version number, `$Latest` or `$Default`. The default value is `$Default`. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `arn` - ARN of the instance. +* `capacity_reservation_specification` - Capacity reservation specification of the instance. +* `instance_state` - State of the instance. One of: `pending`, `running`, `shutting-down`, `terminated`, `stopping`, `stopped`. See [Instance Lifecycle](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-lifecycle.html) for more information. +* `outpost_arn` - ARN of the Outpost the instance is assigned to. +* `password_data` - Base-64 encoded encrypted password data for the instance. Useful for getting the administrator password for instances running Microsoft Windows. This attribute is only exported if `get_password_data` is true. Note that this encrypted value will be stored in the state file, as with all exported attributes. See [GetPasswordData](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_GetPasswordData.html) for more information. +* `primary_network_interface_id` - ID of the instance's primary network interface. +* `private_dns` - Private DNS name assigned to the instance. Can only be used inside the Amazon EC2, and only available if you've enabled DNS hostnames for your VPC. +* `public_dns` - Public DNS name assigned to the instance. For EC2-VPC, this is only available if you've enabled DNS hostnames for your VPC. +* `public_ip` - Public IP address assigned to the instance, if applicable. **NOTE**: If you are using an [`aws_eip`](/docs/providers/aws/r/eip.html) with your instance, you should refer to the EIP's address directly and not use `public_ip` as this field will change after the EIP is attached. +* `tags_all` - Map of tags assigned to the resource, including those inherited from the provider [`default_tags` configuration block](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#default_tags-configuration-block). + +For `ebs_block_device`, in addition to the arguments above, the following attribute is exported: + +* `volume_id` - ID of the volume. For example, the ID can be accessed like this, `aws_instance.web.ebs_block_device.2.volume_id`. + +For `root_block_device`, in addition to the arguments above, the following attributes are exported: + +* `volume_id` - ID of the volume. For example, the ID can be accessed like this, `aws_instance.web.root_block_device.0.volume_id`. +* `device_name` - Device name, e.g., `/dev/sdh` or `xvdh`. + +For `instance_market_options`, in addition to the arguments above, the following attributes are exported: + +* `instance_lifecycle` - Indicates whether this is a Spot Instance or a Scheduled Instance. +* `spot_instance_request_id` - If the request is a Spot Instance request, the ID of the request. + +## Timeouts + +[Configuration options](https://developer.hashicorp.com/terraform/language/resources/syntax#operation-timeouts): + +* `create` - (Default `10m`) +* `update` - (Default `10m`) +* `delete` - (Default `20m`) + +## Import + +Instances can be imported using the `id`, e.g., + +``` +$ terraform import aws_instance.web i-12345678 +``` + + \ No newline at end of file diff --git a/website/docs/cdktf/typescript/r/instance.html.markdown b/website/docs/cdktf/typescript/r/instance.html.markdown new file mode 100644 index 00000000000..21955fee960 --- /dev/null +++ b/website/docs/cdktf/typescript/r/instance.html.markdown @@ -0,0 +1,527 @@ +--- +subcategory: "EC2 (Elastic Compute Cloud)" +layout: "aws" +page_title: "AWS: aws_instance" +description: |- + Provides an EC2 instance resource. This allows instances to be created, updated, and deleted. Instances also support provisioning. +--- + + + +# Resource: aws_instance + +Provides an EC2 instance resource. This allows instances to be created, updated, and deleted. Instances also support [provisioning](https://www.terraform.io/docs/provisioners/index.html). + +## Example Usage + +### Basic example using AMI lookup + +```typescript +// Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +import { Construct } from "constructs"; +import { Token, TerraformStack } from "cdktf"; +/* + * Provider bindings are generated by running `cdktf get`. + * See https://cdk.tf/provider-generation for more details. + */ +import { DataAwsAmi } from "./.gen/providers/aws/data-aws-ami"; +import { Instance } from "./.gen/providers/aws/instance"; +class MyConvertedCode extends TerraformStack { + constructor(scope: Construct, name: string) { + super(scope, name); + const ubuntu = new DataAwsAmi(this, "ubuntu", { + filter: [ + { + name: "name", + values: ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"], + }, + { + name: "virtualization-type", + values: ["hvm"], + }, + ], + mostRecent: true, + owners: ["099720109477"], + }); + new Instance(this, "web", { + ami: Token.asString(ubuntu.id), + instanceType: "t3.micro", + tags: { + Name: "HelloWorld", + }, + }); + } +} + +``` + +### Spot instance example + +```typescript +// Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +import { Construct } from "constructs"; +import { Token, TerraformStack } from "cdktf"; +/* + * Provider bindings are generated by running `cdktf get`. + * See https://cdk.tf/provider-generation for more details. + */ +import { DataAwsAmi } from "./.gen/providers/aws/data-aws-ami"; +import { Instance } from "./.gen/providers/aws/instance"; +class MyConvertedCode extends TerraformStack { + constructor(scope: Construct, name: string) { + super(scope, name); + const thisVar = new DataAwsAmi(this, "this", { + filter: [ + { + name: "architecture", + values: ["arm64"], + }, + { + name: "name", + values: ["al2023-ami-2023*"], + }, + ], + mostRecent: true, + owners: ["amazon"], + }); + const awsInstanceThis = new Instance(this, "this_1", { + ami: Token.asString(thisVar.id), + instanceMarketOptions: { + spotOptions: { + maxPrice: Token.asString(0.0031), + }, + }, + instanceType: "t4g.nano", + tags: { + Name: "test-spot", + }, + }); + /*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/ + awsInstanceThis.overrideLogicalId("this"); + } +} + +``` + +### Network and credit specification example + +```typescript +// Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +import { Construct } from "constructs"; +import { TerraformStack } from "cdktf"; +/* + * Provider bindings are generated by running `cdktf get`. + * See https://cdk.tf/provider-generation for more details. + */ +import { Instance } from "./.gen/providers/aws/instance"; +import { NetworkInterface } from "./.gen/providers/aws/network-interface"; +import { Subnet } from "./.gen/providers/aws/subnet"; +import { Vpc } from "./.gen/providers/aws/vpc"; +class MyConvertedCode extends TerraformStack { + constructor(scope: Construct, name: string) { + super(scope, name); + const myVpc = new Vpc(this, "my_vpc", { + cidrBlock: "172.16.0.0/16", + tags: { + Name: "tf-example", + }, + }); + const mySubnet = new Subnet(this, "my_subnet", { + availabilityZone: "us-west-2a", + cidrBlock: "172.16.10.0/24", + tags: { + Name: "tf-example", + }, + vpcId: myVpc.id, + }); + const foo = new NetworkInterface(this, "foo", { + privateIps: ["172.16.10.100"], + subnetId: mySubnet.id, + tags: { + Name: "primary_network_interface", + }, + }); + const awsInstanceFoo = new Instance(this, "foo_3", { + ami: "ami-005e54dee72cc1d00", + creditSpecification: { + cpuCredits: "unlimited", + }, + instanceType: "t2.micro", + networkInterface: [ + { + deviceIndex: 0, + networkInterfaceId: foo.id, + }, + ], + }); + /*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/ + awsInstanceFoo.overrideLogicalId("foo"); + } +} + +``` + +### CPU options example + +```typescript +// Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +import { Construct } from "constructs"; +import { Token, TerraformStack } from "cdktf"; +/* + * Provider bindings are generated by running `cdktf get`. + * See https://cdk.tf/provider-generation for more details. + */ +import { DataAwsAmi } from "./.gen/providers/aws/data-aws-ami"; +import { Instance } from "./.gen/providers/aws/instance"; +import { Subnet } from "./.gen/providers/aws/subnet"; +import { Vpc } from "./.gen/providers/aws/vpc"; +class MyConvertedCode extends TerraformStack { + constructor(scope: Construct, name: string) { + super(scope, name); + const example = new Vpc(this, "example", { + cidrBlock: "172.16.0.0/16", + tags: { + Name: "tf-example", + }, + }); + const amznLinux2023Ami = new DataAwsAmi(this, "amzn-linux-2023-ami", { + filter: [ + { + name: "name", + values: ["al2023-ami-2023.*-x86_64"], + }, + ], + mostRecent: true, + owners: ["amazon"], + }); + const awsSubnetExample = new Subnet(this, "example_2", { + availabilityZone: "us-east-2a", + cidrBlock: "172.16.10.0/24", + tags: { + Name: "tf-example", + }, + vpcId: example.id, + }); + /*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/ + awsSubnetExample.overrideLogicalId("example"); + const awsInstanceExample = new Instance(this, "example_3", { + ami: Token.asString(amznLinux2023Ami.id), + cpuOptions: { + coreCount: 2, + threadsPerCore: 2, + }, + instanceType: "c6a.2xlarge", + subnetId: Token.asString(awsSubnetExample.id), + tags: { + Name: "tf-example", + }, + }); + /*This allows the Terraform resource name to match the original name. You can remove the call if you don't need them to match.*/ + awsInstanceExample.overrideLogicalId("example"); + } +} + +``` + +### Host resource group or Licence Manager registered AMI example + +A host resource group is a collection of Dedicated Hosts that you can manage as a single entity. As you launch instances, License Manager allocates the hosts and launches instances on them based on the settings that you configured. You can add existing Dedicated Hosts to a host resource group and take advantage of automated host management through License Manager. + +-> **NOTE:** A dedicated host is automatically associated with a License Manager host resource group if **Allocate hosts automatically** is enabled. Otherwise, use the `hostResourceGroupArn` argument to explicitly associate the instance with the host resource group. + +```typescript +// Code generated by 'cdktf convert' - Please report bugs at https://cdk.tf/bug +import { Construct } from "constructs"; +import { TerraformStack } from "cdktf"; +/* + * Provider bindings are generated by running `cdktf get`. + * See https://cdk.tf/provider-generation for more details. + */ +import { Instance } from "./.gen/providers/aws/instance"; +class MyConvertedCode extends TerraformStack { + constructor(scope: Construct, name: string) { + super(scope, name); + new Instance(this, "this", { + ami: "ami-0dcc1e21636832c5d", + hostResourceGroupArn: + "arn:aws:resource-groups:us-west-2:012345678901:group/win-testhost", + instanceType: "m5.large", + tenancy: "host", + }); + } +} + +``` + +## Argument Reference + +The following arguments are supported: + +* `ami` - (Optional) AMI to use for the instance. Required unless `launchTemplate` is specified and the Launch Template specifes an AMI. If an AMI is specified in the Launch Template, setting `ami` will override the AMI specified in the Launch Template. +* `associatePublicIpAddress` - (Optional) Whether to associate a public IP address with an instance in a VPC. +* `availabilityZone` - (Optional) AZ to start the instance in. + +* `capacityReservationSpecification` - (Optional) Describes an instance's Capacity Reservation targeting option. See [Capacity Reservation Specification](#capacity-reservation-specification) below for more details. + +-> **NOTE:** Changing `cpuCoreCount` and/or `cpuThreadsPerCore` will cause the resource to be destroyed and re-created. + +* `cpuCoreCount` - (Optional, **Deprecated** use the `cpuOptions` argument instead) Sets the number of CPU cores for an instance. This option is only supported on creation of instance type that support CPU Options [CPU Cores and Threads Per CPU Core Per Instance Type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#cpu-options-supported-instances-values) - specifying this option for unsupported instance types will return an error from the EC2 API. +* `cpuOptions` - (Optional) The CPU options for the instance. See [CPU Options](#cpu-options) below for more details. +* `cpuThreadsPerCore` - (Optional - has no effect unless `cpuCoreCount` is also set, **Deprecated** use the `cpuOptions` argument instead) If set to 1, hyperthreading is disabled on the launched instance. Defaults to 2 if not set. See [Optimizing CPU Options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) for more information. +* `creditSpecification` - (Optional) Configuration block for customizing the credit specification of the instance. See [Credit Specification](#credit-specification) below for more details. Terraform will only perform drift detection of its value when present in a configuration. Removing this configuration on existing instances will only stop managing it. It will not change the configuration back to the default for the instance type. +* `disableApiStop` - (Optional) If true, enables [EC2 Instance Stop Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html#Using_StopProtection). +* `disableApiTermination` - (Optional) If true, enables [EC2 Instance Termination Protection](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingDisableAPITermination). +* `ebsBlockDevice` - (Optional) One or more configuration blocks with additional EBS block devices to attach to the instance. Block device configurations only apply on resource creation. See [Block Devices](#ebs-ephemeral-and-root-block-devices) below for details on attributes and drift detection. When accessing this as an attribute reference, it is a set of objects. +* `ebsOptimized` - (Optional) If true, the launched EC2 instance will be EBS-optimized. Note that if this is not set on an instance type that is optimized by default then this will show as disabled but if the instance type is optimized by default then there is no need to set this and there is no effect to disabling it. See the [EBS Optimized section](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSOptimized.html) of the AWS User Guide for more information. +* `enclaveOptions` - (Optional) Enable Nitro Enclaves on launched instances. See [Enclave Options](#enclave-options) below for more details. +* `ephemeralBlockDevice` - (Optional) One or more configuration blocks to customize Ephemeral (also known as "Instance Store") volumes on the instance. See [Block Devices](#ebs-ephemeral-and-root-block-devices) below for details. When accessing this as an attribute reference, it is a set of objects. +* `getPasswordData` - (Optional) If true, wait for password data to become available and retrieve it. Useful for getting the administrator password for instances running Microsoft Windows. The password data is exported to the `passwordData` attribute. See [GetPasswordData](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_GetPasswordData.html) for more information. +* `hibernation` - (Optional) If true, the launched EC2 instance will support hibernation. +* `hostId` - (Optional) ID of a dedicated host that the instance will be assigned to. Use when an instance is to be launched on a specific dedicated host. +* `hostResourceGroupArn` - (Optional) ARN of the host resource group in which to launch the instances. If you specify an ARN, omit the `tenancy` parameter or set it to `host`. +* `iamInstanceProfile` - (Optional) IAM Instance Profile to launch the instance with. Specified as the name of the Instance Profile. Ensure your credentials have the correct permission to assign the instance profile according to the [EC2 documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html#roles-usingrole-ec2instance-permissions), notably `iam:passRole`. +* `instanceInitiatedShutdownBehavior` - (Optional) Shutdown behavior for the instance. Amazon defaults this to `stop` for EBS-backed instances and `terminate` for instance-store instances. Cannot be set on instance-store instances. See [Shutdown Behavior](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html#Using_ChangingInstanceInitiatedShutdownBehavior) for more information. +* `instanceMarketOptions` - (Optional) Describes the market (purchasing) option for the instances. See [Market Options](#market-options) below for details on attributes. +* `instanceType` - (Optional) Instance type to use for the instance. Required unless `launchTemplate` is specified and the Launch Template specifies an instance type. If an instance type is specified in the Launch Template, setting `instanceType` will override the instance type specified in the Launch Template. Updates to this field will trigger a stop/start of the EC2 instance. +* `ipv6AddressCount`- (Optional) Number of IPv6 addresses to associate with the primary network interface. Amazon EC2 chooses the IPv6 addresses from the range of your subnet. +* `ipv6Addresses` - (Optional) Specify one or more IPv6 addresses from the range of the subnet to associate with the primary network interface +* `keyName` - (Optional) Key name of the Key Pair to use for the instance; which can be managed using [the `awsKeyPair` resource](key_pair.html). +* `launchTemplate` - (Optional) Specifies a Launch Template to configure the instance. Parameters configured on this resource will override the corresponding parameters in the Launch Template. See [Launch Template Specification](#launch-template-specification) below for more details. +* `maintenanceOptions` - (Optional) Maintenance and recovery options for the instance. See [Maintenance Options](#maintenance-options) below for more details. +* `metadataOptions` - (Optional) Customize the metadata options of the instance. See [Metadata Options](#metadata-options) below for more details. +* `monitoring` - (Optional) If true, the launched EC2 instance will have detailed monitoring enabled. (Available since v0.6.0) +* `networkInterface` - (Optional) Customize network interfaces to be attached at instance boot time. See [Network Interfaces](#network-interfaces) below for more details. +* `placementGroup` - (Optional) Placement Group to start the instance in. +* `placementPartitionNumber` - (Optional) Number of the partition the instance is in. Valid only if [the `awsPlacementGroup` resource's](placement_group.html) `strategy` argument is set to `"partition"`. +* `privateDnsNameOptions` - (Optional) Options for the instance hostname. The default values are inherited from the subnet. See [Private DNS Name Options](#private-dns-name-options) below for more details. +* `privateIp` - (Optional) Private IP address to associate with the instance in a VPC. +* `rootBlockDevice` - (Optional) Configuration block to customize details about the root block device of the instance. See [Block Devices](#ebs-ephemeral-and-root-block-devices) below for details. When accessing this as an attribute reference, it is a list containing one object. +* `secondaryPrivateIps` - (Optional) List of secondary private IPv4 addresses to assign to the instance's primary network interface (eth0) in a VPC. Can only be assigned to the primary network interface (eth0) attached at instance creation, not a pre-existing network interface i.e., referenced in a `networkInterface` block. Refer to the [Elastic network interfaces documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html#AvailableIpPerENI) to see the maximum number of private IP addresses allowed per instance type. +* `securityGroups` - (Optional, EC2-Classic and default VPC only) List of security group names to associate with. + +-> **NOTE:** If you are creating Instances in a VPC, use `vpcSecurityGroupIds` instead. + +* `sourceDestCheck` - (Optional) Controls if traffic is routed to the instance when the destination address does not match the instance. Used for NAT or VPNs. Defaults true. +* `subnetId` - (Optional) VPC Subnet ID to launch in. +* `tags` - (Optional) Map of tags to assign to the resource. Note that these tags apply to the instance and not block storage devices. If configured with a provider [`defaultTags` configuration block](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#default_tags-configuration-block) present, tags with matching keys will overwrite those defined at the provider-level. +* `tenancy` - (Optional) Tenancy of the instance (if the instance is running in a VPC). An instance with a tenancy of `dedicated` runs on single-tenant hardware. The `host` tenancy is not supported for the import-instance command. Valid values are `default`, `dedicated`, and `host`. +* `userData` - (Optional) User data to provide when launching the instance. Do not pass gzip-compressed data via this argument; see `userDataBase64` instead. Updates to this field will trigger a stop/start of the EC2 instance by default. If the `userDataReplaceOnChange` is set then updates to this field will trigger a destroy and recreate. +* `userDataBase64` - (Optional) Can be used instead of `userData` to pass base64-encoded binary data directly. Use this instead of `userData` whenever the value is not a valid UTF-8 string. For example, gzip-encoded user data must be base64-encoded and passed via this argument to avoid corruption. Updates to this field will trigger a stop/start of the EC2 instance by default. If the `userDataReplaceOnChange` is set then updates to this field will trigger a destroy and recreate. +* `userDataReplaceOnChange` - (Optional) When used in combination with `userData` or `userDataBase64` will trigger a destroy and recreate when set to `true`. Defaults to `false` if not set. +* `volumeTags` - (Optional) Map of tags to assign, at instance-creation time, to root and EBS volumes. + +~> **NOTE:** Do not use `volumeTags` if you plan to manage block device tags outside the `awsInstance` configuration, such as using `tags` in an [`awsEbsVolume`](/docs/providers/aws/r/ebs_volume.html) resource attached via [`awsVolumeAttachment`](/docs/providers/aws/r/volume_attachment.html). Doing so will result in resource cycling and inconsistent behavior. + +* `vpcSecurityGroupIds` - (Optional, VPC only) List of security group IDs to associate with. + +### Capacity Reservation Specification + +~> **NOTE:** You can specify only one argument at a time. If you specify both `capacityReservationPreference` and `capacityReservationTarget`, the request fails. Modifying `capacityReservationPreference` or `capacityReservationTarget` in this block requires the instance to be in `stopped` state. + +Capacity reservation specification can be applied/modified to the EC2 Instance at creation time or when the instance is `stopped`. + +The `capacityReservationSpecification` block supports the following: + +* `capacityReservationPreference` - (Optional) Indicates the instance's Capacity Reservation preferences. Can be `"open"` or `"none"`. (Default: `"open"`). +* `capacityReservationTarget` - (Optional) Information about the target Capacity Reservation. See [Capacity Reservation Target](#capacity-reservation-target) below for more details. + +For more information, see the documentation on [Capacity Reservations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/capacity-reservations-using.html). + +### Capacity Reservation Target + +~> **NOTE:** Modifying `capacityReservationId` in this block requires the instance to be in `stopped` state. + +Describes a target Capacity Reservation. + +This `capacityReservationTarget` block supports the following: + +* `capacityReservationId` - (Optional) ID of the Capacity Reservation in which to run the instance. +* `capacityReservationResourceGroupArn` - (Optional) ARN of the Capacity Reservation resource group in which to run the instance. + +### CPU Options + +-> **NOTE:** Changing any of `amdSevSnp`, `coreCount`, `threadsPerCore` will cause the resource to be destroyed and re-created. + +CPU options apply to the instance at launch time. + +The `cpuOptions` block supports the following: + +* `amdSevSnp` - (Optional) Indicates whether to enable the instance for AMD SEV-SNP. AMD SEV-SNP is supported with M6a, R6a, and C6a instance types only. Valid values are `enabled` and `disabled`. +* `coreCount` - (Optional) Sets the number of CPU cores for an instance. This option is only supported on creation of instance type that support CPU Options [CPU Cores and Threads Per CPU Core Per Instance Type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html#cpu-options-supported-instances-values) - specifying this option for unsupported instance types will return an error from the EC2 API. +* `threadsPerCore` - (Optional - has no effect unless `coreCount` is also set) If set to 1, hyperthreading is disabled on the launched instance. Defaults to 2 if not set. See [Optimizing CPU Options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html) for more information. + +For more information, see the documentation on [Optimizing CPU options](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-optimize-cpu.html). + +### Credit Specification + +The `creditSpecification` block supports the following: + +* `cpuCredits` - (Optional) Credit option for CPU usage. Valid values include `standard` or `unlimited`. T3 instances are launched as unlimited by default. T2 instances are launched as standard by default. + +### EBS, Ephemeral, and Root Block Devices + +Each of the `*BlockDevice` attributes control a portion of the EC2 Instance's "Block Device Mapping". For more information, see the [AWS Block Device Mapping documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html). + +The `rootBlockDevice` block supports the following: + +* `deleteOnTermination` - (Optional) Whether the volume should be destroyed on instance termination. Defaults to `true`. +* `encrypted` - (Optional) Whether to enable volume encryption. Defaults to `false`. Must be configured to perform drift detection. +* `iops` - (Optional) Amount of provisioned [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html). Only valid for volume_type of `io1`, `io2` or `gp3`. +* `kmsKeyId` - (Optional) Amazon Resource Name (ARN) of the KMS Key to use when encrypting the volume. Must be configured to perform drift detection. +* `tags` - (Optional) Map of tags to assign to the device. +* `throughput` - (Optional) Throughput to provision for a volume in mebibytes per second (MiB/s). This is only valid for `volumeType` of `gp3`. +* `volumeSize` - (Optional) Size of the volume in gibibytes (GiB). +* `volumeType` - (Optional) Type of volume. Valid values include `standard`, `gp2`, `gp3`, `io1`, `io2`, `sc1`, or `st1`. Defaults to `gp2`. + +Modifying the `encrypted` or `kmsKeyId` settings of the `rootBlockDevice` requires resource replacement. + +Each `ebsBlockDevice` block supports the following: + +* `deleteOnTermination` - (Optional) Whether the volume should be destroyed on instance termination. Defaults to `true`. +* `deviceName` - (Required) Name of the device to mount. +* `encrypted` - (Optional) Enables [EBS encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html) on the volume. Defaults to `false`. Cannot be used with `snapshotId`. Must be configured to perform drift detection. +* `iops` - (Optional) Amount of provisioned [IOPS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-io-characteristics.html). Only valid for volume_type of `io1`, `io2` or `gp3`. +* `kmsKeyId` - (Optional) Amazon Resource Name (ARN) of the KMS Key to use when encrypting the volume. Must be configured to perform drift detection. +* `snapshotId` - (Optional) Snapshot ID to mount. +* `tags` - (Optional) Map of tags to assign to the device. +* `throughput` - (Optional) Throughput to provision for a volume in mebibytes per second (MiB/s). This is only valid for `volumeType` of `gp3`. +* `volumeSize` - (Optional) Size of the volume in gibibytes (GiB). +* `volumeType` - (Optional) Type of volume. Valid values include `standard`, `gp2`, `gp3`, `io1`, `io2`, `sc1`, or `st1`. Defaults to `gp2`. + +~> **NOTE:** Currently, changes to the `ebsBlockDevice` configuration of _existing_ resources cannot be automatically detected by Terraform. To manage changes and attachments of an EBS block to an instance, use the `awsEbsVolume` and `awsVolumeAttachment` resources instead. If you use `ebsBlockDevice` on an `awsInstance`, Terraform will assume management over the full set of non-root EBS block devices for the instance, treating additional block devices as drift. For this reason, `ebsBlockDevice` cannot be mixed with external `awsEbsVolume` and `awsVolumeAttachment` resources for a given instance. + +Each `ephemeralBlockDevice` block supports the following: + +* `deviceName` - Name of the block device to mount on the instance. +* `noDevice` - (Optional) Suppresses the specified device included in the AMI's block device mapping. +* `virtualName` - (Optional) [Instance Store Device Name](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#InstanceStoreDeviceNames) (e.g., `ephemeral0`). + +Each AWS Instance type has a different set of Instance Store block devices available for attachment. AWS [publishes a list](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/InstanceStorage.html#StorageOnInstanceTypes) of which ephemeral devices are available on each type. The devices are always identified by the `virtualName` in the format `ephemeral{0N}`. + +### Enclave Options + +-> **NOTE:** Changing `enabled` will cause the resource to be destroyed and re-created. + +Enclave options apply to the instance at boot time. + +The `enclaveOptions` block supports the following: + +* `enabled` - (Optional) Whether Nitro Enclaves will be enabled on the instance. Defaults to `false`. + +For more information, see the documentation on [Nitro Enclaves](https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html). + +### Maintenance Options + +The `maintenanceOptions` block supports the following: + +* `autoRecovery` - (Optional) Automatic recovery behavior of the Instance. Can be `"default"` or `"disabled"`. See [Recover your instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-recover.html) for more details. + +### Market Options + +The `instanceMarketOptions` block supports the following: + +* `marketType` - (Optional) Type of market for the instance. Valid value is `spot`. Defaults to `spot`. +* `spotOptions` - (Optional) Block to configure the options for Spot Instances. See [Spot Options](#spot-options) below for details on attributes. + +### Metadata Options + +Metadata options can be applied/modified to the EC2 Instance at any time. + +The `metadataOptions` block supports the following: + +* `httpEndpoint` - (Optional) Whether the metadata service is available. Valid values include `enabled` or `disabled`. Defaults to `enabled`. +* `httpPutResponseHopLimit` - (Optional) Desired HTTP PUT response hop limit for instance metadata requests. The larger the number, the further instance metadata requests can travel. Valid values are integer from `1` to `64`. Defaults to `1`. +* `httpTokens` - (Optional) Whether or not the metadata service requires session tokens, also referred to as _Instance Metadata Service Version 2 (IMDSv2)_. Valid values include `optional` or `required`. Defaults to `optional`. +* `instanceMetadataTags` - (Optional) Enables or disables access to instance tags from the instance metadata service. Valid values include `enabled` or `disabled`. Defaults to `disabled`. + +For more information, see the documentation on the [Instance Metadata Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html). + +### Network Interfaces + +Each of the `networkInterface` blocks attach a network interface to an EC2 Instance during boot time. However, because the network interface is attached at boot-time, replacing/modifying the network interface **WILL** trigger a recreation of the EC2 Instance. If you should need at any point to detach/modify/re-attach a network interface to the instance, use the `awsNetworkInterface` or `awsNetworkInterfaceAttachment` resources instead. + +The `networkInterface` configuration block _does_, however, allow users to supply their own network interface to be used as the default network interface on an EC2 Instance, attached at `eth0`. + +Each `networkInterface` block supports the following: + +* `deleteOnTermination` - (Optional) Whether or not to delete the network interface on instance termination. Defaults to `false`. Currently, the only valid value is `false`, as this is only supported when creating new network interfaces when launching an instance. +* `deviceIndex` - (Required) Integer index of the network interface attachment. Limited by instance type. +* `networkCardIndex` - (Optional) Integer index of the network card. Limited by instance type. The default index is `0`. +* `networkInterfaceId` - (Required) ID of the network interface to attach. + +### Private DNS Name Options + +The `privateDnsNameOptions` block supports the following: + +* `enableResourceNameDnsAaaaRecord` - Indicates whether to respond to DNS queries for instance hostnames with DNS AAAA records. +* `enableResourceNameDnsARecord` - Indicates whether to respond to DNS queries for instance hostnames with DNS A records. +* `hostnameType` - Type of hostname for Amazon EC2 instances. For IPv4 only subnets, an instance DNS name must be based on the instance IPv4 address. For IPv6 native subnets, an instance DNS name must be based on the instance ID. For dual-stack subnets, you can specify whether DNS names use the instance IPv4 address or the instance ID. Valid values: `ipName` and `resourceName`. + +### Spot Options + +The `spotOptions` block supports the following: + +* `instanceInterruptionBehavior` - (Optional) The behavior when a Spot Instance is interrupted. Valid values include `hibernate`, `stop`, `terminate` . The default is `terminate`. +* `maxPrice` - (Optional) The maximum hourly price that you're willing to pay for a Spot Instance. +* `spotInstanceType` - (Optional) The Spot Instance request type. Valid values include `oneTime`, `persistent`. Persistent Spot Instance requests are only supported when the instance interruption behavior is either hibernate or stop. The default is `oneTime`. +* `validUntil` - (Optional) The end date of the request, in UTC format (YYYY-MM-DDTHH:MM:SSZ). Supported only for persistent requests. + +### Launch Template Specification + +-> **Note:** Launch Template parameters will be used only once during instance creation. If you want to update existing instance you need to change parameters +directly. Updating Launch Template specification will force a new instance. + +Any other instance parameters that you specify will override the same parameters in the launch template. + +The `launchTemplate` block supports the following: + +* `id` - ID of the launch template. Conflicts with `name`. +* `name` - Name of the launch template. Conflicts with `id`. +* `version` - Template version. Can be a specific version number, `$latest` or `$default`. The default value is `$default`. + +## Attributes Reference + +In addition to all arguments above, the following attributes are exported: + +* `arn` - ARN of the instance. +* `capacityReservationSpecification` - Capacity reservation specification of the instance. +* `instanceState` - State of the instance. One of: `pending`, `running`, `shuttingDown`, `terminated`, `stopping`, `stopped`. See [Instance Lifecycle](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-lifecycle.html) for more information. +* `outpostArn` - ARN of the Outpost the instance is assigned to. +* `passwordData` - Base-64 encoded encrypted password data for the instance. Useful for getting the administrator password for instances running Microsoft Windows. This attribute is only exported if `getPasswordData` is true. Note that this encrypted value will be stored in the state file, as with all exported attributes. See [GetPasswordData](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_GetPasswordData.html) for more information. +* `primaryNetworkInterfaceId` - ID of the instance's primary network interface. +* `privateDns` - Private DNS name assigned to the instance. Can only be used inside the Amazon EC2, and only available if you've enabled DNS hostnames for your VPC. +* `publicDns` - Public DNS name assigned to the instance. For EC2-VPC, this is only available if you've enabled DNS hostnames for your VPC. +* `publicIp` - Public IP address assigned to the instance, if applicable. **NOTE**: If you are using an [`awsEip`](/docs/providers/aws/r/eip.html) with your instance, you should refer to the EIP's address directly and not use `publicIp` as this field will change after the EIP is attached. +* `tagsAll` - Map of tags assigned to the resource, including those inherited from the provider [`defaultTags` configuration block](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#default_tags-configuration-block). + +For `ebsBlockDevice`, in addition to the arguments above, the following attribute is exported: + +* `volumeId` - ID of the volume. For example, the ID can be accessed like this, `awsInstanceWebEbsBlockDevice2VolumeId`. + +For `rootBlockDevice`, in addition to the arguments above, the following attributes are exported: + +* `volumeId` - ID of the volume. For example, the ID can be accessed like this, `awsInstanceWebRootBlockDevice0VolumeId`. +* `deviceName` - Device name, e.g., `/dev/sdh` or `xvdh`. + +For `instanceMarketOptions`, in addition to the arguments above, the following attributes are exported: + +* `instanceLifecycle` - Indicates whether this is a Spot Instance or a Scheduled Instance. +* `spotInstanceRequestId` - If the request is a Spot Instance request, the ID of the request. + +## Timeouts + +[Configuration options](https://developer.hashicorp.com/terraform/language/resources/syntax#operation-timeouts): + +* `create` - (Default `10M`) +* `update` - (Default `10M`) +* `delete` - (Default `20M`) + +## Import + +Instances can be imported using the `id`, e.g., + +``` +$ terraform import aws_instance.web i-12345678 +``` + + \ No newline at end of file