pools

Creates, updates, deletes, gets or lists a pools resource.

Overview

Name	pools
Type	Resource
Id	cloudflare.load_balancers.pools

Fields

The following fields are returned by SELECT queries:

get_by_account

Pool Details response.

Name	Datatype	Description
id	string	(example: 17b5962d775c646f3f9725cbc7a53df4)
name	string	A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. (example: primary-dc-1)
check_regions	array	A list of regions from which to run health checks. Null means every Cloudflare data center.
created_on	string	(example: 2014-01-01T05:20:00.12345Z)
description	string	A human-readable description of the pool. (default: , example: Primary data center - Provider XYZ)
disabled_at	string (date-time)	This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.
enabled	boolean	Whether to enable (the default) or disable this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any).
latitude	number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
load_shedding	object	Configures load shedding policies and percentages for the pool. (x-stainless-terraform-configurability: computed_optional)
longitude	number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
minimum_origins	integer	The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and will failover to the next available pool.
modified_on	string	(example: 2014-01-01T05:20:00.12345Z)
monitor	string	The ID of the Monitor to use for checking the health of origins within this pool.
monitor_group	string	The ID of the Monitor Group to use for checking the health of origins within this pool.
networks	array	List of networks where Load Balancer or Pool is enabled.
notification_email	string	This field is now deprecated. It has been moved to Cloudflare's Centralized Notification service https://developers.cloudflare.com/fundamentals/notifications/. The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. (default: , example: someone@example.com,sometwo@example.com)
notification_filter	object	Filter pool and origin health notifications by resource type or health status. Use null to reset. (x-stainless-terraform-configurability: computed_optional)
origin_steering	object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. (x-stainless-terraform-configurability: computed_optional)
origins	array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. (x-stainless-collection-type: set)

list_by_account

List Pools response.

Name	Datatype	Description
id	string	(example: 17b5962d775c646f3f9725cbc7a53df4)
name	string	A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. (example: primary-dc-1)
check_regions	array	A list of regions from which to run health checks. Null means every Cloudflare data center.
created_on	string	(example: 2014-01-01T05:20:00.12345Z)
description	string	A human-readable description of the pool. (default: , example: Primary data center - Provider XYZ)
disabled_at	string (date-time)	This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.
enabled	boolean	Whether to enable (the default) or disable this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any).
latitude	number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
load_shedding	object	Configures load shedding policies and percentages for the pool. (x-stainless-terraform-configurability: computed_optional)
longitude	number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
minimum_origins	integer	The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and will failover to the next available pool.
modified_on	string	(example: 2014-01-01T05:20:00.12345Z)
monitor	string	The ID of the Monitor to use for checking the health of origins within this pool.
monitor_group	string	The ID of the Monitor Group to use for checking the health of origins within this pool.
networks	array	List of networks where Load Balancer or Pool is enabled.
notification_email	string	This field is now deprecated. It has been moved to Cloudflare's Centralized Notification service https://developers.cloudflare.com/fundamentals/notifications/. The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. (default: , example: someone@example.com,sometwo@example.com)
notification_filter	object	Filter pool and origin health notifications by resource type or health status. Use null to reset. (x-stainless-terraform-configurability: computed_optional)
origin_steering	object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. (x-stainless-terraform-configurability: computed_optional)
origins	array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. (x-stainless-collection-type: set)

get_by_user

Pool Details response.

