Network Load Balancers

A network load balancer (NLB) on the Oracle Private Cloud Appliance provides automated traffic distribution from one entry point to multiple servers reachable from the virtual cloud network (VCN). NLBs, like LBs, offer a choice of using a public or private IP address and various load balancing policies.

For more general information about NLBs, see the Network Load Balancing Overview chapter in the Oracle Private Cloud Appliance Concepts Guide.

Managing a Network Load Balancer

This section describes how to create, update, view details, and delete a network load balancer (NLB).

Creating a Network Load Balancer

This topic describes how to creat a network load balancer (NLB).

Using the Compute Web UI

  1. Open the Navigation Menu, select Networking, and select Network Load Balancers.

  2. Select the Create Network Load Balancer button to open the Create Network Load Balancer dialog.

  3. Enter the following information:

    • Name: Enter a descriptive name for the NLB. The name does not need to be unique, and you can change it.

    • Create in Compartment: Select the compartment in which to create the NLB.

    • Visibility Type: Select either Public or Private Load Balancer.

      • If you select Private Load Balancer, the NLB receives a private IP address from the selected subnet.

      • If you select Public Load Balancer, the Select Public IP menu is shown. Select a public IP from the list. You might need to change the compartment above the menu. If the menu displays None Available or if you do not select a public IP from the list, a public IP is automatically assigned from the configured public IP range.

      See Load Balancing for more information about private and public load balancers.

    • Subnet: Select the name of the VCN and Subnet for the NLB. You might need to change the compartment above the menus.

    • Network Security Group: (Optional) By default, the NLB is not attached to any NSG. Select the box labeled Enable Network Security Group to add this NLB to one or more NSGs.

      1. Select an NSG from the drop-down list. You might need to change the compartment to find the NSG you want.

      2. Click the Add Another NSG button if you want to attach to another NSG.

      3. To remove an NSG from the list, click the trash can to the right of that NSG. To remove the last NSG or all NSGs, uncheck the Enable Network Security Groups box.

  4. Tagging: (Optional) Add defined or free-form tags for this NLB as described in Adding Tags at Resource Creation. Tags can also be applied later.

  5. Select the Create Network Load Balancer button in the dialog. The details page of the new NLB is displayed.

Next Steps: On the NLB details page, scroll down to the Resources section and select resources to create to complete the configuration.

Using the OCI CLI

  1. Gather the information that you need to run the command:

    • Compartment OCID (oci iam compartment list)

    • At least one subnet OCID (oci network subnet list)

  2. Enter the create NLB command.

    Syntax:

    The following shows only the required parameters. Use oci nlb network-load-balancer create -h to get information about optional parameters such as backend sets and listeners. 

    oci nlb network-load-balancer create --compartment-id compartment_OCID \
--display-name name-of-network-load-balancer \ 
--subnet-id subnet_OCID

    Example:

    The following example creates a private NLB (the --is-private option value is true by default), and a private IP address is assigned from the specified subnet. See Load Balancing for more information about private and public load balancers. 

    $ oci nlb network-load-balancer create --compartment-id ocid1.compartment.unique_ID \
  --display-name Private_NLB1 --subnet-id ocid1.subnet.unique_ID

{
  "data": {
    "backend-sets": {},
    "compartment-id": "ocid1.tenancy.unique_ID",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "auser",
        "CreatedOn": "2025-01-28T23:12:58.28Z"
      },
    "display-name": "Private_NLB1",
    "freeform-tags": null,
    "hostnames": {},
    "id": "ocid1.networkloadbalancer.unique_ID",
    "ip-addresses": [
    {
      "ip-address": 10.10.1.16,
      "is-public"; false,
      "reserved-ip": null
    }
    ],
    "is-preserve-source-destination": false,
    "is-private": true,
    "lifecycle-details": null,
    "lifecycle-state": "ACTIVE",
    "listeners": {},
    "network-security-group-ids": null,
    "nlb-ip-version": "IPV4",
    "subnet-id":"ocid1.subnet.unique_ID",
    "system-tags": null,
    "time-created": "2025-01-28T23:12:58.000001+00:00",
    "time-updated": null
  },
"etag": "00c648d7-b654-4583-dbdb-k5oed55"
}

    This output is the same as the output of the oci nlb network-load-balancer get command.

    Next Steps: Complete the NLB configuration by adding resources using their separate commands, such as oci nlb listener create. For a list of commands, see oci nlb -h.

Editing a Network Load Balancer

You can change the network load balancer (NLB) name and tags.

Using the Compute Web UI

To add or update related resources such as backend sets or listeners, go to the NLB details page, scroll down to the resources section, and select the resource that you want to add or edit.

  1. Open the Navigation menu, select Networking, and select Network Load Balancers.

  2. For the NLB that you want to edit, select the Actions menu, and select the Edit option to open the Edit Network Load Balancer dialog.

  3. Make your changes and select the Update Network Load Balancer button to update the NLB properties.

Using the OCI CLI

If you did not add resources such as backend sets or listeners when you created the NLB, add them by using their separate command, such as oci nlb listener create. If you did add resources when you created the NLB, update them by using their separate command, such as oci nlb listener update.

  1. Get the NLB OCID (oci nlb network-load-balancer list)

  2. Run the update NLB command.

    Example:

    $ oci nlb network-load-balancer update \
 --network-load-balancer-id ocid1.networkloadbalancer.unique_ID \
 --display-name new_nlb_name

Viewing Network Load Balancer Details

You can view a list of existing network load balancers and view their details.

Using the Compute Web UI

  1. Open the Navigation menu, select Networking, and select Network Load Balancers.

  2. If necessary, select a different compartment from the compartment menu above the NLB list.

  3. Select the name of the NLB to go to its details page.

    Alternatively, for the NLB for which you want to see the details, select the Actions menu and select the View details option.

Using the OCI CLI

  1. Get the NLB OCID (oci nlb network-load-balancer list)

  2. Run the get NLB command.

    Syntax:

    oci nlb network-load-balancer get --network-load-balancer-id networkloadbalancer_OCID

    The details of all the resources that have been created, such as backend sets, certificates, and listeners are included in the output.

