Network Load Balancer (L4)

oci-network-load-balancer

Status: static-validated, live-test pending. Ships under live-test quarantine — no OCI cloud sandbox is wired into CI yet, so the live apply → verify → destroy gate has not run. Static validation (fmt, validate, tflint) passes.

Low-latency, pass-through Layer-4 Network Load Balancer for OCI: TCP/UDP listeners, backend sets with L4 health checks, and preserved client source IPs. Simpler and cheaper than the L7 Load Balancer — the natural front door for OKE node pools, custom TCP services and UDP workloads. Works with Terraform and OpenTofu (>= 1.6), OCI provider >= 8.0, < 9.0.

Secure defaults

• Private by default (is_private = true): no public IP unless you opt in.
• Deny-by-default backends: a backend only receives traffic once it passes its health check; health checks are required on every backend set.
• NSG-first: attach network_security_group_ids for a stateful, deny-by-default data plane instead of opening the subnet security list.
• Client-IP preservation is available per backend set (is_preserve_source) and NLB-wide (preserve_source_destination) for transparent backends.
• A reserved public IP can only bind to a public NLB (precondition), and symmetric hashing requires source/destination preservation (precondition).

Usage

module "nlb" {
  source = "./oci-network-load-balancer"

  compartment_id = "ocid1.compartment.oc1..xxxx"
  name           = "prod-nlb"
  subnet_id      = module.vcn.subnet_ids["private"]

  network_security_group_ids  = [module.vcn.network_security_group_ids["nlb"]]
  preserve_source_destination = true

  backend_sets = {
    web = {
      policy = "FIVE_TUPLE"
      health_check = {
        protocol = "TCP"
        port     = 8080
      }
      backends = {
        a = { ip_address = "10.0.1.10", port = 8080 }
        b = { ip_address = "10.0.1.11", port = 8080 }
      }
    }
  }

  listeners = {
    https = {
      port                = 443
      protocol            = "TCP"
      default_backend_set = "web"
    }
  }
}

Inputs

Name	Type	Default	Description
compartment_id	string	—	Compartment OCID (required)
name	string	—	NLB display name (required)
subnet_id	string	—	Regional subnet OCID (required)
is_private	bool	true	Private (no public IP) by default
nlb_ip_version	string	IPV4	IPV4 or IPV4_AND_IPV6
network_security_group_ids	list(string)	[]	NSGs on the NLB VNIC
preserve_source_destination	bool	false	Skip VNIC src/dst check (transparent backends)
symmetric_hash_enabled	bool	false	Hash both flow directions to one backend (needs preserve)
reserved_ip_id	string	null	Reserved public IP OCID (public NLB only)
backend_sets	map(object)	{}	Backend sets: policy, health check, backends
listeners	map(object)	{}	Listeners: port, protocol, default backend set
freeform_tags	map(string)	{}	Freeform tags
defined_tags	map(string)	{}	Defined tags (Namespace.Key = value)

Backend set policy is one of FIVE_TUPLE, THREE_TUPLE, TWO_TUPLE. Health check protocol is HTTP, HTTPS, TCP, UDP or DNS. Each backend must set exactly one of ip_address or target_id. Listener protocol is TCP, UDP, TCP_AND_UDP, ANY or L3IP.

Outputs

network_load_balancer_id, ip_addresses (full objects), public_ip_addresses, private_ip_addresses, backend_set_names, listener_names.

Notes

• ANY/ICMP listeners and symmetric hashing require preserve_source_destination = true; on a public NLB ANY maps to TCP/UDP, on a private NLB it adds ICMP.
• A health-check port = 0 makes the check use each backend's own port.
• One always-free NLB is available per tenancy; this module's defaults fit it.

Requirements

• Terraform or OpenTofu >= 1.6
• Provider oracle/oci >= 8.0, < 9.0

Verification

Static-validated (fmt, validate, tflint). Live apply/destroy testing pending cloud sandbox availability — see catalog status.

License

Commercial — LicenseRef-IaCBazaar-Commercial. © IaC Bazaar. Original work (not derived from a third-party module).