Name	Datatype	Description
id	string	(example: 17b5962d775c646f3f9725cbc7a53df4)
name	string	A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. (example: primary-dc-1)
check_regions	array	A list of regions from which to run health checks. Null means every Cloudflare data center.
created_on	string	(example: 2014-01-01T05:20:00.12345Z)
description	string	A human-readable description of the pool. (default: , example: Primary data center - Provider XYZ)
disabled_at	string (date-time)	This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.
enabled	boolean	Whether to enable (the default) or disable this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any).
latitude	number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
load_shedding	object	Configures load shedding policies and percentages for the pool. (x-stainless-terraform-configurability: computed_optional)
longitude	number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
minimum_origins	integer	The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and will failover to the next available pool.
modified_on	string	(example: 2014-01-01T05:20:00.12345Z)
monitor	string	The ID of the Monitor to use for checking the health of origins within this pool.
monitor_group	string	The ID of the Monitor Group to use for checking the health of origins within this pool.
networks	array	List of networks where Load Balancer or Pool is enabled.
notification_email	string	This field is now deprecated. It has been moved to Cloudflare's Centralized Notification service https://developers.cloudflare.com/fundamentals/notifications/. The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. (default: , example: someone@example.com,sometwo@example.com)
notification_filter	object	Filter pool and origin health notifications by resource type or health status. Use null to reset. (x-stainless-terraform-configurability: computed_optional)
origin_steering	object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. (x-stainless-terraform-configurability: computed_optional)
origins	array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. (x-stainless-collection-type: set)

list_by_user

List Pools response.

Name	Datatype	Description
id	string	(example: 17b5962d775c646f3f9725cbc7a53df4)
name	string	A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. (example: primary-dc-1)
check_regions	array	A list of regions from which to run health checks. Null means every Cloudflare data center.
created_on	string	(example: 2014-01-01T05:20:00.12345Z)
description	string	A human-readable description of the pool. (default: , example: Primary data center - Provider XYZ)
disabled_at	string (date-time)	This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at.
enabled	boolean	Whether to enable (the default) or disable this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any).
latitude	number	The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
load_shedding	object	Configures load shedding policies and percentages for the pool. (x-stainless-terraform-configurability: computed_optional)
longitude	number	The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
minimum_origins	integer	The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and will failover to the next available pool.
modified_on	string	(example: 2014-01-01T05:20:00.12345Z)
monitor	string	The ID of the Monitor to use for checking the health of origins within this pool.
monitor_group	string	The ID of the Monitor Group to use for checking the health of origins within this pool.
networks	array	List of networks where Load Balancer or Pool is enabled.
notification_email	string	This field is now deprecated. It has been moved to Cloudflare's Centralized Notification service https://developers.cloudflare.com/fundamentals/notifications/. The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list. (default: , example: someone@example.com,sometwo@example.com)
notification_filter	object	Filter pool and origin health notifications by resource type or health status. Use null to reset. (x-stainless-terraform-configurability: computed_optional)
origin_steering	object	Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. (x-stainless-terraform-configurability: computed_optional)
origins	array	The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy. (x-stainless-collection-type: set)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_by_account	select	pool_id, account_id		Fetch a single configured pool.
list_by_account	select	account_id	monitor	List configured pools.
get_by_user	select	pool_id		Fetch a single configured pool.
list_by_user	select		monitor	List configured pools.
create	insert	account_id, origins, name		Create a new pool.
load_balancer_pools_create_pool	insert	origins, name		Create a new pool.
edit	update	pool_id, account_id		Apply changes to an existing pool, overwriting the supplied properties.
account_load_balancer_pools_patch_pools	update	account_id		Apply changes to a number of existing pools, overwriting the supplied properties. Pools are ordered by ascending name. Returns the list of affected pools. Supports the standard pagination query parameters, either limit/offset or per_page/page.
load_balancer_pools_patch_pool	update	pool_id		Apply changes to an existing pool, overwriting the supplied properties.
load_balancer_pools_patch_pools	update			Apply changes to a number of existing pools, overwriting the supplied properties. Pools are ordered by ascending name. Returns the list of affected pools. Supports the standard pagination query parameters, either limit/offset or per_page/page.
update	replace	pool_id, account_id, origins, name		Modify a configured pool.
load_balancer_pools_update_pool	replace	pool_id, origins, name		Modify a configured pool.
delete	delete	pool_id, account_id		Delete a configured pool.
load_balancer_pools_delete_pool	delete	pool_id		Delete a configured pool.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_id	string	The Cloudflare account ID.
pool_id	string	The Load Balancer pool ID.
monitor	string

