instances

Creates, updates, deletes or gets an instance resource or lists instances in a region

Overview

Name	instances
Type	Resource
Description	Resource Type definition for AWS::EC2::Instance
Id	aws.ec2.instances

Fields

Name	Datatype	Description
tenancy	string	The tenancy of the instance (if the instance is running in a VPC). An instance with a tenancy of dedicated runs on single-tenant hardware.
security_groups	array	the names of the security groups. For a nondefault VPC, you must use security group IDs instead.
private_dns_name	string	The private DNS name of the specified instance. For example: ip-10-24-34-0.ec2.internal.
private_ip_address	string	[EC2-VPC] The primary IPv4 address. You must specify a value from the IPv4 address range of the subnet.
user_data	string	The user data to make available to the instance.
block_device_mappings	array	The block device mapping entries that defines the block devices to attach to the instance at launch.
iam_instance_profile	string	The IAM instance profile.
ipv6_addresses	array	[EC2-VPC] The IPv6 addresses from the range of the subnet to associate with the primary network interface.
kernel_id	string	The ID of the kernel.
subnet_id	string	[EC2-VPC] The ID of the subnet to launch the instance into.
ebs_optimized	boolean	Indicates whether the instance is optimized for Amazon EBS I/O.
propagate_tags_to_volume_on_creation	boolean	Indicates whether to assign the tags from the instance to all of the volumes attached to the instance at launch. If you specify true and you assign tags to the instance, those tags are automatically assigned to all of the volumes that you attach to the instance at launch. If you specify false, those tags are not assigned to the attached volumes.
elastic_gpu_specifications	array	An elastic GPU to associate with the instance.
elastic_inference_accelerators	array	An elastic inference accelerator to associate with the instance.
volumes	array	The volumes to attach to the instance.
private_ip	string	The private IP address of the specified instance. For example: 10.24.34.0.
ipv6_address_count	integer	[EC2-VPC] The number of IPv6 addresses to associate with the primary network interface. Amazon EC2 chooses the IPv6 addresses from the range of your subnet.
launch_template	object	The launch template to use to launch the instances.
enclave_options	object	Indicates whether the instance is enabled for AWS Nitro Enclaves.
network_interfaces	array	The network interfaces to associate with the instance.
image_id	string	The ID of the AMI. An AMI ID is required to launch an instance and must be specified here or in a launch template.
instance_type	string	The instance type.
monitoring	boolean	Specifies whether detailed monitoring is enabled for the instance.
tags	array	The tags to add to the instance.
additional_info	string	This property is reserved for internal use. If you use it, the stack fails with this error: Bad property set: [Testing this property] (Service: AmazonEC2; Status Code: 400; Error Code: InvalidParameterCombination; Request ID: 0XXXXXX-49c7-4b40-8bcc-76885dcXXXXX).
hibernation_options	object	Indicates whether an instance is enabled for hibernation.
license_specifications	array	The license configurations.
instance_id	string	The EC2 Instance ID.
public_ip	string	The public IP address of the specified instance. For example: 192.0.2.0.
instance_initiated_shutdown_behavior	string	Indicates whether an instance stops or terminates when you initiate shutdown from the instance (using the operating system command for system shutdown).
cpu_options	object	The CPU options for the instance.
availability_zone	string	The Availability Zone of the instance.
private_dns_name_options	object	The options for the instance hostname.
host_id	string	If you specify host for the Affinity property, the ID of a dedicated host that the instance is associated with. If you don't specify an ID, Amazon EC2 launches the instance onto any available, compatible dedicated host in your account.
host_resource_group_arn	string	The ARN of the host resource group in which to launch the instances. If you specify a host resource group ARN, omit the Tenancy parameter or set it to host.
public_dns_name	string	The public DNS name of the specified instance. For example: ec2-107-20-50-45.compute-1.amazonaws.com.
security_group_ids	array	The IDs of the security groups.
disable_api_termination	boolean	If you set this parameter to true, you can't terminate the instance using the Amazon EC2 console, CLI, or API; otherwise, you can.
key_name	string	The name of the key pair.
ramdisk_id	string	The ID of the RAM disk to select.
source_dest_check	boolean	Specifies whether to enable an instance launched in a VPC to perform NAT.
placement_group_name	string	The name of an existing placement group that you want to launch the instance into (cluster | partition | spread).
ssm_associations	array	The SSM document and parameter values in AWS Systems Manager to associate with this instance.
vpc_id	string	The ID of the VPC that the instance is running in.
state	object	The current state of the instance.
affinity	string	Indicates whether the instance is associated with a dedicated host. If you want the instance to always restart on the same host on which it was launched, specify host. If you want the instance to restart on any available host, but try to launch onto the last host it ran on (on a best-effort basis), specify default.
credit_specification	object	The credit option for CPU usage of the burstable performance instance. Valid values are standard and unlimited.
region	string	AWS region.

