Skip to main content

nat_gateways

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

Overview​

Namenat_gateways
TypeResource
Idaws.ec2.nat_gateways

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
attached_appliancesstringThe proxy appliances attached to the NAT Gateway for filtering and inspecting traffic to prevent data exfiltration.
auto_provision_zonesstringFor regional NAT gateways only: Indicates whether Amazon Web Services automatically manages AZ coverage. When enabled, the NAT gateway associates EIPs in all AZs where your VPC has subnets to handle outbound NAT traffic, expands to new AZs when you create subnets there, and retracts from AZs where you've removed all subnets. When disabled, you must manually manage which AZs the NAT gateway supports and their corresponding EIPs. A regional NAT gateway is a single NAT Gateway that works across multiple availability zones (AZs) in your VPC, providing redundancy, scalability and availability across all the AZs in a Region. For more information, see Regional NAT gateways for automatic multi-AZ expansion in the Amazon VPC User Guide.
auto_scaling_ipsstringFor regional NAT gateways only: Indicates whether Amazon Web Services automatically allocates additional Elastic IP addresses (EIPs) in an AZ when the NAT gateway needs more ports due to increased concurrent connections to a single destination from that AZ. For more information, see Regional NAT gateways for automatic multi-AZ expansion in the Amazon VPC User Guide.
availability_modestringIndicates whether this is a zonal (single-AZ) or regional (multi-AZ) NAT gateway. A zonal NAT gateway is a NAT Gateway that provides redundancy and scalability within a single availability zone. A regional NAT gateway is a single NAT Gateway that works across multiple availability zones (AZs) in your VPC, providing redundancy, scalability and availability across all the AZs in a Region. For more information, see Regional NAT gateways for automatic multi-AZ expansion in the Amazon VPC User Guide.
connectivity_typestringIndicates whether the NAT gateway supports public or private connectivity.
create_timestringThe date and time the NAT gateway was created.
delete_timestringThe date and time the NAT gateway was deleted, if applicable.
failure_codestringIf the NAT gateway could not be created, specifies the error code for the failure. (InsufficientFreeAddressesInSubnet | Gateway.NotAttached | InvalidAllocationID.NotFound | Resource.AlreadyAssociated | InternalError | InvalidSubnetID.NotFound)
failure_messagestringIf the NAT gateway could not be created, specifies the error message for the failure, that corresponds to the error code. For InsufficientFreeAddressesInSubnet: "Subnet has insufficient free addresses to create this NAT gateway" For Gateway.NotAttached: "Network vpc-xxxxxxxx has no Internet gateway attached" For InvalidAllocationID.NotFound: "Elastic IP address eipalloc-xxxxxxxx could not be associated with this NAT gateway" For Resource.AlreadyAssociated: "Elastic IP address eipalloc-xxxxxxxx is already associated" For InternalError: "Network interface eni-xxxxxxxx, created and used internally by this NAT gateway is in an invalid state. Please try again." For InvalidSubnetID.NotFound: "The specified subnet subnet-xxxxxxxx does not exist or could not be found."
nat_gateway_addressesstringInformation about the IP addresses and network interface associated with the NAT gateway.
nat_gateway_idstringThe ID of the NAT gateway.
provisioned_bandwidthstringReserved. If you need to sustain traffic greater than the documented limits, contact Amazon Web Services Support.
route_table_idstringFor regional NAT gateways only, this is the ID of the NAT gateway.
statestringThe state of the NAT gateway. pending: The NAT gateway is being created and is not ready to process traffic. failed: The NAT gateway could not be created. Check the failureCode and failureMessage fields for the reason. available: The NAT gateway is able to process traffic. This status remains until you delete the NAT gateway, and does not indicate the health of the NAT gateway. deleting: The NAT gateway is in the process of being terminated and may still be processing traffic. deleted: The NAT gateway has been terminated and is no longer processing traffic.
subnet_idstringThe ID of the subnet in which the NAT gateway is located.
tagsstringThe tags for the NAT gateway.
vpc_idstringThe ID of the VPC in which the NAT gateway is located.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_nat_gatewaysselectregionDryRun, Filter, MaxResults, NatGatewayId, NextTokenDescribes your NAT gateways. The default is to describe all your NAT gateways. Alternatively, you can specify specific NAT gateway IDs or filter the results to include only the NAT gateways that match specific criteria.
create_nat_gatewayinsertregionAvailabilityMode, AllocationId, ClientToken, DryRun, SubnetId, VpcId, AvailabilityZoneAddress, TagSpecification, ConnectivityType, PrivateIpAddress, SecondaryAllocationId, SecondaryPrivateIpAddress, SecondaryPrivateIpAddressCountCreates a NAT gateway in the specified subnet. This action creates a network interface in the specified subnet with a private IP address from the IP address range of the subnet. You can create either a public NAT gateway or a private NAT gateway. With a public NAT gateway, internet-bound traffic from a private subnet can be routed to the NAT gateway, so that instances in a private subnet can connect to the internet. With a private NAT gateway, private communication is routed across VPCs and on-premises networks through a transit gateway or virtual private gateway. Common use cases include running large workloads behind a small pool of allowlisted IPv4 addresses, preserving private IPv4 addresses, and communicating between overlapping networks. For more information, see NAT gateways in the Amazon VPC User Guide. When you create a public NAT gateway and assign it an EIP or secondary EIPs, the network border group of the EIPs must match the network border group of the Availability Zone (AZ) that the public NAT gateway is in. If it's not the same, the NAT gateway will fail to launch. You can see the network border group for the subnet's AZ by viewing the details of the subnet. Similarly, you can view the network border group of an EIP by viewing the details of the EIP address. For more information about network border groups and EIPs, see Allocate an Elastic IP address in the Amazon VPC User Guide.
associate_nat_gateway_addressupdateNatGatewayId, AllocationId, regionPrivateIpAddress, DryRun, AvailabilityZone, AvailabilityZoneIdAssociates Elastic IP addresses (EIPs) and private IPv4 addresses with a public NAT gateway. For more information, see Work with NAT gateways in the Amazon VPC User Guide. By default, you can associate up to 2 Elastic IP addresses per public NAT gateway. You can increase the limit by requesting a quota adjustment. For more information, see Elastic IP address quotas in the Amazon VPC User Guide. When you associate an EIP or secondary EIPs with a public NAT gateway, the network border group of the EIPs must match the network border group of the Availability Zone (AZ) that the public NAT gateway is in. If it's not the same, the EIP will fail to associate. You can see the network border group for the subnet's AZ by viewing the details of the subnet. Similarly, you can view the network border group of an EIP by viewing the details of the EIP address. For more information about network border groups and EIPs, see Allocate an Elastic IP address in the Amazon VPC User Guide.
disassociate_nat_gateway_addressupdateNatGatewayId, AssociationId, regionMaxDrainDurationSeconds, DryRunDisassociates secondary Elastic IP addresses (EIPs) from a public NAT gateway. You cannot disassociate your primary EIP. For more information, see Edit secondary IP address associations in the Amazon VPC User Guide. While disassociating is in progress, you cannot associate/disassociate additional EIPs while the connections are being drained. You are, however, allowed to delete the NAT gateway. An EIP is released only at the end of MaxDrainDurationSeconds. It stays associated and supports the existing connections but does not support any new connections (new connections are distributed across the remaining associated EIPs). As the existing connections drain out, the EIPs (and the corresponding private IP addresses mapped to them) are released.
unassign_private_nat_gateway_addressupdateNatGatewayId, PrivateIpAddress, regionMaxDrainDurationSeconds, DryRunUnassigns secondary private IPv4 addresses from a private NAT gateway. You cannot unassign your primary private IP. For more information, see Edit secondary IP address associations in the Amazon VPC User Guide. While unassigning is in progress, you cannot assign/unassign additional IP addresses while the connections are being drained. You are, however, allowed to delete the NAT gateway. A private IP address will only be released at the end of MaxDrainDurationSeconds. The private IP addresses stay associated and support the existing connections, but do not support any new connections (new connections are distributed across the remaining assigned private IP address). After the existing connections drain out, the private IP addresses are released.
assign_private_nat_gateway_addressupdateNatGatewayId, regionPrivateIpAddress, PrivateIpAddressCount, DryRunAssigns private IPv4 addresses to a private NAT gateway. For more information, see Work with NAT gateways in the Amazon VPC User Guide.
delete_nat_gatewaydeleteNatGatewayId, regionDryRunDeletes the specified NAT gateway. Deleting a public NAT gateway disassociates its Elastic IP address, but does not release the address from your account. Deleting a NAT gateway does not delete any NAT gateway routes in your route tables.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
AllocationIdarrayThe allocation IDs of EIPs that you want to associate with your NAT gateway.
AssociationIdarrayThe association IDs of EIPs that have been associated with the NAT gateway.
NatGatewayIdstringThe ID of the NAT gateway.
PrivateIpAddressarrayThe private IPv4 addresses you want to unassign.
regionstringAWS region (default: us-east-1)
AllocationIdstring[Public NAT gateways only] The allocation ID of an Elastic IP address to associate with the NAT gateway. You cannot specify an Elastic IP address with a private NAT gateway. If the Elastic IP address is associated with another resource, you must first disassociate it.
AvailabilityModestringSpecifies whether to create a zonal (single-AZ) or regional (multi-AZ) NAT gateway. Defaults to zonal. A zonal NAT gateway is a NAT Gateway that provides redundancy and scalability within a single availability zone. A regional NAT gateway is a single NAT Gateway that works across multiple availability zones (AZs) in your VPC, providing redundancy, scalability and availability across all the AZs in a Region. For more information, see Regional NAT gateways for automatic multi-AZ expansion in the Amazon VPC User Guide.
AvailabilityZonestringFor regional NAT gateways only: The Availability Zone where you want to associate an Elastic IP address (EIP). The regional NAT gateway uses a separate EIP in each AZ to handle outbound NAT traffic from that AZ. A regional NAT gateway is a single NAT Gateway that works across multiple availability zones (AZs) in your VPC, providing redundancy, scalability and availability across all the AZs in a Region.
AvailabilityZoneAddressarrayFor regional NAT gateways only: Specifies which Availability Zones you want the NAT gateway to support and the Elastic IP addresses (EIPs) to use in each AZ. The regional NAT gateway uses these EIPs to handle outbound NAT traffic from their respective AZs. If not specified, the NAT gateway will automatically expand to new AZs and associate EIPs upon detection of an elastic network interface. If you specify this parameter, auto-expansion is disabled and you must manually manage AZ coverage. A regional NAT gateway is a single NAT Gateway that works across multiple availability zones (AZs) in your VPC, providing redundancy, scalability and availability across all the AZs in a Region. For more information, see Regional NAT gateways for automatic multi-AZ expansion in the Amazon VPC User Guide.
AvailabilityZoneIdstringFor regional NAT gateways only: The ID of the Availability Zone where you want to associate an Elastic IP address (EIP). The regional NAT gateway uses a separate EIP in each AZ to handle outbound NAT traffic from that AZ. Use this instead of AvailabilityZone for consistent identification of AZs across Amazon Web Services Regions. A regional NAT gateway is a single NAT Gateway that works across multiple availability zones (AZs) in your VPC, providing redundancy, scalability and availability across all the AZs in a Region.
ClientTokenstringUnique, case-sensitive identifier that you provide to ensure the idempotency of the request. For more information, see Ensuring idempotency. Constraint: Maximum 64 ASCII characters.
ConnectivityTypestringIndicates whether the NAT gateway supports public or private connectivity. The default is public connectivity.
DryRunbooleanChecks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.
FilterarrayThe filters. nat-gateway-id - The ID of the NAT gateway. state - The state of the NAT gateway (pending | failed | available | deleting | deleted). subnet-id - The ID of the subnet in which the NAT gateway resides. tag - The key/value combination of a tag assigned to the resource. Use the tag key in the filter name and the tag value as the filter value. For example, to find all resources that have a tag with the key Owner and the value TeamA, specify tag:Owner for the filter name and TeamA for the filter value. tag-key - The key of a tag assigned to the resource. Use this filter to find all resources assigned a tag with a specific key, regardless of the tag value. vpc-id - The ID of the VPC in which the NAT gateway resides.
MaxDrainDurationSecondsintegerThe maximum amount of time to wait (in seconds) before forcibly releasing the IP addresses if connections are still in progress. Default value is 350 seconds.
MaxResultsintegerThe maximum number of items to return for this request. To get the next page of items, make another request with the token returned in the output. For more information, see Pagination.
NatGatewayIdarrayThe IDs of the NAT gateways.
NextTokenstringThe token returned from a previous paginated request. Pagination continues from the end of the items returned by the previous request.
PrivateIpAddressarrayThe private IPv4 addresses you want to assign to the private NAT gateway.
PrivateIpAddressCountintegerThe number of private IP addresses to assign to the NAT gateway. You can't specify this parameter when also specifying private IP addresses.
SecondaryAllocationIdarraySecondary EIP allocation IDs. For more information, see Create a NAT gateway in the Amazon VPC User Guide.
SecondaryPrivateIpAddressarraySecondary private IPv4 addresses. For more information about secondary addresses, see Create a NAT gateway in the Amazon VPC User Guide.
SecondaryPrivateIpAddressCountinteger[Private NAT gateway only] The number of secondary private IPv4 addresses you want to assign to the NAT gateway. For more information about secondary addresses, see Create a NAT gateway in the Amazon VPC User Guide.
SubnetIdstringThe ID of the subnet in which to create the NAT gateway.
TagSpecificationarrayThe tags to assign to the NAT gateway.
VpcIdstringThe ID of the VPC where you want to create a regional NAT gateway.

