OpenMCF logoOpenMCF

Loading...

OCI Network Load Balancer

Deploys an Oracle Cloud Infrastructure Network Load Balancer (Layer 4) with backend sets, backends, and listeners in a single deployment unit. The NLB provides high-performance, low-latency traffic distribution for TCP, UDP, and mixed-protocol workloads with fully elastic bandwidth and source IP preservation.

What Gets Created

When you deploy an OciNetworkLoadBalancer resource, OpenMCF provisions:

  • Network Load Balancer — an oci_network_load_balancer_network_load_balancer resource in the specified compartment and subnet. Supports public or private deployment, optional reserved IP addresses, source IP preservation, and symmetric hashing. Standard OpenMCF freeform tags are applied for resource tracking.
  • Backend Sets — one oci_network_load_balancer_backend_set per entry in backendSets. Each set defines a load balancing policy (tuple-based hashing), health checker configuration, and failover behavior. Backend sets are created as children of the NLB.
  • Backends — one oci_network_load_balancer_backend per entry in each backend set's backends list. Backends are identified by IP address, compute instance OCID, or both. Created as children of their backend set.
  • Listeners — one oci_network_load_balancer_listener per entry in listeners. Each listener binds a port and Layer 4 protocol to a default backend set. Listeners are created after all backend sets, ensuring referential integrity.

Prerequisites

  • OCI credentials configured via environment variables or OpenMCF provider config (API Key, Instance Principal, Security Token, Resource Principal, or OKE Workload Identity)
  • A compartment OCID where the NLB will be created — literal value or reference to an OciCompartment resource
  • A subnet OCID for the NLB — literal value or reference to an OciSubnet resource. The subnet determines whether the NLB gets public or private IP addresses.
  • Backend server IP addresses or compute instance OCIDs for traffic targets

Quick Start

Create a file nlb.yaml:

apiVersion: oci.openmcf.org/v1
kind: OciNetworkLoadBalancer
metadata:
  name: my-nlb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.OciNetworkLoadBalancer.my-nlb
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  subnetId:
    value: "ocid1.subnet.oc1.iad.example"
  backendSets:
    - name: "tcp-backends"
      policy: five_tuple
      healthChecker:
        protocol: tcp
      backends:
        - port: 8080
          ipAddress: "10.0.1.10"
        - port: 8080
          ipAddress: "10.0.1.11"
  listeners:
    - name: "tcp-listener"
      port: 80
      protocol: tcp
      defaultBackendSetName: "tcp-backends"

Deploy:

openmcf apply -f nlb.yaml

This creates a public NLB listening on port 80 (TCP) and distributing traffic to two backends on port 8080 using five-tuple hashing. TCP health checks verify backend availability. The NLB ID and assigned IP addresses are exported as stack outputs.

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
compartmentIdStringValueOrRefOCID of the compartment where the NLB will be created. Can reference an OciCompartment resource via valueFrom.Required
subnetIdStringValueOrRefOCID of the subnet where the NLB will be deployed. The NLB is deployed into a single subnet (unlike the L7 load balancer). Changing this after creation forces recreation. Can reference an OciSubnet resource via valueFrom.Required
backendSetsBackendSet[]Backend sets defining groups of backend servers with load balancing policies and health checking. See backendSet fields.Minimum 1 item
listenersListener[]Listeners defining ports and protocols on which the NLB accepts connections. See listener fields.Minimum 1 item

Optional Fields

