"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/source/contributor/caching-layer.rst" between
keystone-17.0.0.tar.gz and keystone-18.0.0.tar.gz

About: OpenStack Keystone (Core Service: Identity) provides an authentication and authorization service for other OpenStack services. Provides a catalog of endpoints for all OpenStack services.
The "Victoria" series (latest release).

caching-layer.rst  (keystone-17.0.0):caching-layer.rst  (keystone-18.0.0)
skipping to change at line 22 skipping to change at line 22
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations License for the specific language governing permissions and limitations
under the License. under the License.
============= =============
Caching Layer Caching Layer
============= =============
The caching layer is designed to be applied to any ``manager`` object within Key stone The caching layer is designed to be applied to any ``manager`` object within Key stone
via the use of the ``on_arguments`` decorator provided in the ``keystone.common. via the use of ``keystone.common.cache`` module. This leverages `oslo.cache`_ ca
cache`` ching
module. This decorator leverages `dogpile.cache`_ caching system to provide a f system to provide a flexible caching backend.
lexible
caching backend.
It is recommended that each of the managers have an independent toggle within th
e config
file to enable caching. The easiest method to utilize the toggle within the
configuration file is to define a ``caching`` boolean option within that manager
's
configuration section (e.g. ``identity``). Once that option is defined you can
pass function to the ``on_arguments`` decorator with the named argument ``should
_cache_fn``.
In the ``keystone.common.cache`` module, there is a function called ``should_cac
he_fn``,
which will provide a reference, to a function, that will consult the global cach
e
``enabled`` option as well as the specific manager's caching enable toggle.
.. NOTE::
If a section-specific boolean option is not defined in the config sectio
n specified when
calling ``should_cache_fn``, the returned function reference will defaul
t to enabling
caching for that ``manager``.
Example use of cache and ``should_cache_fn`` (in this example, ``token`` is the .. _oslo.cache: https://opendev.org/openstack/oslo.cache
manager):
The caching can be setup for all or some subsystems. It is recommended that each
of the
managers have an independent toggle within the config file to enable caching. Th
e easiest
method to utilize the toggle within the configuration file is to define a ``cach
ing``
boolean option within that manager's configuration section (e.g. ``identity``).
Enable the
global cache ``enabled`` option as well as the specific manager's caching enable
toggle in
order to cache that subsystem.
The `oslo.cache`_ is simple and easy to adopt by any system. See the `usage guid
e`_ of
it. There are various cache :ref:`backends <caching_layer>` supported by it. Exa
mple use of
`oslo.cache`_ in keystone (in this example, ``token`` is the manager):
.. code-block:: python .. code-block:: python
from keystone.common import cache from keystone.common import cache
SHOULD_CACHE = cache.should_cache_fn('token')
@cache.on_arguments(should_cache_fn=SHOULD_CACHE) TOKENS_REGION = cache.create_region(name='tokens')
def cacheable_function(arg1, arg2, arg3): MEMOIZE_TOKENS = cache.get_memoization_decorator(
group='token',
region=TOKENS_REGION)
@MEMOIZE_TOKENS
def _validate_token(self, token_id):
... ...
return some_value return token
.. _usage guide: https://docs.openstack.org/oslo.cache/latest/user/usage.html
With the above example, each call to the ``cacheable_function`` would check to s ee if With the above example, each call to the ``cacheable_function`` would check to s ee if
the arguments passed to it matched a currently valid cached item. If the return value the arguments passed to it matched a currently valid cached item. If the return value
was cached, the caching layer would return the cached value; if the return value was was cached, the caching layer would return the cached value; if the return value was
not cached, the caching layer would call the function, pass the value to the ``S not cached, the caching layer would call the function, pass the value to the
HOULD_CACHE`` ``MEMOIZE_TOKEN`` decorator, which would then determine if caching was globally
function reference, which would then determine if caching was globally enabled a enabled
nd enabled and enabled for the ``token`` manager. If either caching toggle is disabled, th
for the ``token`` manager. If either caching toggle is disabled, the value is r e value
eturned but is returned but not cached.
not cached.
It is recommended that each of the managers have an independent configurable tim
It is recommended that each of the managers have an independent configurable tim e-to-live
e-to-live (TTL). (TTL). The option ``cache_time`` is to be set for every manager under its sectio
If a configurable TTL has been defined for the manager configuration section, it n in
is possible to keystone.conf file. If the ``cache_time`` is set to ``None``, the expiration tim
pass it to the ``cache.on_arguments`` decorator with the named-argument ``expira e will be
tion_time``. For set to the global default ``expiration_time`` option in the ``[cache]`` configur
consistency, it is recommended that this option be called ``cache_time`` and def ation section.
ault to ``None``. These options are passed to and handled by oslo.cache.
If the ``expiration_time`` argument passed to the decorator is set to ``None``,
the expiration
time will be set to the global default (``expiration_time`` option in the ``[cac
he]``
configuration section.
Example of using a section specific ``cache_time`` (in this example, ``identity` :ref:`Cache invalidation <cache_invalidation>` can be done if specific cache ent
` is the manager): ries are changed.
Example of invalidating a cache (in this example, ``token`` is the manager):
.. code-block:: python .. code-block:: python
from keystone.common import cache def invalidate_individual_token_cache(self, token_id):
SHOULD_CACHE = cache.should_cache_fn('identity')
@cache.on_arguments(should_cache_fn=SHOULD_CACHE,
expiration_time=CONF.identity.cache_time)
def cachable_function(arg1, arg2, arg3):
... ...
return some_value self._validate_token.invalidate(self, token_id)
For cache invalidation, the ``on_arguments`` decorator will add an ``invalidate`
` method
(attribute) to your decorated function. To invalidate the cache, you pass the s
ame arguments
to the ``invalidate`` method as you would the normal function.
Example (using the above cacheable_function):
.. code-block:: python
def invalidate_cache(arg1, arg2, arg3):
cacheable_function.invalidate(arg1, arg2, arg3)
.. WARNING::
The ``on_arguments`` decorator does not accept keyword-arguments/named argum
ents. An
exception will be raised if keyword arguments are passed to a caching-decora
ted function.
.. NOTE::
In all cases methods work the same as functions except if you are attempting
to invalidate
the cache on a decorated bound-method, you need to pass ``self`` to the ``i
nvalidate``
method as the first argument before the arguments.
.. _`dogpile.cache`: http://dogpilecache.readthedocs.org/
dogpile.cache based MongoDB (NoSQL) backend
The ``dogpile.cache`` based MongoDB backend implementation allows for various Mo
ngoDB
configurations, e.g., standalone, a replica set, sharded replicas, with or witho
ut SSL,
use of TTL type collections, etc.
Example of typical configuration for MongoDB backend:
.. code-block:: python
from dogpile.cache import region
arguments = {
'db_hosts': 'localhost:27017',
'db_name': 'ks_cache',
'cache_collection': 'cache',
'username': 'test_user',
'password': 'test_password',
# optional arguments
'son_manipulator': 'my_son_manipulator_impl'
}
region.make_region().configure('keystone.cache.mongo',
arguments=arguments)
The optional `son_manipulator` is used to manipulate custom data type while its
saved in
or retrieved from MongoDB. If the dogpile cached values contain built-in data ty
pes and no
custom classes, then the provided implementation class is sufficient. For furthe
r details, refer
http://api.mongodb.org/python/current/examples/custom_type.html#automatic-encodi
ng-and-decoding
Similar to other backends, this backend can be added via Keystone configuration
in
``keystone.conf``::
[cache]
# Global cache functionality toggle.
enabled = True
# Referring to specific cache backend
backend = keystone.cache.mongo
# Backend specific configuration arguments
backend_argument = db_hosts:localhost:27017
backend_argument = db_name:ks_cache
backend_argument = cache_collection:cache
backend_argument = username:test_user
backend_argument = password:test_password
This backend is registered in ``keystone.common.cache.core`` module. So, its usa For cache invalidation, there is an ``invalidate`` method (attribute) on the dec
ge orated function.
is similar to other dogpile caching backends as it implements the same dogpile A To invalidate the cache, pass the same arguments to the ``invalidate`` method as
PIs. you would the
normal function. This means you need to pass ``self`` as the first argument.
 End of changes. 10 change blocks. 
145 lines changed or deleted 53 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)