Deleting a Network Load Balancer

You can delete a network load balancer (NLB) to remove it from service.

Using the Compute Web UI

  1. Open the Navigation menu, select Networking, and select Network Load Balancers.

  2. For the NLB that you want to delete, select the Actions menu, and select the Terminate option.

  3. Confirm the operation when prompted.

Using the OCI CLI

  1. Get the NLB OCID (oci nlb network-load-balancer list)

  2. Run the delete NLB command.

    Syntax:

    $ oci nlb network-load-balancer delete --force \
--network-load-balancer-id networkloadbalancer_OCID

Network Load Balancer Backend Sets

This section describes how to use backend sets to create logical entities consisting of a network load balancing policy, health check policy, and a list of backend servers for a Network Load Balancer resource.

Creating a Network Load Balancer Backend Set

You can create a backend set for an existing network load balancer. The backend set is a group of servers to which network traffic is load balanced. You can create backend servers after you create the backend set, or at the same time. This topic creates only the backend set.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the Network Load Balancer for which you want to create the network load balancer backend set.

  3. Click Backend Sets under Resources.
  4. Any existing backend sets are listed, otherwise the list says No data available. To create a backend set, click Create Backend Set.

  5. Enter the following:

    • Name: Specify a friendly name for the backend set. It must be unique within the network load balancer, and cannot be changed. Valid backend set names include only alphanumeric characters, dashes, and underscores. Backend set names cannot contain spaces. Avoid entering confidential information.

    • Load Balancing Policy: The IP Hash policy uses an incoming request's source IP address as a hashing key to route "non-sticky" traffic to the same backend server. The load balancer routes requests from the same client to the same backend server as long as that server is available. This policy honors server weight settings when establishing the initial connection. Select one of the following load balancing policies:
      • 5-Tuple hash: This policy distributes incoming traffic based on 5-Tuple (source IP and port, destination IP and port, protocol) IP Hash.
      • 3-Tuple hash: This policy ensures that requests from a particular client are always directed to the same backend server based on 3-Tuple (source IP, destination IP, protocol) IP Hash.
      • 2-Tuple hash: This policy routes incoming traffic to the same backend server based on 2-Tuple (Source/Destination) IP Hash.
    • Source Header Preservation: The default value cannot be changed.

    • IP Protocol Verion: The network load balancer listener and backend set must use the same IP protocol version. Accepted values are: IPV4.

    • Health Check: Specify the parameters to confirm the health of backend servers in the set:
      • Protocol: Enter the protocol: TCP or HTTP. HTTP is valid for NLB health checks. When using TCP as the protocol, you can optionally provide the request data and the response data.
      • Port: Specify the backend server port against which to run the health check. You can enter the value '0' to have the health check use the backend server's traffic port.
      • Interval in MS: Specify how frequently to run the health check in milliseconds. The default value is 10000 (10 seconds).
      • Timeout in MS: Specify the maximum time in milliseconds to wait for a reply to a health check. A health check is successful only if a reply returns within this timeout period. The default is 3000 (3 seconds).
      • Number of Retries: Specify the number of retries to attempt before a backend server is considered "unhealthy." This number also applies when recovering a server to the "healthy" state. The default is 3.
      • Status Code: Specify the status code a healthy backend server must return.
      • URL Path (URI): Specify a URL endpoint against which to run the health check.

  6. Click the Create Backend Set button in the dialog. To display the details of the new backend set, view the backend set.

Using the OCI CLI

  1. Get the NLB OCID (oci nlb network-load-balancer list)

  2. Run the create backend set command.

    Syntax:

    oci nlb backend-set create --health-checker health-checker-parameters \
  --name backend-set-name --network-load-balancer-id network-load-balancer_OCID \
   --policy network-load-balancer-policy

    Where:

    • health-checker-parameters is the set of parameters associated with the health checker for this backend set.
    • Protocol: Enter the protocol: TCP. Configure your health check protocol to match your application or service. When using TCP as the protocol, you can optionally provide the request data and the response data.
    • Port: Specify the backend server port against which to run the health check. You can enter the value '0' to have the health check use the backend server's traffic port.
    • Interval in MS: Specify how frequently to run the health check in milliseconds. The default value is 10000 (10 seconds).
    • Timeout in MS: Specify the maximum time in milliseconds to wait for a reply to a health check. A health check is successful only if a reply returns within this timeout period. The default is 3000 (3 seconds).
    • Number of Retries: Specify the number of retries to attempt before a backend server is considered "unhealthy." This number also applies when recovering a server to the "healthy" state. The default is 3.
    • Status Code: Specify the status code a healthy backend server must return.
    • URL Path (URI): Specify a URL endpoint against which to run the health check.

    • backend-set-name is the name specific to the backend set.

    • network-load-balancer_OCID is the OCID of the NLB.

    • network-load-balancer-policy is the policy associated with the load balancer.

    Example:

    oci nlb backend-set create --health-checker '{"interval-in-milliseconds":10000,"port": 22,
"protocol": "TCP", "retries": 3, "timeoutInMillis": 3000}' --name PrivTCP_NLB1BESet 
--network-load-balancer-id ocid1.networkloadbalancer.unique_ID \
--policy "TWO_TUPLE"

{
  "opc-work-request-id": "ocid1.workrequest.unique_ID"
}

    The command returns a work request OCID. To view the backend set details, use oci nlb backend-set list with the NLB OCID to list all backend sets associated with the specified NLB, and then use oci lb backend-set get with the NLB OCID and backend set name to view the backend set details. 

    $ oci nlb backend-set list --network-load-balancer-id ocid1.networkloadbalancer.unique_ID
$ oci nlb backend-set get --backend-set-name PrivTCP_NLB1BESet \
--network-load-balancer-id ocid1.networkloadbalancer.unique_ID

Viewing Network Load Balancer Backend Set Details