SELECT examples

get_by_account

Fetch a single configured pool.

SELECT
id,
name,
check_regions,
created_on,
description,
disabled_at,
enabled,
latitude,
load_shedding,
longitude,
minimum_origins,
modified_on,
monitor,
monitor_group,
networks,
notification_email,
notification_filter,
origin_steering,
origins
FROM cloudflare.load_balancers.pools
WHERE pool_id = '{{ pool_id }}' -- required
AND account_id = '{{ account_id }}' -- required
;

list_by_account

List configured pools.

SELECT
id,
name,
check_regions,
created_on,
description,
disabled_at,
enabled,
latitude,
load_shedding,
longitude,
minimum_origins,
modified_on,
monitor,
monitor_group,
networks,
notification_email,
notification_filter,
origin_steering,
origins
FROM cloudflare.load_balancers.pools
WHERE account_id = '{{ account_id }}' -- required
AND monitor = '{{ monitor }}'
;

get_by_user

Fetch a single configured pool.

SELECT
id,
name,
check_regions,
created_on,
description,
disabled_at,
enabled,
latitude,
load_shedding,
longitude,
minimum_origins,
modified_on,
monitor,
monitor_group,
networks,
notification_email,
notification_filter,
origin_steering,
origins
FROM cloudflare.load_balancers.pools
WHERE pool_id = '{{ pool_id }}' -- required
;

list_by_user

List configured pools.

SELECT
id,
name,
check_regions,
created_on,
description,
disabled_at,
enabled,
latitude,
load_shedding,
longitude,
minimum_origins,
modified_on,
monitor,
monitor_group,
networks,
notification_email,
notification_filter,
origin_steering,
origins
FROM cloudflare.load_balancers.pools
WHERE monitor = '{{ monitor }}'
;

INSERT examples

create

Create a new pool.

INSERT INTO cloudflare.load_balancers.pools (
description,
enabled,
latitude,
load_shedding,
longitude,
minimum_origins,
monitor,
monitor_group,
name,
notification_email,
notification_filter,
origin_steering,
origins,
account_id
)
SELECT 
'{{ description }}',
{{ enabled }},
{{ latitude }},
'{{ load_shedding }}',
{{ longitude }},
{{ minimum_origins }},
'{{ monitor }}',
'{{ monitor_group }}',
'{{ name }}' /* required */,
'{{ notification_email }}',
'{{ notification_filter }}',
'{{ origin_steering }}',
'{{ origins }}' /* required */,
'{{ account_id }}'
RETURNING
errors,
messages,
result,
success
;

load_balancer_pools_create_pool

Create a new pool.

INSERT INTO cloudflare.load_balancers.pools (
check_regions,
description,
enabled,
latitude,
load_shedding,
longitude,
minimum_origins,
monitor,
monitor_group,
name,
networks,
notification_email,
notification_filter,
origin_steering,
origins
)
SELECT 
'{{ check_regions }}',
'{{ description }}',
{{ enabled }},
{{ latitude }},
'{{ load_shedding }}',
{{ longitude }},
{{ minimum_origins }},
'{{ monitor }}',
'{{ monitor_group }}',
'{{ name }}' /* required */,
'{{ networks }}',
'{{ notification_email }}',
'{{ notification_filter }}',
'{{ origin_steering }}',
'{{ origins }}' /* required */
RETURNING
errors,
messages,
result,
success
;

Manifest

