STRATEGIES.YAML(5)

📦
version 9.2.5 · 4 versions
, in ubuntu noble, ubuntu questing

💖 strategies.yaml — the Apache Traffic Server cache hierarchy config, bestie 💖

(that's strategies.yaml(5) if you're being formal, which, like, we're not)

✨ NAME ✨

okay so strategies.yaml is the Traffic Server cache hierarchy configuration file. It's the lil file that says who your next hop proxies are and what algorithm picks between them. You come here when you wanna:

  • set up next hop cache hierarchies, with multiple parents and parent failover 🫶
Traffic Server only looks at strategies.yaml when one or more remap lines in remap.config say to use a strategy, via the @strategy tag. No tag, no strategy file, no next-hop shenanigans. Periodt.

remap.config Example:

map http://www.foo.com http://www.bar.com @strategy='mid-tier-north'

And after you edit strategies.yaml? Run the traffic_ctl config reload command to apply your changes. Don't forget, bestie, or you'll be sitting there like "why isn't it working 😭".

🌈 FORMAT 🌈

strategies.yaml is a YAML document with three top level namespaces: hosts, groups and strategies. They're allowed to live in separate files. When they do, you use #include filename inside strategies.yaml so the strategy factory concatenates them into one single YAML document — in this order: hosts, groups, and then strategies.

Alternatively, if the config parameter proxy.config.url_remap.strategies.filename points at a directory, then NextHopStrategyFactory will alphanumerically concatenate all the files in that directory that end in .yaml by name into a single document stream for parsing. The final document has to be a valid YAML document with a single strategies node, and optionally a single hosts and groups node. And heads up: any #include filename strings get 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 you don't use it, then the groups list has to include complete definitions for hosts. (See the group examples below, we gotchu.)

In the example below, hosts is a YAML list of hosts. Each host entry uses a YAML anchor, &p1 and &p2, which you can use elsewhere in the YAML document to refer to hosts p1 and p2. Iconic, honestly. 💅

  • 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. (yes, that's a whole thing, read it twice 🔥)
  • 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. Slay. 👑

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. (order matters, bestie, don't test it 😤)

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 🌸

okay bestie so this namespace is where you define a YAML list of strategies, and each one can get applied to a remap entry using the @strategy tag in remap.config. that's the whole vibe. 💅

Every strategy in the list may use these parameters:

  • strategy — the value here is just the name of the strategy. name your child, bestie.
  • policy — the algorithm the strategy uses to pick hosts. rn it's one of these five:
    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 only get picked when that first host fails.
    4. latched — same as first_live, except the primary selection sticks to whatever host was used by a previous transaction. it's giving commitment issues but make it stable.
    5. consistent_hash — hosts are selected using a hash_key.
  • hash_key — the hashing key used by the consistent_hash policy. if you don't specify it, it defaults to path, which is the same policy used in the parent.config implementation. pick 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 saying whether a transaction may bypass proxies and go direct to the origin. defaults to true.
  • parent_is_proxy — a boolean saying 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 that's 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 it to false disables 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. heads up tho: 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 lets you omit the scheme if hosts aren't shared between strategies, or if all strategies using a given host use the same scheme. slay, flexible queen. 🦋
  • failover — a map of failover information. it's got layers, like an onion. 🧅
    • max_simple_retries — part of the failover map, an integer 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 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. periodt.
    • max_unavailable_retries — part of the failover map, an integer 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 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 retry.
    • 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 🌈

okay here's the whole thing in the wild, no cap:

#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

2026, dev@trafficserver.apache.org

and that's the whole page bestie, you ate it UP. 👑 this was Traffic Server version 9.2, dated Feb 12, 2026, filed under STRATEGIES.YAML(5) — now go configure something iconic. 💖✨🫶

📦 where this page comes from