You can view a list of the backend sets of an existing network load balancer and view their details.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the network load balancer (NLB) for which you want to list the existing backend set details.

  3. Click the Backend Sets under Resources to display a list of any available backend sets.

  4. If the NLB backend set exists, you can view its details by clicking on the backend set name or under the Action (three vertical dots) pull-down menu.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the get command.

    Use the backend set name and NLB OCID to view the details for the NLB backend set in the specified compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb backend-set get --backend-set-name backend_set_name \ 
  --network-load-balancer-id network-load-balancer_OCID

    Where:

    • backend-set-name is the name specific to the backend set.

    • network-load-balancer_OCID is the OCID of the load balancer associated with the backend set.

    Example:

    $ oci nlb backend-set get --backend-set-name PrivTCP_NLB1BESet \ 
  --network-load-balancer-id ocid1.networkloadbalancer..….….uniqueID

{
  "data": {
    "items": [
    {
      "backends": [],
      "health-checker": {
        "interval-in-millis": 10000,
        "port": 22,
        "protocol": "TCP",
        "request-data": "123",
        "response-body-regex": ".*",
        "response-data": "123",
        "retries": 3,
        "return-code": 200,
        "timeout-in-millis": 3000,
        "url-path": "/"
      },
      "ip-version": "IPV4",
      "is-preserve-source": false,
      "name": "PrivTCP_NLB1BESet",
      "policy": "TWO_TUPLE"
      }
    ]
  }
}

Editing a Network Load Balancer Backend Set

You can change network load balancer (NLB) backend set properties, such as the health checker parameters used.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the network load balancer (NLB) for which you want to edit the backend set information.
  3. Under Resources, click Backend Sets.

  4. Select the name of the NLB backend set that you want to edit.

  5. In the Actions list, click Edit to open the Edit Network Load Balancer Backend Set window.

  6. Make allowable changes in the pop-up window.

  7. Click Update Network Load Balancer Backend Set to update the NLB Backend Set properties.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the update command, which returns a work request ID.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb backend-set update --health-checker health-checker-parameters \
  --name backend-set-name --network-load-balancer-id network-load-balancer_OCID \  
   --policy network-load-balancer-policy

    Where:

    • health-checker-parameters is the set of parameters associated with the health checker for this backend set.
    • Protocol: Enter the protocol: TCP. Configure your health check protocol to match your application or service. When using TCP as the protocol, you can optionally provide the request data and the response data.
    • Port: Specify the backend server port against which to run the health check. You can enter the value '0' to have the health check use the backend server's traffic port.
    • Internal in MS: Specify how frequently to run the health check in milliseconds. The default value is 10000 (10 seconds).
    • Timeout in MS: Specify the maximum time in milliseconds to wait for a reply to a health check. A health check is successful only if a reply returns within this timeout period. The default is 3000 (3 seconds).
    • Number of Retries: Specify the number of retries to attempt before a backend server is considered "unhealthy." This number also applies when recovering a server to the "healthy" state. The default is 3.
    • Status Code: Specify the status code a healthy backend server must return.
    • URL Path (URI): Specify a URL endpoint against which to run the health check.
    • Response Body Regex: Provide a regular expression for parsing the response body from the backend server.

    • backend-set-name is the name specific to the backend set.

    • network-load-balancer_OCID is the OCID of the NLB.

    • network-load-balancer-policy is the policy associated with the load balancer.

    Example (change policy to TWO_TUPLE):

    $ oci nlb backend-set update --health-checker '{"intervalInMillis":10000,"port": 22, \ 
  "protocol": "TCP", "retries":3, "timeoutInMillis": 3000}' --backend-set-name PrivTCP_BackEndSet_1 \
  --network-load-balancer-id $Priv_NLB1 --policy "TWO_TUPLE"
WARNING: Updates to backends and health-checker and ssl-configuration and session-persistence-
  configuration and lb-cookie-session-persistence-configuration will replace any existing values. 
  Are you sure you want to continue? [y/N]: y

{
  "opc-work-request-id": "ocid1.workrequest.xxx.networkloadbalancer......unique_ID"
}

    Note:

    The command returns a work request ID. To see the backend set results, you must list backend sets associated with the specified NLB and verify that the backend set parameters are changed. Use the oci nlb backend-set list command to view the backend set details. 
    oci nlb backend-set list --network-load-balancer-id ocid1.networkloadbalancer..….….uniqueID  

{
  "data": {
    "items": [
    {
      "backends": [],
      "health-checker": {
        "interval-in-millis": 10000,
        "port": 22,
        "protocol": "TCP",
        "request-data": "123",
        "response-body-regex": ".*",
        "response-data": "123",
        "retries": 3,
        "return-code": 200,
        "timeout-in-millis": 3000,
        "url-path": "/"
      },
      "ip-version": "IPV4",
      "is-preserve-source": false,
      "name": "PrivTCP_BackEndSet_1",
      "policy": "TWO_TUPLE"
      }
    ]
  }
}

Deleting a Network Load Balancer Backend Set

You can delete a network load balancer (NLB) Backend Set and remove it from service.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the network load balancer (NLB) for which you want to delete the backend set.
  3. Under Resources, click Backend Sets.

  4. Select the name of the NLB backend set you want to delete.

  5. Under the Actions column, click the three-dots pull-down menu, and select Delete.

  6. Confirm the operation when prompted.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the delete command, which returns a work request ID.

    Syntax (entered on a single line):

    $ oci nlb backend-set delete --backend-set-name HTTP_BckEndSet \ 
  --network-load-balancer-id ocid1.networkloadbalancer....….….….uniqueID 
Are you sure you want to delete this resource? [y/N]: y
{
  "opc-work-request-id": "ocid1.workrequest.xxx.networkloadbalancer-...….….….uniqueID"
}

    Note:

    To delete the LB backend set without verification, run the command with the --force option.

Network Load Balancer Backend Servers

This section describes how to manage backend servers for use with a network load balancer.

Creating a Network Load Balancer Backend

