mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 17:09:03 +00:00
9ff2694155
Conflicts: - pkg/salt-minion.service - salt/modules/junos.py - salt/modules/localemod.py - salt/modules/win_system.py - salt/states/junos.py - tests/unit/modules/test_localemod.py - tests/unit/modules/test_win_powercfg.py - tests/unit/states/dockerng_test.py
190 lines
6.8 KiB
ReStructuredText
190 lines
6.8 KiB
ReStructuredText
.. _sdb:
|
|
|
|
===============================
|
|
Storing Data in Other Databases
|
|
===============================
|
|
The SDB interface is designed to store and retrieve data that, unlike pillars
|
|
and grains, is not necessarily minion-specific. The initial design goal was to
|
|
allow passwords to be stored in a secure database, such as one managed by the
|
|
keyring package, rather than as plain-text files. However, as a generic database
|
|
interface, it could conceptually be used for a number of other purposes.
|
|
|
|
SDB was added to Salt in version 2014.7.0.
|
|
|
|
|
|
SDB Configuration
|
|
=================
|
|
In order to use the SDB interface, a configuration profile must be set up.
|
|
To be available for master commands, such as runners, it needs to be
|
|
configured in the master configuration. For modules executed on a minion, it
|
|
can be set either in the minion configuration file, or as a pillar. The
|
|
configuration stanza includes the name/ID that the profile will be referred to
|
|
as, a ``driver`` setting, and any other arguments that are necessary for the SDB
|
|
module that will be used. For instance, a profile called ``mykeyring``, which
|
|
uses the ``system`` service in the ``keyring`` module would look like:
|
|
|
|
.. code-block:: yaml
|
|
|
|
mykeyring:
|
|
driver: keyring
|
|
service: system
|
|
|
|
It is recommended to keep the name of the profile simple, as it is used in the
|
|
SDB URI as well.
|
|
|
|
|
|
SDB URIs
|
|
========
|
|
SDB is designed to make small database queries (hence the name, SDB) using a
|
|
compact URL. This allows users to reference a database value quickly inside
|
|
a number of Salt configuration areas, without a lot of overhead. The basic
|
|
format of an SDB URI is:
|
|
|
|
.. code-block:: yaml
|
|
|
|
sdb://<profile>/<args>
|
|
|
|
The profile refers to the configuration profile defined in either the master or
|
|
the minion configuration file. The args are specific to the module referred to
|
|
in the profile, but will typically only need to refer to the key of a
|
|
key/value pair inside the database. This is because the profile itself should
|
|
define as many other parameters as possible.
|
|
|
|
For example, a profile might be set up to reference credentials for a specific
|
|
OpenStack account. The profile might look like:
|
|
|
|
.. code-block:: yaml
|
|
|
|
kevinopenstack:
|
|
driver: keyring
|
|
service: salt.cloud.openstack.kevin
|
|
|
|
And the URI used to reference the password might look like:
|
|
|
|
.. code-block:: yaml
|
|
|
|
sdb://kevinopenstack/password
|
|
|
|
|
|
Getting, Setting and Deleting SDB Values
|
|
========================================
|
|
Once an SDB driver is configured, you can use the ``sdb`` execution module to
|
|
get, set and delete values from it. There are two functions that may appear in
|
|
most SDB modules: ``get``, ``set`` and ``delete``.
|
|
|
|
Getting a value requires only the SDB URI to be specified. To retrieve a value
|
|
from the ``kevinopenstack`` profile above, you would use:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt-call sdb.get sdb://kevinopenstack/password
|
|
|
|
Some drivers use slightly more complex URIs. For instance, the ``vault`` driver
|
|
requires the full path to where the key is stored, followed by a question mark,
|
|
followed by the key to be retrieved. If you were using a profile called
|
|
``myvault``, you would use a URI that looks like:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt-call sdb.get 'sdb://myvault/secret/salt?saltstack'
|
|
|
|
Setting a value uses the same URI as would be used to retrieve it, followed
|
|
by the value as another argument. For the above ``myvault`` URI, you would set
|
|
a new value using a command like:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt-call sdb.set 'sdb://myvault/secret/salt?saltstack' 'super awesome'
|
|
|
|
Deleting values (if supported by the driver) is done pretty much the same way as
|
|
getting them. Provided that you have a profile called ``mykvstore`` that uses
|
|
a driver allowing to delete values you would delete a value as shown below:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt-call sdb.delete 'sdb://mykvstore/foobar'
|
|
|
|
The ``sdb.get``, ``sdb.set`` and ``sdb.delete`` functions are also available in
|
|
the runner system:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt-run sdb.get 'sdb://myvault/secret/salt?saltstack'
|
|
salt-run sdb.set 'sdb://myvault/secret/salt?saltstack' 'super awesome'
|
|
salt-run sdb.delete 'sdb://mykvstore/foobar'
|
|
|
|
|
|
Using SDB URIs in Files
|
|
=======================
|
|
SDB URIs can be used in both configuration files, and files that are processed
|
|
by the renderer system (jinja, mako, etc.). In a configuration file (such as
|
|
``/etc/salt/master``, ``/etc/salt/minion``, ``/etc/salt/cloud``, etc.), make an
|
|
entry as usual, and set the value to the SDB URI. For instance:
|
|
|
|
.. code-block:: yaml
|
|
|
|
mykey: sdb://myetcd/mykey
|
|
|
|
To retrieve this value using a module, the module in question must use the
|
|
``config.get`` function to retrieve configuration values. This would look
|
|
something like:
|
|
|
|
.. code-block:: python
|
|
|
|
mykey = __salt__['config.get']('mykey')
|
|
|
|
Templating renderers use a similar construct. To get the ``mykey`` value from
|
|
above in Jinja, you would use:
|
|
|
|
.. code-block:: jinja
|
|
|
|
{{ salt['config.get']('mykey') }}
|
|
|
|
When retrieving data from configuration files using ``config.get``, the SDB
|
|
URI need only appear in the configuration file itself.
|
|
|
|
If you would like to retrieve a key directly from SDB, you would call the
|
|
``sdb.get`` function directly, using the SDB URI. For instance, in Jinja:
|
|
|
|
.. code-block:: jinja
|
|
|
|
{{ salt['sdb.get']('sdb://myetcd/mykey') }}
|
|
|
|
When writing Salt modules, it is not recommended to call ``sdb.get`` directly,
|
|
as it requires the user to provide values in SDB, using a specific URI. Use
|
|
``config.get`` instead.
|
|
|
|
|
|
Writing SDB Modules
|
|
===================
|
|
There is currently one function that MUST exist in any SDB module (``get()``),
|
|
one that SHOULD exist (``set_()``) and one that MAY exist (``delete()``). If
|
|
using a (``set_()``) function, a ``__func_alias__`` dictionary MUST be declared
|
|
in the module as well:
|
|
|
|
.. code-block:: python
|
|
|
|
__func_alias__ = {
|
|
'set_': 'set',
|
|
}
|
|
|
|
This is because ``set`` is a Python built-in, and therefore functions should not
|
|
be created which are called ``set()``. The ``__func_alias__`` functionality is
|
|
provided via Salt's loader interfaces, and allows legally-named functions to be
|
|
referred to using names that would otherwise be unwise to use.
|
|
|
|
The ``get()`` function is required, as it will be called via functions in other
|
|
areas of the code which make use of the ``sdb://`` URI. For example, the
|
|
``config.get`` function in the ``config`` execution module uses this function.
|
|
|
|
The ``set_()`` function may be provided, but is not required, as some sources
|
|
may be read-only, or may be otherwise unwise to access via a URI (for instance,
|
|
because of SQL injection attacks).
|
|
|
|
The ``delete()`` function may be provided as well, but is not required, as many
|
|
sources may be read-only or restrict such operations.
|
|
|
|
A simple example of an SDB module is ``salt/sdb/keyring_db.py``, as it provides
|
|
basic examples of most, if not all, of the types of functionality that are
|
|
available not only for SDB modules, but for Salt modules in general.
|