Provided by: trafficserver_9.2.3+ds-1+deb12u1build4_amd64 
NAME
strategies.yaml - Traffic Server cache hierarchy configuration file
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 Fully Qualified Domain Name string
• protocol: a list of schemes, ports, and health check urls for the host. The scheme is
optional; strategies with no scheme will match hosts with no scheme. Note the scheme is
only used to match the strategy, the actual scheme used in the upstream request will be
the scheme of the remap target, regardless of the strategy or host scheme.
• healthcheck: health check information with the url used to check the hosts health by
some external health check agent.
•
hash_string: a string to use for this host's entry in the strategy. By default, the host
is used (notably without a port).
• This is currently only used by consistent_hash policy strategies, but may be
used by other policies in the future.
•
There's generally no benefit to giving any host any particular hash string, but
this may be useful, for example:
• If multiple host objects share the same host FQDN, possibly on
different ports
• If a parent server's FQDN changes, to prevent changing a host's
position on the hash ring, and thus breaking the cache and sending
different requests to different parents
• To force a change in the order of the hash ring for debugging purposes
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.new.foo.com
hash_string: p2.original.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:
1. rr_ip: round robin selection using the modulus of the client IP
2. rr_strict: strict round robin over the list of hosts in the primary group.
3. first_live: always selects the first host in the primary group. Other hosts are
selected when the first host fails.
4. latched: Same as first_live but primary selection sticks to whatever host was
used by a previous transaction.
5. 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:
1. hostname: Creates a hash using the hostname in the request URL.
2. path: (default) Creates a hash over the path portion of the request URL.
3. path+query: Same as path but adds the query string in the request URL.
4. path+fragment: Same as path but adds the fragment portion of the URL.
5. cache_key: Uses the hash key from the cachekey plugin. defaults to path if the
cachekey plugin is not configured on the remap.
6. 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.
• cache_peer_result: A boolean value that is only used when the policy is
'consistent_hash' and a peering_ring mode is used for the strategy. When set to true,
the default, all responses from upstream and peer endpoints are allowed to be cached.
Setting this to false will disable caching responses received from a peer host. Only
responses from upstream origins or parents will be cached for this strategy.
• scheme: Indicates which scheme the strategy supports, http or https. Note this is only
used to match hosts to strategies; the actual scheme used in the upstream request will
be the scheme of the remap.config target, regardless of this value. The scheme is
optional, and strategies without a scheme will match hosts without a scheme. This allows
for omitting the scheme if hosts are not shared between strategies, or if all strategies
using a given host use the same scheme.
• 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.
• max_unavailable_retries: Part of the failover map and is an integer value of the
maximum number of retries for a unavailable retry on the list of indicated markdown
response codes. unavailable 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 markdown response codes configured for this strategy in the failover map.
If no failover markdown response codes are configured, no unavailable retry is
attempted. unavailable retry differs from simple retry in that if a failover for
retry is done, the previously retried server is marked down for rety.
• ring_mode: Part of the failover map. The host ring selection mode. Use either
exhaust_ring, alternate_ring or peering_ring
1. 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
2. alternate_ring: retry hosts are selected from groups in an alternating group
fashion.
3. peering_ring: This mode is only implemented for a policy of consistent_hash and
requires that one or two host groups are defined. The first host group is a list
of peer caches and "this" host itself, the (optional) second group is a list of
upstream caches. Parents are always selected from the peer list however, if the
selected parent is "this" host itself a new parent from the upstream list is
chosen. If the second group is omitted, and go_direct is true, the upstream "list"
has one element, the host in the remapped URL. In addition, if any peer host is
unreachable or times out, a host from the upstream list is chosen for retries.
Because the peer hosts may at times not have consistent up/down markings for the
other peers, requests may be looped sometimes. So it's best to use
proxy.config.http.insert_request_via_str and proxy.config.http.max_proxy_cycles to
stop looping.
• response_codes: Part of the failover map. This is a list of http response codes that
may be used for simple retry.
• markdown_codes: Part of the failover map. This is a list of http response codes that
may be used for unavailable retry which will cause a parent markdown.
• 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.
• self: Part of the failover map. This can only be used when ring_mode is peering_ring.
This is the hostname of the host in the (first) group of peers that is the local host
Traffic Server runs on. (self should only be necessary when the local hostname can
only be translated to an IP address with a DNS lookup.)
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
markdown_codes:
- 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
markdown_codes:
- 503
health_check:
- passive
COPYRIGHT
2024, dev@trafficserver.apache.org