Skip to content

Commit d3c57a9

Browse files
jrushfordjrushford
committed
Add a remap @strategy tag and nexthop selection strategies to remap.
1 parent 14aadf4 commit d3c57a9

37 files changed

+5195
-39
lines changed

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,11 @@ proxy/hdrs/test_proxy_hdrs
106106
proxy/hdrs/test_hdr_heap
107107
proxy/hdrs/test_Huffmancode
108108
proxy/hdrs/test_XPACK
109+
proxy/http/remap/test_NextHopRoundRobin
110+
proxy/http/remap/test_NextHopStrategyFactory
111+
proxy/http/remap/test_PluginDso
112+
proxy/http/remap/test_PluginFactory
113+
proxy/http/remap/test_RemapPluginInfo
109114
proxy/http/test_proxy_http
110115
proxy/http/remap/test_*
111116
proxy/http2/test_Http2DependencyTree

‎configs/strategies.yaml.default‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
#
2+
# strategies.yaml
3+
#
4+
# Documentation:
5+
# https://docs.trafficserver.apache.org/en/latest/admin-guide/files/strategies.yaml.en.html
6+
#
7+
# The purpose of this file is to specify the strategies available for
8+
# use in locating upstream caches for use to satisfy requests
9+
#
10+
# This is a YAML formatted file to define hosts, groups of hosts and next hop strategies that
11+
# may be used by remap
12+
#
13+
# There are three top-level YAML name spaces: 'hosts', 'groups', and 'strategies'.
14+
# 'hosts' is a YAML list of host's definitions and is used when defining 'groups' YAML
15+
# references are supported.
16+
# 'groups' is a YAML list that aggregates a group of hosts together and serves as the
17+
# equivalent to the rings used in parent.config. You may define upto five groups in a
18+
# config, see MAX_GROUPS.
19+
# 'strategies' is a YAML list of strategy definitions.
20+
#
21+
# Files may be broken up into several different files. The main file loaded by the Next Hop
22+
# Strategy factory is this file, strategies.yaml. You may move the 'hosts' and 'groups'
23+
# definitions into separate files and then include them in this file using:
24+
#
25+
# '#include path_to_hosts_and_groups_file'
26+
#
27+
# It is even possible to put individual strategies into separate file. The Next Hop
28+
# strategy factory concatenates all included files together in a single YAML document at
29+
# each point where it sees an '#include file_name'. When using this feature you just need to
30+
# ensure that the final concatenation is a valid YAML document with 'hosts', 'groups'
31+
# and 'strategies' in this given order.
32+
#
33+
#
34+
# This example YAML document shows a complete definiton in a single strategies.yaml
35+
# file. There are other example unit test files in the source tree showing examples of
36+
# using '#include' and different formats available for use, proxy/http/remap/unit-tests/
37+
# See the documentation which describes each parameter in detail.
38+
#
39+
# Example:
40+
#
41+
#
42+
# hosts:
43+
# - &p1
44+
# host: p1.foo.com
45+
# hash_string: slsklslsk # optional hash string that replaces the hostname in consistent hashing.
46+
# protocol:
47+
# - scheme: http
48+
# port: 80
49+
# health_check_url: http://192.168.1.1:80
50+
# - scheme: https
51+
# port: 443
52+
# health_check_url: https://192.168.1.1:443
53+
# - &p2
54+
# host: p2.foo.com
55+
# protocol:
56+
# - scheme: http
57+
# port: 80
58+
# health_check_url: http://192.168.1.2:80
59+
# - scheme: https
60+
# port: 443
61+
# health_check_url: https://192.168.1.2:443
62+
# - &s1
63+
# host: s1.foo.com
64+
# hash_string: slsklslsk # optional hash string that replaces the hostname in consistent hashing.
65+
# protocol:
66+
# - scheme: http
67+
# port: 80
68+
# health_check_url: http://192.168.2.1:80
69+
# - scheme: https
70+
# port: 443
71+
# health_check_url: https://192.168.2.1:443
72+
# - &s2
73+
# host: s2.foo.com
74+
# protocol:
75+
# - scheme: http
76+
# port: 80
77+
# health_check_url: http://192.168.2.2:80
78+
# - scheme: https
79+
# port: 443
80+
# health_check_url: https://192.168.2.2:443
81+
# groups:
82+
# - &g1
83+
# - <<: *p1
84+
# weight: 0.5
85+
# - <<: *p2
86+
# weight: 0.5
87+
# - &g2
88+
# - <<: *s1
89+
# weight: 2.0
90+
# - <<: *s2
91+
# weight: 1.0
92+
# strategies:
93+
# - strategy: 'mid-tier-north'
94+
# policy: rr_ip # Selection strategy policy: Enum of 'consistent_hash' or 'first_live' or 'rr_strict' or 'rr_ip' or 'latched'
95+
# hash_key: hostname # optional key to use for Hashing. Enum of 'url' or 'uri' or 'hostname' or 'path' or 'path+query' or 'cache_key' or 'path+fragment'
96+
# go_direct: true # transactions may routed directly to the origin true/false default is true.
97+
# parent_is_proxy: false # next hop hosts are origin servers when set to 'false', defaults to true and indicates next hop hosts are ats cache's.
98+
# groups: # groups of hosts, these groups are used as rings in consistent hash and arrays of host groups for round_robin.
99+
# - *g1
100+
# - *g2
101+
# scheme: http
102+
# failover:
103+
# max_simple_retries: 2 # default is 1, indicates the maximum number of simple retries for the listed response codes.
104+
# ring_mode: exhaust_ring # enumerated as exhaust_ring or alternate_ring
105+
# #1) in 'exhaust_ring' mode all the servers in a ring are exhausted before failing over to secondary ring
106+
# #2) in 'alternate_ring' mode causes the failover to another server in secondary ring.
107+
# response_codes: # defines the responses codes for failover in exhaust_ring mode
108+
# - 404
109+
# - 502
110+
# - 503
111+
# health_check: # specifies the list of healthchecks that should be considered for failover. A list of enums: 'passive' or 'active'
112+
# - passive
113+
# - active
114+
# - strategy: 'mid-tier-south'
115+
# policy: latched
116+
# hash_key: uri
117+
# go_direct: false
118+
# parent_is_proxy: false # next hop hosts are origin servers
119+
# groups:
120+
# - *g1
121+
# - *g2
122+
# scheme: https
123+
# failover:
124+
# max_simple_retries: 2
125+
# ring_mode: alternate_ring
126+
# response_codes:
127+
# - 404
128+
# - 502
129+
# - 503
130+
# health_check:
131+
# - passive
132+
# - active