You must create backend servers (compute instances) for an existing network load balancer. The backend is one of a group of servers in a backend set to which network traffic is load balanced. You can create backends after you create the backend set, or at the same time. This topic creates only the backend.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the Network Load Balancer for which you want to create the network load balancer backend.

  3. Click Backendset under Resources.
  4. Any existing backends are listed, otherwise the list says No data available. To create a backend server, click on the hyperlink of the BackendSet to add the backend.
  5. Click Create Backend.
  6. Select the way you are adding backends. Possible values are:
    • Computed Instances Backends are added by instance.
    • IP Addresses Backends are added by IP address.

  7. For Computed Instances:

    • Instance: Enter the name of the backend.

    • Port: Enter 22 (TCP).

    • Name: Leave blank to take the default (ipaddress:port#).
    • Weight: Enter a weight in the range 1 to 100.
    • Security Rules: Select the security rules of the backend. Possible values are:
      • Configure Manually You manually configure security rules for the backend.
      • Configure Automatically The system automatically configures security rules for the backend.

  8. For IP Addresses:

    • IP Address: Enter the IP address of the backend.

    • Port: Enter the port number.

    • Name: Enter the name of the backend.
    • Weight: Enter a weight in the range 1 to 100.

  9. Click the Submit button in the dialog. To display the details of the new backend, view the backend.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb load-balancer list --compartment-id compartment_OCID)

  2. Run the backend create command.

    Use the NLB OCID and backend set name to create the backend set for the LB in the specified compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb backend create --backend-set-name [backend-set-name] --ip-address [text]\ 
  --network-load-balancer-id [network-load-balancer_OCID] \ 
  --port [port-number-integer]

    Where:

    • backend-set-name is the name specific to the backend set where the backend is to be added.

    • ip-address is the IP address for the backend to be added.

    • network-load-balancer_OCID is the OCID of the load balancer associated with the backend set and servers.

    • port-number-integer is the port number associated with the backend.

    Example:

    oci nlb backend create --backend-set-name PrivTCP_NLB1BESet \ 
  --ip-address 10.10.1.13 \
  --network-load-balancer-id ocid1.networkloadbalancer..….….uniqueID \ 
  --port 22

{
  "opc-work-request-id": "ocid1.workrequest.....….….….uniqueID "
}

    Note:

    The command returns a work request ID. To see the backend set results, you must list backends associated with the specified NLB and verify that the backend created is listed. Use the oci nlb backend list command to view the backend details. 
    oci nlb backend list --network-load-balancer-id ocid1.networkloadbalancer.....….….….uniqueID  

{
  "data": {
    "items": [
    {
      "ip-address": "10.10.1.13",
      "is-backup": false,
      "is-drain": false,
      "is-offline": false,
      "name": "10.10.1.13:22",
      "port": 22,
      "target-id": "ocid",
      "weight": 1
      },
      {
      "ip-address": "10.10.1.14",    
      "is-backup": false,
      "is-drain": false,
      "is-offline": false,
      "name": "10.10.1.14:22",
      "port": 22,
      "target-id": "ocid",
      "weight": 3
      },
    ]
  }
}

Viewing a Network Load Balancer Backend Details

You can view a list of the backends in an existing network load balancer backend set and view their details.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the network load balancer (NLB) to which you want to list existing backends.

  3. Under Resources, click the name of the existing Backend Set to view its details, such as IP address, port, and weight.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the list command.

    Use the NLB OCID and backend set name to list the backend details for the backend set.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb backend list --backend-set-name backend-set-name \
--load-balancer-id network-load-balancer_OCID

    Where:

    • backend-set-name is the name specific to the backend set where the backends are located.

    • network-load-balancer_OCID is the OCID of the load balancer associated with the backends.

    Example:

    $ oci nlb backend list --backend-set-name PrivLB1_BckEndSet  \
--load-balancer-id ocid1.loadbalancer....….….….uniqueID

{
  "data": {
    "items": [
    {
      "ip-address": "10.10.1.13",
      "is-backup": false,
      "is-drain": false,
      "is-offline": false,
      "name": "10.10.1.13:22",
      "port": 22,
      "target-id": "ocid",
      "weight": 1
    },
    {
      "ip-address": "10.10.1.14",
      "is-backup": false,
      "is-drain": false,
      "is-offline": false,
      "name": "10.10.1.14:22",
      "port": 22,
      "target-id": "ocid",
      "weight": 3
    },
    {
      "ip-address": "10.10.1.2",
      "is-backup": false,
      "is-drain": false,
      "is-offline": false,
      "name": "10.10.1.2:22",
      "port": 22,
      "target-id": "ocid",
      "weight": 1
    },
    {
      "ip-address": "10.10.1.3",
      "is-backup": false,
      "is-drain": false,
      "is-offline": false,
      "name": "10.10.1.3:22",
      "port": 22,
      "target-id": "ocid",
      "weight": 1
    }
    ]
  }
}

Editing a Network Load Balancer Backend

You can change some properties of a network load balancer (NLB) backend that's a member of a backend set.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the network load balancer for which you want to edit backend properties.
  3. Under Resources, click Backend Sets.
  4. Click the name of the Backend Set with the backend that you want to edit.

  5. Select the name of the NLB backend that you want to edit.

  6. In the Actions list, click Edit to open the Edit Network Load Balancer Backend window.

  7. Make allowable changes in the pop-up window.

  8. Click Update Network Load Balancer Backend to update the NLB backend properties.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the update command, which returns a work request ID.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb backend update --backend-name backend-name \ 
--backend-set-name backend-set-name \
--network-load-balancer-id networkloadbalancer_OCID [PARAMETERS TO CHANGE]

    Note:

    The is-drain, is-offline, and is-backup parameters are ignored, but must be set to false.

    Where:

    • backend-name is the name of the backend associated with the backend set being edited.

    • backend-set-name is the name of the backend set associated with the backend being edited.

    • networkloadbalancer_OCID is the OCID of the load balancer associated with the backend set and backend.

    Options:

    • max-wait-seconds The maximum time to wait for the work request to reach the state defined by wait-for-state. Defaults to 1200 seconds.

    • wait-for-state This operation asynchronously creates, modifies or deletes a resource and uses a work request to track the progress of the operation. Accepted values are: ACCEPTED, CANCELED, CANCELING, FAILED, IN_PROGRESS, SUCCEEDED.

    • wait-interval-seconds Check every --wait-interval-seconds to see whether the work request has reached the state defined by --wait-for-state. Defaults to 30 seconds.

    • weight The network load balancing policy weight assigned to the backend. Backend servers with a higher weight receive a larger proportion of incoming traffic.

    Example (change the backend weight to 3):

    $ oci nlb backend update --backend-name 10.0.0.3:8080 --backend-set-name example-backend-set \
  --network-load-balancer-id ocid1.networkloadbalancer....….….….uniqueID \
  --weight 3 

