# Load Balancers ## List Load Balancers `client.LoadBalancers.List(ctx, query) (*SinglePage[LoadBalancer], error)` **get** `/zones/{zone_id}/load_balancers` List configured load balancers. ### Parameters - `query LoadBalancerListParams` - `ZoneID param.Field[string]` ### Returns - `type LoadBalancer struct{…}` - `ID string` - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `CreatedOn string` - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `Description string` Object description. - `Enabled bool` Whether to enable (the default) this load balancer. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `ModifiedOn string` - `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. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied bool` Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules []Rules` BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `ZoneName string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.LoadBalancers.List(context.TODO(), load_balancers.LoadBalancerListParams{ ZoneID: cloudflare.F("699d98642c564d2e855e9661899b7252"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "699d98642c564d2e855e9661899b7252", "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "created_on": "2014-01-01T05:20:00.12345Z", "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "description": "Load Balancer for www.example.com", "enabled": true, "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "modified_on": "2014-01-01T05:20:00.12345Z", "name": "www.example.com", "networks": [ "string" ], "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "proxied": true, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "rules": [ { "condition": "http.request.uri.path contains \"/testing\"", "disabled": true, "fixed_response": { "content_type": "application/json", "location": "www.example.com", "message_body": "Testing Hello", "status_code": 0 }, "name": "route the path /testing to testing datacenter.", "overrides": { "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30 }, "priority": 0, "terminates": true } ], "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30, "zone_name": "example.com" } ], "success": true, "result_info": { "count": 20, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Load Balancer Details `client.LoadBalancers.Get(ctx, loadBalancerID, query) (*LoadBalancer, error)` **get** `/zones/{zone_id}/load_balancers/{load_balancer_id}` Fetch a single configured load balancer. ### Parameters - `loadBalancerID string` - `query LoadBalancerGetParams` - `ZoneID param.Field[string]` ### Returns - `type LoadBalancer struct{…}` - `ID string` - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `CreatedOn string` - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `Description string` Object description. - `Enabled bool` Whether to enable (the default) this load balancer. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `ModifiedOn string` - `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. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied bool` Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules []Rules` BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `ZoneName string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) loadBalancer, err := client.LoadBalancers.Get( context.TODO(), "699d98642c564d2e855e9661899b7252", load_balancers.LoadBalancerGetParams{ ZoneID: cloudflare.F("699d98642c564d2e855e9661899b7252"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", loadBalancer.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "699d98642c564d2e855e9661899b7252", "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "created_on": "2014-01-01T05:20:00.12345Z", "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "description": "Load Balancer for www.example.com", "enabled": true, "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "modified_on": "2014-01-01T05:20:00.12345Z", "name": "www.example.com", "networks": [ "string" ], "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "proxied": true, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "rules": [ { "condition": "http.request.uri.path contains \"/testing\"", "disabled": true, "fixed_response": { "content_type": "application/json", "location": "www.example.com", "message_body": "Testing Hello", "status_code": 0 }, "name": "route the path /testing to testing datacenter.", "overrides": { "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30 }, "priority": 0, "terminates": true } ], "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30, "zone_name": "example.com" }, "success": true } ``` ## Create Load Balancer `client.LoadBalancers.New(ctx, params) (*LoadBalancer, error)` **post** `/zones/{zone_id}/load_balancers` Create a new load balancer. ### Parameters - `params LoadBalancerNewParams` - `ZoneID param.Field[string]` Path param - `DefaultPools param.Field[[]DefaultPools]` Body param: A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool param.Field[string]` Body param: The pool ID to use when all other pools are detected as unhealthy. - `Name param.Field[string]` Body param: 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. - `AdaptiveRouting param.Field[AdaptiveRouting]` Body param: 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools param.Field[map[string, []string]]` Body param: A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `Description param.Field[string]` Body param: Object description. - `LocationStrategy param.Field[LocationStrategy]` Body param: Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Networks param.Field[[]string]` Body param: List of networks where Load Balancer or Pool is enabled. - `POPPools param.Field[map[string, []string]]` Body param: Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied param.Field[bool]` Body param: Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering param.Field[RandomSteering]` Body param: Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools param.Field[map[string, []string]]` Body param: A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules param.Field[[]Rules]` Body param: BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity param.Field[SessionAffinity]` Body param: Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes param.Field[SessionAffinityAttributes]` Body param: Configures attributes for session affinity. - `SessionAffinityTTL param.Field[float64]` Body param: Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy param.Field[SteeringPolicy]` Body param: Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL param.Field[float64]` Body param: Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. ### Returns - `type LoadBalancer struct{…}` - `ID string` - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `CreatedOn string` - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `Description string` Object description. - `Enabled bool` Whether to enable (the default) this load balancer. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `ModifiedOn string` - `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. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied bool` Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules []Rules` BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `ZoneName string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) loadBalancer, err := client.LoadBalancers.New(context.TODO(), load_balancers.LoadBalancerNewParams{ ZoneID: cloudflare.F("699d98642c564d2e855e9661899b7252"), DefaultPools: cloudflare.F([]load_balancers.DefaultPoolsParam{"17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194"}), FallbackPool: cloudflare.F("fallback_pool"), Name: cloudflare.F("www.example.com"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", loadBalancer.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "699d98642c564d2e855e9661899b7252", "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "created_on": "2014-01-01T05:20:00.12345Z", "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "description": "Load Balancer for www.example.com", "enabled": true, "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "modified_on": "2014-01-01T05:20:00.12345Z", "name": "www.example.com", "networks": [ "string" ], "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "proxied": true, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "rules": [ { "condition": "http.request.uri.path contains \"/testing\"", "disabled": true, "fixed_response": { "content_type": "application/json", "location": "www.example.com", "message_body": "Testing Hello", "status_code": 0 }, "name": "route the path /testing to testing datacenter.", "overrides": { "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30 }, "priority": 0, "terminates": true } ], "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30, "zone_name": "example.com" }, "success": true } ``` ## Update Load Balancer `client.LoadBalancers.Update(ctx, loadBalancerID, params) (*LoadBalancer, error)` **put** `/zones/{zone_id}/load_balancers/{load_balancer_id}` Update a configured load balancer. ### Parameters - `loadBalancerID string` - `params LoadBalancerUpdateParams` - `ZoneID param.Field[string]` Path param - `DefaultPools param.Field[[]DefaultPools]` Body param: A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool param.Field[string]` Body param: The pool ID to use when all other pools are detected as unhealthy. - `Name param.Field[string]` Body param: 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. - `AdaptiveRouting param.Field[AdaptiveRouting]` Body param: 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools param.Field[map[string, []string]]` Body param: A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `Description param.Field[string]` Body param: Object description. - `Enabled param.Field[bool]` Body param: Whether to enable (the default) this load balancer. - `LocationStrategy param.Field[LocationStrategy]` Body param: Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Networks param.Field[[]string]` Body param: List of networks where Load Balancer or Pool is enabled. - `POPPools param.Field[map[string, []string]]` Body param: Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied param.Field[bool]` Body param: Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering param.Field[RandomSteering]` Body param: Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools param.Field[map[string, []string]]` Body param: A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules param.Field[[]Rules]` Body param: BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity param.Field[SessionAffinity]` Body param: Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes param.Field[SessionAffinityAttributes]` Body param: Configures attributes for session affinity. - `SessionAffinityTTL param.Field[float64]` Body param: Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy param.Field[SteeringPolicy]` Body param: Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL param.Field[float64]` Body param: Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. ### Returns - `type LoadBalancer struct{…}` - `ID string` - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `CreatedOn string` - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `Description string` Object description. - `Enabled bool` Whether to enable (the default) this load balancer. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `ModifiedOn string` - `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. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied bool` Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules []Rules` BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `ZoneName string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) loadBalancer, err := client.LoadBalancers.Update( context.TODO(), "699d98642c564d2e855e9661899b7252", load_balancers.LoadBalancerUpdateParams{ ZoneID: cloudflare.F("699d98642c564d2e855e9661899b7252"), DefaultPools: cloudflare.F([]load_balancers.DefaultPoolsParam{"17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194"}), FallbackPool: cloudflare.F("fallback_pool"), Name: cloudflare.F("www.example.com"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", loadBalancer.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "699d98642c564d2e855e9661899b7252", "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "created_on": "2014-01-01T05:20:00.12345Z", "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "description": "Load Balancer for www.example.com", "enabled": true, "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "modified_on": "2014-01-01T05:20:00.12345Z", "name": "www.example.com", "networks": [ "string" ], "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "proxied": true, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "rules": [ { "condition": "http.request.uri.path contains \"/testing\"", "disabled": true, "fixed_response": { "content_type": "application/json", "location": "www.example.com", "message_body": "Testing Hello", "status_code": 0 }, "name": "route the path /testing to testing datacenter.", "overrides": { "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30 }, "priority": 0, "terminates": true } ], "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30, "zone_name": "example.com" }, "success": true } ``` ## Patch Load Balancer `client.LoadBalancers.Edit(ctx, loadBalancerID, params) (*LoadBalancer, error)` **patch** `/zones/{zone_id}/load_balancers/{load_balancer_id}` Apply changes to an existing load balancer, overwriting the supplied properties. ### Parameters - `loadBalancerID string` - `params LoadBalancerEditParams` - `ZoneID param.Field[string]` Path param - `AdaptiveRouting param.Field[AdaptiveRouting]` Body param: 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools param.Field[map[string, []string]]` Body param: A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools param.Field[[]DefaultPools]` Body param: A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `Description param.Field[string]` Body param: Object description. - `Enabled param.Field[bool]` Body param: Whether to enable (the default) this load balancer. - `FallbackPool param.Field[string]` Body param: The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy param.Field[LocationStrategy]` Body param: Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Name param.Field[string]` Body param: 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. - `POPPools param.Field[map[string, []string]]` Body param: Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied param.Field[bool]` Body param: Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering param.Field[RandomSteering]` Body param: Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools param.Field[map[string, []string]]` Body param: A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules param.Field[[]Rules]` Body param: BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity param.Field[SessionAffinity]` Body param: Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes param.Field[SessionAffinityAttributes]` Body param: Configures attributes for session affinity. - `SessionAffinityTTL param.Field[float64]` Body param: Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy param.Field[SteeringPolicy]` Body param: Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL param.Field[float64]` Body param: Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. ### Returns - `type LoadBalancer struct{…}` - `ID string` - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `CreatedOn string` - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `Description string` Object description. - `Enabled bool` Whether to enable (the default) this load balancer. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `ModifiedOn string` - `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. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied bool` Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules []Rules` BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `ZoneName string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) loadBalancer, err := client.LoadBalancers.Edit( context.TODO(), "699d98642c564d2e855e9661899b7252", load_balancers.LoadBalancerEditParams{ ZoneID: cloudflare.F("699d98642c564d2e855e9661899b7252"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", loadBalancer.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "699d98642c564d2e855e9661899b7252", "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "created_on": "2014-01-01T05:20:00.12345Z", "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "description": "Load Balancer for www.example.com", "enabled": true, "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "modified_on": "2014-01-01T05:20:00.12345Z", "name": "www.example.com", "networks": [ "string" ], "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "proxied": true, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "rules": [ { "condition": "http.request.uri.path contains \"/testing\"", "disabled": true, "fixed_response": { "content_type": "application/json", "location": "www.example.com", "message_body": "Testing Hello", "status_code": 0 }, "name": "route the path /testing to testing datacenter.", "overrides": { "adaptive_routing": { "failover_across_pools": true }, "country_pools": { "GB": [ "abd90f38ced07c2e2f4df50b1f61d4194" ], "US": [ "de90f38ced07c2e2f4df50b1f61d4194", "00920f38ce07c2e2f4df50b1f61d4194" ] }, "default_pools": [ "17b5962d775c646f3f9725cbc7a53df4", "9290f38c5d07c2e2f4df57b1f61d4196", "00920f38ce07c2e2f4df50b1f61d4194" ], "fallback_pool": "fallback_pool", "location_strategy": { "mode": "resolver_ip", "prefer_ecs": "always" }, "pop_pools": { "LAX": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ], "LHR": [ "abd90f38ced07c2e2f4df50b1f61d4194", "f9138c5d07c2e2f4df57b1f61d4196" ], "SJC": [ "00920f38ce07c2e2f4df50b1f61d4194" ] }, "random_steering": { "default_weight": 0.2, "pool_weights": { "9290f38c5d07c2e2f4df57b1f61d4196": 0.5, "de90f38ced07c2e2f4df50b1f61d4194": 0.3 } }, "region_pools": { "ENAM": [ "00920f38ce07c2e2f4df50b1f61d4194" ], "WNAM": [ "de90f38ced07c2e2f4df50b1f61d4194", "9290f38c5d07c2e2f4df57b1f61d4196" ] }, "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30 }, "priority": 0, "terminates": true } ], "session_affinity": "cookie", "session_affinity_attributes": { "drain_duration": 100, "headers": [ "x" ], "require_all_headers": true, "samesite": "Auto", "secure": "Auto", "zero_downtime_failover": "sticky" }, "session_affinity_ttl": 1800, "steering_policy": "dynamic_latency", "ttl": 30, "zone_name": "example.com" }, "success": true } ``` ## Delete Load Balancer `client.LoadBalancers.Delete(ctx, loadBalancerID, body) (*LoadBalancerDeleteResponse, error)` **delete** `/zones/{zone_id}/load_balancers/{load_balancer_id}` Delete a configured load balancer. ### Parameters - `loadBalancerID string` - `body LoadBalancerDeleteParams` - `ZoneID param.Field[string]` ### Returns - `type LoadBalancerDeleteResponse struct{…}` - `ID string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) loadBalancer, err := client.LoadBalancers.Delete( context.TODO(), "699d98642c564d2e855e9661899b7252", load_balancers.LoadBalancerDeleteParams{ ZoneID: cloudflare.F("699d98642c564d2e855e9661899b7252"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", loadBalancer.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "699d98642c564d2e855e9661899b7252" }, "success": true } ``` ## Domain Types ### Adaptive Routing - `type AdaptiveRouting struct{…}` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. ### Check Region - `type CheckRegion string` WNAM: Western North America, ENAM: Eastern North America, WEU: Western Europe, EEU: Eastern Europe, NSAM: Northern South America, SSAM: Southern South America, OC: Oceania, ME: Middle East, NAF: North Africa, SAF: South Africa, SAS: Southern Asia, SEAS: South East Asia, NEAS: North East Asia, ALL_REGIONS: all regions (ENTERPRISE customers only). - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` ### Default Pools - `type DefaultPools string` A pool ID. ### Filter Options - `type FilterOptions struct{…}` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). ### Header - `type Header struct{…}` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. ### Host - `type Host string` ### Load Balancer - `type LoadBalancer struct{…}` - `ID string` - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `CreatedOn string` - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `Description string` Object description. - `Enabled bool` Whether to enable (the default) this load balancer. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `ModifiedOn string` - `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. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `Proxied bool` Whether the hostname should be gray clouded (false) or orange clouded (true). - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `Rules []Rules` BETA Field Not General Access: A list of rules for this load balancer to execute. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `ZoneName string` ### Load Shedding - `type LoadShedding struct{…}` Configures load shedding policies and percentages for the pool. - `DefaultPercent float64` The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity. - `DefaultPolicy LoadSheddingDefaultPolicy` The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs. - `const LoadSheddingDefaultPolicyRandom LoadSheddingDefaultPolicy = "random"` - `const LoadSheddingDefaultPolicyHash LoadSheddingDefaultPolicy = "hash"` - `SessionPercent float64` The percent of existing sessions to shed from the pool, according to the session policy. - `SessionPolicy LoadSheddingSessionPolicy` Only the hash policy is supported for existing sessions (to avoid exponential decay). - `const LoadSheddingSessionPolicyHash LoadSheddingSessionPolicy = "hash"` ### Location Strategy - `type LocationStrategy struct{…}` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` ### Notification Filter - `type NotificationFilter struct{…}` Filter pool and origin health notifications by resource type or health status. Use null to reset. - `Origin FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). - `Pool FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. ### Origin - `type Origin struct{…}` - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. ### Origin Steering - `type OriginSteering struct{…}` Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Policy OriginSteeringPolicy` The type of origin steering policy to use. - `"random"`: Select an origin randomly. - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP address. - `"least_outstanding_requests"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others. - `"least_connections"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. - `const OriginSteeringPolicyRandom OriginSteeringPolicy = "random"` - `const OriginSteeringPolicyHash OriginSteeringPolicy = "hash"` - `const OriginSteeringPolicyLeastOutstandingRequests OriginSteeringPolicy = "least_outstanding_requests"` - `const OriginSteeringPolicyLeastConnections OriginSteeringPolicy = "least_connections"` ### Random Steering - `type RandomSteering struct{…}` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. ### Rules - `type Rules struct{…}` A rule object containing conditions and overrides for this load balancer to evaluate. - `Condition string` The condition expressions to evaluate. If the condition evaluates to true, the overrides or fixed_response in this rule will be applied. An empty condition is always true. For more details on condition expressions, please see https://developers.cloudflare.com/load-balancing/understand-basics/load-balancing-rules/expressions. - `Disabled bool` Disable this specific rule. It will no longer be evaluated by this load balancer. - `FixedResponse RulesFixedResponse` A collection of fields used to directly respond to the eyeball instead of routing to a pool. If a fixed_response is supplied the rule will be marked as terminates. - `ContentType string` The http 'Content-Type' header to include in the response. - `Location string` The http 'Location' header to include in the response. - `MessageBody string` Text to include as the http body. - `StatusCode int64` The http status code to respond with. - `Name string` Name of this rule. Only used for human readability. - `Overrides RulesOverrides` A collection of overrides to apply to the load balancer when this rule's condition is true. All fields are optional. - `AdaptiveRouting AdaptiveRouting` 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. For example, zero-downtime failover occurs immediately when an origin becomes unavailable due to HTTP 521, 522, or 523 response codes. If there is another healthy origin in the same pool, the request is retried once against this alternate origin. - `FailoverAcrossPools bool` 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 (the default) zero-downtime failover will only occur between origins within the same pool. See `session_affinity_attributes` for control over when sessions are broken or reassigned. - `CountryPools map[string, []string]` A mapping of country codes to a list of pool IDs (ordered by their failover priority) for the given country. Any country not explicitly defined will fall back to using the corresponding region_pool mapping if it exists else to default_pools. - `DefaultPools []DefaultPools` A list of pool IDs ordered by their failover priority. Pools defined here are used by default, or when region_pools are not configured for a given region. - `FallbackPool string` The pool ID to use when all other pools are detected as unhealthy. - `LocationStrategy LocationStrategy` Controls location-based steering for non-proxied requests. See `steering_policy` to learn how steering is affected. - `Mode LocationStrategyMode` Determines the authoritative location when ECS is not preferred, does not exist in the request, or its GeoIP lookup is unsuccessful. - `"pop"`: Use the Cloudflare PoP location. - `"resolver_ip"`: Use the DNS resolver GeoIP location. If the GeoIP lookup is unsuccessful, use the Cloudflare PoP location. - `const LocationStrategyModePOP LocationStrategyMode = "pop"` - `const LocationStrategyModeResolverIP LocationStrategyMode = "resolver_ip"` - `PreferECS LocationStrategyPreferECS` Whether the EDNS Client Subnet (ECS) GeoIP should be preferred as the authoritative location. - `"always"`: Always prefer ECS. - `"never"`: Never prefer ECS. - `"proximity"`: Prefer ECS only when `steering_policy="proximity"`. - `"geo"`: Prefer ECS only when `steering_policy="geo"`. - `const LocationStrategyPreferECSAlways LocationStrategyPreferECS = "always"` - `const LocationStrategyPreferECSNever LocationStrategyPreferECS = "never"` - `const LocationStrategyPreferECSProximity LocationStrategyPreferECS = "proximity"` - `const LocationStrategyPreferECSGeo LocationStrategyPreferECS = "geo"` - `POPPools map[string, []string]` Enterprise only: A mapping of Cloudflare PoP identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). Any PoPs not explicitly defined will fall back to using the corresponding country_pool, then region_pool mapping if it exists else to default_pools. - `RandomSteering RandomSteering` Configures pool weights. - `steering_policy="random"`: A random pool is selected with probability proportional to pool weights. - `steering_policy="least_outstanding_requests"`: Use pool weights to scale each pool's outstanding requests. - `steering_policy="least_connections"`: Use pool weights to scale each pool's open connections. - `DefaultWeight float64` The default weight for pools in the load balancer that are not specified in the pool_weights map. - `PoolWeights map[string, float64]` A mapping of pool IDs to custom weights. The weight is relative to other pools in the load balancer. - `RegionPools map[string, []string]` A mapping of region codes to a list of pool IDs (ordered by their failover priority) for the given region. Any regions not explicitly defined will fall back to using default_pools. - `SessionAffinity SessionAffinity` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` - `SessionAffinityAttributes SessionAffinityAttributes` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` - `SessionAffinityTTL float64` Time, in seconds, until a client's session expires after being created. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. The accepted ranges per `session_affinity` policy are: - `"cookie"` / `"ip_cookie"`: The current default of 23 hours will be used unless explicitly set. The accepted range of values is between [1800, 604800]. - `"header"`: The current default of 1800 seconds will be used unless explicitly set. The accepted range of values is between [30, 3600]. Note: With session affinity by header, sessions only expire after they haven't been used for the number of seconds specified. - `SteeringPolicy SteeringPolicy` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` - `TTL float64` Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This only applies to gray-clouded (unproxied) load balancers. - `Priority int64` The order in which rules should be executed in relation to each other. Lower values are executed first. Values do not need to be sequential. If no value is provided for any rule the array order of the rules field will be used to assign a priority. - `Terminates bool` If this rule's condition is true, this causes rule evaluation to stop after processing this rule. ### Session Affinity - `type SessionAffinity string` Specifies the type of session affinity the load balancer should use unless specified as `"none"`. The supported types are: - `"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. - `"ip_cookie"`: Behaves the same as `"cookie"` except the initial origin selection is stable and based on the client's ip address. - `"header"`: On the first request to a proxied load balancer, a session key based on the configured HTTP headers (see `session_affinity_attributes.headers`) is generated, encoding the request headers used for storing in the load balancer session state which origin the request will be forwarded to. Subsequent requests to the load balancer with the same headers will be sent to the same origin server, for the duration of the session and as long as the origin server remains healthy. If the session has been idle for the duration of `session_affinity_ttl` seconds or the origin server is unhealthy, then a new origin server is calculated and used. See `headers` in `session_affinity_attributes` for additional required configuration. - `const SessionAffinityNone SessionAffinity = "none"` - `const SessionAffinityCookie SessionAffinity = "cookie"` - `const SessionAffinityIPCookie SessionAffinity = "ip_cookie"` - `const SessionAffinityHeader SessionAffinity = "header"` ### Session Affinity Attributes - `type SessionAffinityAttributes struct{…}` Configures attributes for session affinity. - `DrainDuration float64` Configures the drain duration in seconds. This field is only used when session affinity is enabled on the load balancer. - `Headers []string` Configures the names of HTTP headers to base session affinity on when header `session_affinity` is enabled. At least one HTTP header name must be provided. To specify the exact cookies to be used, include an item in the following format: `"cookie:,"` (example) where everything after the colon is a comma-separated list of cookie names. Providing only `"cookie"` will result in all cookies being used. The default max number of HTTP header names that can be provided depends on your plan: 5 for Enterprise, 1 for all other plans. - `RequireAllHeaders bool` When header `session_affinity` is enabled, this option can be used to specify how HTTP headers on load balancing requests will be used. The supported values are: - `"true"`: Load balancing requests must contain *all* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `"false"`: Load balancing requests must contain *at least one* of the HTTP headers specified by the `headers` session affinity attribute, otherwise sessions aren't created. - `Samesite SessionAffinityAttributesSamesite` 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", the secure attribute can not be set to "Never". - `const SessionAffinityAttributesSamesiteAuto SessionAffinityAttributesSamesite = "Auto"` - `const SessionAffinityAttributesSamesiteLax SessionAffinityAttributesSamesite = "Lax"` - `const SessionAffinityAttributesSamesiteNone SessionAffinityAttributesSamesite = "None"` - `const SessionAffinityAttributesSamesiteStrict SessionAffinityAttributesSamesite = "Strict"` - `Secure SessionAffinityAttributesSecure` 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. - `const SessionAffinityAttributesSecureAuto SessionAffinityAttributesSecure = "Auto"` - `const SessionAffinityAttributesSecureAlways SessionAffinityAttributesSecure = "Always"` - `const SessionAffinityAttributesSecureNever SessionAffinityAttributesSecure = "Never"` - `ZeroDowntimeFailover SessionAffinityAttributesZeroDowntimeFailover` Configures the zero-downtime failover between origins within a pool when session affinity is enabled. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. The supported values are: - `"none"`: No failover takes place for sessions pinned to the origin (default). - `"temporary"`: 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. - `"sticky"`: The session affinity cookie is updated and subsequent requests are sent to the new origin. Note: Zero-downtime failover with sticky sessions is currently not supported for session affinity by header. - `const SessionAffinityAttributesZeroDowntimeFailoverNone SessionAffinityAttributesZeroDowntimeFailover = "none"` - `const SessionAffinityAttributesZeroDowntimeFailoverTemporary SessionAffinityAttributesZeroDowntimeFailover = "temporary"` - `const SessionAffinityAttributesZeroDowntimeFailoverSticky SessionAffinityAttributesZeroDowntimeFailover = "sticky"` ### Steering Policy - `type SteeringPolicy string` Steering Policy for this load balancer. - `"off"`: Use `default_pools`. - `"geo"`: Use `region_pools`/`country_pools`/`pop_pools`. For non-proxied requests, the country for `country_pools` is determined by `location_strategy`. - `"random"`: Select a pool randomly. - `"dynamic_latency"`: Use round trip time to select the closest pool in default_pools (requires pool health checks). - `"proximity"`: Use 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. - `"least_outstanding_requests"`: Select 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. - `"least_connections"`: Select 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. - `""`: Will map to `"geo"` if you use `region_pools`/`country_pools`/`pop_pools` otherwise `"off"`. - `const SteeringPolicyOff SteeringPolicy = "off"` - `const SteeringPolicyGeo SteeringPolicy = "geo"` - `const SteeringPolicyRandom SteeringPolicy = "random"` - `const SteeringPolicyDynamicLatency SteeringPolicy = "dynamic_latency"` - `const SteeringPolicyProximity SteeringPolicy = "proximity"` - `const SteeringPolicyLeastOutstandingRequests SteeringPolicy = "least_outstanding_requests"` - `const SteeringPolicyLeastConnections SteeringPolicy = "least_connections"` - `const SteeringPolicyEmpty SteeringPolicy = ""` # Monitors ## List Monitors `client.LoadBalancers.Monitors.List(ctx, query) (*SinglePage[Monitor], error)` **get** `/accounts/{account_id}/load_balancers/monitors` List configured monitors for an account. ### Parameters - `query MonitorListParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type Monitor struct{…}` - `ID string` - `AllowInsecure bool` Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown int64` To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp int64` To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `CreatedOn string` - `Description string` Object description. - `ExpectedBody string` A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes string` The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects bool` Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header map[string, []string]` The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval int64` The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method string` The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `ModifiedOn string` - `Path string` The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port int64` The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone string` Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries int64` The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout int64` The timeout (in seconds) before marking the health check as failed. - `Type MonitorType` The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorTypeHTTP MonitorType = "http"` - `const MonitorTypeHTTPS MonitorType = "https"` - `const MonitorTypeTCP MonitorType = "tcp"` - `const MonitorTypeUdpIcmp MonitorType = "udp_icmp"` - `const MonitorTypeIcmpPing MonitorType = "icmp_ping"` - `const MonitorTypeSmtp MonitorType = "smtp"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.LoadBalancers.Monitors.List(context.TODO(), load_balancers.MonitorListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "allow_insecure": true, "consecutive_down": 0, "consecutive_up": 0, "created_on": "2014-01-01T05:20:00.12345Z", "description": "Login page monitor", "expected_body": "alive", "expected_codes": "2xx", "follow_redirects": true, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }, "interval": 0, "method": "GET", "modified_on": "2014-01-01T05:20:00.12345Z", "path": "/health", "port": 0, "probe_zone": "example.com", "retries": 0, "timeout": 0, "type": "https" } ], "success": true, "result_info": { "count": 20, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Monitor Details `client.LoadBalancers.Monitors.Get(ctx, monitorID, query) (*Monitor, error)` **get** `/accounts/{account_id}/load_balancers/monitors/{monitor_id}` List a single configured monitor for an account. ### Parameters - `monitorID string` - `query MonitorGetParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type Monitor struct{…}` - `ID string` - `AllowInsecure bool` Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown int64` To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp int64` To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `CreatedOn string` - `Description string` Object description. - `ExpectedBody string` A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes string` The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects bool` Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header map[string, []string]` The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval int64` The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method string` The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `ModifiedOn string` - `Path string` The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port int64` The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone string` Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries int64` The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout int64` The timeout (in seconds) before marking the health check as failed. - `Type MonitorType` The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorTypeHTTP MonitorType = "http"` - `const MonitorTypeHTTPS MonitorType = "https"` - `const MonitorTypeTCP MonitorType = "tcp"` - `const MonitorTypeUdpIcmp MonitorType = "udp_icmp"` - `const MonitorTypeIcmpPing MonitorType = "icmp_ping"` - `const MonitorTypeSmtp MonitorType = "smtp"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitor, err := client.LoadBalancers.Monitors.Get( context.TODO(), "f1aba936b94213e5b8dca0c0dbf1f9cc", load_balancers.MonitorGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitor.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "allow_insecure": true, "consecutive_down": 0, "consecutive_up": 0, "created_on": "2014-01-01T05:20:00.12345Z", "description": "Login page monitor", "expected_body": "alive", "expected_codes": "2xx", "follow_redirects": true, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }, "interval": 0, "method": "GET", "modified_on": "2014-01-01T05:20:00.12345Z", "path": "/health", "port": 0, "probe_zone": "example.com", "retries": 0, "timeout": 0, "type": "https" }, "success": true } ``` ## Create Monitor `client.LoadBalancers.Monitors.New(ctx, params) (*Monitor, error)` **post** `/accounts/{account_id}/load_balancers/monitors` Create a configured monitor. ### Parameters - `params MonitorNewParams` - `AccountID param.Field[string]` Path param: Identifier. - `AllowInsecure param.Field[bool]` Body param: Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown param.Field[int64]` Body param: To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp param.Field[int64]` Body param: To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `Description param.Field[string]` Body param: Object description. - `ExpectedBody param.Field[string]` Body param: A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes param.Field[string]` Body param: The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects param.Field[bool]` Body param: Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header param.Field[map[string, []string]]` Body param: The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval param.Field[int64]` Body param: The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method param.Field[string]` Body param: The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `Path param.Field[string]` Body param: The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port param.Field[int64]` Body param: The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone param.Field[string]` Body param: Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries param.Field[int64]` Body param: The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout param.Field[int64]` Body param: The timeout (in seconds) before marking the health check as failed. - `Type param.Field[MonitorNewParamsType]` Body param: The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorNewParamsTypeHTTP MonitorNewParamsType = "http"` - `const MonitorNewParamsTypeHTTPS MonitorNewParamsType = "https"` - `const MonitorNewParamsTypeTCP MonitorNewParamsType = "tcp"` - `const MonitorNewParamsTypeUdpIcmp MonitorNewParamsType = "udp_icmp"` - `const MonitorNewParamsTypeIcmpPing MonitorNewParamsType = "icmp_ping"` - `const MonitorNewParamsTypeSmtp MonitorNewParamsType = "smtp"` ### Returns - `type Monitor struct{…}` - `ID string` - `AllowInsecure bool` Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown int64` To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp int64` To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `CreatedOn string` - `Description string` Object description. - `ExpectedBody string` A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes string` The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects bool` Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header map[string, []string]` The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval int64` The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method string` The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `ModifiedOn string` - `Path string` The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port int64` The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone string` Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries int64` The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout int64` The timeout (in seconds) before marking the health check as failed. - `Type MonitorType` The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorTypeHTTP MonitorType = "http"` - `const MonitorTypeHTTPS MonitorType = "https"` - `const MonitorTypeTCP MonitorType = "tcp"` - `const MonitorTypeUdpIcmp MonitorType = "udp_icmp"` - `const MonitorTypeIcmpPing MonitorType = "icmp_ping"` - `const MonitorTypeSmtp MonitorType = "smtp"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitor, err := client.LoadBalancers.Monitors.New(context.TODO(), load_balancers.MonitorNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitor.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "allow_insecure": true, "consecutive_down": 0, "consecutive_up": 0, "created_on": "2014-01-01T05:20:00.12345Z", "description": "Login page monitor", "expected_body": "alive", "expected_codes": "2xx", "follow_redirects": true, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }, "interval": 0, "method": "GET", "modified_on": "2014-01-01T05:20:00.12345Z", "path": "/health", "port": 0, "probe_zone": "example.com", "retries": 0, "timeout": 0, "type": "https" }, "success": true } ``` ## Update Monitor `client.LoadBalancers.Monitors.Update(ctx, monitorID, params) (*Monitor, error)` **put** `/accounts/{account_id}/load_balancers/monitors/{monitor_id}` Modify a configured monitor. ### Parameters - `monitorID string` - `params MonitorUpdateParams` - `AccountID param.Field[string]` Path param: Identifier. - `AllowInsecure param.Field[bool]` Body param: Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown param.Field[int64]` Body param: To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp param.Field[int64]` Body param: To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `Description param.Field[string]` Body param: Object description. - `ExpectedBody param.Field[string]` Body param: A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes param.Field[string]` Body param: The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects param.Field[bool]` Body param: Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header param.Field[map[string, []string]]` Body param: The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval param.Field[int64]` Body param: The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method param.Field[string]` Body param: The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `Path param.Field[string]` Body param: The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port param.Field[int64]` Body param: The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone param.Field[string]` Body param: Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries param.Field[int64]` Body param: The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout param.Field[int64]` Body param: The timeout (in seconds) before marking the health check as failed. - `Type param.Field[MonitorUpdateParamsType]` Body param: The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorUpdateParamsTypeHTTP MonitorUpdateParamsType = "http"` - `const MonitorUpdateParamsTypeHTTPS MonitorUpdateParamsType = "https"` - `const MonitorUpdateParamsTypeTCP MonitorUpdateParamsType = "tcp"` - `const MonitorUpdateParamsTypeUdpIcmp MonitorUpdateParamsType = "udp_icmp"` - `const MonitorUpdateParamsTypeIcmpPing MonitorUpdateParamsType = "icmp_ping"` - `const MonitorUpdateParamsTypeSmtp MonitorUpdateParamsType = "smtp"` ### Returns - `type Monitor struct{…}` - `ID string` - `AllowInsecure bool` Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown int64` To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp int64` To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `CreatedOn string` - `Description string` Object description. - `ExpectedBody string` A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes string` The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects bool` Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header map[string, []string]` The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval int64` The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method string` The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `ModifiedOn string` - `Path string` The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port int64` The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone string` Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries int64` The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout int64` The timeout (in seconds) before marking the health check as failed. - `Type MonitorType` The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorTypeHTTP MonitorType = "http"` - `const MonitorTypeHTTPS MonitorType = "https"` - `const MonitorTypeTCP MonitorType = "tcp"` - `const MonitorTypeUdpIcmp MonitorType = "udp_icmp"` - `const MonitorTypeIcmpPing MonitorType = "icmp_ping"` - `const MonitorTypeSmtp MonitorType = "smtp"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitor, err := client.LoadBalancers.Monitors.Update( context.TODO(), "f1aba936b94213e5b8dca0c0dbf1f9cc", load_balancers.MonitorUpdateParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitor.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "allow_insecure": true, "consecutive_down": 0, "consecutive_up": 0, "created_on": "2014-01-01T05:20:00.12345Z", "description": "Login page monitor", "expected_body": "alive", "expected_codes": "2xx", "follow_redirects": true, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }, "interval": 0, "method": "GET", "modified_on": "2014-01-01T05:20:00.12345Z", "path": "/health", "port": 0, "probe_zone": "example.com", "retries": 0, "timeout": 0, "type": "https" }, "success": true } ``` ## Patch Monitor `client.LoadBalancers.Monitors.Edit(ctx, monitorID, params) (*Monitor, error)` **patch** `/accounts/{account_id}/load_balancers/monitors/{monitor_id}` Apply changes to an existing monitor, overwriting the supplied properties. ### Parameters - `monitorID string` - `params MonitorEditParams` - `AccountID param.Field[string]` Path param: Identifier. - `AllowInsecure param.Field[bool]` Body param: Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown param.Field[int64]` Body param: To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp param.Field[int64]` Body param: To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `Description param.Field[string]` Body param: Object description. - `ExpectedBody param.Field[string]` Body param: A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes param.Field[string]` Body param: The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects param.Field[bool]` Body param: Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header param.Field[map[string, []string]]` Body param: The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval param.Field[int64]` Body param: The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method param.Field[string]` Body param: The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `Path param.Field[string]` Body param: The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port param.Field[int64]` Body param: The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone param.Field[string]` Body param: Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries param.Field[int64]` Body param: The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout param.Field[int64]` Body param: The timeout (in seconds) before marking the health check as failed. - `Type param.Field[MonitorEditParamsType]` Body param: The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorEditParamsTypeHTTP MonitorEditParamsType = "http"` - `const MonitorEditParamsTypeHTTPS MonitorEditParamsType = "https"` - `const MonitorEditParamsTypeTCP MonitorEditParamsType = "tcp"` - `const MonitorEditParamsTypeUdpIcmp MonitorEditParamsType = "udp_icmp"` - `const MonitorEditParamsTypeIcmpPing MonitorEditParamsType = "icmp_ping"` - `const MonitorEditParamsTypeSmtp MonitorEditParamsType = "smtp"` ### Returns - `type Monitor struct{…}` - `ID string` - `AllowInsecure bool` Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown int64` To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp int64` To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `CreatedOn string` - `Description string` Object description. - `ExpectedBody string` A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes string` The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects bool` Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header map[string, []string]` The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval int64` The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method string` The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `ModifiedOn string` - `Path string` The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port int64` The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone string` Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries int64` The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout int64` The timeout (in seconds) before marking the health check as failed. - `Type MonitorType` The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorTypeHTTP MonitorType = "http"` - `const MonitorTypeHTTPS MonitorType = "https"` - `const MonitorTypeTCP MonitorType = "tcp"` - `const MonitorTypeUdpIcmp MonitorType = "udp_icmp"` - `const MonitorTypeIcmpPing MonitorType = "icmp_ping"` - `const MonitorTypeSmtp MonitorType = "smtp"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitor, err := client.LoadBalancers.Monitors.Edit( context.TODO(), "f1aba936b94213e5b8dca0c0dbf1f9cc", load_balancers.MonitorEditParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitor.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "allow_insecure": true, "consecutive_down": 0, "consecutive_up": 0, "created_on": "2014-01-01T05:20:00.12345Z", "description": "Login page monitor", "expected_body": "alive", "expected_codes": "2xx", "follow_redirects": true, "header": { "Host": [ "example.com" ], "X-App-ID": [ "abc123" ] }, "interval": 0, "method": "GET", "modified_on": "2014-01-01T05:20:00.12345Z", "path": "/health", "port": 0, "probe_zone": "example.com", "retries": 0, "timeout": 0, "type": "https" }, "success": true } ``` ## Delete Monitor `client.LoadBalancers.Monitors.Delete(ctx, monitorID, body) (*MonitorDeleteResponse, error)` **delete** `/accounts/{account_id}/load_balancers/monitors/{monitor_id}` Delete a configured monitor. ### Parameters - `monitorID string` - `body MonitorDeleteParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type MonitorDeleteResponse struct{…}` - `ID string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitor, err := client.LoadBalancers.Monitors.Delete( context.TODO(), "f1aba936b94213e5b8dca0c0dbf1f9cc", load_balancers.MonitorDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitor.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "f1aba936b94213e5b8dca0c0dbf1f9cc" }, "success": true } ``` ## Domain Types ### Monitor - `type Monitor struct{…}` - `ID string` - `AllowInsecure bool` Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown int64` To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp int64` To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `CreatedOn string` - `Description string` Object description. - `ExpectedBody string` A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes string` The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects bool` Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header map[string, []string]` The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval int64` The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method string` The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `ModifiedOn string` - `Path string` The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port int64` The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone string` Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries int64` The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout int64` The timeout (in seconds) before marking the health check as failed. - `Type MonitorType` The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorTypeHTTP MonitorType = "http"` - `const MonitorTypeHTTPS MonitorType = "https"` - `const MonitorTypeTCP MonitorType = "tcp"` - `const MonitorTypeUdpIcmp MonitorType = "udp_icmp"` - `const MonitorTypeIcmpPing MonitorType = "icmp_ping"` - `const MonitorTypeSmtp MonitorType = "smtp"` # Previews ## Preview Monitor `client.LoadBalancers.Monitors.Previews.New(ctx, monitorID, params) (*MonitorPreviewNewResponse, error)` **post** `/accounts/{account_id}/load_balancers/monitors/{monitor_id}/preview` Preview pools using the specified monitor with provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results. ### Parameters - `monitorID string` - `params MonitorPreviewNewParams` - `AccountID param.Field[string]` Path param: Identifier. - `AllowInsecure param.Field[bool]` Body param: Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown param.Field[int64]` Body param: To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp param.Field[int64]` Body param: To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `Description param.Field[string]` Body param: Object description. - `ExpectedBody param.Field[string]` Body param: A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes param.Field[string]` Body param: The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects param.Field[bool]` Body param: Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header param.Field[map[string, []string]]` Body param: The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval param.Field[int64]` Body param: The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method param.Field[string]` Body param: The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `Path param.Field[string]` Body param: The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port param.Field[int64]` Body param: The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone param.Field[string]` Body param: Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries param.Field[int64]` Body param: The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout param.Field[int64]` Body param: The timeout (in seconds) before marking the health check as failed. - `Type param.Field[MonitorPreviewNewParamsType]` Body param: The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const MonitorPreviewNewParamsTypeHTTP MonitorPreviewNewParamsType = "http"` - `const MonitorPreviewNewParamsTypeHTTPS MonitorPreviewNewParamsType = "https"` - `const MonitorPreviewNewParamsTypeTCP MonitorPreviewNewParamsType = "tcp"` - `const MonitorPreviewNewParamsTypeUdpIcmp MonitorPreviewNewParamsType = "udp_icmp"` - `const MonitorPreviewNewParamsTypeIcmpPing MonitorPreviewNewParamsType = "icmp_ping"` - `const MonitorPreviewNewParamsTypeSmtp MonitorPreviewNewParamsType = "smtp"` ### Returns - `type MonitorPreviewNewResponse struct{…}` - `Pools map[string, string]` Monitored pool IDs mapped to their respective names. - `PreviewID string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) preview, err := client.LoadBalancers.Monitors.Previews.New( context.TODO(), "f1aba936b94213e5b8dca0c0dbf1f9cc", load_balancers.MonitorPreviewNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", preview.PreviewID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "pools": { "abwlnp5jbqn45ecgxd03erbgtxtqai0d": "WNAM Datacenter", "ve8h9lrcip5n5bbga9yqmdws28ay5d0l": "EEU Datacenter" }, "preview_id": "f1aba936b94213e5b8dca0c0dbf1f9cc" }, "success": true } ``` # References ## List Monitor References `client.LoadBalancers.Monitors.References.Get(ctx, monitorID, query) (*SinglePage[MonitorReferenceGetResponse], error)` **get** `/accounts/{account_id}/load_balancers/monitors/{monitor_id}/references` Get the list of resources that reference the provided monitor. ### Parameters - `monitorID string` - `query MonitorReferenceGetParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type MonitorReferenceGetResponse struct{…}` - `ReferenceType MonitorReferenceGetResponseReferenceType` - `const MonitorReferenceGetResponseReferenceTypeStar MonitorReferenceGetResponseReferenceType = "*"` - `const MonitorReferenceGetResponseReferenceTypeReferral MonitorReferenceGetResponseReferenceType = "referral"` - `const MonitorReferenceGetResponseReferenceTypeReferrer MonitorReferenceGetResponseReferenceType = "referrer"` - `ResourceID string` - `ResourceName string` - `ResourceType string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.LoadBalancers.Monitors.References.Get( context.TODO(), "f1aba936b94213e5b8dca0c0dbf1f9cc", load_balancers.MonitorReferenceGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "reference_type": "referrer", "resource_id": "17b5962d775c646f3f9725cbc7a53df4", "resource_name": "primary-dc-1", "resource_type": "pool" } ], "success": true } ``` # Monitor Groups ## List Monitor Groups `client.LoadBalancers.MonitorGroups.List(ctx, query) (*SinglePage[MonitorGroup], error)` **get** `/accounts/{account_id}/load_balancers/monitor_groups` List configured monitor groups. ### Parameters - `query MonitorGroupListParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type MonitorGroup struct{…}` - `ID string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Description string` A short description of the monitor group - `Members []MonitorGroupMember` List of monitors in this group - `Enabled bool` Whether this monitor is enabled in the group - `MonitorID string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitoringOnly bool` Whether this monitor is used for monitoring only (does not affect pool health) - `MustBeHealthy bool` Whether this monitor must be healthy for the pool to be considered healthy - `CreatedAt Time` The timestamp of when the monitor was added to the group - `UpdatedAt Time` The timestamp of when the monitor group member was last updated - `CreatedAt Time` The timestamp of when the monitor group was created - `UpdatedAt Time` The timestamp of when the monitor group was last updated ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.LoadBalancers.MonitorGroups.List(context.TODO(), load_balancers.MonitorGroupListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "id", "description": "Primary datacenter monitors", "members": [ { "enabled": true, "monitor_id": "monitor_id", "monitoring_only": false, "must_be_healthy": true, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } ], "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } ], "success": true, "result_info": { "count": 20, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Monitor Group Details `client.LoadBalancers.MonitorGroups.Get(ctx, monitorGroupID, query) (*MonitorGroup, error)` **get** `/accounts/{account_id}/load_balancers/monitor_groups/{monitor_group_id}` Fetch a single configured monitor group. ### Parameters - `monitorGroupID string` - `query MonitorGroupGetParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type MonitorGroup struct{…}` - `ID string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Description string` A short description of the monitor group - `Members []MonitorGroupMember` List of monitors in this group - `Enabled bool` Whether this monitor is enabled in the group - `MonitorID string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitoringOnly bool` Whether this monitor is used for monitoring only (does not affect pool health) - `MustBeHealthy bool` Whether this monitor must be healthy for the pool to be considered healthy - `CreatedAt Time` The timestamp of when the monitor was added to the group - `UpdatedAt Time` The timestamp of when the monitor group member was last updated - `CreatedAt Time` The timestamp of when the monitor group was created - `UpdatedAt Time` The timestamp of when the monitor group was last updated ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitorGroup, err := client.LoadBalancers.MonitorGroups.Get( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.MonitorGroupGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitorGroup.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "description": "Primary datacenter monitors", "members": [ { "enabled": true, "monitor_id": "monitor_id", "monitoring_only": false, "must_be_healthy": true, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } ], "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" }, "success": true } ``` ## Create Monitor Group `client.LoadBalancers.MonitorGroups.New(ctx, params) (*MonitorGroup, error)` **post** `/accounts/{account_id}/load_balancers/monitor_groups` Create a new monitor group. ### Parameters - `params MonitorGroupNewParams` - `AccountID param.Field[string]` Path param: Identifier. - `MonitorGroup param.Field[MonitorGroup]` Body param ### Returns - `type MonitorGroup struct{…}` - `ID string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Description string` A short description of the monitor group - `Members []MonitorGroupMember` List of monitors in this group - `Enabled bool` Whether this monitor is enabled in the group - `MonitorID string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitoringOnly bool` Whether this monitor is used for monitoring only (does not affect pool health) - `MustBeHealthy bool` Whether this monitor must be healthy for the pool to be considered healthy - `CreatedAt Time` The timestamp of when the monitor was added to the group - `UpdatedAt Time` The timestamp of when the monitor group member was last updated - `CreatedAt Time` The timestamp of when the monitor group was created - `UpdatedAt Time` The timestamp of when the monitor group was last updated ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitorGroup, err := client.LoadBalancers.MonitorGroups.New(context.TODO(), load_balancers.MonitorGroupNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), MonitorGroup: load_balancers.MonitorGroupParam{ ID: cloudflare.F("id"), Description: cloudflare.F("Primary datacenter monitors"), Members: cloudflare.F([]load_balancers.MonitorGroupMemberParam{load_balancers.MonitorGroupMemberParam{ Enabled: cloudflare.F(true), MonitorID: cloudflare.F("monitor_id"), MonitoringOnly: cloudflare.F(false), MustBeHealthy: cloudflare.F(true), }}), }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitorGroup.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "description": "Primary datacenter monitors", "members": [ { "enabled": true, "monitor_id": "monitor_id", "monitoring_only": false, "must_be_healthy": true, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } ], "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" }, "success": true } ``` ## Update Monitor Group `client.LoadBalancers.MonitorGroups.Update(ctx, monitorGroupID, params) (*MonitorGroup, error)` **put** `/accounts/{account_id}/load_balancers/monitor_groups/{monitor_group_id}` Modify a configured monitor group. ### Parameters - `monitorGroupID string` - `params MonitorGroupUpdateParams` - `AccountID param.Field[string]` Path param: Identifier. - `MonitorGroup param.Field[MonitorGroup]` Body param ### Returns - `type MonitorGroup struct{…}` - `ID string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Description string` A short description of the monitor group - `Members []MonitorGroupMember` List of monitors in this group - `Enabled bool` Whether this monitor is enabled in the group - `MonitorID string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitoringOnly bool` Whether this monitor is used for monitoring only (does not affect pool health) - `MustBeHealthy bool` Whether this monitor must be healthy for the pool to be considered healthy - `CreatedAt Time` The timestamp of when the monitor was added to the group - `UpdatedAt Time` The timestamp of when the monitor group member was last updated - `CreatedAt Time` The timestamp of when the monitor group was created - `UpdatedAt Time` The timestamp of when the monitor group was last updated ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitorGroup, err := client.LoadBalancers.MonitorGroups.Update( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.MonitorGroupUpdateParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), MonitorGroup: load_balancers.MonitorGroupParam{ ID: cloudflare.F("id"), Description: cloudflare.F("Primary datacenter monitors"), Members: cloudflare.F([]load_balancers.MonitorGroupMemberParam{load_balancers.MonitorGroupMemberParam{ Enabled: cloudflare.F(true), MonitorID: cloudflare.F("monitor_id"), MonitoringOnly: cloudflare.F(false), MustBeHealthy: cloudflare.F(true), }}), }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitorGroup.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "description": "Primary datacenter monitors", "members": [ { "enabled": true, "monitor_id": "monitor_id", "monitoring_only": false, "must_be_healthy": true, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } ], "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" }, "success": true } ``` ## Patch Monitor Group `client.LoadBalancers.MonitorGroups.Edit(ctx, monitorGroupID, params) (*MonitorGroup, error)` **patch** `/accounts/{account_id}/load_balancers/monitor_groups/{monitor_group_id}` Apply changes to an existing monitor group, overwriting the supplied properties. ### Parameters - `monitorGroupID string` - `params MonitorGroupEditParams` - `AccountID param.Field[string]` Path param: Identifier. - `MonitorGroup param.Field[MonitorGroup]` Body param ### Returns - `type MonitorGroup struct{…}` - `ID string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Description string` A short description of the monitor group - `Members []MonitorGroupMember` List of monitors in this group - `Enabled bool` Whether this monitor is enabled in the group - `MonitorID string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitoringOnly bool` Whether this monitor is used for monitoring only (does not affect pool health) - `MustBeHealthy bool` Whether this monitor must be healthy for the pool to be considered healthy - `CreatedAt Time` The timestamp of when the monitor was added to the group - `UpdatedAt Time` The timestamp of when the monitor group member was last updated - `CreatedAt Time` The timestamp of when the monitor group was created - `UpdatedAt Time` The timestamp of when the monitor group was last updated ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitorGroup, err := client.LoadBalancers.MonitorGroups.Edit( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.MonitorGroupEditParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), MonitorGroup: load_balancers.MonitorGroupParam{ ID: cloudflare.F("id"), Description: cloudflare.F("Primary datacenter monitors"), Members: cloudflare.F([]load_balancers.MonitorGroupMemberParam{load_balancers.MonitorGroupMemberParam{ Enabled: cloudflare.F(true), MonitorID: cloudflare.F("monitor_id"), MonitoringOnly: cloudflare.F(false), MustBeHealthy: cloudflare.F(true), }}), }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitorGroup.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "description": "Primary datacenter monitors", "members": [ { "enabled": true, "monitor_id": "monitor_id", "monitoring_only": false, "must_be_healthy": true, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } ], "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" }, "success": true } ``` ## Delete Monitor Group `client.LoadBalancers.MonitorGroups.Delete(ctx, monitorGroupID, body) (*MonitorGroup, error)` **delete** `/accounts/{account_id}/load_balancers/monitor_groups/{monitor_group_id}` Delete a configured monitor group. ### Parameters - `monitorGroupID string` - `body MonitorGroupDeleteParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type MonitorGroup struct{…}` - `ID string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Description string` A short description of the monitor group - `Members []MonitorGroupMember` List of monitors in this group - `Enabled bool` Whether this monitor is enabled in the group - `MonitorID string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitoringOnly bool` Whether this monitor is used for monitoring only (does not affect pool health) - `MustBeHealthy bool` Whether this monitor must be healthy for the pool to be considered healthy - `CreatedAt Time` The timestamp of when the monitor was added to the group - `UpdatedAt Time` The timestamp of when the monitor group member was last updated - `CreatedAt Time` The timestamp of when the monitor group was created - `UpdatedAt Time` The timestamp of when the monitor group was last updated ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) monitorGroup, err := client.LoadBalancers.MonitorGroups.Delete( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.MonitorGroupDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", monitorGroup.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "id", "description": "Primary datacenter monitors", "members": [ { "enabled": true, "monitor_id": "monitor_id", "monitoring_only": false, "must_be_healthy": true, "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" } ], "created_at": "2014-01-01T05:20:00.12345Z", "updated_at": "2014-01-01T05:20:00.12345Z" }, "success": true } ``` ## Domain Types ### Monitor Group - `type MonitorGroup struct{…}` - `ID string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Description string` A short description of the monitor group - `Members []MonitorGroupMember` List of monitors in this group - `Enabled bool` Whether this monitor is enabled in the group - `MonitorID string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitoringOnly bool` Whether this monitor is used for monitoring only (does not affect pool health) - `MustBeHealthy bool` Whether this monitor must be healthy for the pool to be considered healthy - `CreatedAt Time` The timestamp of when the monitor was added to the group - `UpdatedAt Time` The timestamp of when the monitor group member was last updated - `CreatedAt Time` The timestamp of when the monitor group was created - `UpdatedAt Time` The timestamp of when the monitor group was last updated # Pools ## List Pools `client.LoadBalancers.Pools.List(ctx, params) (*SinglePage[Pool], error)` **get** `/accounts/{account_id}/load_balancers/pools` List configured pools. ### Parameters - `params PoolListParams` - `AccountID param.Field[string]` Path param: Identifier. - `Monitor param.Field[string]` Query param: The ID of the Monitor to use for checking the health of origins within this pool. ### Returns - `type Pool struct{…}` - `ID string` - `CheckRegions []CheckRegion` A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `CreatedOn string` - `Description string` A human-readable description of the pool. - `DisabledAt Time` This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at. - `Enabled bool` 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 float64` 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. - `LoadShedding LoadShedding` Configures load shedding policies and percentages for the pool. - `DefaultPercent float64` The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity. - `DefaultPolicy LoadSheddingDefaultPolicy` The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs. - `const LoadSheddingDefaultPolicyRandom LoadSheddingDefaultPolicy = "random"` - `const LoadSheddingDefaultPolicyHash LoadSheddingDefaultPolicy = "hash"` - `SessionPercent float64` The percent of existing sessions to shed from the pool, according to the session policy. - `SessionPolicy LoadSheddingSessionPolicy` Only the hash policy is supported for existing sessions (to avoid exponential decay). - `const LoadSheddingSessionPolicyHash LoadSheddingSessionPolicy = "hash"` - `Longitude float64` 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. - `MinimumOrigins int64` 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. - `ModifiedOn string` - `Monitor string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Name string` A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `NotificationEmail 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. - `NotificationFilter NotificationFilter` Filter pool and origin health notifications by resource type or health status. Use null to reset. - `Origin FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). - `Pool FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `OriginSteering OriginSteering` Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Policy OriginSteeringPolicy` The type of origin steering policy to use. - `"random"`: Select an origin randomly. - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP address. - `"least_outstanding_requests"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others. - `"least_connections"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. - `const OriginSteeringPolicyRandom OriginSteeringPolicy = "random"` - `const OriginSteeringPolicyHash OriginSteeringPolicy = "hash"` - `const OriginSteeringPolicyLeastOutstandingRequests OriginSteeringPolicy = "least_outstanding_requests"` - `const OriginSteeringPolicyLeastConnections OriginSteeringPolicy = "least_connections"` - `Origins []Origin` 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.LoadBalancers.Pools.List(context.TODO(), load_balancers.PoolListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "17b5962d775c646f3f9725cbc7a53df4", "check_regions": [ "WEU", "ENAM" ], "created_on": "2014-01-01T05:20:00.12345Z", "description": "Primary data center - Provider XYZ", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": false, "latitude": 0, "load_shedding": { "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }, "longitude": 0, "minimum_origins": 0, "modified_on": "2014-01-01T05:20:00.12345Z", "monitor": "monitor", "monitor_group": "monitor_group", "name": "primary-dc-1", "networks": [ "string" ], "notification_email": "someone@example.com,sometwo@example.com", "notification_filter": { "origin": { "disable": true, "healthy": true }, "pool": { "disable": true, "healthy": false } }, "origin_steering": { "policy": "random" }, "origins": [ { "address": "0.0.0.0", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": true, "header": { "Host": [ "example.com" ] }, "name": "app-server-1", "port": 0, "virtual_network_id": "a5624d4e-044a-4ff0-b3e1-e2465353d4b4", "weight": 0.6 } ] } ], "success": true, "result_info": { "count": 20, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Pool Details `client.LoadBalancers.Pools.Get(ctx, poolID, query) (*Pool, error)` **get** `/accounts/{account_id}/load_balancers/pools/{pool_id}` Fetch a single configured pool. ### Parameters - `poolID string` - `query PoolGetParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type Pool struct{…}` - `ID string` - `CheckRegions []CheckRegion` A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `CreatedOn string` - `Description string` A human-readable description of the pool. - `DisabledAt Time` This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at. - `Enabled bool` 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 float64` 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. - `LoadShedding LoadShedding` Configures load shedding policies and percentages for the pool. - `DefaultPercent float64` The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity. - `DefaultPolicy LoadSheddingDefaultPolicy` The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs. - `const LoadSheddingDefaultPolicyRandom LoadSheddingDefaultPolicy = "random"` - `const LoadSheddingDefaultPolicyHash LoadSheddingDefaultPolicy = "hash"` - `SessionPercent float64` The percent of existing sessions to shed from the pool, according to the session policy. - `SessionPolicy LoadSheddingSessionPolicy` Only the hash policy is supported for existing sessions (to avoid exponential decay). - `const LoadSheddingSessionPolicyHash LoadSheddingSessionPolicy = "hash"` - `Longitude float64` 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. - `MinimumOrigins int64` 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. - `ModifiedOn string` - `Monitor string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Name string` A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `NotificationEmail 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. - `NotificationFilter NotificationFilter` Filter pool and origin health notifications by resource type or health status. Use null to reset. - `Origin FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). - `Pool FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `OriginSteering OriginSteering` Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Policy OriginSteeringPolicy` The type of origin steering policy to use. - `"random"`: Select an origin randomly. - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP address. - `"least_outstanding_requests"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others. - `"least_connections"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. - `const OriginSteeringPolicyRandom OriginSteeringPolicy = "random"` - `const OriginSteeringPolicyHash OriginSteeringPolicy = "hash"` - `const OriginSteeringPolicyLeastOutstandingRequests OriginSteeringPolicy = "least_outstanding_requests"` - `const OriginSteeringPolicyLeastConnections OriginSteeringPolicy = "least_connections"` - `Origins []Origin` 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) pool, err := client.LoadBalancers.Pools.Get( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.PoolGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", pool.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "17b5962d775c646f3f9725cbc7a53df4", "check_regions": [ "WEU", "ENAM" ], "created_on": "2014-01-01T05:20:00.12345Z", "description": "Primary data center - Provider XYZ", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": false, "latitude": 0, "load_shedding": { "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }, "longitude": 0, "minimum_origins": 0, "modified_on": "2014-01-01T05:20:00.12345Z", "monitor": "monitor", "monitor_group": "monitor_group", "name": "primary-dc-1", "networks": [ "string" ], "notification_email": "someone@example.com,sometwo@example.com", "notification_filter": { "origin": { "disable": true, "healthy": true }, "pool": { "disable": true, "healthy": false } }, "origin_steering": { "policy": "random" }, "origins": [ { "address": "0.0.0.0", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": true, "header": { "Host": [ "example.com" ] }, "name": "app-server-1", "port": 0, "virtual_network_id": "a5624d4e-044a-4ff0-b3e1-e2465353d4b4", "weight": 0.6 } ] }, "success": true } ``` ## Create Pool `client.LoadBalancers.Pools.New(ctx, params) (*Pool, error)` **post** `/accounts/{account_id}/load_balancers/pools` Create a new pool. ### Parameters - `params PoolNewParams` - `AccountID param.Field[string]` Path param: Identifier. - `Name param.Field[string]` Body param: A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Origins param.Field[[]Origin]` Body param: 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. - `Description param.Field[string]` Body param: A human-readable description of the pool. - `Enabled param.Field[bool]` Body param: 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 param.Field[float64]` Body param: 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. - `LoadShedding param.Field[LoadShedding]` Body param: Configures load shedding policies and percentages for the pool. - `Longitude param.Field[float64]` Body param: 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. - `MinimumOrigins param.Field[int64]` Body param: 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. - `Monitor param.Field[string]` Body param: The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup param.Field[string]` Body param: The ID of the Monitor Group to use for checking the health of origins within this pool. - `NotificationEmail param.Field[string]` Body param: 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. - `NotificationFilter param.Field[NotificationFilter]` Body param: Filter pool and origin health notifications by resource type or health status. Use null to reset. - `OriginSteering param.Field[OriginSteering]` Body param: Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. ### Returns - `type Pool struct{…}` - `ID string` - `CheckRegions []CheckRegion` A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `CreatedOn string` - `Description string` A human-readable description of the pool. - `DisabledAt Time` This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at. - `Enabled bool` 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 float64` 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. - `LoadShedding LoadShedding` Configures load shedding policies and percentages for the pool. - `DefaultPercent float64` The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity. - `DefaultPolicy LoadSheddingDefaultPolicy` The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs. - `const LoadSheddingDefaultPolicyRandom LoadSheddingDefaultPolicy = "random"` - `const LoadSheddingDefaultPolicyHash LoadSheddingDefaultPolicy = "hash"` - `SessionPercent float64` The percent of existing sessions to shed from the pool, according to the session policy. - `SessionPolicy LoadSheddingSessionPolicy` Only the hash policy is supported for existing sessions (to avoid exponential decay). - `const LoadSheddingSessionPolicyHash LoadSheddingSessionPolicy = "hash"` - `Longitude float64` 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. - `MinimumOrigins int64` 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. - `ModifiedOn string` - `Monitor string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Name string` A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `NotificationEmail 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. - `NotificationFilter NotificationFilter` Filter pool and origin health notifications by resource type or health status. Use null to reset. - `Origin FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). - `Pool FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `OriginSteering OriginSteering` Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Policy OriginSteeringPolicy` The type of origin steering policy to use. - `"random"`: Select an origin randomly. - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP address. - `"least_outstanding_requests"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others. - `"least_connections"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. - `const OriginSteeringPolicyRandom OriginSteeringPolicy = "random"` - `const OriginSteeringPolicyHash OriginSteeringPolicy = "hash"` - `const OriginSteeringPolicyLeastOutstandingRequests OriginSteeringPolicy = "least_outstanding_requests"` - `const OriginSteeringPolicyLeastConnections OriginSteeringPolicy = "least_connections"` - `Origins []Origin` 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) pool, err := client.LoadBalancers.Pools.New(context.TODO(), load_balancers.PoolNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Name: cloudflare.F("primary-dc-1"), Origins: cloudflare.F([]load_balancers.OriginParam{load_balancers.OriginParam{ }}), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", pool.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "17b5962d775c646f3f9725cbc7a53df4", "check_regions": [ "WEU", "ENAM" ], "created_on": "2014-01-01T05:20:00.12345Z", "description": "Primary data center - Provider XYZ", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": false, "latitude": 0, "load_shedding": { "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }, "longitude": 0, "minimum_origins": 0, "modified_on": "2014-01-01T05:20:00.12345Z", "monitor": "monitor", "monitor_group": "monitor_group", "name": "primary-dc-1", "networks": [ "string" ], "notification_email": "someone@example.com,sometwo@example.com", "notification_filter": { "origin": { "disable": true, "healthy": true }, "pool": { "disable": true, "healthy": false } }, "origin_steering": { "policy": "random" }, "origins": [ { "address": "0.0.0.0", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": true, "header": { "Host": [ "example.com" ] }, "name": "app-server-1", "port": 0, "virtual_network_id": "a5624d4e-044a-4ff0-b3e1-e2465353d4b4", "weight": 0.6 } ] }, "success": true } ``` ## Update Pool `client.LoadBalancers.Pools.Update(ctx, poolID, params) (*Pool, error)` **put** `/accounts/{account_id}/load_balancers/pools/{pool_id}` Modify a configured pool. ### Parameters - `poolID string` - `params PoolUpdateParams` - `AccountID param.Field[string]` Path param: Identifier. - `Name param.Field[string]` Body param: A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Origins param.Field[[]Origin]` Body param: 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. - `CheckRegions param.Field[[]CheckRegion]` Body param: A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `Description param.Field[string]` Body param: A human-readable description of the pool. - `Enabled param.Field[bool]` Body param: 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 param.Field[float64]` Body param: 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. - `LoadShedding param.Field[LoadShedding]` Body param: Configures load shedding policies and percentages for the pool. - `Longitude param.Field[float64]` Body param: 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. - `MinimumOrigins param.Field[int64]` Body param: 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. - `Monitor param.Field[string]` Body param: The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup param.Field[string]` Body param: The ID of the Monitor Group to use for checking the health of origins within this pool. - `NotificationEmail param.Field[string]` Body param: 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. - `NotificationFilter param.Field[NotificationFilter]` Body param: Filter pool and origin health notifications by resource type or health status. Use null to reset. - `OriginSteering param.Field[OriginSteering]` Body param: Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. ### Returns - `type Pool struct{…}` - `ID string` - `CheckRegions []CheckRegion` A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `CreatedOn string` - `Description string` A human-readable description of the pool. - `DisabledAt Time` This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at. - `Enabled bool` 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 float64` 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. - `LoadShedding LoadShedding` Configures load shedding policies and percentages for the pool. - `DefaultPercent float64` The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity. - `DefaultPolicy LoadSheddingDefaultPolicy` The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs. - `const LoadSheddingDefaultPolicyRandom LoadSheddingDefaultPolicy = "random"` - `const LoadSheddingDefaultPolicyHash LoadSheddingDefaultPolicy = "hash"` - `SessionPercent float64` The percent of existing sessions to shed from the pool, according to the session policy. - `SessionPolicy LoadSheddingSessionPolicy` Only the hash policy is supported for existing sessions (to avoid exponential decay). - `const LoadSheddingSessionPolicyHash LoadSheddingSessionPolicy = "hash"` - `Longitude float64` 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. - `MinimumOrigins int64` 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. - `ModifiedOn string` - `Monitor string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Name string` A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `NotificationEmail 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. - `NotificationFilter NotificationFilter` Filter pool and origin health notifications by resource type or health status. Use null to reset. - `Origin FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). - `Pool FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `OriginSteering OriginSteering` Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Policy OriginSteeringPolicy` The type of origin steering policy to use. - `"random"`: Select an origin randomly. - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP address. - `"least_outstanding_requests"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others. - `"least_connections"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. - `const OriginSteeringPolicyRandom OriginSteeringPolicy = "random"` - `const OriginSteeringPolicyHash OriginSteeringPolicy = "hash"` - `const OriginSteeringPolicyLeastOutstandingRequests OriginSteeringPolicy = "least_outstanding_requests"` - `const OriginSteeringPolicyLeastConnections OriginSteeringPolicy = "least_connections"` - `Origins []Origin` 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) pool, err := client.LoadBalancers.Pools.Update( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.PoolUpdateParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Name: cloudflare.F("primary-dc-1"), Origins: cloudflare.F([]load_balancers.OriginParam{load_balancers.OriginParam{ }}), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", pool.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "17b5962d775c646f3f9725cbc7a53df4", "check_regions": [ "WEU", "ENAM" ], "created_on": "2014-01-01T05:20:00.12345Z", "description": "Primary data center - Provider XYZ", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": false, "latitude": 0, "load_shedding": { "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }, "longitude": 0, "minimum_origins": 0, "modified_on": "2014-01-01T05:20:00.12345Z", "monitor": "monitor", "monitor_group": "monitor_group", "name": "primary-dc-1", "networks": [ "string" ], "notification_email": "someone@example.com,sometwo@example.com", "notification_filter": { "origin": { "disable": true, "healthy": true }, "pool": { "disable": true, "healthy": false } }, "origin_steering": { "policy": "random" }, "origins": [ { "address": "0.0.0.0", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": true, "header": { "Host": [ "example.com" ] }, "name": "app-server-1", "port": 0, "virtual_network_id": "a5624d4e-044a-4ff0-b3e1-e2465353d4b4", "weight": 0.6 } ] }, "success": true } ``` ## Patch Pool `client.LoadBalancers.Pools.Edit(ctx, poolID, params) (*Pool, error)` **patch** `/accounts/{account_id}/load_balancers/pools/{pool_id}` Apply changes to an existing pool, overwriting the supplied properties. ### Parameters - `poolID string` - `params PoolEditParams` - `AccountID param.Field[string]` Path param: Identifier. - `CheckRegions param.Field[[]CheckRegion]` Body param: A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `Description param.Field[string]` Body param: A human-readable description of the pool. - `Enabled param.Field[bool]` Body param: 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 param.Field[float64]` Body param: 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. - `LoadShedding param.Field[LoadShedding]` Body param: Configures load shedding policies and percentages for the pool. - `Longitude param.Field[float64]` Body param: 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. - `MinimumOrigins param.Field[int64]` Body param: 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. - `Monitor param.Field[string]` Body param: The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup param.Field[string]` Body param: The ID of the Monitor Group to use for checking the health of origins within this pool. - `Name param.Field[string]` Body param: A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `NotificationEmail param.Field[string]` Body param: 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. - `NotificationFilter param.Field[NotificationFilter]` Body param: Filter pool and origin health notifications by resource type or health status. Use null to reset. - `OriginSteering param.Field[OriginSteering]` Body param: Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Origins param.Field[[]Origin]` Body param: 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. ### Returns - `type Pool struct{…}` - `ID string` - `CheckRegions []CheckRegion` A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `CreatedOn string` - `Description string` A human-readable description of the pool. - `DisabledAt Time` This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at. - `Enabled bool` 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 float64` 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. - `LoadShedding LoadShedding` Configures load shedding policies and percentages for the pool. - `DefaultPercent float64` The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity. - `DefaultPolicy LoadSheddingDefaultPolicy` The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs. - `const LoadSheddingDefaultPolicyRandom LoadSheddingDefaultPolicy = "random"` - `const LoadSheddingDefaultPolicyHash LoadSheddingDefaultPolicy = "hash"` - `SessionPercent float64` The percent of existing sessions to shed from the pool, according to the session policy. - `SessionPolicy LoadSheddingSessionPolicy` Only the hash policy is supported for existing sessions (to avoid exponential decay). - `const LoadSheddingSessionPolicyHash LoadSheddingSessionPolicy = "hash"` - `Longitude float64` 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. - `MinimumOrigins int64` 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. - `ModifiedOn string` - `Monitor string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Name string` A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `NotificationEmail 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. - `NotificationFilter NotificationFilter` Filter pool and origin health notifications by resource type or health status. Use null to reset. - `Origin FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). - `Pool FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `OriginSteering OriginSteering` Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Policy OriginSteeringPolicy` The type of origin steering policy to use. - `"random"`: Select an origin randomly. - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP address. - `"least_outstanding_requests"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others. - `"least_connections"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. - `const OriginSteeringPolicyRandom OriginSteeringPolicy = "random"` - `const OriginSteeringPolicyHash OriginSteeringPolicy = "hash"` - `const OriginSteeringPolicyLeastOutstandingRequests OriginSteeringPolicy = "least_outstanding_requests"` - `const OriginSteeringPolicyLeastConnections OriginSteeringPolicy = "least_connections"` - `Origins []Origin` 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) pool, err := client.LoadBalancers.Pools.Edit( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.PoolEditParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", pool.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "17b5962d775c646f3f9725cbc7a53df4", "check_regions": [ "WEU", "ENAM" ], "created_on": "2014-01-01T05:20:00.12345Z", "description": "Primary data center - Provider XYZ", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": false, "latitude": 0, "load_shedding": { "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }, "longitude": 0, "minimum_origins": 0, "modified_on": "2014-01-01T05:20:00.12345Z", "monitor": "monitor", "monitor_group": "monitor_group", "name": "primary-dc-1", "networks": [ "string" ], "notification_email": "someone@example.com,sometwo@example.com", "notification_filter": { "origin": { "disable": true, "healthy": true }, "pool": { "disable": true, "healthy": false } }, "origin_steering": { "policy": "random" }, "origins": [ { "address": "0.0.0.0", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": true, "header": { "Host": [ "example.com" ] }, "name": "app-server-1", "port": 0, "virtual_network_id": "a5624d4e-044a-4ff0-b3e1-e2465353d4b4", "weight": 0.6 } ] }, "success": true } ``` ## Delete Pool `client.LoadBalancers.Pools.Delete(ctx, poolID, body) (*PoolDeleteResponse, error)` **delete** `/accounts/{account_id}/load_balancers/pools/{pool_id}` Delete a configured pool. ### Parameters - `poolID string` - `body PoolDeleteParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type PoolDeleteResponse struct{…}` - `ID string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) pool, err := client.LoadBalancers.Pools.Delete( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.PoolDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", pool.ID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "id": "17b5962d775c646f3f9725cbc7a53df4" }, "success": true } ``` ## Patch Pools `client.LoadBalancers.Pools.BulkEdit(ctx, params) (*SinglePage[Pool], error)` **patch** `/accounts/{account_id}/load_balancers/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`. ### Parameters - `params PoolBulkEditParams` - `AccountID param.Field[string]` Path param: Identifier. - `NotificationEmail param.Field[PoolBulkEditParamsNotificationEmail]` Body param: The email address to send health status notifications to. This field is now deprecated in favor of Cloudflare Notifications for Load Balancing, so only resetting this field with an empty string `""` is accepted. - `const PoolBulkEditParamsNotificationEmailEmpty PoolBulkEditParamsNotificationEmail = ""` ### Returns - `type Pool struct{…}` - `ID string` - `CheckRegions []CheckRegion` A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `CreatedOn string` - `Description string` A human-readable description of the pool. - `DisabledAt Time` This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at. - `Enabled bool` 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 float64` 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. - `LoadShedding LoadShedding` Configures load shedding policies and percentages for the pool. - `DefaultPercent float64` The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity. - `DefaultPolicy LoadSheddingDefaultPolicy` The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs. - `const LoadSheddingDefaultPolicyRandom LoadSheddingDefaultPolicy = "random"` - `const LoadSheddingDefaultPolicyHash LoadSheddingDefaultPolicy = "hash"` - `SessionPercent float64` The percent of existing sessions to shed from the pool, according to the session policy. - `SessionPolicy LoadSheddingSessionPolicy` Only the hash policy is supported for existing sessions (to avoid exponential decay). - `const LoadSheddingSessionPolicyHash LoadSheddingSessionPolicy = "hash"` - `Longitude float64` 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. - `MinimumOrigins int64` 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. - `ModifiedOn string` - `Monitor string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Name string` A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `NotificationEmail 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. - `NotificationFilter NotificationFilter` Filter pool and origin health notifications by resource type or health status. Use null to reset. - `Origin FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). - `Pool FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `OriginSteering OriginSteering` Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Policy OriginSteeringPolicy` The type of origin steering policy to use. - `"random"`: Select an origin randomly. - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP address. - `"least_outstanding_requests"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others. - `"least_connections"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. - `const OriginSteeringPolicyRandom OriginSteeringPolicy = "random"` - `const OriginSteeringPolicyHash OriginSteeringPolicy = "hash"` - `const OriginSteeringPolicyLeastOutstandingRequests OriginSteeringPolicy = "least_outstanding_requests"` - `const OriginSteeringPolicyLeastConnections OriginSteeringPolicy = "least_connections"` - `Origins []Origin` 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.LoadBalancers.Pools.BulkEdit(context.TODO(), load_balancers.PoolBulkEditParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "id": "17b5962d775c646f3f9725cbc7a53df4", "check_regions": [ "WEU", "ENAM" ], "created_on": "2014-01-01T05:20:00.12345Z", "description": "Primary data center - Provider XYZ", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": false, "latitude": 0, "load_shedding": { "default_percent": 0, "default_policy": "random", "session_percent": 0, "session_policy": "hash" }, "longitude": 0, "minimum_origins": 0, "modified_on": "2014-01-01T05:20:00.12345Z", "monitor": "monitor", "monitor_group": "monitor_group", "name": "primary-dc-1", "networks": [ "string" ], "notification_email": "someone@example.com,sometwo@example.com", "notification_filter": { "origin": { "disable": true, "healthy": true }, "pool": { "disable": true, "healthy": false } }, "origin_steering": { "policy": "random" }, "origins": [ { "address": "0.0.0.0", "disabled_at": "2019-12-27T18:11:19.117Z", "enabled": true, "header": { "Host": [ "example.com" ] }, "name": "app-server-1", "port": 0, "virtual_network_id": "a5624d4e-044a-4ff0-b3e1-e2465353d4b4", "weight": 0.6 } ] } ], "success": true, "result_info": { "count": 20, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ``` ## Domain Types ### Pool - `type Pool struct{…}` - `ID string` - `CheckRegions []CheckRegion` A list of regions from which to run health checks. Null means every Cloudflare data center. - `const CheckRegionWnam CheckRegion = "WNAM"` - `const CheckRegionEnam CheckRegion = "ENAM"` - `const CheckRegionWeu CheckRegion = "WEU"` - `const CheckRegionEeu CheckRegion = "EEU"` - `const CheckRegionNsam CheckRegion = "NSAM"` - `const CheckRegionSsam CheckRegion = "SSAM"` - `const CheckRegionOc CheckRegion = "OC"` - `const CheckRegionMe CheckRegion = "ME"` - `const CheckRegionNaf CheckRegion = "NAF"` - `const CheckRegionSaf CheckRegion = "SAF"` - `const CheckRegionSas CheckRegion = "SAS"` - `const CheckRegionSeas CheckRegion = "SEAS"` - `const CheckRegionNeas CheckRegion = "NEAS"` - `const CheckRegionAllRegions CheckRegion = "ALL_REGIONS"` - `CreatedOn string` - `Description string` A human-readable description of the pool. - `DisabledAt Time` This field shows up only if the pool is disabled. This field is set with the time the pool was disabled at. - `Enabled bool` 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 float64` 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. - `LoadShedding LoadShedding` Configures load shedding policies and percentages for the pool. - `DefaultPercent float64` The percent of traffic to shed from the pool, according to the default policy. Applies to new sessions and traffic without session affinity. - `DefaultPolicy LoadSheddingDefaultPolicy` The default policy to use when load shedding. A random policy randomly sheds a given percent of requests. A hash policy computes a hash over the CF-Connecting-IP address and sheds all requests originating from a percent of IPs. - `const LoadSheddingDefaultPolicyRandom LoadSheddingDefaultPolicy = "random"` - `const LoadSheddingDefaultPolicyHash LoadSheddingDefaultPolicy = "hash"` - `SessionPercent float64` The percent of existing sessions to shed from the pool, according to the session policy. - `SessionPolicy LoadSheddingSessionPolicy` Only the hash policy is supported for existing sessions (to avoid exponential decay). - `const LoadSheddingSessionPolicyHash LoadSheddingSessionPolicy = "hash"` - `Longitude float64` 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. - `MinimumOrigins int64` 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. - `ModifiedOn string` - `Monitor string` The ID of the Monitor to use for checking the health of origins within this pool. - `MonitorGroup string` The ID of the Monitor Group to use for checking the health of origins within this pool. - `Name string` A short name (tag) for the pool. Only alphanumeric characters, hyphens, and underscores are allowed. - `Networks []string` List of networks where Load Balancer or Pool is enabled. - `NotificationEmail 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. - `NotificationFilter NotificationFilter` Filter pool and origin health notifications by resource type or health status. Use null to reset. - `Origin FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `Disable bool` If set true, disable notifications for this type of resource (pool or origin). - `Healthy bool` If present, send notifications only for this health status (e.g. false for only DOWN events). Use null to reset (all events). - `Pool FilterOptions` Filter options for a particular resource type (pool or origin). Use null to reset. - `OriginSteering OriginSteering` Configures origin steering for the pool. Controls how origins are selected for new sessions and traffic without session affinity. - `Policy OriginSteeringPolicy` The type of origin steering policy to use. - `"random"`: Select an origin randomly. - `"hash"`: Select an origin by computing a hash over the CF-Connecting-IP address. - `"least_outstanding_requests"`: Select an origin by taking into consideration origin weights, as well as each origin's number of outstanding requests. Origins with more pending requests are weighted proportionately less relative to others. - `"least_connections"`: Select an origin by taking into consideration origin weights, as well as each origin's number of open connections. Origins with more open connections are weighted proportionately less relative to others. Supported for HTTP/1 and HTTP/2 connections. - `const OriginSteeringPolicyRandom OriginSteeringPolicy = "random"` - `const OriginSteeringPolicyHash OriginSteeringPolicy = "hash"` - `const OriginSteeringPolicyLeastOutstandingRequests OriginSteeringPolicy = "least_outstanding_requests"` - `const OriginSteeringPolicyLeastConnections OriginSteeringPolicy = "least_connections"` - `Origins []Origin` 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. - `Address string` The IP address (IPv4 or IPv6) of the origin, or its publicly addressable hostname. Hostnames entered here should resolve directly to the origin, and not be a hostname proxied by Cloudflare. To set an internal/reserved address, virtual_network_id must also be set. - `DisabledAt Time` This field shows up only if the origin is disabled. This field is set with the time the origin was disabled. - `Enabled bool` Whether to enable (the default) this origin within the pool. Disabled origins will not receive traffic and are excluded from health checks. The origin will only be disabled for the current pool. - `Header Header` The request header is used to pass additional information with an HTTP request. Currently supported header is 'Host'. - `Host []Host` The 'Host' header allows to override the hostname set in the HTTP request. Current support is 1 'Host' header override per origin. - `Name string` A human-identifiable name for the origin. - `Port int64` The port for upstream connections. A value of 0 means the default port for the protocol will be used. - `VirtualNetworkID string` The virtual network subnet ID the origin belongs in. Virtual network must also belong to the account. - `Weight float64` The weight of this origin relative to other origins in the pool. Based on the configured weight the total traffic is distributed among origins within the pool. - `origin_steering.policy="least_outstanding_requests"`: Use weight to scale the origin's outstanding requests. - `origin_steering.policy="least_connections"`: Use weight to scale the origin's open connections. # Health ## Pool Health Details `client.LoadBalancers.Pools.Health.Get(ctx, poolID, query) (*PoolHealthGetResponse, error)` **get** `/accounts/{account_id}/load_balancers/pools/{pool_id}/health` Fetch the latest pool health status for a single pool. ### Parameters - `poolID string` - `query PoolHealthGetParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type PoolHealthGetResponse struct{…}` A list of regions from which to run health checks. Null means every Cloudflare data center. - `PoolID string` Pool ID. - `POPHealth PoolHealthGetResponsePOPHealth` List of regions and associated health status. - `Healthy bool` Whether health check in region is healthy. - `Origins []PoolHealthGetResponsePOPHealthOrigin` - `IP PoolHealthGetResponsePOPHealthOriginsIP` - `FailureReason string` Failure reason. - `Healthy bool` Origin health status. - `ResponseCode float64` Response code from origin health check. - `RTT string` Origin RTT (Round Trip Time) response. ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) health, err := client.LoadBalancers.Pools.Health.Get( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.PoolHealthGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", health.PoolID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "pool_id": "17b5962d775c646f3f9725cbc7a53df4", "pop_health": { "healthy": true, "origins": [ { "ip": { "failure_reason": "No failure reasons", "healthy": true, "response_code": 200, "rtt": "201.5ms" } } ] } }, "success": true } ``` ## Preview Pool `client.LoadBalancers.Pools.Health.New(ctx, poolID, params) (*PoolHealthNewResponse, error)` **post** `/accounts/{account_id}/load_balancers/pools/{pool_id}/preview` Preview pool health using provided monitor details. The returned preview_id can be used in the preview endpoint to retrieve the results. ### Parameters - `poolID string` - `params PoolHealthNewParams` - `AccountID param.Field[string]` Path param: Identifier. - `AllowInsecure param.Field[bool]` Body param: Do not validate the certificate when monitor use HTTPS. This parameter is currently only valid for HTTP and HTTPS monitors. - `ConsecutiveDown param.Field[int64]` Body param: To be marked unhealthy the monitored origin must fail this healthcheck N consecutive times. - `ConsecutiveUp param.Field[int64]` Body param: To be marked healthy the monitored origin must pass this healthcheck N consecutive times. - `Description param.Field[string]` Body param: Object description. - `ExpectedBody param.Field[string]` Body param: A case-insensitive sub-string to look for in the response body. If this string is not found, the origin will be marked as unhealthy. This parameter is only valid for HTTP and HTTPS monitors. - `ExpectedCodes param.Field[string]` Body param: The expected HTTP response code or code range of the health check. This parameter is only valid for HTTP and HTTPS monitors. - `FollowRedirects param.Field[bool]` Body param: Follow redirects if returned by the origin. This parameter is only valid for HTTP and HTTPS monitors. - `Header param.Field[map[string, []string]]` Body param: The HTTP request headers to send in the health check. It is recommended you set a Host header by default. The User-Agent header cannot be overridden. This parameter is only valid for HTTP and HTTPS monitors. - `Interval param.Field[int64]` Body param: The interval between each health check. Shorter intervals may improve failover time, but will increase load on the origins as we check from multiple locations. - `Method param.Field[string]` Body param: The method to use for the health check. This defaults to 'GET' for HTTP/HTTPS based checks and 'connection_established' for TCP based health checks. - `Path param.Field[string]` Body param: The endpoint path you want to conduct a health check against. This parameter is only valid for HTTP and HTTPS monitors. - `Port param.Field[int64]` Body param: The port number to connect to for the health check. Required for TCP, UDP, and SMTP checks. HTTP and HTTPS checks should only define the port when using a non-standard port (HTTP: default 80, HTTPS: default 443). - `ProbeZone param.Field[string]` Body param: Assign this monitor to emulate the specified zone while probing. This parameter is only valid for HTTP and HTTPS monitors. - `Retries param.Field[int64]` Body param: The number of retries to attempt in case of a timeout before marking the origin as unhealthy. Retries are attempted immediately. - `Timeout param.Field[int64]` Body param: The timeout (in seconds) before marking the health check as failed. - `Type param.Field[PoolHealthNewParamsType]` Body param: The protocol to use for the health check. Currently supported protocols are 'HTTP','HTTPS', 'TCP', 'ICMP-PING', 'UDP-ICMP', and 'SMTP'. - `const PoolHealthNewParamsTypeHTTP PoolHealthNewParamsType = "http"` - `const PoolHealthNewParamsTypeHTTPS PoolHealthNewParamsType = "https"` - `const PoolHealthNewParamsTypeTCP PoolHealthNewParamsType = "tcp"` - `const PoolHealthNewParamsTypeUdpIcmp PoolHealthNewParamsType = "udp_icmp"` - `const PoolHealthNewParamsTypeIcmpPing PoolHealthNewParamsType = "icmp_ping"` - `const PoolHealthNewParamsTypeSmtp PoolHealthNewParamsType = "smtp"` ### Returns - `type PoolHealthNewResponse struct{…}` - `Pools map[string, string]` Monitored pool IDs mapped to their respective names. - `PreviewID string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) health, err := client.LoadBalancers.Pools.Health.New( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.PoolHealthNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", health.PreviewID) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "pools": { "abwlnp5jbqn45ecgxd03erbgtxtqai0d": "WNAM Datacenter", "ve8h9lrcip5n5bbga9yqmdws28ay5d0l": "EEU Datacenter" }, "preview_id": "f1aba936b94213e5b8dca0c0dbf1f9cc" }, "success": true } ``` # References ## List Pool References `client.LoadBalancers.Pools.References.Get(ctx, poolID, query) (*SinglePage[PoolReferenceGetResponse], error)` **get** `/accounts/{account_id}/load_balancers/pools/{pool_id}/references` Get the list of resources that reference the provided pool. ### Parameters - `poolID string` - `query PoolReferenceGetParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type PoolReferenceGetResponse struct{…}` - `ReferenceType PoolReferenceGetResponseReferenceType` - `const PoolReferenceGetResponseReferenceTypeStar PoolReferenceGetResponseReferenceType = "*"` - `const PoolReferenceGetResponseReferenceTypeReferral PoolReferenceGetResponseReferenceType = "referral"` - `const PoolReferenceGetResponseReferenceTypeReferrer PoolReferenceGetResponseReferenceType = "referrer"` - `ResourceID string` - `ResourceName string` - `ResourceType string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.LoadBalancers.Pools.References.Get( context.TODO(), "17b5962d775c646f3f9725cbc7a53df4", load_balancers.PoolReferenceGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": [ { "reference_type": "referrer", "resource_id": "699d98642c564d2e855e9661899b7252", "resource_name": "www.example.com", "resource_type": "load_balancer" }, { "reference_type": "referral", "resource_id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "resource_name": "Login page monitor", "resource_type": "monitor" } ], "success": true } ``` # Previews ## Preview Result `client.LoadBalancers.Previews.Get(ctx, previewID, query) (*PreviewGetResponse, error)` **get** `/accounts/{account_id}/load_balancers/preview/{preview_id}` Get the result of a previous preview operation using the provided preview_id. ### Parameters - `previewID string` - `query PreviewGetParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type PreviewGetResponse map[string, PreviewGetResponseItem]` Resulting health data from a preview operation. - `Healthy bool` - `Origins []map[string, PreviewGetResponseItemOrigin]` - `FailureReason string` - `Healthy bool` - `ResponseCode float64` - `RTT string` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) preview, err := client.LoadBalancers.Previews.Get( context.TODO(), "p1aba936b94213e5b8dca0c0dbf1f9cc", load_balancers.PreviewGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", preview) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "abwlnp5jbqn45ecgxd03erbgtxtqai0d": { "healthy": true, "origins": [ { "originone.example.com.": { "failure_reason": "No failures", "healthy": true, "response_code": 200, "rtt": "66ms" } } ] } }, "success": true } ``` # Regions ## List Regions `client.LoadBalancers.Regions.List(ctx, params) (*unknown, error)` **get** `/accounts/{account_id}/load_balancers/regions` List all region mappings. ### Parameters - `params RegionListParams` - `AccountID param.Field[string]` Path param: Identifier. - `CountryCodeA2 param.Field[string]` Query param: Two-letter alpha-2 country code followed in ISO 3166-1. - `SubdivisionCode param.Field[string]` Query param: Two-letter subdivision code followed in ISO 3166-2. - `SubdivisionCodeA2 param.Field[string]` Query param: Two-letter subdivision code followed in ISO 3166-2. ### Returns - `type RegionListResponseEnvelopeResult interface{…}` - `unknown` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) regions, err := client.LoadBalancers.Regions.List(context.TODO(), load_balancers.RegionListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", regions) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": {}, "success": true } ``` ## Get Region `client.LoadBalancers.Regions.Get(ctx, regionID, query) (*unknown, error)` **get** `/accounts/{account_id}/load_balancers/regions/{region_id}` Get a single region mapping. ### Parameters - `regionID RegionGetParamsRegionID` A list of Cloudflare regions. WNAM: Western North America, ENAM: Eastern North America, WEU: Western Europe, EEU: Eastern Europe, NSAM: Northern South America, SSAM: Southern South America, OC: Oceania, ME: Middle East, NAF: North Africa, SAF: South Africa, SAS: Southern Asia, SEAS: South East Asia, NEAS: North East Asia). - `const RegionGetParamsRegionIDWnam RegionGetParamsRegionID = "WNAM"` - `const RegionGetParamsRegionIDEnam RegionGetParamsRegionID = "ENAM"` - `const RegionGetParamsRegionIDWeu RegionGetParamsRegionID = "WEU"` - `const RegionGetParamsRegionIDEeu RegionGetParamsRegionID = "EEU"` - `const RegionGetParamsRegionIDNsam RegionGetParamsRegionID = "NSAM"` - `const RegionGetParamsRegionIDSsam RegionGetParamsRegionID = "SSAM"` - `const RegionGetParamsRegionIDOc RegionGetParamsRegionID = "OC"` - `const RegionGetParamsRegionIDMe RegionGetParamsRegionID = "ME"` - `const RegionGetParamsRegionIDNaf RegionGetParamsRegionID = "NAF"` - `const RegionGetParamsRegionIDSaf RegionGetParamsRegionID = "SAF"` - `const RegionGetParamsRegionIDSas RegionGetParamsRegionID = "SAS"` - `const RegionGetParamsRegionIDSeas RegionGetParamsRegionID = "SEAS"` - `const RegionGetParamsRegionIDNeas RegionGetParamsRegionID = "NEAS"` - `query RegionGetParams` - `AccountID param.Field[string]` Identifier. ### Returns - `type RegionGetResponseEnvelopeResult interface{…}` A list of countries and subdivisions mapped to a region. - `unknown` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) region, err := client.LoadBalancers.Regions.Get( context.TODO(), load_balancers.RegionGetParamsRegionIDWnam, load_balancers.RegionGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", region) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "iso_standard": "Country and subdivision codes follow ISO 3166-1 alpha-2 and ISO 3166-2", "regions": [ { "countries": [ { "country_code_a2": "CA", "country_name": "Canada", "country_subdivisions": [ { "subdivision_code_a2": "AB", "subdivision_name": "Alberta" }, { "subdivision_code_a2": "BC", "subdivision_name": "British Columbia" } ] }, { "country_code_a2": "HT", "country_name": "Haiti" }, { "country_code_a2": "MX", "country_name": "Mexico" }, { "country_code_a2": "US", "country_name": "United States", "country_subdivisions": [ { "subdivision_code_a2": "AZ", "subdivision_name": "Arizona" }, { "subdivision_code_a2": "CA", "subdivision_name": "California" }, { "subdivision_code_a2": "CO", "subdivision_name": "Colorado" }, { "subdivision_code_a2": "HI", "subdivision_name": "Hawaii" }, { "subdivision_code_a2": "MN", "subdivision_name": "Minnesota" }, { "subdivision_code_a2": "MO", "subdivision_name": "Missouri" }, { "subdivision_code_a2": "NV", "subdivision_name": "Nevada" }, { "subdivision_code_a2": "OR", "subdivision_name": "Oregon" }, { "subdivision_code_a2": "TX", "subdivision_name": "Texas" }, { "subdivision_code_a2": "UT", "subdivision_name": "Utah" }, { "subdivision_code_a2": "WA", "subdivision_name": "Washington" } ] } ], "region_code": "WNAM" } ] }, "success": true } ``` # Searches ## Search Resources `client.LoadBalancers.Searches.List(ctx, params) (*V4PagePagination[SearchListResponse], error)` **get** `/accounts/{account_id}/load_balancers/search` Search for Load Balancing resources. ### Parameters - `params SearchListParams` - `AccountID param.Field[string]` Path param: Identifier. - `Page param.Field[float64]` Query param - `PerPage param.Field[float64]` Query param - `Query param.Field[string]` Query param: Search query term. - `References param.Field[SearchListParamsReferences]` Query param: The type of references to include. "*" to include both referral and referrer references. "" to not include any reference information. - `const SearchListParamsReferencesEmpty SearchListParamsReferences = ""` - `const SearchListParamsReferencesStar SearchListParamsReferences = "*"` - `const SearchListParamsReferencesReferral SearchListParamsReferences = "referral"` - `const SearchListParamsReferencesReferrer SearchListParamsReferences = "referrer"` ### Returns - `type SearchListResponse struct{…}` - `Resources []SearchListResponseResource` A list of resources matching the search query. - `ReferenceType SearchListResponseResourcesReferenceType` When listed as a reference, the type (direction) of the reference. - `const SearchListResponseResourcesReferenceTypeReferral SearchListResponseResourcesReferenceType = "referral"` - `const SearchListResponseResourcesReferenceTypeReferrer SearchListResponseResourcesReferenceType = "referrer"` - `References []unknown` A list of references to (referrer) or from (referral) this resource. - `ResourceID string` - `ResourceName string` The human-identifiable name of the resource. - `ResourceType SearchListResponseResourcesResourceType` The type of the resource. - `const SearchListResponseResourcesResourceTypeLoadBalancer SearchListResponseResourcesResourceType = "load_balancer"` - `const SearchListResponseResourcesResourceTypeMonitor SearchListResponseResourcesResourceType = "monitor"` - `const SearchListResponseResourcesResourceTypePool SearchListResponseResourcesResourceType = "pool"` ### Example ```go package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/load_balancers" "github.com/cloudflare/cloudflare-go/option" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) page, err := client.LoadBalancers.Searches.List(context.TODO(), load_balancers.SearchListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "result": { "resources": [ { "reference_type": "referral", "references": [ { "reference_type": "referrer", "resource_id": "699d98642c564d2e855e9661899b7252", "resource_name": "www.example.com", "resource_type": "load_balancer" }, { "reference_type": "referral", "resource_id": "f1aba936b94213e5b8dca0c0dbf1f9cc", "resource_name": "Login page monitor", "resource_type": "monitor" } ], "resource_id": "17b5962d775c646f3f9725cbc7a53df4", "resource_name": "primary-dc-1", "resource_type": "pool" } ] }, "success": true, "result_info": { "count": 20, "page": 1, "per_page": 20, "total_count": 2000, "total_pages": 100 } } ```