FieldTypeDefaultDescription
displayNamestringmetadata.nameHuman-readable name shown in the OCI Console.
isPrivateboolfalseWhen true, creates a private NLB accessible only within the VCN. Private NLBs receive only private IP addresses. Changing this after creation forces recreation.
isPreserveSourceDestinationboolfalseWhen true, preserves the original source and destination IP addresses in packet headers. Automatically enables skip-source-dest-check on the NLB's VNIC. Essential for firewalls and security appliances.
isSymmetricHashEnabledboolfalseWhen true, enables symmetric hashing. Only valid when isPreserveSourceDestination is also true. Removes the need for backends to perform SNAT.
networkSecurityGroupIdsStringValueOrRef[]—OCIDs of network security groups applied to the NLB. Can reference OciSecurityGroup resources via valueFrom.
nlbIpVersionstring"IPV4"IP version for the NLB. Values: "IPV4", "IPV6", "IPV4_AND_IPV6".
reservedIpsReservedIp[]—Pre-created reserved public IPs to assign. When omitted, OCI assigns ephemeral public IPs (for public NLBs). Each entry has an id field (OCID of the reserved IP).
assignedIpv6string—IPv6 address to assign to the NLB. Must be part of one of the subnet's IPv6 prefixes.
assignedPrivateIpv4string—Private IPv4 address within the subnet's CIDR range. When omitted, OCI assigns one automatically. Changing this after creation forces recreation.
subnetIpv6cidrstring—IPv6 subnet prefix selection. When provided, the NLB IPv6 address is assigned within this CIDR block.

backendSet Fields

FieldTypeDescriptionValidation
namestringUnique name for this backend set. Listeners reference backend sets by this name.Minimum 1 character
policyenumLoad balancing policy. Values: five_tuple (src IP, src port, dst IP, dst port, protocol), three_tuple (src IP, dst IP, protocol), two_tuple (src IP, dst IP).Required (cannot be unspecified)
healthCheckerHealthCheckerHealth checker configuration. See healthChecker fields.Required
backendsBackend[]Backend servers in this set. When omitted, the set is created empty. See backend fields.Optional
isPreserveSourceboolWhen true, preserves the source IP when forwarding to backends in this set.Optional
isFailOpenboolWhen true, continues distributing traffic to all backends even when all are marked unhealthy.Optional
isInstantFailoverEnabledboolWhen true, immediately forwards existing connections to a healthy backend when the current one becomes unhealthy.Optional
isInstantFailoverTcpResetEnabledboolWhen true (and instant failover is enabled), sends a TCP RST to clients instead of silently failing over.Optional
areOperationallyActiveBackendsPreferredboolWhen true, preferentially routes traffic to operationally active backends (active-standby support).Optional
ipVersionstringIP version for this backend set. When omitted, inherits from the NLB's nlbIpVersion.Optional

healthChecker Fields

FieldTypeDescriptionValidation
protocolenumHealth check protocol. Values: http, https, tcp, udp, dns.Required (cannot be unspecified)
portint32Port to probe. When omitted, uses the backend's traffic port.Optional
urlPathstringURL path for HTTP/HTTPS health checks (e.g., "/health"). Required when protocol is http or https.Optional
returnCodeint32Expected HTTP status code (e.g., 200). Used with http and https protocols.Optional
responseBodyRegexstringRegex pattern to match against the response body.Optional
intervalInMillisint32Interval between health checks in milliseconds. Default: 10000.Optional
timeoutInMillisint32Maximum wait time for a response in milliseconds. Default: 3000.Optional
retriesint32Consecutive failures before marking a backend unhealthy. Default: 3.Optional
requestDatastringBase64-encoded probe payload for TCP/UDP health checks.Optional
responseDatastringBase64-encoded expected response for TCP/UDP health checks.Optional
dnsHealthCheckDnsHealthCheckDNS health check configuration. Required when protocol is dns. See dnsHealthCheck fields.Optional

dnsHealthCheck Fields

FieldTypeDescriptionValidation
domainNamestringFully qualified domain name to query.Minimum 1 character
queryClassstringDNS query class. Values: "IN", "CH". Default: "IN".Optional
queryTypestringDNS query type. Values: "A", "AAAA", "TXT". Default: "A".Optional
rcodesstring[]Acceptable DNS response codes (e.g., ["NOERROR"]). Default: ["NOERROR"].Optional
transportProtocolstringTransport protocol for DNS queries. Values: "UDP", "TCP". Default: "UDP".Optional

backend Fields