{ 
  "opc-work-request-id": "ocid1.workrequest.xxx....….….….uniqueID"
}

    Note:

    To see the backend update results, use the backend get command for that backend. 
    $ oci nlb backend get --backend-name 172.16.0.151:22 --backend-set-name example_backend_set \
--network-load-balancer-id ocid1.networkloadbalancer....….….….uniqueID 

{
  "data": {
    "ip-address": "172.16.0.151:222",
    "is-backup": false,
    "is-drain": false,
    "is-offline": false,
    "name": "172.16.0.151:222",
    "port": 22,
    "target-id": "ocid",
    "weight": 3
  },
}

Deleting a Network Load Balancer Backend

You can delete a network load balancer (NLB) Backend from a Backend Set and remove it from service.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the network load balancer for which you want to delete the backend server.
  3. Under Resources, click Backend Sets.
  4. Click the name of the Backend Set that contains the backend you want to delete in order to view the backend set details.

  5. Select the name of the backend you want to delete.

  6. Under the Actions column, click the three-dots pull-down menu, and select Delete.

  7. Confirm the operation when prompted.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the nlb backend delete command.

    Syntax (entered on a single line):

    $ oci nlb backend delete --backend-name backend-name --backend-set-name backend-set-name \
--network-load-balancer-id network-load-balancer_OCID

    Note:

    To delete the NLB backend server without verification, run the command with the --force option.

    Where:

    • backend-name is the name of the backend associated with the backend set.

    • backend-set-name is the name of the backend set associated with the backend being deleted.

    • network-load-balancer_OCID is the OCID of the network load balancer associated with the backend set and backend.

    Example:

    $ oci nlb backend delete --backend-name 172.16.0.154:80 --backend-set-name PubLB1_BckEndSet \
--network-load-balancer-id ocid1.networkloadbalancer....….….….uniqueID
Are you sure you want to delete this resource? [y/N]: y

Network Load Balancer Listeners

This section describes how to use listeners to check for incoming traffic on the network load balancer's IP address.

Creating a Network Load Balancer Listener

A listener waits for traffic to arrive for an IP address and distributes the traffic to the backend set servers of the NLB. Configure at least one listener for each traffic type. Ensure that your VCN's security rules allow the listener to accept traffic.

Using the Compute Web UI

  1. On the Navigation menu. select Networking, and select Network Load Balancers.

  2. In the list, select the name of the Network Load Balancer for which you want to create the listener.

  3. On the network load balancer's details page, scroll to the Resources section, and select Listeners.

  4. On the Listeners list, select the Create Listener button.

  5. Enter the following information:

    • Name: Enter a descriptive name for the Listener.

    • Protocol: Select TCP from the drop-down list.

    • Port: Enter the port you want to use. For TCP, the default port value 22 is preselected. Use the up or down arrows to change the port value, or enter a value between 1 and 65,535.

    • Backend Set: Select the backend set for the listener from the pull-down list. If the value is None Available, then you haven't yet created any NLB backend sets and must do so before this parameter can be configured.

    • IP Version: The default IP Version 4 is preselected.

  6. Click the Create Listener button in the dialog. To display the details of the listener, you must view the details for the network load balancer.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list)

    • NLB OCID (oci nlb network-load-balancer list)

    • NLB accepted protocol list (oci nlb protocol list)

  2. Run the create listener command.

    Syntax:

    oci nlb listener create --default-backend-set-name backend-set-name \
--network-load-balancer-id network-load-balancer_OCID \  
--name listener-name --port listener-port \
--protocol listener-protocol

    Where:

    • backend-set-name is the name of the associated backend set.

    • network-load-balancer_OCID is the OCID of the load balancer on which to add a listener.

    • listener-name is a user-friendly name for the listener. It must be unique and it cannot be changed.

    • listener-port is the communication port integer for the listener.

    • listener-protocol is the protocol on which the listener accepts connection requests.

    For information about optional parameters, use oci nlb listener create -h.

    Example:

    $ oci nlb listener create --default-backend-set-name PublicNLB1-Backend-Set \
--network-load-balancer-id ocid1.networkloadbalancer.uniqueID \  
--name LB1-Listener --port 22 --protocol TCP  

{
 "opc-work-request-id": "ocid1.workrequest.oc1.pca.networkloadbalancer.uniqueID"
}

    To view the listener details, use oci nlb load-balancer get: 

    $ oci nlb listener get --listener-name PrivNLB_TCPListener \
--network-load-balancer-id ocid1.networkloadbalancer.uniqueID
{
  "data": {
    "default-backend-set-name": "PrivNLB_TCPListen",
    "ip-version": "IPV4",
    "name": "PrivNLB_TCPListener",
    "port": 22,
    "protocol": "TCP"
  },
}

Editing a Network Load Balancer Listener

You can change some network load balancer (NLB) listener properties.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click on the Network Load Balancer for which you want to view listeners.
  3. Under Resources, click Listeners.

  4. Select the name of the NLB listener that you want to edit.

  5. In the Actions list, click Edit to open the Edit Network Load Balancer Listener window.

  6. Make allowable changes to the listener in the pop-up window.

  7. Click Update Network Load Balancer Listener to update the NLB Listener properties.

Using the OCI CLI

  1. Get the NLB OCID (oci nlb network-load-balancer list)

  2. Run the update listener command.

    Syntax:

    oci nlb listener update --default-backend-set-name default-backendset-name \ 
--listener-name listener-name --network-load-balancer-id networkloadbalancer_OCID\
--port port-integer --protocol protocol-text

    Where:

    • default-backendset-name is the name of the associated backend set.

    • listener-name is the name of the listener to update. Example: example_listener

    • networkloadbalancer_OCID is the OCID of the load balancer associated with the listener to update

    • port-integer is the communication port for the listener. Example: 22.

    • protocol-text is the protocol on which the listener accepts connection requests. Example: TCP

    Example (change listener port to 222):

    $ oci nlb listener update --default-backend-set-name PublicLB1-Backend-Set \ 
  --listener-name NLB1_Listener --network-load-balancer-id \ 
  ocid1.networkloadbalancer.unique_ID \
  --port 222 --protocol TCP

