Skip to content

Commit

Permalink
load_balancing: support header session affinity policy
Browse files Browse the repository at this point in the history
  • Loading branch information
Cole Bennett committed Jul 24, 2023
1 parent e7a4ac8 commit 4636a24
Show file tree
Hide file tree
Showing 6 changed files with 136 additions and 16 deletions.
3 changes: 3 additions & 0 deletions .changelog/2521.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
```release-note:enhancement
resource/cloudflare_load_balancer: support header session affinity policy
```
33 changes: 24 additions & 9 deletions docs/resources/load_balancer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,9 +91,14 @@ resource "cloudflare_load_balancer_pool" "example" {
- `random_steering` (Block Set) Configures pool weights. When [`steering_policy="random"`](#steering_policy), a random pool is selected with probability proportional to pool weights. When [`steering_policy="least_outstanding_requests"`](#steering_policy), pool weights are used to scale each pool's outstanding requests. (see [below for nested schema](#nestedblock--random_steering))
- `region_pools` (Block Set) A set containing mappings of region codes to a list of pool IDs (ordered by their failover priority) for the given region. (see [below for nested schema](#nestedblock--region_pools))
- `rules` (Block List) A list of rules for this load balancer to execute. (see [below for nested schema](#nestedblock--rules))
- `session_affinity` (String) Specifies the type of session affinity the load balancer should use unless specified as `none` or `""` (default). With value `cookie`, on the first request to a proxied load balancer, a cookie is generated, encoding information of which origin the request will be forwarded to. Subsequent requests, by the same client to the same load balancer, will be sent to the origin server the cookie encodes, for the duration of the cookie and as long as the origin server remains healthy. If the cookie has expired or the origin server is unhealthy then a new origin server is calculated and used. Value `ip_cookie` behaves the same as `cookie` except the initial origin selection is stable and based on the client's IP address. Available values: `""`, `none`, `cookie`, `ip_cookie`. Defaults to `none`.
- `session_affinity_attributes` (Block Set) Configure cookie attributes for session affinity cookie. (see [below for nested schema](#nestedblock--session_affinity_attributes))
- `session_affinity_ttl` (Number) Time, in seconds, until this load balancer's session affinity cookie expires after being created. This parameter is ignored unless a supported session affinity policy is set. The current default of `82800` (23 hours) will be used unless [`session_affinity_ttl`](#session_affinity_ttl) is explicitly set. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. Valid values are between `1800` and `604800`.
- `session_affinity` Specifies the type of session affinity the load balancer should use unless specified as "none" or "" (default). 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.
- `session_affinity_attributes` (Block Set) Configures attributes for session affinity. (see [below for nested schema](#nestedblock--session_affinity_attributes))
- `session_affinity_ttl` (Number) 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. This parameter is ignored unless a supported session affinity policy is set. 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.
- `steering_policy` (String) The method the load balancer uses to determine the route to your origin. Value `off` uses [`default_pool_ids`](#default_pool_ids). Value `geo` uses [`pop_pools`](#pop_pools)/[`country_pools`](#country_pools)/[`region_pools`](#region_pools). For non-proxied requests, the [`country`](#country) for [`country_pools`](#country_pools) is determined by [`location_strategy`](#location_strategy). Value `random` selects a pool randomly. Value `dynamic_latency` uses round trip time to select the closest pool in [`default_pool_ids`](#default_pool_ids) (requires pool health checks). Value `proximity` uses the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by [`location_strategy`](#location_strategy) for non-proxied requests. Value `least_outstanding_requests` selects a pool by taking into consideration [`random_steering`](#random_steering) weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others. Value `""` maps to `geo` if you use [`pop_pools`](#pop_pools)/[`country_pools`](#country_pools)/[`region_pools`](#region_pools) otherwise `off`. Available values: `off`, `geo`, `dynamic_latency`, `random`, `proximity`, `least_outstanding_requests`, `""` Defaults to `""`.
- `ttl` (Number) Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This cannot be set for proxied load balancers. Defaults to `30`. Conflicts with `proxied`.

Expand Down Expand Up @@ -196,9 +201,14 @@ Optional:
- `pop_pools` (Block Set) A set containing mappings of Cloudflare Point-of-Presence (PoP) identifiers to a list of pool IDs (ordered by their failover priority) for the PoP (datacenter). This feature is only available to enterprise customers. (see [below for nested schema](#nestedblock--rules--overrides--pop_pools))
- `random_steering` (Block Set) Configures pool weights. When [`steering_policy="random"`](#steering_policy), a random pool is selected with probability proportional to pool weights. When [`steering_policy="least_outstanding_requests"`](#steering_policy), pool weights are used to scale each pool's outstanding requests. (see [below for nested schema](#nestedblock--rules--overrides--random_steering))
- `region_pools` (Block Set) A set containing mappings of region codes to a list of pool IDs (ordered by their failover priority) for the given region. (see [below for nested schema](#nestedblock--rules--overrides--region_pools))
- `session_affinity` (String) Configure cookie attributes for session affinity cookie.
- `session_affinity_attributes` (Block Set) Configure cookie attributes for session affinity cookie. Note that the property [`drain_duration`](#drain_duration) is not currently supported as a rule override. (see [below for nested schema](#nestedblock--rules--overrides--session_affinity_attributes))
- `session_affinity_ttl` (Number) Time, in seconds, until this load balancer's session affinity cookie expires after being created. This parameter is ignored unless a supported session affinity policy is set. The current default of `82800` (23 hours) will be used unless [`session_affinity_ttl`](#session_affinity_ttl) is explicitly set. Once the expiry time has been reached, subsequent requests may get sent to a different origin server. Valid values are between `1800` and `604800`.
- `session_affinity` Specifies the type of session affinity the load balancer should use unless specified as "none" or "" (default). 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.
- `session_affinity_attributes` (Block Set) Configures attributes for session affinity. Note that the property [`drain_duration`](#drain_duration) is not currently supported as a rule override. (see [below for nested schema](#nestedblock--rules--overrides--session_affinity_attributes))
- `session_affinity_ttl` (Number) 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. This parameter is ignored unless a supported session affinity policy is set. 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.
- `steering_policy` (String) The method the load balancer uses to determine the route to your origin. Value `off` uses [`default_pool_ids`](#default_pool_ids). Value `geo` uses [`pop_pools`](#pop_pools)/[`country_pools`](#country_pools)/[`region_pools`](#region_pools). For non-proxied requests, the [`country`](#country) for [`country_pools`](#country_pools) is determined by [`location_strategy`](#location_strategy). Value `random` selects a pool randomly. Value `dynamic_latency` uses round trip time to select the closest pool in [`default_pool_ids`](#default_pool_ids) (requires pool health checks). Value `proximity` uses the pools' latitude and longitude to select the closest pool using the Cloudflare PoP location for proxied requests or the location determined by [`location_strategy`](#location_strategy) for non-proxied requests. Value `least_outstanding_requests` selects a pool by taking into consideration [`random_steering`](#random_steering) weights, as well as each pool's number of outstanding requests. Pools with more pending requests are weighted proportionately less relative to others. Value `""` maps to `geo` if you use [`pop_pools`](#pop_pools)/[`country_pools`](#country_pools)/[`region_pools`](#region_pools) otherwise `off`. Available values: `off`, `geo`, `dynamic_latency`, `random`, `proximity`, `least_outstanding_requests`, `""` Defaults to `""`.
- `ttl` (Number) Time to live (TTL) of the DNS entry for the IP address returned by this load balancer. This cannot be set for proxied load balancers. Defaults to `30`.

Expand Down Expand Up @@ -263,9 +273,10 @@ Optional:
- `samesite` (String) Configures the SameSite attribute on session affinity cookie. Value `Auto` will be translated to `Lax` or `None` depending if Always Use HTTPS is enabled. Note: when using value `None`, then you can not set [`secure="Never"`](#secure). Available values: `Auto`, `Lax`, `None`, `Strict`.
- `secure` (String) Configures the Secure attribute on session affinity cookie. Value `Always` indicates the Secure attribute will be set in the Set-Cookie header, `Never` indicates the Secure attribute will not be set, and `Auto` will set the Secure attribute depending if Always Use HTTPS is enabled. Available values: `Auto`, `Always`, `Never`.
- `zero_downtime_failover` (String) Configures the zero-downtime failover between origins within a pool when session affinity is enabled. Value `none` means no failover takes place for sessions pinned to the origin. Value `temporary` means traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping. Value `sticky` means the session affinity cookie is updated and subsequent requests are sent to the new origin. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. Available values: `none`, `temporary`, `sticky`.



- `headers` (List of String) Configures the names of HTTP headers used 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:<cookie-name-1>,<cookie-name-2>` (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.
- `require_all_headers` (Boolean) 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.

<a id="nestedblock--session_affinity_attributes"></a>
### Nested Schema for `session_affinity_attributes`
Expand All @@ -276,6 +287,10 @@ Optional:
- `samesite` (String) Configures the SameSite attribute on session affinity cookie. Value `Auto` will be translated to `Lax` or `None` depending if Always Use HTTPS is enabled. Note: when using value `None`, then you can not set [`secure="Never"`](#secure). Available values: `Auto`, `Lax`, `None`, `Strict`. Defaults to `Auto`.
- `secure` (String) Configures the Secure attribute on session affinity cookie. Value `Always` indicates the Secure attribute will be set in the Set-Cookie header, `Never` indicates the Secure attribute will not be set, and `Auto` will set the Secure attribute depending if Always Use HTTPS is enabled. Available values: `Auto`, `Always`, `Never`. Defaults to `Auto`.
- `zero_downtime_failover` (String) Configures the zero-downtime failover between origins within a pool when session affinity is enabled. Value `none` means no failover takes place for sessions pinned to the origin. Value `temporary` means traffic will be sent to another other healthy origin until the originally pinned origin is available; note that this can potentially result in heavy origin flapping. Value `sticky` means the session affinity cookie is updated and subsequent requests are sent to the new origin. This feature is currently incompatible with Argo, Tiered Cache, and Bandwidth Alliance. Available values: `none`, `temporary`, `sticky`. Defaults to `none`.
- `headers` (List of String) Configures the names of HTTP headers used 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:<cookie-name-1>,<cookie-name-2>` (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.
- `require_all_headers` (Boolean) 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.

## Import

Expand Down
1 change: 1 addition & 0 deletions go.sum
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,7 @@ github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXl
github.com/vmihailenco/msgpack v3.3.3+incompatible/go.mod h1:fy3FlTQTDXWkZ7Bh6AcGMlsjHatGryHQYUTf1ShIgkk=
github.com/vmihailenco/msgpack v4.0.4+incompatible h1:dSLoQfGFAo3F6OoNhwUmLwVgaUXK79GlxNBwueZn0xI=
github.com/vmihailenco/msgpack v4.0.4+incompatible/go.mod h1:fy3FlTQTDXWkZ7Bh6AcGMlsjHatGryHQYUTf1ShIgkk=
github.com/vmihailenco/msgpack/v4 v4.3.12/go.mod h1:gborTTJjAo/GWTqqRjrLCn9pgNN+NXzzngzBKDPIqw4=
github.com/vmihailenco/msgpack/v5 v5.3.5 h1:5gO0H1iULLWGhs2H5tbAHIZTV8/cYafcFOr9znI5mJU=
github.com/vmihailenco/msgpack/v5 v5.3.5/go.mod h1:7xyJ9e+0+9SaZT0Wt1RGleJXzli6Q/V5KbhBonMG9jc=
github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
Expand Down
13 changes: 13 additions & 0 deletions internal/sdkv2provider/resource_cloudflare_load_balancer.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,8 @@ func flattenSessionAffinityAttrs(properties *cloudflare.SessionAffinityAttribute
"samesite": properties.SameSite,
"secure": properties.Secure,
"zero_downtime_failover": properties.ZeroDowntimeFailover,
"headers": properties.Headers,
"require_all_headers": properties.RequireAllHeaders,
},
}
return schema.NewSet(schema.HashResource(loadBalancerSessionAffinityAttributesElem), flattened)
Expand Down Expand Up @@ -547,6 +549,13 @@ func expandRules(rdata interface{}) ([]*cloudflare.LoadBalancerRule, error) {
case "zero_downtime_failover":
saaOverride.ZeroDowntimeFailover = v.(string)
lbr.Overrides.SessionAffinityAttrs = saaOverride
case "headers":
saaOverride.Headers = v.([]string)
lbr.Overrides.SessionAffinityAttrs = saaOverride
case "require_all_headers":
requireAllHeaders := v.(bool)
saaOverride.RequireAllHeaders = &requireAllHeaders
lbr.Overrides.SessionAffinityAttrs = saaOverride
}
}
}
Expand Down Expand Up @@ -685,6 +694,10 @@ func expandSessionAffinityAttrs(set interface{}) *cloudflare.SessionAffinityAttr
cfSessionAffinityAttrs.DrainDuration = v.(int)
case "zero_downtime_failover":
cfSessionAffinityAttrs.ZeroDowntimeFailover = v.(string)
case "headers":
cfSessionAffinityAttrs.Headers = v.([]string)
case "require_all_headers":
cfSessionAffinityAttrs.RequireAllHeaders = v.(bool)
}
}
}
Expand Down
Loading

0 comments on commit 4636a24

Please sign in to comment.