Cloudflare Docs
Load Balancing
Cloudflare Docs
Load Balancing
GitHub icon
Visit Load Balancing on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Load Balancing
  3. Basic tasks
  4. Manage pools

Manage origin server pools

A pool is a group of origin servers, with each origin identified by its IP address or hostname.

If you are familiar with DNS terminology, think of a pool as a “record set,” except Cloudflare only returns addresses that are considered healthy. You can attach health monitors to individual pools for customized monitoring.


For more background information on pools, refer to Origin pools.

​​ Create a pool

You can create a pool within the load balancer workflow or in the Origin Pools section of the dashboard:

  1. Go to Traffic > Load Balancing.

  2. Select Manage Pools and then Create.

  3. For your pool, enter the following information:

    • A name (must be unique)
    • A description to provide more detail on the name
    • A choice for Origin Steering, which affects how your pool routes traffic to each origin

  4. For each origin, enter the following information:

    • A name (must be unique)
    • The origin server address or associated hostname
    • (Optional) A Virtual Network. Required when the origin has a private IP address.
    • A Weight
    • (Optional) A hostname by clicking Add host header

  5. Repeat this process for additional origins in the pool.

  6. (Optional) Set up coordinates for Proximity Steering on the pool.

  7. On the origin pool, update the following information:

    • Health Threshold: The Health Threshold is the number of healthy origins for the pool as a whole to be considered Healthy and receive traffic based on pool order in a load balancer. Increasing this number makes the pool more reliable, but also more likely to become unhealthy.
    • Monitor: Attach a monitor
    • Health Monitor Regions: Choose whether to check pool health from multiple locations, which increases accuracy but can lead to probe traffic to your origin
    • Pool Notifications: You can set up new alerts - and view existing alerts - to be notified when pools are enabled or disabled, or pools or origins have changes in their health status.

  8. When finished, select Save.

For a full list of properties, refer to Create Pool. If you need help with API authentication, refer to Cloudflare API documentation.

Request
curl -X POST \
-H "X-Auth-Email: user@cloudflare.com" \
-H "X-Auth-Key: REDACTED" \
"https://api.cloudflare.com/client/v4/accounts/:account_id/load-balancers/pools" \
-H "Content-Type: application/json" \
-d '{
    "description":"Primary data center - Provider XYZ",
    "name":"primary-dc-1",
    "enabled":false,
    "load_shedding": {
        "default_percent":0,
        "default_policy":"random",
        "session_percent":0,
        "session_policy":"hash"
    },
    "minimum_origins":2,
    "monitor":"f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
        "WEU",
        "ENAM"
    ],
    "origins": [
      {
        "name":"app-server-1",
        "address":"0.0.0.0",
        "enabled":true,
        "weight":0.56,
        "header": {
        "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_filter": {
        "origin": {
            "disable":false,
            "healthy":null
        },
        "pool": {
            "disable":false,
            "healthy":null
        }
    }

}'

The response contains the complete definition of the new pool.

Response
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "17b5962d775c646f3f9725cbc7a53df4",
    "created_on": "2021-01-01T05:20:00.12345Z",
    "modified_on": "2021-01-01T05:20:00.12345Z",
    "description": "Primary data center - Provider XYZ",
    "name": "primary-dc-1",
    "enabled": false,
    "load_shedding": {
      "default_percent": 0,
      "default_policy": "random",
      "session_percent": 0,
      "session_policy": "hash"
    },
    "minimum_origins": 2,
    "monitor": "f1aba936b94213e5b8dca0c0dbf1f9cc",
    "check_regions": [
      "WEU",
      "ENAM"
    ],
    "origins": [
      {
        "name": "app-server-1",
        "address": "0.0.0.0",
        "enabled": true,
        "weight": 0.56,
        "header": {
          "Host": [
            "example.com"
          ]
        }
      }
    ],
    "origin_steering": {
      "policy": "random"
    },
    "notification_filter": {
      "origin": {
        "disable": false,
        "healthy": null
      },
      "pool": {
        "disable": false,
        "healthy": null
      }
    }
  }

}

After creating the pool, you would also want to create a new notification with the following parameters specified:


"alert_type": "load_balancing_health_alert",

"filters": {
    "pool_id": <<ARRAY_OF_INCLUDED_POOL_IDS>>,
    "new_health": <<ARRAY_OF_STATUS_TRIGGERS>> ["Unhealthy", "Healthy"],
    "event_source": <<ARRAY_OF_OBJECTS_WATCHED>> ["pool", "origin"]

}

​​ Edit a pool

To edit a pool in the dashboard:

  1. Go to Traffic > Load Balancing.
  2. Click Manage Pools.
  3. On a specific pool, click Edit.
  4. Update settings as needed.
  5. Click Save.

When you edit a pool with the API, your request type depends on how much you want to edit.

To update specific settings without having to resubmit the entire configuration, use a PATCH request. For broader changes, use a PUT request.

​​ Delete a pool

To delete a pool in the dashboard:

  1. Go to Traffic > Load Balancing.
  2. Click Manage Pools.
  3. On a specific pool, click Delete.

To delete a pool using the API, send a DELETE request.