{
  "opc-work-request-id": "ocid1.workrequest.unique_ID"
}

    To view the listener details, use oci nlb listener get: 

    $ oci nlb listener get --listener-name NLB1_Listener \
--network-load-balancer-id  --network-load-balancer-id ocid1.networkloadbalancer.unique_ID
{
  "data": {
    "default-backend-set-name": "PrivNLB_TCPListen",
    "ip-version": "IPV4",
    "name": "PrivNLB_TCPListener",
    "port": 22,
    "protocol": "TCP"
  },
}

Deleting a Network Load Balancer Listener

You can delete a network load balancer (NLB) Listener and remove it from service.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the network load balancer (NLB) or which you want to list existing listeners.
  3. Under Resources, click Listeners.

  4. Select the name of the NLB listener you want to delete.

  5. Under the Actions column, click the three-dots pull-down menu, and select Delete.

  6. Confirm the operation when prompted.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the delete command.

    Syntax (entered on a single line):

    $ oci nlb listener delete --listener-name listener-name-text \
  --network-load-balancer-id ocid1.networkloadbalancer....….….….uniqueID 
Are you sure you want to delete this resource? [y/N]: y

    Note:

    To delete the NLB listener without verification, run the command with the --force option.

Network Load Balancer Health Checks

A network load balancer (NLB) backend set health check is a test to confirm the availability of NLB backend servers. A health check can be a request or a connection attempt. The NLB applies the health check policy, based on a configured time interval, to monitor the backend server set. If a server fails the health check, then the NLB takes the server temporarily out of the balancing rotation. If the server later passes a subsequent health check, then the NLB returns the backend server to the balancing rotation.

The health status of the specified backend set server is reported by the primary and standby network load balancers.

You can perform the following network load balancer (NLB) health checks:

For general information about NLB, see the Oracle Private Cloud Appliance Concepts Guide.

Viewing Health Checker Status for All Network Load Balancers

You can view network load balancer (NLB) backend set health status indicators to report on the general health of your network load balancers and their resources.

The NLB provides health status indicators that use your health check policies to report on the general health of your NLBs and their components. You can see health status indicators and summaries in the NLBs, backend sets, and backend servers.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the NLB for which you want to view health checker status.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

  2. Run the network-load-balancer list command, which lists the status of all NLBs in the compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb network-load-balancer-health list --compartment-id compartment_OCID \
[OPTIONS]

    Where [OPTIONS] are:

    • --all Fetches all pages of results. If you provide this option, then you cannot provide the --limit option.
    • --from-json [text] Provide input to this command as a JSON document from a file using the file://path-to/file syntax.
    • --limit [integer] For list pagination. The maximum number of results per page or items to return, in a paginated “List” call.
    • --page [text] The page token representing the page from which to start retrieving results.
    • --page-size [integer] When fetching results, the number of results to fetch per call. Only valid when used with --all or --limit, and ignored otherwise.
    • --sort-by [text] The field to sort by. Only one sort order can be provided. The default order for timeCreated is descending. The default order for displayName is ascending. If no value is specified, then timeCreated is the default. Accepted values are: displayName, timeCreated.
    • --sort-order [text] The sort order to use, either ‘asc’ (ascending) or ‘desc’ (descending). Accepted values are: ASC, DESC.

    Examples:

    $ oci nlb network-load-balancer-health list --compartment-id ocid1.tenancy....….….….uniqueID

{
  "data": {
    "items": [
    {
      "network-load-balancer-id": "ocid1.networkloadbalancer....….….….uniqueID2",
      "status": "UNKNOWN"
    },
    {
      "network-load-balancer-id": "ocid1.networkloadbalancer....….….….uniqueID1",
      "status": "OK"
    }
    ]
  }
}
    $ oci nlb network-load-balancer-health list --compartment-id ocid1.tenancy....….….….uniqueID \
    --sort-order ASC

{
  "data": {
    "items": [
    {
      "network-load-balancer-id": "ocid1.networkloadbalancer....….….….uniqueID1",
      "status": "OK"
    },
    {
      "network-load-balancer-id": "ocid1.networkloadbalancer....….….….uniqueID2",
      "status": "UNKNOWN"
    }
    ]
  }
}

Viewing a Network Load Balancer Health Checker Status

You can view the status (OK, warning, critical, unknown) of the health of the backend servers in an existing network load balancer (NLB).

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the NLB for which you want to view existing load balancer backend set health parameters.

  3. Under Resources, click Backend Sets.

  4. Click the name of the Backend Set to view its health check details, such as OK or Critical, among others.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the network-load-balancer-health get command.

    Use the NLB OCID to list the details for the NLB in the specified compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    $ oci nlb network-load-balancer-health get --network-load-balancer-id \
  network-load-balancer_OCID

    Where:

    • network-load-balancer_OCID is the OCID of the network load balancer associated with the backend set.

    Example:

    $ oci nlb network-load-balancer-health get --network-load-balancer-id \
  ocid1.networkloadbalancer....….….….uniqueID

{
 "data": {
 "critical-state-backend-names": [],
 "status": "OK",
 "total-backend-count": 2,
 "unknown-state-backend-names": [],
 "warning-state-backend-names": []
 }
}

Viewing Network Load Balancer Health Checker Policy

You can view the health checker policy parameters used by a network load balancer (NLB) to check backend set health.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the NLB for which you want to view heath check policy.

  3. Under Resources, click Backend Sets.

  4. To view the health check parameters of a backend set, you can:

    1. Click View Details under the Actions column (three dots) pull down menu.
    2. Click the backend set to view its details.

  5. Click Backend Set Configuration on the Backend-Set Details page under the backend-set name for which to you want to view the health check policy.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the health-checker get command and view the health-checker parameters.

    Use the NLB OCID to list the details for the backend set health checker policy in the specified compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb health-checker get --backend-set-name backend-set-name-text \
 --network-load-balancer-id network-load-balancer_OCID

    Where:

    • backend-set-name is the name specific to the backend set.

    • network-load-balancer_OCID is the OCID of the load balancer associated with the backend set.

    Example:

    $ oci nlb health-checker get --backend-set-name BckEndSet \
  --network-load-balancer-id ocid1.networkloadbalancer.. . .unique-id

