mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 17:09:03 +00:00
72d16c9fa9
There are many `.. code-block: yaml` definitions that should really be `.. code-block: jinja` definitions. This commit cleans up some of those and removes warnings like these from the doc build: ``` WARNING: Could not lex literal_block as "yaml". Highlighting skipped. ```
217 lines
6.6 KiB
ReStructuredText
217 lines
6.6 KiB
ReStructuredText
.. _tutorial-states-part-4:
|
|
|
|
=======================
|
|
States tutorial, part 4
|
|
=======================
|
|
|
|
.. note::
|
|
|
|
This tutorial builds on topics covered in :ref:`part 1 <states-tutorial>`,
|
|
:ref:`part 2 <tutorial-states-part-2>`, and :ref:`part 3 <tutorial-states-part-3>`.
|
|
It is recommended that you begin there.
|
|
|
|
This part of the tutorial will show how to use salt's :conf_master:`file_roots`
|
|
to set up a workflow in which states can be "promoted" from dev, to QA, to
|
|
production.
|
|
|
|
Salt fileserver path inheritance
|
|
================================
|
|
|
|
Salt's fileserver allows for more than one root directory per environment, like
|
|
in the below example, which uses both a local directory and a secondary
|
|
location shared to the salt master via NFS:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# In the master config file (/etc/salt/master)
|
|
file_roots:
|
|
base:
|
|
- /srv/salt
|
|
- /mnt/salt-nfs/base
|
|
|
|
Salt's fileserver collapses the list of root directories into a single virtual
|
|
environment containing all files from each root. If the same file exists at the
|
|
same relative path in more than one root, then the top-most match "wins". For
|
|
example, if ``/srv/salt/foo.txt`` and ``/mnt/salt-nfs/base/foo.txt`` both
|
|
exist, then ``salt://foo.txt`` will point to ``/srv/salt/foo.txt``.
|
|
|
|
.. note::
|
|
|
|
When using multiple fileserver backends, the order in which they are listed
|
|
in the :conf_master:`fileserver_backend` parameter also matters. If both
|
|
``roots`` and ``git`` backends contain a file with the same relative path,
|
|
and ``roots`` appears before ``git`` in the
|
|
:conf_master:`fileserver_backend` list, then the file in ``roots`` will
|
|
"win", and the file in gitfs will be ignored.
|
|
|
|
A more thorough explanation of how Salt's modular fileserver works can be
|
|
found :ref:`here <file-server-backends>`. We recommend reading this.
|
|
|
|
Environment configuration
|
|
=========================
|
|
|
|
Configure a multiple-environment setup like so:
|
|
|
|
.. code-block:: yaml
|
|
|
|
file_roots:
|
|
base:
|
|
- /srv/salt/prod
|
|
qa:
|
|
- /srv/salt/qa
|
|
- /srv/salt/prod
|
|
dev:
|
|
- /srv/salt/dev
|
|
- /srv/salt/qa
|
|
- /srv/salt/prod
|
|
|
|
Given the path inheritance described above, files within ``/srv/salt/prod``
|
|
would be available in all environments. Files within ``/srv/salt/qa`` would be
|
|
available in both ``qa``, and ``dev``. Finally, the files within
|
|
``/srv/salt/dev`` would only be available within the ``dev`` environment.
|
|
|
|
Based on the order in which the roots are defined, new files/states can be
|
|
placed within ``/srv/salt/dev``, and pushed out to the dev hosts for testing.
|
|
|
|
Those files/states can then be moved to the same relative path within
|
|
``/srv/salt/qa``, and they are now available only in the ``dev`` and ``qa``
|
|
environments, allowing them to be pushed to QA hosts and tested.
|
|
|
|
Finally, if moved to the same relative path within ``/srv/salt/prod``, the
|
|
files are now available in all three environments.
|
|
|
|
Requesting files from specific fileserver environments
|
|
======================================================
|
|
|
|
See :ref:`here <file-server-environments>` for documentation on how to request
|
|
files from specific environments.
|
|
|
|
Practical Example
|
|
=================
|
|
|
|
As an example, consider a simple website, installed to ``/var/www/foobarcom``.
|
|
Below is a top.sls that can be used to deploy the website:
|
|
|
|
``/srv/salt/prod/top.sls:``
|
|
|
|
.. code-block:: yaml
|
|
|
|
base:
|
|
'web*prod*':
|
|
- webserver.foobarcom
|
|
qa:
|
|
'web*qa*':
|
|
- webserver.foobarcom
|
|
dev:
|
|
'web*dev*':
|
|
- webserver.foobarcom
|
|
|
|
|
|
Using pillar, roles can be assigned to the hosts:
|
|
|
|
``/srv/pillar/top.sls:``
|
|
|
|
.. code-block:: yaml
|
|
|
|
base:
|
|
'web*prod*':
|
|
- webserver.prod
|
|
'web*qa*':
|
|
- webserver.qa
|
|
'web*dev*':
|
|
- webserver.dev
|
|
|
|
``/srv/pillar/webserver/prod.sls:``
|
|
|
|
.. code-block:: yaml
|
|
|
|
webserver_role: prod
|
|
|
|
``/srv/pillar/webserver/qa.sls:``
|
|
|
|
.. code-block:: yaml
|
|
|
|
webserver_role: qa
|
|
|
|
``/srv/pillar/webserver/dev.sls:``
|
|
|
|
.. code-block:: yaml
|
|
|
|
webserver_role: dev
|
|
|
|
|
|
And finally, the SLS to deploy the website:
|
|
|
|
``/srv/salt/prod/webserver/foobarcom.sls:``
|
|
|
|
.. code-block:: jinja
|
|
|
|
{% if pillar.get('webserver_role', '') %}
|
|
/var/www/foobarcom:
|
|
file.recurse:
|
|
- source: salt://webserver/src/foobarcom
|
|
- env: {{ pillar['webserver_role'] }}
|
|
- user: www
|
|
- group: www
|
|
- dir_mode: 755
|
|
- file_mode: 644
|
|
{% endif %}
|
|
|
|
Given the above SLS, the source for the website should initially be placed in
|
|
``/srv/salt/dev/webserver/src/foobarcom``.
|
|
|
|
First, let's deploy to dev. Given the configuration in the top file, this can
|
|
be done using :py:func:`state.apply <salt.modules.state.apply_>`:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt --pillar 'webserver_role:dev' state.apply
|
|
|
|
However, in the event that it is not desirable to apply all states configured
|
|
in the top file (which could be likely in more complex setups), it is possible
|
|
to apply just the states for the ``foobarcom`` website, by invoking
|
|
:py:func:`state.apply <salt.modules.state.apply_>` with the desired SLS target
|
|
as an argument:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt --pillar 'webserver_role:dev' state.apply webserver.foobarcom
|
|
|
|
Once the site has been tested in dev, then the files can be moved from
|
|
``/srv/salt/dev/webserver/src/foobarcom`` to
|
|
``/srv/salt/qa/webserver/src/foobarcom``, and deployed using the following:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt --pillar 'webserver_role:qa' state.apply webserver.foobarcom
|
|
|
|
Finally, once the site has been tested in qa, then the files can be moved from
|
|
``/srv/salt/qa/webserver/src/foobarcom`` to
|
|
``/srv/salt/prod/webserver/src/foobarcom``, and deployed using the following:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt --pillar 'webserver_role:prod' state.apply webserver.foobarcom
|
|
|
|
Thanks to Salt's fileserver inheritance, even though the files have been moved
|
|
to within ``/srv/salt/prod``, they are still available from the same
|
|
``salt://`` URI in both the qa and dev environments.
|
|
|
|
|
|
Continue Learning
|
|
=================
|
|
|
|
The best way to continue learning about Salt States is to read through the
|
|
:ref:`reference documentation <state-system-reference>` and to look through examples
|
|
of existing state trees. Many pre-configured state trees
|
|
can be found on GitHub in the `saltstack-formulas`_ collection of repositories.
|
|
|
|
.. _`saltstack-formulas`: https://github.com/saltstack-formulas
|
|
|
|
If you have any questions, suggestions, or just want to chat with other people
|
|
who are using Salt, we have a very :ref:`active community <salt-community>`
|
|
and we'd love to hear from you.
|
|
|
|
In addition, by continuing to the :ref:`Orchestrate Runner <orchestrate-runner>` docs,
|
|
you can learn about the powerful orchestration of which Salt is capable.
|