# Description fields are for documentation purposes
- name: pools
props:
  - name: account_id
    value: "{{ account_id }}"
    description: Required parameter for the pools resource.
  - name: description
    value: "{{ description }}"
    description: |
      A human-readable description of the pool.
    default: 
  - name: enabled
    value: {{ enabled }}
    description: |
      Whether to enable (the default) or disable this pool. Disabled pools will not receive traffic and are excluded from health checks. Disabling a pool will cause any load balancers using it to failover to the next pool (if any).
    default: true
  - name: latitude
    value: {{ latitude }}
    description: |
      The latitude of the data center containing the origins used in this pool in decimal degrees. If this is set, longitude must also be set.
  - name: load_shedding
    description: |
      Configures load shedding policies and percentages for the pool.
    value:
      default_percent: {{ default_percent }}
      default_policy: "{{ default_policy }}"
      session_percent: {{ session_percent }}
      session_policy: "{{ session_policy }}"
  - name: longitude
    value: {{ longitude }}
    description: |
      The longitude of the data center containing the origins used in this pool in decimal degrees. If this is set, latitude must also be set.
  - name: minimum_origins
    value: {{ minimum_origins }}
    description: |
      The minimum number of origins that must be healthy for this pool to serve traffic. If the number of healthy origins falls below this number, the pool will be marked unhealthy and will failover to the next available pool.
    default: 1
  - name: monitor
    value: "{{ monitor }}"
    description: |
      The ID of the Monitor to use for checking the health of origins within this pool.
  - name: monitor_group
    value: "{{ monitor_group }}"
    description: |
      The ID of the Monitor Group to use for checking the health of origins within this pool.
  - name: name
    value: "{{ name }}"
    description: |
      A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed.
  - name: notification_email
    value: "{{ notification_email }}"
    description: |
      This field is now deprecated. It has been moved to Cloudflare's Centralized Notification service https://developers.cloudflare.com/fundamentals/notifications/. The email address to send health status notifications to. This can be an individual mailbox or a mailing list. Multiple emails can be supplied as a comma delimited list.
    default: 
  - name: notification_filter
    description: |
      Filter pool and origin health notifications by resource type or health status. Use null to reset.
    value:
      origin:
        disable: {{ disable }}
        healthy: {{ healthy }}
      pool:
        disable: {{ disable }}
        healthy: {{ healthy }}
  - name: origin_steering
    description: |
      Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity.
    value:
      policy: "{{ policy }}"
  - name: origins
    description: |
      The list of origins within this pool. Traffic directed at this pool is balanced across all currently healthy origins, provided the pool itself is healthy.
    value:
      - address: "{{ address }}"
        disabled_at: "{{ disabled_at }}"
        enabled: {{ enabled }}
        flatten_cname: {{ flatten_cname }}
        header:
          Host:
            - "{{ Host }}"
        name: "{{ name }}"
        port: {{ port }}
        virtual_network_id: "{{ virtual_network_id }}"
        weight: {{ weight }}
  - name: check_regions
    value:
      - "{{ check_regions }}"
    description: |
      A list of regions from which to run health checks. Null means every Cloudflare data center.
  - name: networks
    value:
      - "{{ networks }}"
    description: |
      List of networks where Load Balancer or Pool is enabled.

UPDATE examples

edit

Apply changes to an existing pool, overwriting the supplied properties.

UPDATE cloudflare.load_balancers.pools
SET 
check_regions = '{{ check_regions }}',
description = '{{ description }}',
enabled = {{ enabled }},
latitude = {{ latitude }},
load_shedding = '{{ load_shedding }}',
longitude = {{ longitude }},
minimum_origins = {{ minimum_origins }},
monitor = '{{ monitor }}',
monitor_group = '{{ monitor_group }}',
name = '{{ name }}',
notification_email = '{{ notification_email }}',
notification_filter = '{{ notification_filter }}',
origin_steering = '{{ origin_steering }}',
origins = '{{ origins }}'
WHERE 
pool_id = '{{ pool_id }}' --required
AND account_id = '{{ account_id }}' --required
RETURNING
errors,
messages,
result,
success;