Methods

Name	Accessible by	Required Params
create_resource	INSERT	region
delete_resource	DELETE	data__Identifier, region
update_resource	UPDATE	data__Identifier, data__PatchDocument, region
list_resources	SELECT	region
get_resource	SELECT	data__Identifier, region

SELECT examples

Gets all instances in a region.

SELECT
region,
tenancy,
security_groups,
private_dns_name,
private_ip_address,
user_data,
block_device_mappings,
iam_instance_profile,
ipv6_addresses,
kernel_id,
subnet_id,
ebs_optimized,
propagate_tags_to_volume_on_creation,
elastic_gpu_specifications,
elastic_inference_accelerators,
volumes,
private_ip,
ipv6_address_count,
launch_template,
enclave_options,
network_interfaces,
image_id,
instance_type,
monitoring,
tags,
additional_info,
hibernation_options,
license_specifications,
instance_id,
public_ip,
instance_initiated_shutdown_behavior,
cpu_options,
availability_zone,
private_dns_name_options,
host_id,
host_resource_group_arn,
public_dns_name,
security_group_ids,
disable_api_termination,
key_name,
ramdisk_id,
source_dest_check,
placement_group_name,
ssm_associations,
vpc_id,
state,
affinity,
credit_specification
FROM aws.ec2.instances
WHERE region = 'us-east-1';

Gets all properties from an individual instance.

SELECT
region,
tenancy,
security_groups,
private_dns_name,
private_ip_address,
user_data,
block_device_mappings,
iam_instance_profile,
ipv6_addresses,
kernel_id,
subnet_id,
ebs_optimized,
propagate_tags_to_volume_on_creation,
elastic_gpu_specifications,
elastic_inference_accelerators,
volumes,
private_ip,
ipv6_address_count,
launch_template,
enclave_options,
network_interfaces,
image_id,
instance_type,
monitoring,
tags,
additional_info,
hibernation_options,
license_specifications,
instance_id,
public_ip,
instance_initiated_shutdown_behavior,
cpu_options,
availability_zone,
private_dns_name_options,
host_id,
host_resource_group_arn,
public_dns_name,
security_group_ids,
disable_api_termination,
key_name,
ramdisk_id,
source_dest_check,
placement_group_name,
ssm_associations,
vpc_id,
state,
affinity,
credit_specification
FROM aws.ec2.instances
WHERE region = 'us-east-1' AND data__Identifier = '<InstanceId>';

INSERT example

Use the following StackQL query and manifest file to create a new instance resource, using stack-deploy.

Required Properties

