Move caching docs into admin-guide
The admin-guide and configuration guide both had separate sections dedicated to documenting caching. This patch attempts to consolidate them into a single section in the admin-guide. It also takes the opportunity to update a couple pieces of information that have changed since writing the original docs in configuration.rst. The old configuration section also reference a lot of configuration options for caching. These were removed because they should be documented in the configuration guide. Change-Id: Ifb39075a6a78419e5c44c7e0871f3e1c055c2332
This commit is contained in:
Lance Bragstad
parent
0bc462a8c1
commit
6ae5cbc383
|
|
@ -3,14 +3,16 @@
|
|||
Caching layer
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
OpenStack Identity supports a caching layer that is above the
|
||||
configurable subsystems (for example, token). OpenStack Identity uses the
|
||||
`oslo.cache <https://docs.openstack.org/developer/oslo.cache/>`__
|
||||
library which allows flexible cache back ends. The majority of the
|
||||
caching configuration options are set in the ``[cache]`` section of the
|
||||
``/etc/keystone/keystone.conf`` file. However, each section that has
|
||||
the capability to be cached usually has a caching boolean value that
|
||||
toggles caching.
|
||||
OpenStack Identity supports a caching layer that is above the configurable
|
||||
subsystems (for example, token). This gives you the flexibility to setup
|
||||
caching for all or some subsystems. OpenStack Identity uses the `oslo.cache
|
||||
<https://docs.openstack.org/developer/oslo.cache/>`__ library which allows
|
||||
flexible cache back ends. The majority of the caching configuration options are
|
||||
set in the ``[cache]`` section of the ``/etc/keystone/keystone.conf`` file. The
|
||||
``enabled`` option of the ``[cache]`` section must be set to ``True`` in order
|
||||
for any subsystem to cache responses. Each section that has the capability to
|
||||
be cached will have a caching boolean value that toggles caching behavior of
|
||||
that particular subsystem.
|
||||
|
||||
So to enable only the token back end caching, set the values as follows:
|
||||
|
||||
|
|
@ -42,14 +44,15 @@ So to enable only the token back end caching, set the values as follows:
|
|||
|
||||
.. note::
|
||||
|
||||
Since the Newton release, the default setting is enabled for subsystem
|
||||
caching and the global toggle. As a result, all subsystems that support
|
||||
caching are doing this by default.
|
||||
Each subsystem is configured to cache by default. However, the global
|
||||
toggle for caching defaults to ``False``. A subsystem is only able to cache
|
||||
responses if the global toggle is enabled.
|
||||
|
||||
Caching for tokens and tokens validation
|
||||
----------------------------------------
|
||||
|
||||
All types of tokens benefit from caching, including Fernet tokens. Although
|
||||
The token subsystem is OpenStack Identity's most heavily used API. As a result,
|
||||
all types of tokens benefit from caching, including Fernet tokens. Although
|
||||
Fernet tokens do not need to be persisted, they should still be cached for
|
||||
optimal token validation performance.
|
||||
|
||||
|
|
@ -111,6 +114,26 @@ options), see:
|
|||
|
||||
- `dogpile.cache.dbm <https://dogpilecache.readthedocs.io/en/latest/api.html#file-backends>`__
|
||||
|
||||
Cache invalidation
|
||||
------------------
|
||||
|
||||
A common concern with caching is relaying inaccurate information after updating
|
||||
or deleting a resource. Most subsystems within OpenStack Identity invalidate
|
||||
specific cache entries once they have changed. In cases where a specific cache
|
||||
entry cannot be invalidated from the cache, the cache region will be
|
||||
invalidated instead. This invalidates all entries within the cache to prevent
|
||||
returning stale or misleading data. A subsequent request for the resource will
|
||||
be fully processed and cached.
|
||||
|
||||
.. WARNING::
|
||||
Be aware that if a read-only back end is in use for a particular subsystem,
|
||||
the cache will not immediately reflect changes performed through the back
|
||||
end. Any given change may take up to the ``cache_time`` (if set in the
|
||||
subsystem section of the configuration) or the global ``expiration_time``
|
||||
(set in the ``[cache]`` section of the configuration) before it is
|
||||
reflected. If this type of delay is an issue, we recommend disabling
|
||||
caching for that particular subsystem.
|
||||
|
||||
Configure the Memcached back end example
|
||||
----------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -584,154 +584,6 @@ plugins specified in ``methods``. This effectively disables external
|
|||
authentication. For more details, refer to :doc:`External Authentication
|
||||
<advanced-topics/external-auth>`.
|
||||
|
||||
Caching Layer
|
||||
=============
|
||||
|
||||
Keystone's configuration file offers two separate sections related to caching,
|
||||
``[memcache]`` and ``[cache]``. The ``[memcache]`` section provides caching
|
||||
options to configure memcache backends. For example, if your deployment issues
|
||||
UUID tokens (``[token] provider = uuid``) and your token storage driver is
|
||||
memcache (``[token] driver = kvs``), the configuration options in the
|
||||
``[memcache]`` section will effect token storage behavior. The ``[cache]``
|
||||
section is provided through the ``oslo.cache`` library and consists of options
|
||||
to configure the caching of data between a particular keystone subsystem (e.g.
|
||||
``token``, ``identity``, etc) and its configured storage backend. For example,
|
||||
if your deployment's identity backend is using SQL (``[identity] driver =
|
||||
sql``) and you have caching enabled (``[cache] enabled = true``),
|
||||
``oslo.cache`` will cache responses from SQL improving the overall performance
|
||||
of the identity subsystem. The options in the ``[cache]`` section will effect
|
||||
the caching layer in-between a keystone subsystem and its storage backend.
|
||||
|
||||
Keystone uses the `dogpile.cache`_ library which allows for flexible cache
|
||||
backends. The majority of the caching configuration options are set in the
|
||||
``[cache]`` section. However, each section that has the capability to be
|
||||
cached usually has a ``caching`` boolean value that will toggle caching for
|
||||
that specific section. The current default behavior is that global and
|
||||
subsystem caching is enabled.
|
||||
|
||||
``[cache]`` configuration section
|
||||
---------------------------------
|
||||
|
||||
* ``enabled`` - enables/disables caching across all of keystone
|
||||
* ``debug_cache_backend`` - enables more in-depth logging from the cache
|
||||
backend (get, set, delete, etc)
|
||||
* ``backend`` - the caching backend module to use e.g.
|
||||
``dogpile.cache.memcached``
|
||||
|
||||
.. NOTE::
|
||||
A given ``backend`` must be registered with ``dogpile.cache`` before it
|
||||
can be used. The default backend is the keystone no-op backend
|
||||
(``keystone.common.cache.noop``). If caching is desired a different
|
||||
backend will need to be specified. Current functional backends are:
|
||||
|
||||
* ``dogpile.cache.memcached`` - Memcached backend using the standard
|
||||
`python-memcached`_ library (recommended for use with Apache httpd with
|
||||
``mod_wsgi``)
|
||||
* ``dogpile.cache.pylibmc`` - Memcached backend using the `pylibmc`_
|
||||
library
|
||||
* ``dogpile.cache.bmemcached`` - Memcached using `python-binary-memcached`_
|
||||
library.
|
||||
* ``dogpile.cache.redis`` - `Redis`_ backend
|
||||
* ``dogpile.cache.dbm`` - local DBM file backend
|
||||
* ``dogpile.cache.memory`` - in-memory cache
|
||||
* ``oslo_cache.mongo`` - MongoDB as caching backend
|
||||
* ``oslo_cache.memcache_pool`` - Memcache with pooling.
|
||||
This implementation also provides client connection re-use.
|
||||
|
||||
.. WARNING::
|
||||
``dogpile.cache.memory`` is not suitable for use outside of unit
|
||||
testing as it does not cleanup its internal cache on cache
|
||||
expiration, does not provide isolation to the cached data (values
|
||||
in the store can be inadvertently changed without extra layers of
|
||||
data protection added), and does not share cache between processes.
|
||||
This means that caching and cache invalidation will not be
|
||||
consistent or reliable when using ``keystone`` and the
|
||||
``dogpile.cache.memory`` backend under any real workload.
|
||||
|
||||
* ``expiration_time`` - int, the default length of time to cache a specific
|
||||
value. A value of ``0`` indicates to not cache anything. It is recommended
|
||||
that the ``enabled`` option be used to disable cache instead of setting this
|
||||
to ``0``.
|
||||
* ``backend_argument`` - an argument passed to the backend when instantiated
|
||||
``backend_argument`` should be specified once per argument to be passed to
|
||||
the backend and in the format of ``<argument name>:<argument value>``. e.g.:
|
||||
``backend_argument = host:localhost``
|
||||
* ``proxies`` - comma delimited list of `ProxyBackends`_ e.g.
|
||||
``my.example.Proxy, my.example.Proxy2``
|
||||
|
||||
Current keystone systems that have caching capabilities:
|
||||
* ``token``
|
||||
The token system has a separate ``cache_time`` configuration option,
|
||||
that can be set to a value above or below the global
|
||||
``expiration_time`` default, allowing for different caching behavior
|
||||
from the other systems in keystone. This option is set in the
|
||||
``[token]`` section of the configuration file.
|
||||
|
||||
The Token Revocation List cache time is handled by the configuration
|
||||
option ``revocation_cache_time`` in the ``[token]`` section. The
|
||||
revocation list is refreshed whenever a token is revoked. It typically
|
||||
sees significantly more requests than specific token retrievals or
|
||||
token validation calls.
|
||||
* ``resource``
|
||||
The resource system has a separate ``cache_time`` configuration option,
|
||||
that can be set to a value above or below the global
|
||||
``expiration_time`` default, allowing for different caching behavior
|
||||
from the other systems in keystone. This option is set in the
|
||||
``[resource]`` section of the configuration file.
|
||||
|
||||
Currently ``resource`` has caching for ``project`` and ``domain``
|
||||
specific requests (primarily around the CRUD actions). The
|
||||
``list_projects`` and ``list_domains`` methods are not subject to
|
||||
caching.
|
||||
|
||||
.. WARNING::
|
||||
Be aware that if a read-only ``resource`` backend is in use, the
|
||||
cache will not immediately reflect changes on the back end. Any
|
||||
given change may take up to the ``cache_time`` (if set in the
|
||||
``[resource]`` section of the configuration) or the global
|
||||
``expiration_time`` (set in the ``[cache]`` section of the
|
||||
configuration) before it is reflected. If this type of delay (when
|
||||
using a read-only ``resource`` backend) is an issue, it is
|
||||
recommended that caching be disabled on ``resource``. To disable
|
||||
caching specifically on ``resource``, in the ``[resource]`` section
|
||||
of the configuration set ``caching`` to ``False``.
|
||||
* ``role``
|
||||
Currently ``role`` has caching for ``get_role``, but not for ``list_roles``.
|
||||
The role system has a separate ``cache_time`` configuration option,
|
||||
that can be set to a value above or below the global ``expiration_time``
|
||||
default, allowing for different caching behavior from the other systems in
|
||||
keystone. This option is set in the ``[role]`` section of the
|
||||
configuration file.
|
||||
|
||||
.. WARNING::
|
||||
Be aware that if a read-only ``role`` backend is in use, the cache
|
||||
will not immediately reflect changes on the back end. Any given change
|
||||
may take up to the ``cache_time`` (if set in the ``[role]``
|
||||
section of the configuration) or the global ``expiration_time`` (set in
|
||||
the ``[cache]`` section of the configuration) before it is reflected.
|
||||
If this type of delay (when using a read-only ``role`` backend) is
|
||||
an issue, it is recommended that caching be disabled on ``role``.
|
||||
To disable caching specifically on ``role``, in the ``[role]``
|
||||
section of the configuration set ``caching`` to ``False``.
|
||||
|
||||
For more information about the different backends (and configuration options):
|
||||
* `dogpile.cache.backends.memory`_
|
||||
* `dogpile.cache.backends.memcached`_
|
||||
* `dogpile.cache.backends.redis`_
|
||||
* `dogpile.cache.backends.file`_
|
||||
|
||||
.. _`dogpile.cache`: http://dogpilecache.readthedocs.org/en/latest/
|
||||
.. _`python-memcached`: http://www.tummy.com/software/python-memcached/
|
||||
.. _`pylibmc`: http://sendapatch.se/projects/pylibmc/index.html
|
||||
.. _`python-binary-memcached`: https://github.com/jaysonsantos/python-binary-memcached
|
||||
.. _`Redis`: http://redis.io/
|
||||
.. _`dogpile.cache.backends.memory`: http://dogpilecache.readthedocs.org/en/latest/api.html#memory-backend
|
||||
.. _`dogpile.cache.backends.memcached`: http://dogpilecache.readthedocs.org/en/latest/api.html#memcached-backends
|
||||
.. _`dogpile.cache.backends.redis`: http://dogpilecache.readthedocs.org/en/latest/api.html#redis-backends
|
||||
.. _`dogpile.cache.backends.file`: http://dogpilecache.readthedocs.org/en/latest/api.html#file-backends
|
||||
.. _`ProxyBackends`: http://dogpilecache.readthedocs.org/en/latest/api.html#proxy-backends
|
||||
|
||||
|
||||
Certificates for PKI
|
||||
====================
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue