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

Open the Navigation Menu. Under Networking, click Network Load Balancers.
Click the name of the NLB for which you want to view health checker status.

Using the OCI CLI

Gather the information you need to run the command:
- Compartment OCID (oci iam compartment list --compartment-id-in-subtree true)
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

Open the Navigation Menu. Under Networking, click Network Load Balancers.
Click the name of the NLB for which you want to view existing load balancer backend set health parameters.
Under Resources, click Backend Sets.
Click the name of the Backend Set to view its health check details, such as OK or Critical, among others.

Using the OCI CLI

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)

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

Open the Navigation Menu. Under Networking, click Network Load Balancers.
Click the name of the NLB for which you want to view heath check policy.
Under Resources, click Backend Sets.
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.
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

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)

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

Open the Navigation Menu. Under Networking, click Network Load Balancers.
Click the name of the NLB for which you want to edit existing backend set health check parameters.
Under Resources, click Backend Sets
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.
Click Save to save the changes.

Using the OCI CLI

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)
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

Open the Navigation Menu. Under Networking, click Network Load Balancers.
Click the name of the NLB for which you want to view backend set health status.
Under Resources, click Backend Sets
Click the Backend Set to view the backend set health status for an NLB.

Using the OCI CLI

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)
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

Open the Navigation Menu. Under Networking, click Network Load Balancers.
Click the name of the NLB for which you want to view backend set health status.
Under Resources, click Backend Sets
Click the Backend Set to view the backend health status for a backend in the NLB.

Using the OCI CLI

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)

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"
}