Quickstart

Set up the monitor

You can create a monitor within the load balancer workflow or in the Monitors section of the dashboard:

1. Go to Traffic > Load Balancing.

2. Select Manage Monitors.

3. Select Create.

4. Add the following information:

   • Type: The protocol to use for health monitors
     • Non-enterprise customers: Choose HTTP, HTTPS, or TCP.
     • Enterprise customers: Choose HTTP, HTTPS, TCP, UDP ICMP, ICMP Ping, or SMTP.
   • Path: The endpoint path to run health monitor requests against
   • Port: The destination port for health monitors

5. For additional settings, select Advanced health monitor settings:

   • Interval:
     • By increasing the default, you can improve failover time, but you may also increase load on your endpoints.
     • Minimum time in seconds is 60 (Pro), 15 (Business), and 10 (Enterprise).
   • Timeout and Retries:
     • The health monitor request will return unhealthy if it exceeds the duration specified in Timeout (and exceeds this duration more times than the specified number of Retries).
   • Expected Code(s): The expected HTTP response codes listed individually (200, 302) or as a range (for example, entering 2xx would cover all response codes in the 200 range).
   • Response Body:
     • Looks for a case-insensitive substring in the response body.
     • Make sure that the value is relatively static and within the first 100 MB of the HTML page.
   • Simulate Zone:
     • Pushes a request from Cloudflare health monitors through the Cloudflare stack as if it were a real visitor request to help analyze behavior or validate a configuration using the zone specified.
     • It is recommended to use the same zone in which the Load Balancer exists.
     • Ensures health monitor requests are compatible with features like authenticated origin pulls and Argo Smart Routing.
   • Follow Redirects:
     • Instead of reporting a 301 or 302 code as unhealthy, the health monitor request follows redirects to the final endpoint.
   • Configure Request Header(s):
     • Useful if your endpoints are expecting specific incoming headers.
   • Header:
     • The HTTP request headers to send in the health monitor. It is recommended that you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors.

6. Select Save.

Prepare your servers

Make sure that your firewall or web server does not block or rate limit your configured health monitors or requests associated with Cloudflare IP addresses Open external link .

Each health monitor has the HTTP user-agent of "Mozilla/5.0 (compatible; Cloudflare-Traffic-Manager/1.0; +https://www.cloudflare.com/traffic-manager/; pool-id: $poolid)", where the $poolid is the first 16 characters of the associated pool.

Set up the monitor

For a full list of monitor properties, refer to Create Monitor Open API docs link . If you need help with API authentication, refer to Cloudflare API documentation.

Request
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/load_balancers/monitors" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "type": "https",
  "description": "Login page monitor",
  "method": "GET",
  "path": "/health",
  "header":  {
    "Host": ["example.com"],
    "X-App-ID": ["abc123"]
  },
  "port": 8080,
  "timeout": 3,
  "retries": 0,
  "interval": 90,
  "expected_body": "alive",
  "expected_codes": "2xx",
  "follow_redirects": true,
  "allow_insecure": true,
  "consecutive_up": 3,
  "consecutive_down": 2,
  "probe_zone": "example.com"
}'

The response contains the complete definition of the new monitor.

Response
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": ":monitor-id",
    "created_on": "2021-01-01T05:20:00.12345Z",
    "modified_on": "2021-01-01T05:20:00.12345Z",
    "type": "https",
    "description": "Login page monitor",
    "method": "GET",
    "path": "/health",
    "header": {
      "Host": [
        "example.com"
      ],
      "X-App-ID": [
        "abc123"
      ]
    },
    "port": 8080,
    "timeout": 3,
    "retries": 0,
    "interval": 90,
    "expected_body": "alive",
    "expected_codes": "2xx",
    "follow_redirects": true,
    "allow_insecure": true,
    "consecutive_up": 3,
    "consecutive_down": 2,
    "probe_zone": "example.com"
  }
}

Prepare your servers

Make sure that your firewall or web server does not block or rate limit your configured health monitors or requests associated with Cloudflare IP addresses Open external link .

Each health monitor has the HTTP user-agent of "Mozilla/5.0 (compatible; Cloudflare-Traffic-Manager/1.0; +https://www.cloudflare.com/traffic-manager/; pool-id: $poolid)", where the $poolid is the first 16 characters of the associated pool.

You can create a pool within the load balancer workflow or in the 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 Endpoint Steering, which affects how your pool routes traffic to each endpoint

4. For each endpoint, enter the following information:

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

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

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