SELECT examples​

Describes your NAT gateways. The default is to describe all your NAT gateways. Alternatively, you can specify specific NAT gateway IDs or filter the results to include only the NAT gateways that match specific criteria.

SELECT
attached_appliances,
auto_provision_zones,
auto_scaling_ips,
availability_mode,
connectivity_type,
create_time,
delete_time,
failure_code,
failure_message,
nat_gateway_addresses,
nat_gateway_id,
provisioned_bandwidth,
route_table_id,
state,
subnet_id,
tags,
vpc_id
FROM aws.ec2.nat_gateways
WHERE region = '{{ region }}' -- required
AND DryRun = '{{ DryRun }}'
AND Filter = '{{ Filter }}'
AND MaxResults = '{{ MaxResults }}'
AND NatGatewayId = '{{ NatGatewayId }}'
AND NextToken = '{{ NextToken }}'
;

INSERT examples​

Creates a NAT gateway in the specified subnet. This action creates a network interface in the specified subnet with a private IP address from the IP address range of the subnet. You can create either a public NAT gateway or a private NAT gateway. With a public NAT gateway, internet-bound traffic from a private subnet can be routed to the NAT gateway, so that instances in a private subnet can connect to the internet. With a private NAT gateway, private communication is routed across VPCs and on-premises networks through a transit gateway or virtual private gateway. Common use cases include running large workloads behind a small pool of allowlisted IPv4 addresses, preserving private IPv4 addresses, and communicating between overlapping networks. For more information, see NAT gateways in the Amazon VPC User Guide. When you create a public NAT gateway and assign it an EIP or secondary EIPs, the network border group of the EIPs must match the network border group of the Availability Zone (AZ) that the public NAT gateway is in. If it's not the same, the NAT gateway will fail to launch. You can see the network border group for the subnet's AZ by viewing the details of the subnet. Similarly, you can view the network border group of an EIP by viewing the details of the EIP address. For more information about network border groups and EIPs, see Allocate an Elastic IP address in the Amazon VPC User Guide.

