strategies.yaml¶
The strategies.yaml file identifies the next hop proxies used in an
cache hierarchy and the algorithms used to select the next hop proxy. Use
this file to perform the following configuration:
Set up next hop cache hierarchies, with multiple parents and parent failover
Traffic Server uses the strategies.yaml file only when one or more
remap lines in remap.config specifies the use of a strategy with the @strategy tag.
remap.config Example:
map http://www.foo.com http://www.bar.com @strategy='mid-tier-north'
After you modify the strategies.yaml file, run the traffic_ctl config reload
command to apply your changes.
Format¶
The strategies.yaml is a YAML document with three top level namespaces: hosts, groups and strategies. These name spaces may be in separate files. When in separate files, use #include filename in the strategies.yaml so that they are concatenated by the strategy factory into a single YAML document in the order, hosts, groups, and the strategies.
Alternatively if the config parameter proxy.config.url_remap.strategies.filename refers to a directory, the NextHopStrategyFactory will alphanumerically concatenate all files in that directory that end in .yaml by name into a single document stream for parsing. The final document must be a valid YAML document with single strategies node and optionally a single hosts and groups node. Any #include filename strings are ignored when reading .yaml files in a directory.
Hosts definitions¶
The hosts definitions is a YAML list of hosts. This list is optional but if not used, the groups list must include complete definitions for hosts. See the group examples below.
In the example below, hosts is a YAML list of hosts. Each host entry uses a YAML anchor, &p1 and &p2 that may be used elsewhere in the YAML document to refer to hosts p1 and p2.
host: the host value is a hostname string
protocol: a list of schemes, ports, and health check urls for the host.
healthcheck: health check information with the url used to check the hosts health by some external health check agent.
Example:
hosts:
- &p1
host: p1.foo.com
protocol:
- scheme: http
port: 80
health_check_url: http://192.168.1.1:80
- scheme: https
port: 443
health_check_url: https://192.168.1.1:443
- &p2
host: p2.foo.com
protocol:
- scheme: http
port: 80
health_check_url: http://192.168.1.2:80
Groups definitions¶
The groups definitions is a YAML list of host groups. host groups are used as the primary and secondary groups used by nexthop to choose hosts from. The first group is the primary group next hop chooses hosts from. The remaining groups are used failover. The strategies policy specifies how the groups are used.
Below are examples of group definitions. The first example is using YAML anchors and references. When using references, the complete YAML document must include the anchors portion of the document first.
The second example shows a complete groups definition without the use of a hosts name space and it’s YAML anchors.
The field definitions in the examples below are defined in the hosts section.
Example using YAML anchors and references:
groups:
- &g1
- <<: *p1
weight: 1.5
- <<: *p2
weight: 0.5
- &g2
- <<: *p3
weight: 0.5
- <<: *p4
weight: 1.5
Explicitly defined Example, no YAML references:
groups:
- &g1
- host: p1.foo.com
protocol:
- scheme: http
port: 80
health_check_url: http://192.168.1.1:80
- scheme: https
port: 443
health_check_url: https://192.168.1.1:443
weight: 0.5
- host: p2.foo.com
protocol:
- scheme: http
port: 80
health_check_url: http://192.168.1.2:80
- scheme: https
port: 443
health_check_url: https://192.168.1.2:443
weight: 0.5
- &g2
- host: p3.foo.com
protocol:
- scheme: http
port: 80
health_check_url: http://192.168.1.3:80
- scheme: https
port: 443
health_check_url: https://192.168.1.3:443
weight: 0.5
- host: p4.foo.com
protocol:
- scheme: http
port: 80
health_check_url: http://192.168.1.4:80
- scheme: https
port: 443
health_check_url: https://192.168.1.4:443
weight: 0.5
Strategies definitions¶
The strategies namespace defines a YAML list of strategies that may be applied to a remap entry using the @strategy tag in remap.config.
Each strategy in the list may using the following parameters:
- **strategy**: The value is the name of the strategy.
- **policy**: The algorithm the **strategy** uses to select hosts. Currently one of the following:
rr_ip: round robin selection using the modulus of the client IP
rr_strict: strict round robin over the list of hosts in the primary group.
first_live: always selects the first host in the primary group. Other hosts are selected when the first host fails.
latched: Same as first_live but primary selection sticks to whatever host was used by a previous transaction.
consistent_hash: hosts are selected using a hash_key.
hash_key: The hashing key used by the consistent_hash policy. If not specified, defaults to path which is the same policy used in the parent.config implementation. Use one of:
hostname: Creates a hash using the hostname in the request URL.
path: (default) Creates a hash over the path portion of the request URL.
path+query: Same as path but adds the query string in the request URL.
path+fragment: Same as path but adds the fragment portion of the URL.
cache_key: Uses the hash key from the cachekey plugin. defaults to path if the cachekey plugin is not configured on the remap.
url: Creates a hash from the entire request url.
go_direct - A boolean value indicating whether a transaction may bypass proxies and go direct to the origin. Defaults to true
parent_is_proxy: A boolean value which indicates if the groups of hosts are proxy caches or origins. true (default) means all the hosts used in the remap are Traffic Server caches. false means the hosts are origins that the next hop strategies may use for load balancing and/or failover.
scheme Indicates which scheme the strategy supports, http or https - failover: A map of failover information. - max_simple_retries: Part of the failover map and is an integer value of the maximum number of retries for a simple retry on the list of indicated response codes. simple retry is used to retry an upstream request using another upstream server if the response received on from the original upstream request matches any of the response codes configured for this strategy in the failover map. If no failover response codes are configured, no simple retry is attempted.
ring_mode: Part of the failover map. The host ring selection mode. Use either exhaust_ring or alternate_ring
exhaust_ring: when a host normally selected by the policy fails, another host is selected from the same group. A new group is not selected until all hosts on the previous group have been exhausted
alternate_ring: retry hosts are selected from groups in an alternating group fashion.
response_codes: Part of the failover map. This is a list of http response codes that may be used for simple retry.
health_check: Part of the failover map. A list of health checks. passive is the default and means that the state machine marks down hosts when a transaction timeout or connection error is detected. passive is always used by the next hop strategies. active means that some external process may actively health check the hosts using the defined health check url and mark them down using traffic_ctl.
Example:
#include unit-tests/hosts.yaml
#
strategies:
- strategy: 'strategy-1'
policy: consistent_hash
hash_key: cache_key
go_direct: false
groups:
- *g1
- *g2
scheme http
failover:
ring_mode: exhaust_ring
response_codes:
- 404
- 503
health_check:
- passive
- strategy: 'strategy-2'
policy: rr_strict
hash_key: cache_key
go_direct: true
groups:
- *g1
- *g2
scheme http
failover:
ring_mode: exhaust_ring
response_codes:
- 404
- 503
health_check:
- passive