/*+ create */
INSERT INTO aws.ec2.instances (
 Tenancy,
 SecurityGroups,
 PrivateIpAddress,
 UserData,
 BlockDeviceMappings,
 IamInstanceProfile,
 Ipv6Addresses,
 KernelId,
 SubnetId,
 EbsOptimized,
 PropagateTagsToVolumeOnCreation,
 ElasticGpuSpecifications,
 ElasticInferenceAccelerators,
 Volumes,
 Ipv6AddressCount,
 LaunchTemplate,
 EnclaveOptions,
 NetworkInterfaces,
 ImageId,
 InstanceType,
 Monitoring,
 Tags,
 AdditionalInfo,
 HibernationOptions,
 LicenseSpecifications,
 InstanceInitiatedShutdownBehavior,
 CpuOptions,
 AvailabilityZone,
 PrivateDnsNameOptions,
 HostId,
 HostResourceGroupArn,
 SecurityGroupIds,
 DisableApiTermination,
 KeyName,
 RamdiskId,
 SourceDestCheck,
 PlacementGroupName,
 SsmAssociations,
 Affinity,
 CreditSpecification,
 region
)
SELECT 
'{{ Tenancy }}',
 '{{ SecurityGroups }}',
 '{{ PrivateIpAddress }}',
 '{{ UserData }}',
 '{{ BlockDeviceMappings }}',
 '{{ IamInstanceProfile }}',
 '{{ Ipv6Addresses }}',
 '{{ KernelId }}',
 '{{ SubnetId }}',
 '{{ EbsOptimized }}',
 '{{ PropagateTagsToVolumeOnCreation }}',
 '{{ ElasticGpuSpecifications }}',
 '{{ ElasticInferenceAccelerators }}',
 '{{ Volumes }}',
 '{{ Ipv6AddressCount }}',
 '{{ LaunchTemplate }}',
 '{{ EnclaveOptions }}',
 '{{ NetworkInterfaces }}',
 '{{ ImageId }}',
 '{{ InstanceType }}',
 '{{ Monitoring }}',
 '{{ Tags }}',
 '{{ AdditionalInfo }}',
 '{{ HibernationOptions }}',
 '{{ LicenseSpecifications }}',
 '{{ InstanceInitiatedShutdownBehavior }}',
 '{{ CpuOptions }}',
 '{{ AvailabilityZone }}',
 '{{ PrivateDnsNameOptions }}',
 '{{ HostId }}',
 '{{ HostResourceGroupArn }}',
 '{{ SecurityGroupIds }}',
 '{{ DisableApiTermination }}',
 '{{ KeyName }}',
 '{{ RamdiskId }}',
 '{{ SourceDestCheck }}',
 '{{ PlacementGroupName }}',
 '{{ SsmAssociations }}',
 '{{ Affinity }}',
 '{{ CreditSpecification }}',
'{{ region }}';

All Properties

/*+ create */
INSERT INTO aws.ec2.instances (
 Tenancy,
 SecurityGroups,
 PrivateIpAddress,
 UserData,
 BlockDeviceMappings,
 IamInstanceProfile,
 Ipv6Addresses,
 KernelId,
 SubnetId,
 EbsOptimized,
 PropagateTagsToVolumeOnCreation,
 ElasticGpuSpecifications,
 ElasticInferenceAccelerators,
 Volumes,
 Ipv6AddressCount,
 LaunchTemplate,
 EnclaveOptions,
 NetworkInterfaces,
 ImageId,
 InstanceType,
 Monitoring,
 Tags,
 AdditionalInfo,
 HibernationOptions,
 LicenseSpecifications,
 InstanceInitiatedShutdownBehavior,
 CpuOptions,
 AvailabilityZone,
 PrivateDnsNameOptions,
 HostId,
 HostResourceGroupArn,
 SecurityGroupIds,
 DisableApiTermination,
 KeyName,
 RamdiskId,
 SourceDestCheck,
 PlacementGroupName,
 SsmAssociations,
 Affinity,
 CreditSpecification,
 region
)
SELECT 
 '{{ Tenancy }}',
 '{{ SecurityGroups }}',
 '{{ PrivateIpAddress }}',
 '{{ UserData }}',
 '{{ BlockDeviceMappings }}',
 '{{ IamInstanceProfile }}',
 '{{ Ipv6Addresses }}',
 '{{ KernelId }}',
 '{{ SubnetId }}',
 '{{ EbsOptimized }}',
 '{{ PropagateTagsToVolumeOnCreation }}',
 '{{ ElasticGpuSpecifications }}',
 '{{ ElasticInferenceAccelerators }}',
 '{{ Volumes }}',
 '{{ Ipv6AddressCount }}',
 '{{ LaunchTemplate }}',
 '{{ EnclaveOptions }}',
 '{{ NetworkInterfaces }}',
 '{{ ImageId }}',
 '{{ InstanceType }}',
 '{{ Monitoring }}',
 '{{ Tags }}',
 '{{ AdditionalInfo }}',
 '{{ HibernationOptions }}',
 '{{ LicenseSpecifications }}',
 '{{ InstanceInitiatedShutdownBehavior }}',
 '{{ CpuOptions }}',
 '{{ AvailabilityZone }}',
 '{{ PrivateDnsNameOptions }}',
 '{{ HostId }}',
 '{{ HostResourceGroupArn }}',
 '{{ SecurityGroupIds }}',
 '{{ DisableApiTermination }}',
 '{{ KeyName }}',
 '{{ RamdiskId }}',
 '{{ SourceDestCheck }}',
 '{{ PlacementGroupName }}',
 '{{ SsmAssociations }}',
 '{{ Affinity }}',
 '{{ CreditSpecification }}',
 '{{ region }}';