INSERT INTO aws.ec2.nat_gateways (
region,
AvailabilityMode,
AllocationId,
ClientToken,
DryRun,
SubnetId,
VpcId,
AvailabilityZoneAddress,
TagSpecification,
ConnectivityType,
PrivateIpAddress,
SecondaryAllocationId,
SecondaryPrivateIpAddress,
SecondaryPrivateIpAddressCount
)
SELECT 
'{{ region }}',
'{{ AvailabilityMode }}',
'{{ AllocationId }}',
'{{ ClientToken }}',
'{{ DryRun }}',
'{{ SubnetId }}',
'{{ VpcId }}',
'{{ AvailabilityZoneAddress }}',
'{{ TagSpecification }}',
'{{ ConnectivityType }}',
'{{ PrivateIpAddress }}',
'{{ SecondaryAllocationId }}',
'{{ SecondaryPrivateIpAddress }}',
'{{ SecondaryPrivateIpAddressCount }}'
RETURNING
attached_appliances,
auto_provision_zones,
auto_scaling_ips,
availability_mode,
connectivity_type,
create_time,
delete_time,
failure_code,
failure_message,
nat_gateway_addresses,
nat_gateway_id,
provisioned_bandwidth,
route_table_id,
state,
subnet_id,
tags,
vpc_id
;

