diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/server/caching.txt | 58 | ||||
| -rw-r--r-- | doc/server/index.txt | 1 | ||||
| -rw-r--r-- | doc/server/plugins/grouping/metadata.txt | 17 |
3 files changed, 73 insertions, 3 deletions
diff --git a/doc/server/caching.txt b/doc/server/caching.txt new file mode 100644 index 000000000..ab98e9902 --- /dev/null +++ b/doc/server/caching.txt @@ -0,0 +1,58 @@ +.. -*- mode: rst -*- + +.. _server-caching: + +=================== +Server-side Caching +=================== + +Metadata Caching +================ + +.. versionadded:: 1.3.0 + +Caching (or, rather, cache expiration) is always a difficult problem, +but it's particularly vexing in Bcfg2 due to the number of different +data sources incorporated. In 1.3.0, we introduce some limited +caching of client metadata objects. Since a client metadata object +can be generated anywhere from 7 to dozens of times per client run +(depending on your templates), and since client metadata generation +was made more complex and powerful in 1.3.0, caching these objects +provides the easiest performance gain. + +There are four caching modes available: + +* ``off``: No caching of client metadata objects is performed. This + is the default. +* ``initial``: Only initial metadata objects are cached. Initial + metadata objects are created only from the data in the + :ref:`server-plugins-grouping-metadata` plugin, before additional + groups from other plugins are merged in. +* ``cautious``: Final metadata objects are cached, but each client's + cache is cleared at the start of each client run, immediately after + probe data is received. Cache is also cleared as in ``aggressive`` + mode. ``on`` is a synonym for ``cautious``. +* ``aggressive``: Final metadata objects are cached. Each plugin is + responsible for clearing cache when appropriate. + +These are presented roughly in ascending order of speed, and +descending order of reliability. That is, odds are higher that +``aggressive`` mode will result in stale data, but it gives the +biggest speed boost. ``off`` will never result in stale data, but it +gives no speed boost. + +In addition to the :ref:`server-plugins-grouping-metadata` plugin, +Bcfg2 includes three plugins that can set additional groups, and thus +may affect the caching behavior. They are +:ref:`server-plugins-grouping-grouppatterns`, +:ref:`server-plugins-probes-index`, and +:ref:`server-plugins-connectors-puppetenc`. All of those plugins +**except** for PuppetENC fully support all caching levels. PuppetENC +is incompatible with ``aggressive``, and may result in some stale data +with ``cautious``. + +If you are not using the PuppetENC plugin, and do not have any custom +plugins that provide additional groups, then all four modes should be +safe to use. If you are using PuppetENC or have custom Connector +plugins that provide additional groups, then you may want to start +with ``cautious`` or ``initial``. diff --git a/doc/server/index.txt b/doc/server/index.txt index 1b832dbee..b28924034 100644 --- a/doc/server/index.txt +++ b/doc/server/index.txt @@ -31,3 +31,4 @@ clients. selinux backends database + caching diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index 88bb0c460..4e716bc1b 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -1,4 +1,4 @@ -.. -*- mode: rst -*- +].. -*- mode: rst -*- .. _server-plugins-grouping-metadata: @@ -107,9 +107,8 @@ but that is deprecated. For detailed information on client authentication see :ref:`appendix-guides-authentication` -================ Clients Database -================ +~~~~~~~~~~~~~~~~ .. versionadded:: 1.3.0 @@ -350,8 +349,20 @@ Probes The metadata plugin includes client-side probing functionality. This is fully documented :ref:`here <server-plugins-probes-index>`. +Metadata Caching +================ + +.. versionadded:: 1.3.0 + +Client metadata can be cached in order to improve performance. This +is particularly important if you have lots of templates that use +metadata from other clients (e.g., with the MetadataQuery interface +described below. See :ref:`server-caching` for a full description of +the caching features available. + .. _server-plugins-grouping-metadata-clientmetadata: + ClientMetadata ============== |