[trafficserver] branch 8.0.x updated: Doc: cache.config isn't a substitute for Cache-Control

[bc...@apache.org]

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

bcall pushed a commit to branch 8.0.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/8.0.x by this push:
     new dbb49cf  Doc: cache.config isn't a substitute for Cache-Control
dbb49cf is described below

commit dbb49cfc5526dbcfe6474e85a4cd851a3f1eb7ac
Author: Miles Libbey <ml...@apache.org>
AuthorDate: Sat Nov 17 16:33:48 2018 +0900

    Doc: cache.config isn't a substitute for Cache-Control
    
    As the first file in the admin-guide config files,
    and saying that the cache.config file
    controls the cache, folks think it is *the* way
    to get objects cached. Having the origin provide
    caching infor via the Cache-Control: header is the prefered
    method of communicating cache policies.
    
    (cherry picked from commit cc5f301a587658f477f9eadf6e31b08176f0a496)
---
 doc/admin-guide/files/cache.config.en.rst | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/doc/admin-guide/files/cache.config.en.rst b/doc/admin-guide/files/cache.config.en.rst
index 32e7552..40d3a05 100644
--- a/doc/admin-guide/files/cache.config.en.rst
+++ b/doc/admin-guide/files/cache.config.en.rst
@@ -22,8 +22,8 @@
 cache.config
 ************
 
-The :file:`cache.config` file  defines how |TS| caches web objects. You can add
-caching rules to specify the following:
+The :file:`cache.config` file allows you to overrule the origin's cache
+policies. You can add caching rules to specify the following:
 
 - Not to cache objects from specific IP addresses.
 - How long to pin particular objects in the cache.
@@ -32,6 +32,15 @@ caching rules to specify the following:
 
 .. important::
 
+   Generally, using this file to define cache policies is an antipattern.
+   It's usually better to have the origin specify the cache policy via the
+   `Cache-Control: <https://tools.ietf.org/html/rfc7234#section-5.2>`_ header.
+   That way, all the business logic stays with the content generation. The
+   origin is in a much better position to know which content can be safely
+   cached, and for how long. It can make fine grained decisions, changing
+   Cache-Control: header value per object. This file allows for some overrides
+   but, is relatively crude compared to what the origin can provide.
+
    After modifying :file:`cache.config`, run :option:`traffic_ctl config reload`
    to apply changes.