7. On the pool, update the following information:

   • Health Threshold: The Health Threshold is the number of healthy endpoints 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 endpoint
   • Pool Notifications: You can set up new alerts - and view existing alerts - to be notified when pools are enabled or disabled, or pools or endpoints have changes in their health status.

8. When finished, select Save.

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

Request
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/load_balancers/pools" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "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 Open API docs link 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"]
}

To confirm pool health using the dashboard:

1. Go to Traffic > Load Balancing.
2. Select Manage Pools.
3. For pools and individual endpoints, review the values in the Health and Endpoint Health columns.

For more information on pool and endpoint health statuses, refer to How a pool becomes unhealthy.

To fetch the latest health status of all pools, use the List Pools Open API docs link command, paying attention to the healthy value for pools and origins (endpoints).

For troubleshooting a specific pool’s health, use the Pool Health Details Open API docs link command.

To create a load balancer in the dashboard:

1. Go to Traffic > Load Balancing.

2. Select Create Load Balancer.

3. On the Hostname page:

   • Enter a Hostname, which is the DNS name at which the load balancer is available. For more details on record priority, refer to DNS records for load balancing.
   • Toggle the orange cloud icon to update the proxy mode, which affects how traffic is routed and which IP addresses are advertised.
   • If you want session-based load balancing, toggle the Session Affinity switch.

4. Select Next.

5. On the Add a Pool page:

   • Select one or more existing pools or create a new pool.
   • If you are going to set traffic steering to Off, re-order the pools in your load balancer to adjust the fallback order.
   • If needed, update the Fallback Pool.
   • If you choose to set traffic steering to Random, you can set Weights (via the API) to your pools to determine the percentage of traffic sent to each pool.

6. Select Next.

7. On the Monitors page:

   • Review the monitors attached to your pools.
   • If needed, you can attach an existing monitor or create a new monitor.

8. Select Next.

9. On the Traffic Steering page, choose an option for Traffic steering and select Next.

10. On the Custom Rules page, select an existing rule or create a new rule.

11. Select Next.

12. On the Review page:

    • Review your configuration and make any changes.
    • Choose whether to Save as Draft or Save and Deploy.

For a full list of properties, refer to Create Load Balancer Open API docs link . If you need help with API authentication, refer to Cloudflare API documentation.

Request
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/load_balancers" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
  "description": "Load Balancer for lb.example.com",
  "name": "lb.example.com",
  "enabled": true,
  "ttl": 30,
  "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
  "default_pools": [
    "17b5962d775c646f3f9725cbc7a53df4",
    "9290f38c5d07c2e2f4df57b1f61d4196",
    "00920f38ce07c2e2f4df50b1f61d4194"
  ],
  "proxied": true,
  "steering_policy": "random_steering",
  "session_affinity": "cookie",
  "session_affinity_attributes": {
    "samesite": "Auto",
    "secure": "Auto",
    "drain_duration": 100,
    "zero_downtime_failover": "sticky"
  },
  "session_affinity_ttl": 5000,
  "adaptive_routing": {
    "failover_across_pools": true
  },
  "location_strategy": {
    "prefer_ecs": "always",
    "mode": "resolver_ip"
  },
  "random_steering": {
    "pool_weights": {
      "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
      "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
    },
    "default_weight": 0.2
  }
}'

The response contains the complete definition of the new load balancer.

Response
{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "id": "699d98642c564d2e855e9661899b7252",
    "created_on": "2021-01-01T05:20:00.12345Z",
    "modified_on": "2021-01-01T05:20:00.12345Z",
    "description": "Load Balancer for lb.example.com",
    "name": "lb.example.com",
    "enabled": true,
    "ttl": 30,
    "fallback_pool": "17b5962d775c646f3f9725cbc7a53df4",
    "default_pools": [
      "17b5962d775c646f3f9725cbc7a53df4",
      "9290f38c5d07c2e2f4df57b1f61d4196",
      "00920f38ce07c2e2f4df50b1f61d4194"
    ],
    "proxied": true,
    "steering_policy": "random_steering",
    "session_affinity": "cookie",
    "session_affinity_attributes": {
      "samesite": "Auto",
      "secure": "Auto",
      "drain_duration": 100,
      "zero_downtime_failover": "sticky"
    },
    "session_affinity_ttl": 5000,
    "random_steering": {
      "pool_weights": {
        "de90f38ced07c2e2f4df50b1f61d4194": 0.3,
        "9290f38c5d07c2e2f4df57b1f61d4196": 0.5
      },
      "default_weight": 0.2
    }
  }
}