Merge "Included a 'Caching' section to the Identity chapter"
This commit is contained in:
commit
d8c951c6f1
@ -28,6 +28,7 @@
|
||||
<xi:include href="../common/section_keystone-external-auth.xml"/>
|
||||
<xi:include href="../common/section_keystone_config_ldap.xml"/>
|
||||
<xi:include href="identity/section_keystone-token-binding.xml"/>
|
||||
<xi:include href="identity/section_caching-layer.xml"/>
|
||||
<section xml:id="user-crud">
|
||||
<title>User CRUD</title>
|
||||
<para>Identity provides a user CRUD filter that can
|
||||
|
117
doc/admin-guide-cloud/identity/section_caching-layer.xml
Normal file
117
doc/admin-guide-cloud/identity/section_caching-layer.xml
Normal file
@ -0,0 +1,117 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
version="5.0"
|
||||
xml:id="section_caching-layer">
|
||||
<?dbhtml stop-chunking?>
|
||||
<title>Caching layer</title>
|
||||
<para>OpenStack Identity supports a caching layer that is above the
|
||||
configurable subsystems (for example, token, assignment). OpenStack Identity
|
||||
uses the <link xlink:href="http://dogpilecache.readthedocs.org/en/latest/">
|
||||
<literal>dogpile.cache</literal></link> library which allows flexible
|
||||
cache backends. The majority of the caching configuration options are set in
|
||||
the <literal>[cache]</literal> section of the <filename>keystone.conf</filename>
|
||||
file. However, each section that has the capability to be cached usually
|
||||
has a caching boolean value that toggles caching.</para>
|
||||
<para>So to enable only the token backend caching, set the values as follows:</para>
|
||||
<programlisting language="ini">[cache]
|
||||
enabled=true
|
||||
|
||||
[assignment]
|
||||
caching=false
|
||||
|
||||
[token]
|
||||
caching=true</programlisting>
|
||||
<note><para>For the Juno release, the default setting is enabled for subsystem
|
||||
caching, but the global toggle is disabled. As a result, no caching in available
|
||||
unless the global toggle for <literal>[cache]</literal> is enabled by setting
|
||||
the value to <literal>true</literal>.</para></note>
|
||||
<section xml:id="caching_layer-token">
|
||||
<title>Caching for tokens and tokens validation</title>
|
||||
<para>
|
||||
The token system has a separate <literal>cache_time</literal> configuration
|
||||
option, that can be set to a value above or below the global
|
||||
<literal>expiration_time</literal> default, allowing for different caching
|
||||
behavior from the other systems in OpenStack Identity. This option
|
||||
is set in the <literal>[token]</literal> section of the configuration file.
|
||||
</para>
|
||||
<para>
|
||||
The token revocation list cache time is handled by the configuration
|
||||
option <literal>revocation_cache_time</literal> in the <literal>[token]</literal>
|
||||
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.
|
||||
</para>
|
||||
<para>Here is a list of actions that are affected by the cached time:
|
||||
getting a new token, revoking tokens, validating tokens, checking v2 tokens,
|
||||
and checking v3 tokens.</para>
|
||||
<para>The delete token API calls invalidate the cache for the tokens being
|
||||
acted upon, as well as invalidating the cache for the revoked token list
|
||||
and the validate/check token calls.</para>
|
||||
<para>Token caching is configurable independently of the <literal>revocation_list</literal>
|
||||
caching. Lifted expiration checks from the token drivers to the token manager.
|
||||
This ensures that cached tokens will still raise a <literal>TokenNotFound</literal>
|
||||
flag when expired.</para>
|
||||
<para>For cache consistency, all token IDs are transformed into the short
|
||||
token hash at the provider and token driver level. Some methods have access
|
||||
to the full ID (PKI Tokens), and some methods do not. Cache invalidation is
|
||||
inconsistent without token ID normalization.</para>
|
||||
</section>
|
||||
<section xml:id="caching_layer-assignment">
|
||||
<title>Caching around assignment CRUD</title>
|
||||
<para>The assignment system has a separate <literal>cache_time</literal>
|
||||
configuration option, that can be set to a value above or below the global
|
||||
<literal>expiration_time</literal> default, allowing for different caching
|
||||
behavior from the other systems in Identity service. This option
|
||||
is set in the <literal>[assignment]</literal> section of the configuration file.</para>
|
||||
<para>
|
||||
Currently <literal>assignment</literal> has caching for <literal>project</literal>,
|
||||
<literal>domain</literal>, and <literal>role</literal> specific requests
|
||||
(primarily around the CRUD actions). Caching is currently not implemented
|
||||
on grants. The <literal>list</literal> methods are not subject to caching.</para>
|
||||
<para>Here is a list of actions that are affected by the assignment:
|
||||
assign domain API, assign project API, and assign role API.</para>
|
||||
<para>The create, update, and delete actions for domains, projects and
|
||||
roles will perform proper invalidations of the cached methods listed
|
||||
above.</para>
|
||||
<note>
|
||||
<para>
|
||||
If a read-only <literal>assignment</literal> back end is in
|
||||
use, the cache will not immediately reflect changes on the back end. Any
|
||||
given change may take up to the <literal>cache_time</literal> (if set in
|
||||
the <literal>[assignment]</literal> section of the configuration file)
|
||||
or the global <literal>expiration_time</literal> (set in the <literal>[cache]</literal>
|
||||
section of the configuration file) before it is reflected. If this type
|
||||
of delay (when using a read-only <literal>assignment</literal> backend)
|
||||
is an issue, it is recommended that caching be disabled on
|
||||
<literal>assignment</literal>. To disable caching specifically on
|
||||
<literal>assignment</literal>, in the <literal>[assignment]</literal>
|
||||
section of the configuration set <literal>caching</literal> to
|
||||
<literal>False</literal>.</para>
|
||||
</note>
|
||||
<para>For more information about the different backends (and configuration options), see:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para><link xlink:href="http://dogpilecache.readthedocs.org/en/latest/api.html#memory-backend">
|
||||
<literal>dogpile.cache.backends.memory</literal></link></para></listitem>
|
||||
<listitem><para><link xlink:href="http://dogpilecache.readthedocs.org/en/latest/api.html#memcached-backends">
|
||||
<literal>dogpile.cache.backends.memcached</literal></link></para>
|
||||
<note><para>The memory backend is not suitable for use in a production environment.</para></note></listitem>
|
||||
<listitem><para><link xlink:href="http://dogpilecache.readthedocs.org/en/latest/api.html#redis-backends">
|
||||
<literal>dogpile.cache.backends.redis</literal></link></para></listitem>
|
||||
<listitem><para><link xlink:href="http://dogpilecache.readthedocs.org/en/latest/api.html#file-backends">
|
||||
<literal>dogpile.cache.backends.file</literal></link></para></listitem>
|
||||
<listitem><para><literal>keystone.common.cache.backends.mongo</literal></para></listitem>
|
||||
</itemizedlist>
|
||||
<example>
|
||||
<title>Configure the Memcached backend</title>
|
||||
<para>The following example shows how to configure the memcached backend:</para>
|
||||
<programlisting language="ini">[cache]
|
||||
|
||||
enabled = true
|
||||
backend = dogpile.cache.memcached
|
||||
backend_argument = url:<replaceable>127.0.0.1</replaceable>:11211</programlisting>
|
||||
<para>You need to specify the URL to reach the <literal>memcached</literal> instance with the <literal>backend_argument</literal> parameter.</para>
|
||||
</example>
|
||||
</section>
|
||||
</section>
|
Loading…
Reference in New Issue
Block a user