Skip to main content

Network Load Balancer (NLB)

Overview​

The NLB resource manages AWS Network Load Balancers (NLB), providing ultra-low latency Layer 4 (TCP/UDP) load balancing.

Use Cases​

  • High Performance: Millions of requests per second with ultra-low latency
  • Static IP: Use Elastic IPs for whitelisting
  • TCP/UDP: Support for non-HTTP protocols
  • Long Connections: WebSocket, gaming, streaming

Basic Example​

Example:

apiVersion: aws-infra-operator.runner.codes/v1alpha1
kind: NLB
metadata:
  name: my-nlb
  namespace: default
spec:
  providerRef:
    name: aws-provider

  # Load balancer name
  loadBalancerName: my-network-lb

  # Scheme: internet-facing or internal
  scheme: internet-facing

  # Subnets (minimum 1, multi-AZ recommended)
  subnets:
- subnet-abc123
- subnet-def456

  # Security groups (optional for NLB)
  securityGroups:
- sg-12345678

  # Cross-zone load balancing
  enableCrossZoneLoadBalancing: true

  # Tags
  tags:
    Environment: production
    Application: api

  # Deletion policy
  deletionPolicy: Delete

Spec Fields​

FieldTypeRequiredDescription
providerRefObjectYesReference to AWSProvider
loadBalancerNameStringYesName of the load balancer
schemeStringNointernet-facing (default) or internal
subnetsArrayYesSubnet IDs (min 1)
securityGroupsArrayNoSecurity group IDs
enableCrossZoneLoadBalancingBooleanNoEnable cross-AZ balancing (default: false)
ipAddressTypeStringNoipv4 or dualstack
tagsMapNoKey-value tags
deletionPolicyStringNoDelete, Retain, or Orphan

Status Fields​

FieldDescription
readyBoolean indicating if NLB is active
loadBalancerARNAWS ARN of the load balancer
dnsNameDNS name for the NLB
stateCurrent state (active, provisioning, failed)

Advanced Examples​

Internal NLB with Static IPs​

Example:

apiVersion: aws-infra-operator.runner.codes/v1alpha1
kind: NLB
metadata:
  name: internal-nlb
spec:
  providerRef:
    name: aws-provider
  loadBalancerName: internal-api-nlb
  scheme: internal
  subnets:
- subnet-private-1
- subnet-private-2
  subnetMappings:
- subnetId: subnet-private-1
      allocationId: eipalloc-abc123  # Elastic IP
- subnetId: subnet-private-2
      allocationId: eipalloc-def456
  enableCrossZoneLoadBalancing: true

Dual-Stack NLB (IPv4 + IPv6)​

Example:

apiVersion: aws-infra-operator.runner.codes/v1alpha1
kind: NLB
metadata:
  name: dualstack-nlb
spec:
  providerRef:
    name: aws-provider
  loadBalancerName: dualstack-lb
  scheme: internet-facing
  ipAddressType: dualstack
  subnets:
- subnet-abc123
- subnet-def456
  tags:
IPv6: enabled

Multi-AZ with Cross-Zone​

Example:

apiVersion: aws-infra-operator.runner.codes/v1alpha1
kind: NLB
metadata:
  name: multi-az-nlb
spec:
  providerRef:
    name: aws-provider
  loadBalancerName: multi-az-lb
  scheme: internet-facing
  subnets:
- subnet-us-east-1a
- subnet-us-east-1b
- subnet-us-east-1c
  enableCrossZoneLoadBalancing: true
  tags:
    AvailabilityZones: "3"
    CrossZone: "true"

NLB vs ALB​

FeatureNLBALB
LayerLayer 4 (TCP/UDP)Layer 7 (HTTP/HTTPS)
PerformanceUltra-low latencyModerate latency
ThroughputMillions req/secThousands req/sec
Static IPYes (Elastic IP)No
Path RoutingNoYes
WebSocketYesYes
gRPCYesYes (with HTTP/2)

Scheme Types​

Internet-Facing​

Publicly accessible from the internet:

scheme: internet-facing

Internal​

Only accessible from within VPC:

scheme: internal

Cross-Zone Load Balancing​

Distribute traffic evenly across all AZs:

enableCrossZoneLoadBalancing: true

Benefits:

  • Even distribution across AZs
  • Better fault tolerance
  • No cross-AZ data transfer charges (NLB)

IP Address Types​

IPv4 Only (Default)​

Example:

ipAddressType: ipv4

Dual Stack (IPv4 + IPv6)​

Example:

ipAddressType: dualstack

Monitoring​

Check NLB status:

kubectl get nlb my-nlb -o yaml

Example output:

status:
  ready: true
  loadBalancerARN: arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/net/my-nlb/abc123
  dnsName: my-nlb-abc123.elb.us-east-1.amazonaws.com
  state: active

Best Practices​

Best Practices
  • Use NLB for TCP/UDP traffic — Lower latency than ALB, supports static IPs
  • Enable cross-zone load balancing — Distributes traffic evenly across all AZs
  • Configure health checks properly — Set appropriate intervals and thresholds
  • Use target groups efficiently — Separate target groups per service/port
  • Enable access logs — Store in S3 for troubleshooting and audit

Troubleshooting​

NLB Stuck in Provisioning​

Check subnet availability and quotas:

kubectl describe nlb my-nlb

DNS Not Resolving​

Wait for DNS propagation (can take 60 seconds):

nslookup <nlb-dns-name>

No Traffic Reaching Targets​

Check:

  • Security groups allow traffic
  • Target group health checks passing
  • Listener rules configured

Complete Example with Target Groups​

Example:

---
apiVersion: aws-infra-operator.runner.codes/v1alpha1
kind: NLB
metadata:
  name: production-nlb
  namespace: production
spec:
  providerRef:
    name: aws-provider
  loadBalancerName: prod-api-nlb
  scheme: internet-facing
  subnets:
- subnet-us-east-1a
- subnet-us-east-1b
  subnetMappings:
- subnetId: subnet-us-east-1a
      allocationId: eipalloc-static-ip-1
- subnetId: subnet-us-east-1b
      allocationId: eipalloc-static-ip-2
  enableCrossZoneLoadBalancing: true
  tags:
    Environment: production
    Team: platform
    CostCenter: engineering
  deletionPolicy: Retain

AWS Documentation​