Manifest

version: 1
name: stack name
description: stack description
providers:
  - aws
globals:
  - name: region
    value: '{{ vars.AWS_REGION }}'
resources:
  - name: instance
    props:
      - name: Tenancy
        value: '{{ Tenancy }}'
      - name: SecurityGroups
        value:
          - '{{ SecurityGroups[0] }}'
      - name: PrivateIpAddress
        value: '{{ PrivateIpAddress }}'
      - name: UserData
        value: '{{ UserData }}'
      - name: BlockDeviceMappings
        value:
          - DeviceName: '{{ DeviceName }}'
            Ebs:
              DeleteOnTermination: '{{ DeleteOnTermination }}'
              Encrypted: '{{ Encrypted }}'
              Iops: '{{ Iops }}'
              SnapshotId: '{{ SnapshotId }}'
              VolumeSize: '{{ VolumeSize }}'
              VolumeType: '{{ VolumeType }}'
            NoDevice: '{{ NoDevice }}'
            VirtualName: '{{ VirtualName }}'
      - name: IamInstanceProfile
        value: '{{ IamInstanceProfile }}'
      - name: Ipv6Addresses
        value:
          - Ipv6Address: '{{ Ipv6Address }}'
      - name: KernelId
        value: '{{ KernelId }}'
      - name: SubnetId
        value: '{{ SubnetId }}'
      - name: EbsOptimized
        value: '{{ EbsOptimized }}'
      - name: PropagateTagsToVolumeOnCreation
        value: '{{ PropagateTagsToVolumeOnCreation }}'
      - name: ElasticGpuSpecifications
        value:
          - Type: '{{ Type }}'
      - name: ElasticInferenceAccelerators
        value:
          - Type: '{{ Type }}'
            Count: '{{ Count }}'
      - name: Volumes
        value:
          - MultiAttachEnabled: '{{ MultiAttachEnabled }}'
            KmsKeyId: '{{ KmsKeyId }}'
            Encrypted: '{{ Encrypted }}'
            Size: '{{ Size }}'
            AutoEnableIO: '{{ AutoEnableIO }}'
            OutpostArn: '{{ OutpostArn }}'
            AvailabilityZone: '{{ AvailabilityZone }}'
            Throughput: '{{ Throughput }}'
            Iops: '{{ Iops }}'
            SnapshotId: '{{ SnapshotId }}'
            VolumeType: '{{ VolumeType }}'
            Tags:
              - Key: '{{ Key }}'
                Value: '{{ Value }}'
      - name: Ipv6AddressCount
        value: '{{ Ipv6AddressCount }}'
      - name: LaunchTemplate
        value:
          LaunchTemplateName: '{{ LaunchTemplateName }}'
          Version: '{{ Version }}'
          LaunchTemplateId: '{{ LaunchTemplateId }}'
      - name: EnclaveOptions
        value:
          Enabled: '{{ Enabled }}'
      - name: NetworkInterfaces
        value:
          - Description: '{{ Description }}'
            PrivateIpAddress: '{{ PrivateIpAddress }}'
            PrivateIpAddresses:
              - Primary: '{{ Primary }}'
                PrivateIpAddress: '{{ PrivateIpAddress }}'
            SecondaryPrivateIpAddressCount: '{{ SecondaryPrivateIpAddressCount }}'
            Ipv4Prefixes:
              - Ipv4Prefix: '{{ Ipv4Prefix }}'
            Ipv4PrefixCount: '{{ Ipv4PrefixCount }}'
            GroupSet:
              - '{{ GroupSet[0] }}'
            Ipv6Addresses:
              - null
            Ipv6Prefixes:
              - Ipv6Prefix: '{{ Ipv6Prefix }}'
            Ipv6PrefixCount: '{{ Ipv6PrefixCount }}'
            SubnetId: '{{ SubnetId }}'
            SourceDestCheck: '{{ SourceDestCheck }}'
            InterfaceType: '{{ InterfaceType }}'
            Ipv6AddressCount: '{{ Ipv6AddressCount }}'
            EnablePrimaryIpv6: '{{ EnablePrimaryIpv6 }}'
            ConnectionTrackingSpecification:
              TcpEstablishedTimeout: '{{ TcpEstablishedTimeout }}'
              UdpStreamTimeout: '{{ UdpStreamTimeout }}'
              UdpTimeout: '{{ UdpTimeout }}'
            Tags:
              - null
      - name: ImageId
        value: '{{ ImageId }}'
      - name: InstanceType
        value: '{{ InstanceType }}'
      - name: Monitoring
        value: '{{ Monitoring }}'
      - name: Tags
        value:
          - null
      - name: AdditionalInfo
        value: '{{ AdditionalInfo }}'
      - name: HibernationOptions
        value:
          Configured: '{{ Configured }}'
      - name: LicenseSpecifications
        value:
          - LicenseConfigurationArn: '{{ LicenseConfigurationArn }}'
      - name: InstanceInitiatedShutdownBehavior
        value: '{{ InstanceInitiatedShutdownBehavior }}'
      - name: CpuOptions
        value:
          ThreadsPerCore: '{{ ThreadsPerCore }}'
          CoreCount: '{{ CoreCount }}'
      - name: AvailabilityZone
        value: '{{ AvailabilityZone }}'
      - name: PrivateDnsNameOptions
        value:
          EnableResourceNameDnsARecord: '{{ EnableResourceNameDnsARecord }}'
          HostnameType: '{{ HostnameType }}'
          EnableResourceNameDnsAAAARecord: '{{ EnableResourceNameDnsAAAARecord }}'
      - name: HostId
        value: '{{ HostId }}'
      - name: HostResourceGroupArn
        value: '{{ HostResourceGroupArn }}'
      - name: SecurityGroupIds
        value:
          - '{{ SecurityGroupIds[0] }}'
      - name: DisableApiTermination
        value: '{{ DisableApiTermination }}'
      - name: KeyName
        value: '{{ KeyName }}'
      - name: RamdiskId
        value: '{{ RamdiskId }}'
      - name: SourceDestCheck
        value: '{{ SourceDestCheck }}'
      - name: PlacementGroupName
        value: '{{ PlacementGroupName }}'
      - name: SsmAssociations
        value:
          - AssociationParameters:
              - Value:
                  - '{{ Value[0] }}'
                Key: '{{ Key }}'
            DocumentName: '{{ DocumentName }}'
      - name: Affinity
        value: '{{ Affinity }}'
      - name: CreditSpecification
        value:
          CPUCredits: '{{ CPUCredits }}'

