"Fossies" - the Fresh Open Source Software Archive

Member "keystone-18.0.0/doc/source/admin/caching-layer.inc" (14 Oct 2020, 7832 Bytes) of package /linux/misc/openstack/keystone-18.0.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) fasm source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "caching-layer.inc" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 17.0.0_vs_18.0.0.

    1 .. -*- rst -*-
    2 
    3 .. _caching_layer:
    4 
    5 Caching layer
    6 =============
    7 
    8 OpenStack Identity supports a caching layer that is above the configurable
    9 subsystems (for example, token). This gives you the flexibility to setup
   10 caching for all or some subsystems. OpenStack Identity uses the `oslo.cache
   11 <https://docs.openstack.org/oslo.cache/latest/>`__ library which allows
   12 flexible cache back ends. The majority of the caching configuration options are
   13 set in the ``[cache]`` section of the ``/etc/keystone/keystone.conf`` file. The
   14 ``enabled`` option of the ``[cache]`` section must be set to ``True`` in order
   15 for any subsystem to cache responses. Each section that has the capability to
   16 be cached will have a ``caching`` boolean value that toggles caching behavior
   17 of that particular subsystem.
   18 
   19 So to enable only the token back end caching, set the values as follows:
   20 
   21 .. code-block:: ini
   22 
   23    [cache]
   24    enabled=true
   25 
   26    [catalog]
   27    caching=false
   28 
   29    [domain_config]
   30    caching=false
   31 
   32    [federation]
   33    caching=false
   34 
   35    [resource]
   36    caching=false
   37 
   38    [revoke]
   39    caching=false
   40 
   41    [role]
   42    caching=false
   43 
   44    [token]
   45    caching=true
   46 
   47 .. note::
   48 
   49    Each subsystem is configured to cache by default. However, the global
   50    toggle for caching defaults to ``False``. A subsystem is only able to cache
   51    responses if the global toggle is enabled.
   52 
   53 Current functional back ends are:
   54 
   55 ``dogpile.cache.null``
   56    A "null" backend that effectively disables all cache operations.(Default)
   57 
   58 ``dogpile.cache.memcached``
   59    Memcached back end using the standard ``python-memcached`` library.
   60 
   61 ``dogpile.cache.pylibmc``
   62    Memcached back end using the ``pylibmc`` library.
   63 
   64 ``dogpile.cache.bmemcached``
   65    Memcached using the ``python-binary-memcached`` library.
   66 
   67 ``dogpile.cache.redis``
   68    Redis back end.
   69 
   70 ``dogpile.cache.dbm``
   71    Local DBM file back end.
   72 
   73 ``dogpile.cache.memory``
   74    In-memory cache, not suitable for use outside of testing as it does not
   75    cleanup its internal cache on cache expiration and does not share cache
   76    between processes. This means that caching and cache invalidation will not
   77    be consistent or reliable.
   78 
   79 ``dogpile.cache.memory_pickle``
   80    In-memory cache, but serializes objects with pickle lib. It's not suitable
   81    for use outside of testing. The reason is the same with
   82    ``dogpile.cache.memory``
   83 
   84 ``oslo_cache.mongo``
   85    MongoDB as caching back end.
   86 
   87 ``oslo_cache.memcache_pool``
   88    Memcached backend that does connection pooling.
   89 
   90 ``oslo_cache.etcd3gw``
   91    Uses etcd 3.x for storage.
   92 
   93 ``oslo_cache.dict``
   94    A DictCacheBackend based on dictionary, not suitable for use outside of
   95    testing as it does not share cache between processes.This means that caching
   96    and cache invalidation will not be consistent or reliable.
   97 
   98 Caching for tokens and tokens validation
   99 ----------------------------------------
  100 
  101 The token subsystem is OpenStack Identity's most heavily used API. As a result,
  102 all types of tokens benefit from caching, including Fernet tokens. Although
  103 Fernet tokens do not need to be persisted, they should still be cached for
  104 optimal token validation performance.
  105 
  106 The token system has a separate ``cache_time`` configuration option,
  107 that can be set to a value above or below the global ``expiration_time``
  108 default, allowing for different caching behavior from the other systems
  109 in OpenStack Identity. This option is set in the ``[token]`` section of
  110 the configuration file.
  111 
  112 The token revocation list cache time is handled by the configuration
  113 option ``revocation_cache_time`` in the ``[token]`` section. The
  114 revocation list is refreshed whenever a token is revoked. It typically
  115 sees significantly more requests than specific token retrievals or token
  116 validation calls.
  117 
  118 Here is a list of actions that are affected by the cached time:
  119 
  120 * getting a new token
  121 * revoking tokens
  122 * validating tokens
  123 * checking v3 tokens
  124 
  125 The delete token API calls invalidate the cache for the tokens being
  126 acted upon, as well as invalidating the cache for the revoked token list
  127 and the validate/check token calls.
  128 
  129 Token caching is configurable independently of the ``revocation_list``
  130 caching. Lifted expiration checks from the token drivers to the token
  131 manager. This ensures that cached tokens will still raise a
  132 ``TokenNotFound`` flag when expired.
  133 
  134 For cache consistency, all token IDs are transformed into the short
  135 token hash at the provider and token driver level. Some methods have
  136 access to the full ID (PKI Tokens), and some methods do not. Cache
  137 invalidation is inconsistent without token ID normalization.
  138 
  139 Caching for non-token resources
  140 -------------------------------
  141 
  142 Various other keystone components have a separate ``cache_time`` configuration
  143 option, that can be set to a value above or below the global
  144 ``expiration_time`` default, allowing for different caching behavior
  145 from the other systems in Identity service. This option can be set in various
  146 sections (for example, ``[role]`` and ``[resource]``) of the configuration
  147 file.
  148 The create, update, and delete actions for domains, projects and roles
  149 will perform proper invalidations of the cached methods listed above.
  150 
  151 For more information about the different back ends (and configuration
  152 options), see:
  153 
  154 - `dogpile.cache.memory <https://dogpilecache.sqlalchemy.org/en/latest/api.html#memory-backends>`__
  155 
  156 - `dogpile.cache.memcached <https://dogpilecache.sqlalchemy.org/en/latest/api.html#memcached-backends>`__
  157 
  158   .. note::
  159 
  160      The memory back end is not suitable for use in a production
  161      environment.
  162 
  163 - `dogpile.cache.redis <https://dogpilecache.sqlalchemy.org/en/latest/api.html#redis-backends>`__
  164 
  165 - `dogpile.cache.dbm <https://dogpilecache.sqlalchemy.org/en/latest/api.html#file-backends>`__
  166 
  167 .. _cache_invalidation:
  168 
  169 Cache invalidation
  170 ------------------
  171 
  172 A common concern with caching is relaying inaccurate information after updating
  173 or deleting a resource. Most subsystems within OpenStack Identity invalidate
  174 specific cache entries once they have changed. In cases where a specific cache
  175 entry cannot be invalidated from the cache, the cache region will be
  176 invalidated instead. This invalidates all entries within the cache to prevent
  177 returning stale or misleading data. A subsequent request for the resource will
  178 be fully processed and cached.
  179 
  180 .. WARNING::
  181     Be aware that if a read-only back end is in use for a particular subsystem,
  182     the cache will not immediately reflect changes performed through the back
  183     end. Any given change may take up to the ``cache_time`` (if set in the
  184     subsystem section of the configuration) or the global ``expiration_time``
  185     (set in the ``[cache]`` section of the configuration) before it is
  186     reflected. If this type of delay is an issue, we recommend disabling
  187     caching for that particular subsystem.
  188 
  189 Configure the Memcached back end example
  190 ----------------------------------------
  191 
  192 The following example shows how to configure the memcached back end:
  193 
  194 .. code-block:: ini
  195 
  196    [cache]
  197 
  198    enabled = true
  199    backend = dogpile.cache.memcached
  200    backend_argument = url:127.0.0.1:11211
  201 
  202 You need to specify the URL to reach the ``memcached`` instance with the
  203 ``backend_argument`` parameter.
  204 
  205 Verbose cache logging
  206 ---------------------
  207 
  208 We do not recommend using verbose cache logging by default in production
  209 systems since it's extremely noisy. However, you may need to debug cache
  210 issues. One way to see how keystone is interacting with a cache backend is to
  211 enhance logging. The following configuration will aggregate oslo and dogpile
  212 logs into keystone's log file with increased verbosity:
  213 
  214 .. code-block:: ini
  215 
  216    [DEFAULT]
  217    default_log_levels = oslo.cache=DEBUG,dogpile.core.dogpile=DEBUG
  218 
  219    [cache]
  220    debug_cache_backend = True
  221 
  222 These logs will include cache hits and misses, making it easier to diagnose
  223 cache configuration and connectivity issues.