{
  "data": {
    "health-checker": {
      "interval-in-millis": 10000,
      "port": 22,
      "protocol": "TCP",
      "request-data": null,
      "response-body-regex": ".*",
      "response-data": null,
      "retries": 3,
      "return-code": 200,
      "timeout-in-millis": 3000,
      "url-path": "/"
      },
  },
}

Editing Network Load Balancer Health Check Parameters

You can change network load balancer (NLB) backend server set health check properties, such as the health check interval.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the NLB for which you want to edit existing backend set health check parameters.

  3. Under Resources, click Backend Sets

  4. To edit the health check parameters of a backend set, you can:

    1. Click Edit under the Actions column (three dots) pull down menu.
    2. Click the backend set to view its details, then click Edit to make allowable changes.

  5. Click Save to save the changes.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the nlb health-checker update command.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb health-checker update --backend-set-name name-of-backend-set \
 --interval-in-millis integer-in-millis --max-wait-seconds wait-in-seconds \ 
 --network-load-balancer-id networkloadbalancer_OCID --port port-integer \
 --protocol protocol-text --response-body-regex expression-text \ 
 --retries retries-integer --return-code integer \ 
 --timeout-in-millis integer-in-millis --url-path text \
 --wait-for-state text --wait-interval-secondx integer

    Note:

    The update command returns a work request ID. To see the command results, use the NLB backend set get command.

    Where:

    • name-of-backend-set is the name of the backend set associated with the health check policy to be edited. Example: example_backend_set.
    • networkloadbalancer_OCID is the OCID of the network load balancer associated with the backend set health status to be edited.

    OPTIONS:

    --from-json [text] provides input to this command as a JSON document from a file using the file://path-to/file syntax.

    --if-match [text] optimistic concurrency control is desired, in the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource.

    --interval-in-millis [integer-in-millis] is the interval between health checks, in milliseconds. Example: 10000 (10 seconds).

    --max-wait-seconds [wait-in-seconds] is the maximum time to wait for the work request to reach the state defined by --wait-for-state. Defaults to 1200 seconds.

    --port [port-integer] is the backend server port against which to run the health check. Example: 22.

    --protocol [protocol-text] is the protocol the health check must use. Example: TCP.

    --response-body-regex [expression-text] is a regular expression for parsing the response body from the backend server. Example: ^((?!false).|\s)*$

    --retries [retries-integer] is the number of retries to attempt before a backend server is considered “unhealthy”. This number also applies when recovering a server to the “healthy” state. Example: 3

    --return-code [integer] is the status code a healthy backend server should return. Example: 200.

    --timeout-in-millis [integer-in-millis] is the maximum time in milliseconds to wait for a reply to a health check. A health check is successful only if a reply returns within this timeout period. Example:3000

    --url-path [text] is the path against which to run the health check. Example: /healthcheck

    --wait-for-state [text] asynchronously creates, modifies, or deletes a resource and uses a work request to track the progress of the operation. Specify this option to perform the action and then wait until the work request reaches a certain state. Accepted values are: ACCEPTED, CANCELED, CANCELING, FAILED, IN_PROGRESS, SUCCEEDED

    --wait-interval-seconds [integer] checks every --wait-interval-seconds to see whether the work request has reached the state defined by --wait-for-state. Defaults to 30 seconds.

    Example updating health-checker internal to 10000 milliseconds (10 seconds):

    $ oci nlb health-checker update --backend-set-name PrivTCP_BackEndSet \
  --interval-in-millis 10000 --load-balancer-id ocid1.loadbalancer....….….….uniqueID  

{
"opc-work-request-id": "ocid1.workrequest.....….….….uniqueID"
}

    $ oci nlb backend-set get --backend-set-name PrivTCP_BackEndSet \
  --network-load-balancer-id ocid1.loadbalancer.. . .unique-id

{
  "data": {
    "backends": [
    {
      "ip-address": "10.10.1.2",
      "is-backup": false,
      "is-drain": false,
      "is-offline": false,
      "name": "nlbserver1",
      "port": 22,
      "target-id": "ocid",
      "weight": 1
    },
    {
      "ip-address": "10.10.2.3",
      "is-backup": false,
      "is-drain": false,
      "is-offline": false,
      "name": "nlbserver4",
      "port": 22,
      "target-id": "ocid",
      "weight": 1
    },
    ],
    "health-checker": {
      "interval-in-millis": 10000,
      "port": 22,
      "protocol": "TCP",
      "request-data": null,
      "response-body-regex": ".*",
      "response-data": null,
      "retries": 3,
      "return-code": 200,
      "timeout-in-millis": 3000,
      "url-path": "/"
      },
    "ip-version": "IPV4",
    "is-preserve-source": false,
    "name": "PrivTCP_BackEndSet",
    "policy": "THREE_TUPLE"
  },
}

Viewing Health of a Network Load Balancer Backend Set

You can view backend set health status for a network load balancer (NLB).

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the NLB for which you want to view backend set health status.

  3. Under Resources, click Backend Sets

  4. Click the Backend Set to view the backend set health status for an NLB.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the backend-set-health get command.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb backend-set-health get --backend-set-name backend_set_name \
  --network-load-balancer-id network-load-balancer_OCID [OPTIONS]

    Where:

    • backend-set-name is the name specific to the backend set.

    • network-load-balancer_OCID is the OCID of the network load balancer associated with the backend set.

    Where [OPTIONS] are:

    • --from-json [text] Provide input to this command as a JSON document from a file using the file://path-to/file syntax.

    Example:

    $ oci nlb backend-set-health get --backend-set-name PubTCP_BackEndSet_1 \
    --network-load-balancer-id ocid1.networkloadbalancer.. . .unique-id

{
  "data": {
    "critical-state-backend-names": [],
    "status": "OK",
    "total-backend-count": 4,
    "unknown-state-backend-names": [],
    "warning-state-backend-names": []
  },
}