DELETE example

/*+ delete */
DELETE FROM aws.ec2.instances
WHERE data__Identifier = '<InstanceId>'
AND region = 'us-east-1';

Permissions

To operate on the instances resource, the following permissions are required:

Read

ec2:DescribeElasticGpus,
ec2:DescribeNetworkInterfaces,
ec2:DescribeVolumes,
ec2:DescribeInstances,
ec2:DescribeInstanceAttribute,
ec2:DescribeInstanceCreditSpecifications,
ec2:DescribeLaunchTemplates,
elastic-inference:DescribeAccelerators,
ssm:DescribeAssociation,
ssm:ListAssociations

Create

iam:PassRole,
ec2:ModifyPrivateDnsNameOptions,
ec2:DescribeElasticGpus,
ec2:DescribeNetworkInterfaces,
ec2:DescribeVolumes,
ec2:RunInstances,
ec2:AssociateIamInstanceProfile,
ec2:DescribeIamInstanceProfileAssociations,
ec2:DescribeInstances,
ec2:DescribeSubnets,
ec2:DescribeKeyPairs,
ec2:DescribeSecurityGroups,
ec2:DescribeVpcs,
ec2:DescribeInstanceAttribute,
ec2:DescribeInstanceCreditSpecifications,
ec2:DescribeLaunchTemplates,
ec2:DescribeLaunchTemplateVersions,
ec2:DetachVolume,
ec2:DisassociateIamInstanceProfile,
ec2:ModifyInstanceAttribute,
ec2:ModifyInstanceCreditSpecification,
ec2:ModifyInstancePlacement,
ec2:MonitorInstances,
ec2:AttachVolume,
ec2:CreateTags,
ec2:ReplaceIamInstanceProfileAssociation,
ec2:StartInstances,
elastic-inference:DescribeAccelerators,
ssm:CreateAssociation,
ssm:DescribeAssociation,
ssm:ListAssociations