‎doc/admin-guide/files/strategies.yaml.en.rst‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
or more contributor license agreements. See the NOTICE file
3+
distributed with this work for additional information
4+
regarding copyright ownership. The ASF licenses this file
5+
to you under the Apache License, Version 2.0 (the
6+
"License"); you may not use this file except in compliance
7+
with the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing,
12+
software distributed under the License is distributed on an
13+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
KIND, either express or implied. See the License for the
15+
specific language governing permissions and limitations
16+
under the License.
17+
18+
.. include:: ../../common.defs
19+
20+
===============
21+
strategies.yaml
22+
===============
23+
24+
.. configfile:: strategies.yaml
25+
26+
The :file:`strategies.yaml` file identifies the next hop proxies used in an
27+
cache hierarchy and the algorithms used to select the next hop proxy. Use
28+
this file to perform the following configuration:
29+
30+
- Set up next hop cache hierarchies, with multiple parents and parent
31+
failover
32+
33+
Traffic Server uses the :file:`strategies.yaml` file only when one or more
34+
remap lines in remap.config specifies the use of a strategy with the @strategy tag.
35+
remap.config Example::
36+
37+
map http://www.foo.com http://www.bar.com @strategy='mid-tier-north'
38+
39+
After you modify the :file:`strategies.yaml` file, run the :option:`traffic_ctl config reload`
40+
command to apply your changes.
41+
42+
Format
43+
======
44+
45+
The `strategies.yaml` is a YAML document with three top level namespaces: **hosts**, **groups**
46+
and **strategies**. These name spaces may be in separate files. When in separate files, use
47+
**#include filename** in the `strategies.yaml` so that they are concatenated by the strategy
48+
factory into a single YAML document in the order, **hosts**, **groups**, and the **strategies**.
49+
50+
Alternatively if the config parameter `proxy.config.url_remap.strategies.filename` refers to
51+
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 vaild `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.
52+
53+
Hosts definitions
54+
=================
55+
56+
The **hosts** definitions is a **YAML** list of hosts. This list is **optional** but if not used, the
57+
**groups** list **must** include complete defintions for hosts. See the **group** examples below.
58+
59+
In the example below, **hosts** is a **YAML** list of hosts. Each host entry uses a **YAML** anchor,
60+
**&p1** and **&p2** that may be used elsewhere in the **YAML** document to refer to hosts **p1** and **p2**.
61+
62+
- **host**: the host value is a hostname string
63+
- **protocol**: a list of schemes, ports, and health check urls for the host.
64+
- **healthcheck**: health check information with the **url** used to check
65+
the hosts health by some external health check agent.
66+
67+
Example::
68+
69+
hosts:
70+
- &p1
71+
host: p1.foo.com
72+
protocol:
73+
- scheme: http
74+
port: 80
75+
health_check_url: http://192.168.1.1:80
76+
- scheme: https
77+
port: 443
78+
health_check_url: https://192.168.1.1:443
79+
- &p2
80+
host: p2.foo.com
81+
protocol:
82+
- scheme: http
83+
port: 80
84+
health_check_url: http://192.168.1.2:80
85+
86+
Groups definitions
87+
==================
88+
89+
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 remaing groups are used failover. The **strategies** **policy** specifies how the groups are used.
90+
91+
Below are examples of group definitions. The first example is using **YAML** anchors and references.
92+
When using **references**, the complete **YAML** document must include the **anchors** portion of the document first.
93+
94+
The second example shows a complete **groups** definition without the use of a **hosts** name space and it's **YAML** anchors.
95+
96+
The field defintions in the examples below are defined in the **hosts** section.
97+
98+
Example using **YAML** anchors and references::
99+
100+
groups:
101+
- &g1
102+
- <<: *p1
103+
weight: 1.5
104+
- <<: *p2
105+
weight: 0.5
106+
- &g2
107+
- <<: *p3
108+
weight: 0.5
109+
- <<: *p4
110+
weight: 1.5
111+
112+
Explicitly defined Example, no **YAML** referenences::
113+
114+
groups:
115+
- &g1
116+
- p1
117+
host: p1.foo.com
118+
protocol:
119+
- scheme: http
120+
port: 80
121+
health_check_url: http://192.168.1.1:80
122+
- scheme: https
123+
port: 443
124+
health_check_url: https://192.168.1.1:443
125+
weight: 0.5
126+
- p2
127+
host: p2.foo.com
128+
protocol:
129+
- scheme: http
130+
port: 80
131+
health_check_url: http://192.168.1.2:80
132+
- scheme: https
133+
port: 443
134+
health_check_url: https://192.168.1.2:443
135+
weight: 0.5
136+
- &g2
137+
- p3
138+
host: p3.foo.com
139+
protocol:
140+
- scheme: http
141+
port: 80
142+
health_check_url: http://192.168.1.3:80
143+
- scheme: https
144+
port: 443
145+
health_check_url: https://192.168.1.3:443
146+
weight: 0.5
147+
- p4
148+
host: p4.foo.com
149+
protocol:
150+
- scheme: http
151+
port: 80
152+
health_check_url: http://192.168.1.4:80
153+
- scheme: https
154+
port: 443
155+
health_check_url: https://192.168.1.4:443
156+
weight: 0.5
157+
158+
Strategies defintions
159+
=====================
160+
161+
The **strategies** namespace defines a **YAML** list of strategies that may be applied to a **remap**
162+
entry using the **@strategy** tag in remap.config.
163+
164+
Each **strategy** in the list may using the following parameters::
165+
166+
- **strategy**: The value is the name of the strategy.
167+
- **policy**: The algorithm the **strategy** uses to select hosts. Currently one of the following:
168+
169+
#. **rr_ip**: round robin selection using the modulus of the client IP
170+
#. **rr_strict**: strict round robin over the list of hosts in the primary group.
171+
#. **first_live**: always selects the first host in the primary group. Other hosts are selected when the first host fails.
172+
#. **latched**: Same as **first_live** but primary selection sticks to whatever host was used by a previous transaction.
173+
#. **consistent_hash**: hosts are selected using a **hash_key**.
174+
175+
- **hash_key**: The hashing key used by the **consistent_hash** policy. If not specified, defaults to **path** which is the
176+
same policy used in the **parent.config** implementation. Use one of::
177+
#. **hostname**: Creates a hash using the **hostname** in the request URL.
178+
#. **path**: (**default**) Creates a hash over the path poertion of the request URL.
179+
#. **path+query**: Same as **path** but adds the **query string** in the request URL.
180+
#. **path+fragment**: Same as **path** but adds the fragement portion of the URL.
181+
#. **cache_key**: Uses the hash key from the **cachekey** plugin. defaults to **path** if the **cachekey** plugin is not configured on the **remap**.
182+
#. **url**: Creates a hash from the entire request url.
183+
184+
- **go_direct** - A boolean value indicating whether a transaction may bypass proxies and go direct to the origin. Defaults to **true**
185+
- **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 reamp are trafficserver caches. **false** means the hosts are origins that the next hop strategies may use for load balancing and/or failover.
186+
- **scheme** Indicates which scheme the strategy supports, *http* or *https*
187+
- **failover**: A map of **failover** information.
188+
- **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.
189+
190+
- **ring_mode**: Part of the **failover** map. The host ring selection mode. Use either **exhaust_ring** or **alternate_ring**
191+
#. **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.
192+
#. **alternate_ring**: retry hosts are selected from groups in an alternating group fashion.
193+
- **response_codes**: Part of the **failover** map. This is a list of **http** response codes that may be used for **simple retry**.
194+
- **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**.
195+
196+
197+
Example::
198+
199+
#include unit-tests/hosts.yaml
200+
#
201+
strategies:
202+
- strategy: 'strategy-1'
203+
policy: consistent_hash
204+
hash_key: cache_key
205+
go_direct: false
206+
groups:
207+
- *g1
208+
- *g2
209+
scheme http
210+
failover:
211+
ring_mode: exhaust_ring
212+
response_codes:
213+
- 404
214+
- 503
215+
health_check:
216+
- passive
217+
- strategy: 'strategy-2'
218+
policy: rr_strict
219+
hash_key: cache_key
220+
go_direct: true
221+
groups:
222+
- *g1
223+
- *g2
224+
scheme http
225+
failover:
226+
ring_mode: exhaust_ring
227+
response_codes:
228+
- 404
229+
- 503
230+
health_check:
231+
- passive

‎mgmt/RecordsConfig.cc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1044,6 +1044,8 @@ static const RecordElement RecordsConfig[] =
10441044
,
10451045
{RECT_CONFIG, "proxy.config.url_remap.filename", RECD_STRING, ts::filename::REMAP, RECU_DYNAMIC, RR_NULL, RECC_NULL, nullptr, RECA_NULL}
10461046
,
1047+
{RECT_CONFIG, "proxy.config.url_remap.strategies.filename", RECD_STRING, "strategies.yaml", RECU_DYNAMIC, RR_NULL, RECC_NULL, nullptr, RECA_NULL}
1048+
,
10471049
{RECT_CONFIG, "proxy.config.url_remap.remap_required", RECD_INT, "1", RECU_DYNAMIC, RR_NULL, RECC_INT, "[0-1]", RECA_NULL}
10481050
,
10491051
{RECT_CONFIG, "proxy.config.url_remap.pristine_host_hdr", RECD_INT, "0", RECU_DYNAMIC, RR_NULL, RECC_INT, "[0-1]", RECA_NULL}

‎proxy/ParentSelection.cc‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,6 @@ static const char *default_var = "proxy.config.http.parent_proxies";
4848
static const char *retry_var = "proxy.config.http.parent_proxy.retry_time";
4949
static const char *threshold_var = "proxy.config.http.parent_proxy.fail_threshold";
5050

51-
static const char *ParentResultStr[] = {"PARENT_UNDEFINED", "PARENT_DIRECT", "PARENT_SPECIFIED", "PARENT_AGENT", "PARENT_FAIL"};
52-
5351
//
5452
// Config Callback Prototypes
5553
//

0 commit comments

Comments
 (0)