Provides a Cloudflare Load Balancer resource. This sits in front of a number of defined pools of origins and provides various options for geographically-aware load balancing. Note that the load balancing feature must be enabled in your Cloudflare account before you can use this resource.
# Define a load balancer which always points to a pool we define below.
# In normal usage, would have different pools set for different pops
# (cloudflare points-of-presence) and/or for different regions.
# Within each pop or region we can define multiple pools in failover order.
resource "cloudflare_load_balancer" "example" {
zone_id = "0da42c8d2132a9ddaf714f9e7c920711"
name = "example-load-balancer.example.com"
fallback_pool_id = cloudflare_load_balancer_pool.example.id
default_pool_ids = [cloudflare_load_balancer_pool.example.id]
description = "example load balancer using geo-balancing"
proxied = true
steering_policy = "geo"
pop_pools {
pop = "LAX"
pool_ids = [cloudflare_load_balancer_pool.example.id]
}
country_pools {
country = "US"
pool_ids = [cloudflare_load_balancer_pool.example.id]
}
region_pools {
region = "WNAM"
pool_ids = [cloudflare_load_balancer_pool.example.id]
}
rules {
name = "example rule"
condition = "http.request.uri.path contains \"testing\""
fixed_response {
message_body = "hello"
status_code = 200
content_type = "html"
location = "www.example.com"
}
}
}
resource "cloudflare_load_balancer_pool" "example" {
name = "example-lb-pool"
origins {
name = "example-1"
address = "192.0.2.1"
enabled = false
}
}
default_pool_ids
(List of String) A list of pool IDs ordered by their failover priority. Used whenever pop_pools
/country_pools
/region_pools
are not defined.fallback_pool_id
(String) The pool ID to use when all other pools are detected as unhealthy.name
(String) The DNS hostname to associate with your load balancer. If this hostname already exists as a DNS record in Cloudflare's DNS, the load balancer will take precedence and the DNS record will not be used.zone_id
(String) The zone ID to add the load balancer to. Modifying this attribute will force creation of a new resource.adaptive_routing
(Block Set) Controls features that modify the routing of requests to pools and origins in response to dynamic conditions, such as during the interval between active health monitoring requests. (see below for nested schema)country_pools
(Block Set) A set containing mappings of country codes to a list of pool IDs (ordered by their failover priority) for the given country. (see below for nested schema)description
(String) Free text description.enabled
(Boolean) Enable or disable the load balancer. Defaults to true
.location_strategy
(Block Set) Controls location-based steering for non-proxied requests. (see below for nested schema)pop_pools
(Block Set) A set containing mappings of Cloudflare Point-of-Presence (PoP) identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). This feature is only available to enterprise customers. (see below for nested schema)proxied
(Boolean) Whether the hostname gets Cloudflare's origin protection. Defaults to false
. Conflicts with ttl
.random_steering
(Block Set) Configures pool weights. When steering_policy="random"
, a random pool is selected with probability proportional to pool weights. When steering_policy="least_outstanding_requests"
, pool weights are used to scale each pool's outstanding requests. When steering_policy="least_connections"
, pool weights are used to scale each pool's open connections. (see below for nested schema)region_pools
(Block Set) A set containing mappings of region codes to a list of pool IDs (ordered by their failover priority) for the given region. (see below for nested schema)rules
(Block List) A list of rules for this load balancer to execute. (see below for nested schema)session_affinity
(String) Specifies the type of session affinity the load balancer should use unless specified as none
or ""
(default). With value cookie
, on the first request to a proxied load balancer, a cookie is generated, encoding information of which origin the request will be forwarded to. Subsequent requests, by the same client to the same load balancer, will be sent to the origin server the cookie encodes, for the duration of the cookie and as long as the origin server remains healthy. If the cookie has expired or the origin server is unhealthy then a new origin server is calculated and used. Value ip_cookie
behaves the same as cookie
except the initial origin selection is stable and based on the client's IP address. Available values: ""
, none
, cookie
, ip_cookie
, header
. Defaults to none
.session_affinity_attributes
(Block Set) Configure attributes for session affinity. (see below for nested schema)session_affinity_ttl
(Number) Time, in seconds, until this load balancer's session affinity cookie expires after being created. This parameter is ignored unless a supported session affinity policy is set. The current default of 82800
(23 hours) will be used unless session_affinity_ttl
is explicitly set. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. Valid values are between 1800
and 604800
.steering_policy
(String) The method the load balancer uses to determine the route to your origin. Value off
uses default_pool_ids
. Value geo
uses pop_pools
/country_pools
/region_pools
. For non-proxied requests, the country
for country_pools
is determined by location_strategy
. Value random
selects a pool randomly. Value dynamic_latency
uses round trip time to select the closest pool in default_pool_ids
(requires pool health checks). Value proximity
uses the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by location_strategy
for non-proxied requests. Value least_outstanding_requests
selects a pool by taking into consideration random_steering
weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others. Value least_connections
selects a pool by taking into consideration random_steering
weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. Value ""
maps to geo
if you use pop_pools
/country_pools
/region_pools
otherwise off
. Available values: off
, geo
, dynamic_latency
, random
, proximity
, least_outstanding_requests
, least_connections
, ""
Defaults to ""
.ttl
(Number) Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This cannot be set for proxied load balancers. Defaults to 30
. Conflicts with proxied
.created_on
(String) The RFC3339 timestamp of when the load balancer was created.id
(String) The ID of this resource.modified_on
(String) The RFC3339 timestamp of when the load balancer was last modified.adaptive_routing
Optional:
failover_across_pools
(Boolean) Extends zero-downtime failover of requests to healthy origins from alternate pools, when no healthy alternate exists in the same pool, according to the failover order defined by traffic and origin steering. When set false
, zero-downtime failover will only occur between origins within the same pool. Defaults to false
.country_pools
Required:
country
(String) A country code which can be determined with the Load Balancing Regions API described here. Multiple entries should not be specified with the same country.pool_ids
(List of String) A list of pool IDs in failover priority to use in the given country.location_strategy
Optional:
mode
(String) Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. Value pop
will use the Cloudflare PoP location. Value resolver_ip
will use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, it will use the Cloudflare PoP location. Available values: pop
, resolver_ip
. Defaults to pop
.prefer_ecs
(String) Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. Value always
will always prefer ECS, never
will never prefer ECS, proximity
will prefer ECS only when steering_policy="proximity"
, and geo
will prefer ECS only when steering_policy="geo"
. Available values: always
, never
, proximity
, geo
. Defaults to proximity
.pop_pools
Required:
pool_ids
(List of String) A list of pool IDs in failover priority to use for traffic reaching the given PoP.pop
(String) A 3-letter code for the Point-of-Presence. Allowed values can be found in the list of datacenters on the status page. Multiple entries should not be specified with the same PoP.random_steering
Optional:
default_weight
(Number) The default weight for pools in the load balancer that are not specified in the pool_weights
map.pool_weights
(Map of Number) A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer.region_pools
Required:
pool_ids
(List of String) A list of pool IDs in failover priority to use in the given region.region
(String) A region code which must be in the list defined here. Multiple entries should not be specified with the same region.rules
Required:
name
(String) Human readable name for this rule.Optional:
condition
(String) The statement to evaluate to determine if this rule's effects should be applied. An empty condition is always true. See load balancing rules.disabled
(Boolean) A disabled rule will not be executed.fixed_response
(Block List, Max: 1) Settings for a HTTP response to return directly to the eyeball if the condition is true. Note: overrides
or fixed_response
must be set. (see below for nested schema)overrides
(Block List) The load balancer settings to alter if this rule's condition
is true. Note: overrides
or fixed_response
must be set. (see below for nested schema)priority
(Number) Priority used when determining the order of rule execution. Lower values are executed first. If not provided, the list order will be used.terminates
(Boolean) Terminates indicates that if this rule is true no further rules should be executed. Note: setting a fixed_response
forces this field to true
.rules.fixed_response
Optional:
content_type
(String) The value of the HTTP context-type header for this fixed response.location
(String) The value of the HTTP location header for this fixed response.message_body
(String) The text used as the html body for this fixed response.status_code
(Number) The HTTP status code used for this fixed response.rules.overrides
Optional:
adaptive_routing
(Block Set) Controls features that modify the routing of requests to pools and origins in response to dynamic conditions, such as during the interval between active health monitoring requests. (see below for nested schema)country_pools
(Block Set) A set containing mappings of country codes to a list of pool IDs (ordered by their failover priority) for the given country. (see below for nested schema)default_pools
(List of String) A list of pool IDs ordered by their failover priority. Used whenever pop_pools
/country_pools
/region_pools
are not defined.fallback_pool
(String) The pool ID to use when all other pools are detected as unhealthy.location_strategy
(Block Set) Controls location-based steering for non-proxied requests. (see below for nested schema)pop_pools
(Block Set) A set containing mappings of Cloudflare Point-of-Presence (PoP) identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). This feature is only available to enterprise customers. (see below for nested schema)random_steering
(Block Set) Configures pool weights. When steering_policy="random"
, a random pool is selected with probability proportional to pool weights. When steering_policy="least_outstanding_requests"
, pool weights are used to scale each pool's outstanding requests. When steering_policy="least_connections"
, pool weights are used to scale each pool's open connections. (see below for nested schema)region_pools
(Block Set) A set containing mappings of region codes to a list of pool IDs (ordered by their failover priority) for the given region. (see below for nested schema)session_affinity
(String) Configure attributes for session affinity.session_affinity_attributes
(Block Set) Configure attributes for session affinity. Note that the property drain_duration
is not currently supported as a rule override. (see below for nested schema)session_affinity_ttl
(Number) Time, in seconds, until this load balancer's session affinity cookie expires after being created. This parameter is ignored unless a supported session affinity policy is set. The current default of 82800
(23 hours) will be used unless session_affinity_ttl
is explicitly set. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. Valid values are between 1800
and 604800
.steering_policy
(String) The method the load balancer uses to determine the route to your origin. Value off
uses default_pool_ids
. Value geo
uses pop_pools
/country_pools
/region_pools
. For non-proxied requests, the country
for country_pools
is determined by location_strategy
. Value random
selects a pool randomly. Value dynamic_latency
uses round trip time to select the closest pool in default_pool_ids
(requires pool health checks). Value proximity
uses the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by location_strategy
for non-proxied requests. Value least_outstanding_requests
selects a pool by taking into consideration random_steering
weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others. Value least_connections
selects a pool by taking into consideration random_steering
weights, as well as each pool's number of open connections. Pools with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. Value ""
maps to geo
if you use pop_pools
/country_pools
/region_pools
otherwise off
. Available values: off
, geo
, dynamic_latency
, random
, proximity
, least_outstanding_requests
, least_connections
, ""
Defaults to ""
.ttl
(Number) Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This cannot be set for proxied load balancers. Defaults to 30
.rules.overrides.adaptive_routing
Optional:
failover_across_pools
(Boolean) Extends zero-downtime failover of requests to healthy origins from alternate pools, when no healthy alternate exists in the same pool, according to the failover order defined by traffic and origin steering. When set false
, zero-downtime failover will only occur between origins within the same pool.rules.overrides.country_pools
Required:
country
(String) A country code which can be determined with the Load Balancing Regions API described here. Multiple entries should not be specified with the same country.pool_ids
(List of String) A list of pool IDs in failover priority to use in the given country.rules.overrides.location_strategy
Optional:
mode
(String) Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. Value pop
will use the Cloudflare PoP location. Value resolver_ip
will use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, it will use the Cloudflare PoP location. Available values: pop
, resolver_ip
.prefer_ecs
(String) Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. Value always
will always prefer ECS, never
will never prefer ECS, proximity
will prefer ECS only when steering_policy="proximity"
, and geo
will prefer ECS only when steering_policy="geo"
. Available values: always
, never
, proximity
, geo
.rules.overrides.pop_pools
Required:
pool_ids
(List of String) A list of pool IDs in failover priority to use for traffic reaching the given PoP.pop
(String) A 3-letter code for the Point-of-Presence. Allowed values can be found in the list of datacenters on the status page. Multiple entries should not be specified with the same PoP.rules.overrides.random_steering
Optional:
default_weight
(Number) The default weight for pools in the load balancer that are not specified in the pool_weights
map.pool_weights
(Map of Number) A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer.rules.overrides.region_pools
Required:
pool_ids
(List of String) A list of pool IDs in failover priority to use in the given region.region
(String) A region code which must be in the list defined here. Multiple entries should not be specified with the same region.rules.overrides.session_affinity_attributes
Optional:
headers
(List of String) Configures the HTTP header names to use when header session affinity is enabled.require_all_headers
(Boolean) Configures how headers are used when header session affinity is enabled. Set to true to require all headers to be present on requests in order for sessions to be created or false to require at least one header to be present. Defaults to false
.samesite
(String) Configures the SameSite attribute on session affinity cookie. Value Auto
will be translated to Lax
or None
depending if Always Use HTTPS is enabled. Note: when using value None
, then you can not set secure="Never"
. Available values: Auto
, Lax
, None
, Strict
.secure
(String) Configures the Secure attribute on session affinity cookie. Value Always
indicates the Secure attribute will be set in the Set-Cookie header, Never
indicates the Secure attribute will not be set, and Auto
will set the Secure attribute depending if Always Use HTTPS is enabled. Available values: Auto
, Always
, Never
.zero_downtime_failover
(String) Configures the zero-downtime failover between origins within a pool when session affinity is enabled. Value none
means no failover takes place for sessions pinned to the origin. Value temporary
means traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping. Value sticky
means the session affinity cookie is updated and subsequent requests are sent to the new origin. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. Available values: none
, temporary
, sticky
.session_affinity_attributes
Optional:
drain_duration
(Number) Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. Defaults to 0
.headers
(List of String) Configures the HTTP header names to use when header session affinity is enabled.require_all_headers
(Boolean) Configures how headers are used when header session affinity is enabled. Set to true to require all headers to be present on requests in order for sessions to be created or false to require at least one header to be present. Defaults to false
.samesite
(String) Configures the SameSite attribute on session affinity cookie. Value Auto
will be translated to Lax
or None
depending if Always Use HTTPS is enabled. Note: when using value None
, then you can not set secure="Never"
. Available values: Auto
, Lax
, None
, Strict
. Defaults to Auto
.secure
(String) Configures the Secure attribute on session affinity cookie. Value Always
indicates the Secure attribute will be set in the Set-Cookie header, Never
indicates the Secure attribute will not be set, and Auto
will set the Secure attribute depending if Always Use HTTPS is enabled. Available values: Auto
, Always
, Never
. Defaults to Auto
.zero_downtime_failover
(String) Configures the zero-downtime failover between origins within a pool when session affinity is enabled. Value none
means no failover takes place for sessions pinned to the origin. Value temporary
means traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping. Value sticky
means the session affinity cookie is updated and subsequent requests are sent to the new origin. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. Available values: none
, temporary
, sticky
. Defaults to none
.Import is supported using the following syntax:
$ terraform import cloudflare_load_balancer.example <zone_id>/<load_balancer_id>