mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 08:58:59 +00:00
151 lines
4.6 KiB
ReStructuredText
151 lines
4.6 KiB
ReStructuredText
=========================
|
|
GitFS Backend Walkthrough
|
|
=========================
|
|
|
|
While the default location of the salt state tree is on the Salt master,
|
|
in /srv/salt, the master can create a bridge to external resources for files.
|
|
One of these resources is the ability for the master to directly pull files
|
|
from a git repository and serve them to minions.
|
|
|
|
.. note::
|
|
|
|
This walkthrough assumes basic knowledge of Salt:
|
|
|
|
:doc:`Walkthrough </topics/tutorials/walkthrough>`
|
|
|
|
And a basic knowledge of file roots:
|
|
|
|
:doc:`File Roots </ref/file_server/file_roots>`
|
|
|
|
The gitfs backend hooks into any number of remote git repositories and caches
|
|
the data from the repository on the master. This makes distributing a state
|
|
tree to multiple masters seamless and automated.
|
|
|
|
Salt's file server also has a concept of environments, when using the gitfs
|
|
backend, Salt translates git branches and tags into environments, making
|
|
environment management very simple. Just merging a QA or staging branch up
|
|
to a production branch can be all that is required to make those file changes
|
|
available to Salt.
|
|
|
|
Simple Configuration
|
|
====================
|
|
|
|
To use the gitfs backend only two configuration changes are required on the
|
|
master. The ``fileserver_backend`` option needs to be set with `git`:
|
|
|
|
.. code-block:: yaml
|
|
|
|
fileserver_backend:
|
|
- git
|
|
|
|
To configure what fileserver backends will be searched for requested files.
|
|
|
|
Now the gitfs system needs to be configured with a remote:
|
|
|
|
.. code-block:: yaml
|
|
|
|
gitfs_remotes:
|
|
- git://github.com/saltstack/salt-states.git
|
|
|
|
These changes require a restart of the master, then the git repo will be cached
|
|
on the master and new requests for the `salt://` protocol will send files found
|
|
in the remote git repository via the master.
|
|
|
|
.. note::
|
|
|
|
The master caches the files from the git server and serves them out,
|
|
minions do not connect directly to the git server meaning that only
|
|
requested files are delivered to minions.
|
|
|
|
Multiple Remotes
|
|
================
|
|
|
|
The ``gitfs_remotes`` option can accept a list of git remotes, the remotes are
|
|
then searched in order for the requested file. A simple scenario can illustrate
|
|
this behavior.
|
|
|
|
Assuming that the ``gitfs_remotes`` option specifies three remotes:
|
|
|
|
.. code-block:: yaml
|
|
|
|
gitfs_remotes:
|
|
- git://github.com/example/first.git
|
|
- git://github.com/example/second.git
|
|
- file:///root/third
|
|
|
|
.. note::
|
|
|
|
This example is purposefully contrived to illustrate the behavior of the
|
|
gitfs backend. This example should not be read as a recommended way to lay
|
|
out files and git repos.
|
|
|
|
.. note::
|
|
|
|
The file:// prefix denotes a git repository in a local directory. However,
|
|
it will still use the given file:// URL as a remote, rather than copying
|
|
the git repo to the salt cache. This means that any refs you want
|
|
accessible must exist as *local* refs in the specified repo.
|
|
|
|
Assume that each repository contains some files:
|
|
|
|
first.git:
|
|
top.sls
|
|
edit/vim.sls
|
|
edit/vimrc
|
|
nginx/init.sls
|
|
|
|
second.git:
|
|
edit/dev_vimrc
|
|
haproxy/init.sls
|
|
|
|
third:
|
|
haproxy/haproxy.conf
|
|
edit/dev_vimrc
|
|
|
|
The repositories will be searched for files by the master in the order in which
|
|
they are defined in the configuration, Therefore the remote
|
|
`git://github.com/example/first.git` will be searched first, if the requested
|
|
file is found then it is served and no further searching is executed. This
|
|
means that if the file `salt://haproxy/init.sls` is requested then it will be
|
|
pulled from the `git://github.com/example/second.git` git repo. If
|
|
`salt://haproxy/haproxy.conf` is requested then it will be pulled from the
|
|
third repo.
|
|
|
|
Multiple Backends
|
|
=================
|
|
|
|
Sometimes it may make sense to use multiple backends. For instance, if sls
|
|
files are stored in git, but larger files need to be stored directly on the
|
|
master.
|
|
|
|
The logic used for multiple remotes is also used for multiple backends. If
|
|
the ``fileserver_backend`` option contains multiple backends:
|
|
|
|
.. code-block:: yaml
|
|
|
|
fileserver_backend:
|
|
- roots
|
|
- git
|
|
|
|
Then the `roots` backend (the default backend of files in /srv/salt) will be
|
|
searched first for the requested file, then if it is not found on the master
|
|
the git remotes will be searched.
|
|
|
|
GitFS Remotes over SSH
|
|
======================
|
|
|
|
In order to configure a ``gitfs_remotes`` repository over SSH transport the
|
|
``git+ssh`` URL form must be used.
|
|
|
|
.. code-block:: yaml
|
|
|
|
gitfs_remotes:
|
|
- git+ssh://git@github.com/example/salt-states.git
|
|
|
|
The private key used to connect to the repository must be located in ``~/.ssh/id_rsa``
|
|
for the user running the salt-master.
|
|
|
|
.. note::
|
|
|
|
GitFS requires library ``gitpython`` > 0.3.0.
|