Viewing Health of a Network Load Balancer Backend Server

You can view backend server health status for backend in a network load balancer (NLB).

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the NLB for which you want to view backend set health status.

  3. Under Resources, click Backend Sets

  4. Click the Backend Set to view the backend health status for a backend in the NLB.

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

    • NLB OCID (oci nlb network-load-balancer list --compartment-id compartment_OCID)

  2. Run the backend-health get command.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb backend-health get --backend-name backend_name \
  --backend-set-name backend_set_name \
  --network-load-balancer-id network-load-balancer_OCID [OPTIONS]

    Where:

    • backend-name is the name specific to the backend, such as 10.10.1.13:22.

    • backend-set-name is the name specific to the backend set.

    • network-load-balancer_OCID is the OCID of the network load balancer associated with the backend set.

    Where [OPTIONS] are:

    • --from-json [text] Provide input to this command as a JSON document from a file using the file://path-to/file syntax.

    Example:

    $ oci nlb backend-health get --backend-name 10.10.1.13:22 \ 
    --backend-set-name PubTCP_BackEndSet_1 \
    --network-load-balancer-id ocid1.networkloadbalancer.. . .unique-id

{
  "data": {
    "health-check-results": [
    {
      "health-check-status": "OK",
      "timestamp": "2023-10-04T12:37:54.934773+00:00"
    },
    {
      "health-check-status": "OK",
      "timestamp": "2023-10-04T12:37:54.934777+00:00"
    }
    ],
  "status": "OK"
}

Viewing Network Load Balancer Work Request Errors

Many of the configuration steps used to create and configure network load balancer (NLB) operation do not take effect immediately. In these cases, the request initiates an asynchronous work flow known as a work request to carry out the operation.

Because of the asynchronous nature of work request fulfillment, it is not always obvious that a configuration step has failed with an error. The failed step is often not revealed until the next step, dependent on the success of the first, is attempted,

You can view NLB work request status indicators to find out if a work request has failed with an error. Using these methods, you can check the progress of each operation, whether or not it resulted in a failed state, which step it failed on, and the reason for the failure.

Using the Compute Web UI

  1. Open the Navigation Menu. Under Networking, click Network Load Balancers.

  2. Click the name of the NLB for which you want to view work request errors.

  3. In the Resources list, click on Work Requests.
  4. From the listing of work requests, for each work request you can view:
    • Type of work request
    • State of the work request (Succeeded, Failed, and so on)
    • Start and finish time stamp
  5. From the View Details page of each work request, you can view:
    • General information about the work request, such as type
    • OCID of the work request
    • Error detail of the work request failed (nothing is displayed for non-failure status)
    • Start and finish time stamp

Using the OCI CLI

  1. Gather the information you need to run the command:

    • Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)

  2. Run the nlb work-request list command, which lists the OCIDs for all work requests for all the NLBs in the compartment.

    Note:

    For information about optional parameters, run the command with the --help option.

    Syntax (entered on a single line):

    oci nlb work-request-errors list --work-request-id workrequest_OCID \
  --compartment-id tenancy _OCID [OPTIONS]

    Where [OPTIONS] are:

    • --all Fetches all pages of results. If you provide this option, then you cannot provide the --limit option.
    • --from-json [text] Provide input to this command as a JSON document from a file using the file://path-to/file syntax.
    • --limit [integer] For list pagination. The maximum number of results per page or items to return, in a paginated “List” call.
    • --page [text] The page token representing the page from which to start retrieving results.
    • --page-size [integer] When fetching results, the number of results to fetch per call. Only valid when used with --all or --limit, and ignored otherwise.

    Example: (Attempt to create an NLB with an invalid Subnet ID, see that the work request has failed, and display the error details):

    $ oci nlb network-load-balancer create --display-name Priv_NLB1  \
  --compartment-id ocid1.tenancy....….….….uniqueID --subnet-id ocid1.subnet....….….….uniqueID \
  --is-private true

{
  "data": {
    "backend-sets": {},
    "compartment-id": "ocid1.tenancy.1....….….….uniqueID",
    "defined-tags": {},
    "display-name": "Priv_NLB1",
    "freeform-tags": {},
    "id": "ocid1.networkloadbalancer.....….….….uniqueID",
    "ip-addresses": null,
    "is-preserve-source-destination": false,
    "is-private": true,
    "lifecycle-details": null,
    "lifecycle-state": "CREATING",
    "listeners": {},
    "network-security-group-ids": null,
    "nlb-ip-version": "IPV4",
    "subnet-id": "ocid1.subnet.....….….….uniqueID",
    "system-tags": null,
    "time-created": "2023-10-18T12:58:34.000001+00:00",
    "time-updated": null
    },
  "opc-work-request-id": "ocid1.workrequest.....….….….uniqueID"
}
    $ oci nlb work-request get --work-request-id ocid1.workrequest.....….….….uniqueID

{
  "data": {
    "compartment-id": "ocid1.tenancy.....….….….uniqueID",
    "id": "ocid1.workrequest.1.....….….….uniqueID",
    "operation-type": "CREATE_NETWORK_LOAD_BALANCER",
    "percent-complete": 100.0,
    "resources": [
    {
      "action-type": "CREATED",
      "entity-type": "NetworkLoadbalancer",
      "entity-uri": null,
      "identifier": "ocid1.networkloadbalancer.1.....….….….uniqueID"
    }
    ],
    "status": "FAILED",
    "time-accepted": "2023-10-18T12:58:34.701224+00:00",
    "time-finished": "2023-10-18T12:58:34.977166+00:00",
    "time-started": "2023-10-18T12:58:34.715807+00:00"
  }
}

    $ oci nlb work-request-error list --compartment-id ocid1.tenancy....….….….uniqueID \
  --work-request-id ocid1.workrequest....….….….uniqueID

{
  "data": {
    "items": [
    {
      "code": "INTERNAL_ERROR",
      "message": "Error occurred. Network response code: 404.Error Message: 
        'No Subnet was found'",
      "timestamp": "2023-10-18T12:58:34.948927+00:00"
    }
    ]
  }
}