UPDATE examples​

Associates Elastic IP addresses (EIPs) and private IPv4 addresses with a public NAT gateway. For more information, see Work with NAT gateways in the Amazon VPC User Guide. By default, you can associate up to 2 Elastic IP addresses per public NAT gateway. You can increase the limit by requesting a quota adjustment. For more information, see Elastic IP address quotas in the Amazon VPC User Guide. When you associate an EIP or secondary EIPs with a public NAT gateway, the network border group of the EIPs must match the network border group of the Availability Zone (AZ) that the public NAT gateway is in. If it's not the same, the EIP will fail to associate. You can see the network border group for the subnet's AZ by viewing the details of the subnet. Similarly, you can view the network border group of an EIP by viewing the details of the EIP address. For more information about network border groups and EIPs, see Allocate an Elastic IP address in the Amazon VPC User Guide.

UPDATE aws.ec2.nat_gateways
SET 
-- No updatable properties
WHERE 
NatGatewayId = '{{ NatGatewayId }}' --required
AND AllocationId = '{{ AllocationId }}' --required
AND region = '{{ region }}' --required
AND PrivateIpAddress = '{{ PrivateIpAddress}}'
AND DryRun = {{ DryRun}}
AND AvailabilityZone = '{{ AvailabilityZone}}'
AND AvailabilityZoneId = '{{ AvailabilityZoneId}}'
RETURNING
nat_gateway_addresses,
nat_gateway_id;

DELETE examples​

Deletes the specified NAT gateway. Deleting a public NAT gateway disassociates its Elastic IP address, but does not release the address from your account. Deleting a NAT gateway does not delete any NAT gateway routes in your route tables.

DELETE FROM aws.ec2.nat_gateways
WHERE NatGatewayId = '{{ NatGatewayId }}' --required
AND region = '{{ region }}' --required
AND DryRun = '{{ DryRun }}'
;
Last updated on