FieldTypeDescriptionValidation
portint32Port on which the backend server listens for traffic.1–65535
ipAddressstringIP address of the backend server. When omitted, targetId must be provided.Optional
targetIdstringOCID of a compute instance or private IP. OCI resolves the IP address automatically. When omitted, ipAddress must be provided.Optional
weightint32Relative weight for traffic distribution. Higher weights receive more traffic. Default: 1.Optional
isBackupboolWhen true, this backend only receives traffic when all non-backup backends are unhealthy.Optional
isDrainboolWhen true, existing connections complete but no new connections are routed to this backend.Optional
isOfflineboolWhen true, no traffic is sent to this backend.Optional
namestringUnique name for the backend within the set. When omitted, OCI generates "IP:port".Optional

listener Fields

FieldTypeDescriptionValidation
namestringUnique name for this listener.Minimum 1 character
portint32Port on which the listener accepts connections.1–65535
protocolenumLayer 4 protocol. Values: tcp, udp, tcp_and_udp, any.Required (cannot be unspecified)
defaultBackendSetNamestringName of the backend set that receives traffic. Must match a name in backendSets.Minimum 1 character
ipVersionstringIP version for this listener. When omitted, inherits from the NLB's nlbIpVersion.Optional
isPpv2EnabledboolWhen true, enables Proxy Protocol v2. PPv2 prepends connection metadata (source IP, port, protocol) to the TCP stream.Optional
tcpIdleTimeoutint32TCP idle timeout in seconds. Connections idle longer than this are closed.Optional
udpIdleTimeoutint32UDP idle timeout in seconds.Optional
l3ipIdleTimeoutint32L3IP idle timeout in seconds. Applies when protocol is any.Optional

Examples

Basic TCP Load Balancer

A public NLB distributing TCP traffic across two backends with five-tuple hashing and TCP health checks:

apiVersion: oci.openmcf.org/v1
kind: OciNetworkLoadBalancer
metadata:
  name: web-nlb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.OciNetworkLoadBalancer.web-nlb
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  subnetId:
    value: "ocid1.subnet.oc1.iad.example"
  backendSets:
    - name: "web-backends"
      policy: five_tuple
      healthChecker:
        protocol: http
        port: 8080
        urlPath: "/health"
        returnCode: 200
      backends:
        - port: 8080
          ipAddress: "10.0.1.10"
        - port: 8080
          ipAddress: "10.0.1.11"
  listeners:
    - name: "http-listener"
      port: 80
      protocol: tcp
      defaultBackendSetName: "web-backends"

Private NLB with Failover

A private NLB for internal services with instant failover and fail-open enabled. When a backend becomes unhealthy, existing connections immediately move to a healthy backend with a TCP RST signal:

apiVersion: oci.openmcf.org/v1
kind: OciNetworkLoadBalancer
metadata:
  name: internal-nlb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: acme
    pulumi.openmcf.org/project: platform
    pulumi.openmcf.org/stack.name: prod.OciNetworkLoadBalancer.internal-nlb
spec:
  compartmentId:
    valueFrom:
      kind: OciCompartment
      name: prod-compartment
      fieldPath: status.outputs.compartmentId
  subnetId:
    valueFrom:
      kind: OciSubnet
      name: private-subnet
      fieldPath: status.outputs.subnetId
  isPrivate: true
  displayName: "Internal Service NLB"
  networkSecurityGroupIds:
    - valueFrom:
        kind: OciSecurityGroup
        name: nlb-nsg
        fieldPath: status.outputs.networkSecurityGroupId
  backendSets:
    - name: "grpc-backends"
      policy: five_tuple
      isFailOpen: true
      isInstantFailoverEnabled: true
      isInstantFailoverTcpResetEnabled: true
      healthChecker:
        protocol: http
        port: 8081
        urlPath: "/healthz"
        returnCode: 200
        intervalInMillis: 5000
        timeoutInMillis: 2000
        retries: 2
      backends:
        - port: 9090
          ipAddress: "10.0.2.10"
          weight: 3
        - port: 9090
          ipAddress: "10.0.2.11"
          weight: 3
        - port: 9090
          ipAddress: "10.0.2.12"
          isBackup: true
  listeners:
    - name: "grpc-listener"
      port: 9090
      protocol: tcp
      defaultBackendSetName: "grpc-backends"
      tcpIdleTimeout: 3600

