Technical Tip: Managing FortiWeb server pools through REST API in HA deployments

Description

This article describes how REST API configuration requests behave in an Active-Active High Volume HA deployment on FortiWeb and how to identify the correct unit for server pool management operations.

Scope

FortiWeb REST API.
FortiWeb HA deployments.

Solution

In a FortiWeb HA deployment, configuration changes can only be processed by the primary unit.

When REST API configuration requests are sent through a load balancer that distributes traffic across multiple HA members, intermittent failures may occur if requests are forwarded to a secondary unit.

This behavior may result in HTTP 500 responses during configuration operations such as server pool member maintenance updates. Example API operation:

curl -k \
--request PUT \
"https://<ip>:<port>/api/v2.0/cmdb/server-policy/server-pool/pserver-list?mkey=<pool>&sub_mkey=<member>" \
--header "Authorization: <token>" \
--header 'Accept: application/json' \
--data-raw "{'data':{'status':'disable'}}"

To ensure successful configuration changes, API requests must be directed only to the active primary unit. FortiWeb provides an HA status API endpoint which can be used to dynamically identify the active node:

curl -k \
--request GET \
"https://<ip>:<port>/api/v2.0/system/status.hastatus" \
--header "Authorization: <token>"

Example response from the primary unit:

{
  "results": {
    "cfg_sync_state": "In sync"
  }
}
Example response from the secondary unit:
{
  "results": {
    "cfg_sync_state": "Secondary"
  }
}

The unit reporting the following value is the active primary node: cfg_sync_state: "In sync".

The recommended automation workflow is:

1. Query all known HA management IP addresses using /api/v2.0/system/status.hastatus.

2. Identify the unit reporting cfg_sync_state as In sync.

3. Send all configuration-related REST API requests only to that unit.

Accounts used for this operation require sufficient permissions to query HA status information and perform server policy modifications. The following access profile permissions are sufficient:

1. System Configuration = Read Only.

2. Server Policy Configuration = Read-Write.

A 401 Unauthorized response may occur if the account or access profile has not yet been synchronized across HA members.

For additional information, refer to:
FortiWEB Monitor