Network Address Translation
Nstance supports IPv4-only, dual-stack, and IPv6-only workload networks on
AWS and Google Cloud. ipv4_enabled and ipv6_enabled select the workload
address families.
nat_mode then selects provider NAT, Nstance NAT instances,
or no translation. Depending on the address families, the selected service
provides NAT44 or NAT64.
The OpenTofu/Terraform reference lists every valid combination and the exact module inputs.
Choosing a NAT mode
provider
Provider NAT uses AWS NAT Gateway or Google Cloud NAT. Choose it when you prefer the cloud provider to operate and scale the translation service. It reduces the Nstance operational surface, but incurs the provider’s gateway and traffic charges.
nstance
Nstance NAT uses ordinary VM instances as the translation service. Choose it to avoid managed-gateway costs or retain control of the NAT host. Nstance creates, scales, replaces, and removes the NAT VMs as workload subnets need them.
none
No NAT is valid only for IPv6-only workload networks. Workloads use native IPv6 routes and cannot reach IPv4-only destinations through translation.
How Nstance NAT works
Nstance Server creates one active NAT instance for each tenant and populated workload subnet. It creates the instance before the first dependent workload and removes it only after the subnet has remained empty for the configured grace period. The workload subnet route targets that instance’s primary network interface.
The NAT instance scales vertically through a configured instance-type ladder. Nstance uses CPU utilization, conntrack utilization, and packet drops for scaling decisions; byte and packet rates remain available for observability. Replacement is create-before-destroy: the new instance must register and report healthy before Nstance moves the route and optional fixed public IPv4 address, then removes the old instance. Route cutover can interrupt existing translated connections, so this is not a stateful hot-standby design.
How IPv6-only workloads reach IPv4 services
An IPv6-only workload cannot connect directly to an IPv4 address. NAT64 and DNS64 bridge that gap without assigning IPv4 addresses to the workload:
- The workload looks up a hostname.
- If the hostname has only an IPv4 address, DNS64 returns a synthetic IPv6
address in
64:ff9b::/96. - The workload connects to that IPv6 address.
- NAT64 translates the connection to IPv4 and forwards it to the destination.
Hostnames with native IPv6 addresses continue to use IPv6 directly and bypass translation.
Applications should resolve hostnames rather than depend on IPv4 literals: DNS64 cannot synthesize a destination from an address embedded directly in application configuration. Protocols that carry or validate IP addresses in their payloads may also require application-specific support.
With nat_mode = "provider", AWS NAT Gateway or Google Cloud NAT performs the
translation. With nat_mode = "nstance", Nstance routes the prefix through a
NAT instance running Jool. The minimal demonstration userdata installs Jool
from Debian packages during first boot. Production deployments should instead
use a hardened image or userdata that supplies and configures Jool without
depending on boot-time package installation.
Stable public IPv4 addresses
Nstance NAT can optionally associate a reserved public IPv4 address with each active NAT instance. This gives translated IPv4 traffic a stable egress identity without reserving a second address for replacement. Once the new instance is healthy, Nstance reassigns the address and changes the workload route as part of the cutover.
Without a fixed address, the NAT VM uses its ordinary provider-assigned public address and the egress address may change when the VM is replaced. Fixed public IPv4 addresses do not affect native IPv6 traffic.
Changing modes
The network modules preserve workload subnets when switching between provider and Nstance NAT. Switching to provider NAT creates the provider path before Nstance retires its NAT instances. Switching to Nstance NAT must wait for a healthy NAT instance and can temporarily interrupt translated egress while Nstance establishes the new route.
See the nat server configuration for
Nstance NAT lifecycle and scaling settings.