Firewall Appliance with Source IP Preservation

An NLB in transparent mode forwarding all traffic to firewall appliances while preserving the original source and destination IPs. Symmetric hashing ensures return traffic follows the same path:

apiVersion: oci.openmcf.org/v1
kind: OciNetworkLoadBalancer
metadata:
  name: fw-nlb
  org: acme
  env: prod
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: acme
    pulumi.openmcf.org/project: security
    pulumi.openmcf.org/stack.name: prod.OciNetworkLoadBalancer.fw-nlb
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  subnetId:
    value: "ocid1.subnet.oc1.iad.example"
  isPreserveSourceDestination: true
  isSymmetricHashEnabled: true
  displayName: "Firewall NLB"
  backendSets:
    - name: "firewall-backends"
      policy: five_tuple
      isPreserveSource: true
      isFailOpen: true
      healthChecker:
        protocol: tcp
        port: 443
        intervalInMillis: 5000
        timeoutInMillis: 3000
        retries: 3
      backends:
        - port: 0
          targetId: "ocid1.instance.oc1.iad.firewallvm1"
        - port: 0
          targetId: "ocid1.instance.oc1.iad.firewallvm2"
  listeners:
    - name: "all-traffic"
      port: 0
      protocol: any
      defaultBackendSetName: "firewall-backends"

Multi-Protocol NLB with DNS Health Checks

An NLB serving both TCP and UDP traffic on separate listeners, using DNS-based health checks for a DNS server backend set:

apiVersion: oci.openmcf.org/v1
kind: OciNetworkLoadBalancer
metadata:
  name: dns-nlb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: acme
    pulumi.openmcf.org/project: platform
    pulumi.openmcf.org/stack.name: prod.OciNetworkLoadBalancer.dns-nlb
spec:
  compartmentId:
    value: "ocid1.compartment.oc1..example"
  subnetId:
    value: "ocid1.subnet.oc1.iad.example"
  isPrivate: true
  backendSets:
    - name: "dns-backends"
      policy: three_tuple
      healthChecker:
        protocol: dns
        dnsHealthCheck:
          domainName: "health.internal.example.com"
          queryType: "A"
          rcodes:
            - "NOERROR"
          transportProtocol: "UDP"
      backends:
        - port: 53
          ipAddress: "10.0.3.10"
        - port: 53
          ipAddress: "10.0.3.11"
  listeners:
    - name: "dns-udp"
      port: 53
      protocol: udp
      defaultBackendSetName: "dns-backends"
      udpIdleTimeout: 120
    - name: "dns-tcp"
      port: 53
      protocol: tcp
      defaultBackendSetName: "dns-backends"
      tcpIdleTimeout: 300

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
network_load_balancer_idstringOCID of the created network load balancer.
ip_addressesstringComma-separated IP addresses assigned to the NLB (includes both public and private IPs as applicable).

Related Components

  • OciCompartment — provides the compartment referenced by compartmentId via valueFrom
  • OciSubnet — provides the subnet referenced by subnetId via valueFrom
  • OciSecurityGroup — manages network security rules for the NLB via networkSecurityGroupIds
  • OciApplicationLoadBalancer — the Layer 7 counterpart for HTTP/HTTPS workloads with SSL termination, hostname routing, and rule sets
  • OciPublicIp — provides reserved public IPs that can be assigned to the NLB via reservedIps

Next article

OCI Network Security Group

OCI Network Security Group Deploys an Oracle Cloud Infrastructure Network Security Group (NSG) with inline ingress and egress security rules. Rules are split by direction so that source and destination fields are never ambiguous. Each NSG supports up to 120 rules total and attaches to individual VNICs for per-resource traffic control. What Gets Created When you deploy an OciSecurityGroup resource, OpenMCF provisions: Network Security Group — an ocicorenetworksecuritygroup resource in the...
Read next article
Presets
3 ready-to-deploy configurationsView presets →