Update

ec2:DescribeElasticGpus,
ec2:ModifyPrivateDnsNameOptions,
ec2:DescribeNetworkInterfaces,
ec2:AssociateIamInstanceProfile,
ec2:DescribeIamInstanceProfileAssociations,
ec2:DescribeInstances,
ec2:DescribeSubnets,
ec2:DescribeKeyPairs,
ec2:DescribeSecurityGroups,
ec2:DescribeVpcs,
ec2:DescribeInstanceAttribute,
ec2:DescribeInstanceCreditSpecifications,
ec2:DescribeLaunchTemplates,
ec2:DetachVolume,
ec2:DisassociateIamInstanceProfile,
ec2:ModifyInstanceAttribute,
ec2:ModifyInstanceCreditSpecification,
ec2:ModifyInstanceMaintenanceOptions,
ec2:ModifyInstancePlacement,
ec2:MonitorInstances,
ec2:AttachVolume,
ec2:CreateTags,
ec2:DeleteTags,
ec2:ReplaceIamInstanceProfileAssociation,
ec2:StartInstances,
ec2:StopInstances,
ec2:UnmonitorInstances,
elastic-inference:DescribeAccelerators,
ssm:CreateAssociation,
ssm:DeleteAssociation,
ssm:DescribeAssociation,
ssm:ListAssociations

List

ec2:DescribeInstances

Delete

ec2:DescribeInstances,
ec2:TerminateInstances,
ec2:DescribeElasticGpus,
ec2:DescribeNetworkInterfaces,
ec2:DescribeVolumes,
ec2:DescribeInstances,
ec2:DescribeInstanceAttribute,
ec2:DescribeInstanceCreditSpecifications,
ec2:DescribeLaunchTemplates,
elastic-inference:DescribeAccelerators,
ssm:DescribeAssociation,
ssm:ListAssociations