account_load_balancer_pools_patch_pools

Apply changes to a number of existing pools, overwriting the supplied properties. Pools are ordered by ascending name. Returns the list of affected pools. Supports the standard pagination query parameters, either limit/offset or per_page/page.

UPDATE cloudflare.load_balancers.pools
SET 
notification_email = '{{ notification_email }}'
WHERE 
account_id = '{{ account_id }}' --required
RETURNING
errors,
messages,
result,
result_info,
success;

load_balancer_pools_patch_pool

Apply changes to an existing pool, overwriting the supplied properties.

UPDATE cloudflare.load_balancers.pools
SET 
check_regions = '{{ check_regions }}',
description = '{{ description }}',
enabled = {{ enabled }},
latitude = {{ latitude }},
load_shedding = '{{ load_shedding }}',
longitude = {{ longitude }},
minimum_origins = {{ minimum_origins }},
monitor = '{{ monitor }}',
monitor_group = '{{ monitor_group }}',
name = '{{ name }}',
notification_email = '{{ notification_email }}',
notification_filter = '{{ notification_filter }}',
origin_steering = '{{ origin_steering }}',
origins = '{{ origins }}'
WHERE 
pool_id = '{{ pool_id }}' --required
RETURNING
errors,
messages,
result,
success;

load_balancer_pools_patch_pools

Apply changes to a number of existing pools, overwriting the supplied properties. Pools are ordered by ascending name. Returns the list of affected pools. Supports the standard pagination query parameters, either limit/offset or per_page/page.

UPDATE cloudflare.load_balancers.pools
SET 
notification_email = '{{ notification_email }}'
RETURNING
errors,
messages,
result,
result_info,
success;

REPLACE examples

update

Modify a configured pool.

REPLACE cloudflare.load_balancers.pools
SET 
check_regions = '{{ check_regions }}',
description = '{{ description }}',
enabled = {{ enabled }},
latitude = {{ latitude }},
load_shedding = '{{ load_shedding }}',
longitude = {{ longitude }},
minimum_origins = {{ minimum_origins }},
monitor = '{{ monitor }}',
monitor_group = '{{ monitor_group }}',
name = '{{ name }}',
notification_email = '{{ notification_email }}',
notification_filter = '{{ notification_filter }}',
origin_steering = '{{ origin_steering }}',
origins = '{{ origins }}'
WHERE 
pool_id = '{{ pool_id }}' --required
AND account_id = '{{ account_id }}' --required
AND origins = '{{ origins }}' --required
AND name = '{{ name }}' --required
RETURNING
errors,
messages,
result,
success;

load_balancer_pools_update_pool

Modify a configured pool.

REPLACE cloudflare.load_balancers.pools
SET 
check_regions = '{{ check_regions }}',
description = '{{ description }}',
enabled = {{ enabled }},
latitude = {{ latitude }},
load_shedding = '{{ load_shedding }}',
longitude = {{ longitude }},
minimum_origins = {{ minimum_origins }},
monitor = '{{ monitor }}',
monitor_group = '{{ monitor_group }}',
name = '{{ name }}',
networks = '{{ networks }}',
notification_email = '{{ notification_email }}',
notification_filter = '{{ notification_filter }}',
origin_steering = '{{ origin_steering }}',
origins = '{{ origins }}'
WHERE 
pool_id = '{{ pool_id }}' --required
AND origins = '{{ origins }}' --required
AND name = '{{ name }}' --required
RETURNING
errors,
messages,
result,
success;

DELETE examples

delete

Delete a configured pool.

DELETE FROM cloudflare.load_balancers.pools
WHERE pool_id = '{{ pool_id }}' --required
AND account_id = '{{ account_id }}' --required
;

load_balancer_pools_delete_pool

Delete a configured pool.

DELETE FROM cloudflare.load_balancers.pools
WHERE pool_id = '{{ pool_id }}' --required
;