[trafficserver] branch master updated: Add docs for parent_select plugin (#8055)

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rob pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/master by this push:
     new e5ce8ed  Add docs for parent_select plugin (#8055)
e5ce8ed is described below

commit e5ce8ed78438d1da2582ce5f4f0623aa55fa1ae2
Author: Robert O Butts <ro...@users.noreply.github.com>
AuthorDate: Mon Jul 12 09:48:03 2021 -0600

    Add docs for parent_select plugin (#8055)
---
 doc/admin-guide/plugins/index.en.rst         |  5 +++
 doc/admin-guide/plugins/parent_select.en.rst | 65 ++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)

diff --git a/doc/admin-guide/plugins/index.en.rst b/doc/admin-guide/plugins/index.en.rst
index 7d29199..a848475 100644
--- a/doc/admin-guide/plugins/index.en.rst
+++ b/doc/admin-guide/plugins/index.en.rst
@@ -165,6 +165,7 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
    MP4 <mp4.en>
    Multiplexer <multiplexer.en>
    MySQL Remap <mysql_remap.en>
+   Parent Select <parent_select.en>
    Rate Limit <rate_limit.en>
    URI Signing <uri_signing.en>
    Legacy Signed URLs <url_sig.en>
@@ -231,6 +232,10 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
 :doc:`Prefetch <prefetch.en>`
    Pre-fetch objects based on the requested URL path pattern.
 
+:doc:`Parent Select <parent_select.en>`
+   This remap plugin allows selection of parent proxies or origins during requests. This
+   provides the same functionality as the core :file:`parent.config` and :file:`strategies.yaml` config files.
+
 :doc:`Rate Limit <rate_limit.en>`
    Simple transaction rate limiting.
 
diff --git a/doc/admin-guide/plugins/parent_select.en.rst b/doc/admin-guide/plugins/parent_select.en.rst
new file mode 100644
index 0000000..6ff352e
--- /dev/null
+++ b/doc/admin-guide/plugins/parent_select.en.rst
@@ -0,0 +1,65 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. include:: ../../common.defs
+
+.. _admin-plugins-parent-select:
+
+Parent Select Plugin
+********************
+
+This remap plugin allows selection of parent proxies or origins during
+requests. This provides the same functionality as the core :file:`parent.config`
+and :file:`strategies.yaml` config files via a plugin.
+
+Purpose
+=======
+
+The purpose of this plugin is to provide a base for creating custom
+parent selection plugins, as well as to eventually replace the core
+parent and strategy logic so all nontrivial parent selection will
+be done via plugins.
+
+Installation
+============
+
+This plugin is still experimental, but is included with |TS| when you
+build with the experimental plugins enabled via ``configure``.
+
+Configuration
+=============
+
+This plugin only functions as a remap plugin, and is therefore
+configured in :file:`remap.config`.
+
+It requires two options: the strategies config file, and the name of the strategy.
+
+For example, a remap.config line might look like:
+
+.. code-block::
+
+    map https://example.net/ https://example.net/ @plugin=parent_select.so @pparam=strategies.yaml @pparam=example-strategy
+
+This means all remap rules can use the same ``strategies.yaml`` file containing multiple strategies, or each remap rule can have its own strategies file, whichever the operator prefers.
+
+
+Strategies file
+---------------
+
+The ``strategies.yaml`` file is the same format as the core ``strategies.yaml`` config file.
+
+See :doc:`../files/strategies.yaml.en`.