mirror of
https://github.com/saltstack/salt.git
synced 2025-04-17 10:10:20 +00:00
Doc restructuring, organization, and cleanup. Updated the doc navigation.
This commit is contained in:
Jacob Hammons
parent
e202ce1ce0
commit
b192a9ba38
58 changed files with 1695 additions and 1855 deletions
|
|
@ -105,10 +105,14 @@ button#prev-button{float:left;margin:15px 0 0}
|
|||
#sidebar-nav .collapsed > ul{display:none}
|
||||
#sidebar-nav .glyphicon{padding-left:5px;font-size:14px}
|
||||
.nav>li>a:hover,.nav>li>a:focus{background-color:transparent}
|
||||
#sidebar-nav li a{display:block;text-decoration:none;color:#424242;border-top:1px solid #e3e3e3;font-size:12px}
|
||||
#sidebar-nav ul li:not(.tocify-item){padding-left:10px}
|
||||
#sidebar-nav li a{display:block;text-decoration:none;color:#424242;border-top:1px solid #e3e3e3}
|
||||
#sidebar-nav li.toctree-l1 > a{font-size:16px}
|
||||
#sidebar-nav li.toctree-l2 > a{font-size:14px;font-weight:bold}
|
||||
#sidebar-nav ul li:not(.tocify-item){padding-left:15px}
|
||||
#sidebar-nav ul a{padding-top:5px;padding-bottom:5px}
|
||||
#sidebar-nav > ul > .current{min-height:20px;padding:5px;background-color:#f5f5f5;border:1px solid #e3e3e3;border-radius:4px;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.05);box-shadow:inset 0 1px 1px rgba(0,0,0,.05)}
|
||||
li.toctree-l2.current{min-height:20px;padding:5px;/*background-color:#f5f5f5;*/background-color:#fff;border:1px solid #e3e3e3;border-radius:4px;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.05);box-shadow:inset 0 1px 1px rgba(0,0,0,.05)}
|
||||
li.toctree-l3.current{min-height:20px;padding:5px;background-color:#f5f5f5;border:1px solid #999;border-radius:4px;-webkit-box-shadow:inset 0 1px 1px rgba(0,0,0,.05);box-shadow:inset 0 1px 1px rgba(0,0,0,.05)}
|
||||
#sidebar-nav > ul > .current a{border:none}
|
||||
#sidebar-nav .tocify li.current > a{font-weight:400;background:#48b4fb}
|
||||
#sidebar-nav .tocify ul{list-style:circle}
|
||||
|
|
@ -116,8 +120,8 @@ button#prev-button{float:left;margin:15px 0 0}
|
|||
.tocify li a{display:block;text-decoration:none;color:#fff;border-bottom:none;font-size:14px;font-weight:300}
|
||||
#tocify-header0 > li a{border-bottom:1px solid #2C3E50}
|
||||
ul.tocify-subheader ul li{margin-left:20px}
|
||||
#gen-links > li.current > .tocify > ul > li > a{font-weight:400;font-size:20px;background:transparent;border-bottom:none;border-top:none;color:#333}
|
||||
#sidebar-nav li.current:not(.tocify-item) > a{font-weight:400;font-size:20px;border-bottom:none;border-top:none}
|
||||
#gen-links > li.current > .tocify > ul > li > a{font-weight:400;font-size:16px;background:transparent;border-bottom:none;border-top:none;color:#333}
|
||||
#sidebar-nav li.current:not(.tocify-item) > a{font-weight:400;font-size:16px;border-bottom:none;border-top:none;}
|
||||
#gen-links{border-bottom:1px solid #e3e3e3}
|
||||
#guide-links a{border-top:none;font-size:20px;color:#333}
|
||||
#guide-links a:hover,a:focus{text-decoration:none}
|
||||
|
|
|
|||
|
|
@ -1,17 +0,0 @@
|
|||
======================
|
||||
Salt Table of Contents
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:glob:
|
||||
|
||||
topics/index
|
||||
topics/installation/index
|
||||
topics/tutorials/index
|
||||
topics/targeting/index
|
||||
topics/pillar/index
|
||||
topics/reactor/index
|
||||
topics/mine/index
|
||||
topics/eauth/index
|
||||
glossary
|
||||
|
|
@ -1,19 +0,0 @@
|
|||
======================
|
||||
Salt Table of Contents
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:glob:
|
||||
|
||||
topics/jobs/index
|
||||
topics/event/index
|
||||
topics/proxyminion/index
|
||||
topics/topology/index
|
||||
topics/highavailability/index
|
||||
topics/windows/index
|
||||
topics/cloud/index
|
||||
topics/netapi/index
|
||||
topics/virt/index
|
||||
topics/yaml/index
|
||||
glossary
|
||||
|
|
@ -1,18 +0,0 @@
|
|||
======================
|
||||
Salt Table of Contents
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:glob:
|
||||
|
||||
topics/master_tops/index
|
||||
topics/ssh/*
|
||||
topics/best_practices
|
||||
topics/troubleshooting/index
|
||||
topics/development/index
|
||||
topics/releases/index
|
||||
topics/projects/index
|
||||
security/index
|
||||
faq
|
||||
glossary
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
======================
|
||||
Salt Table of Contents
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:glob:
|
||||
|
||||
ref/index
|
||||
glossary
|
||||
|
|
@ -4,44 +4,23 @@ Salt Table of Contents
|
|||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
topics/index
|
||||
index
|
||||
topics/installation/index
|
||||
topics/tutorials/index
|
||||
topics/targeting/index
|
||||
topics/pillar/index
|
||||
topics/reactor/index
|
||||
topics/mine/index
|
||||
topics/eauth/index
|
||||
topics/eauth/access_control
|
||||
topics/jobs/index
|
||||
topics/jobs/job_cache
|
||||
topics/jobs/external_cache
|
||||
topics/sdb/index
|
||||
topics/configuration/index
|
||||
topics/using_salt
|
||||
topics/execution/index
|
||||
topics/states/index
|
||||
topics/event/index
|
||||
topics/beacons/index
|
||||
topics/engines/index
|
||||
topics/ext_processes/index
|
||||
topics/highavailability/index
|
||||
topics/topology/index
|
||||
topics/proxyminion/index
|
||||
topics/spm/index
|
||||
topics/transports/index
|
||||
topics/windows/index
|
||||
topics/orchestrate/index
|
||||
topics/ssh/index
|
||||
topics/cloud/index
|
||||
topics/netapi/index
|
||||
topics/proxyminion/index
|
||||
topics/virt/index
|
||||
topics/yaml/index
|
||||
topics/master_tops/index
|
||||
topics/ssh/*
|
||||
ref/cli/index
|
||||
ref/index
|
||||
topics/best_practices
|
||||
topics/hardening
|
||||
topics/troubleshooting/index
|
||||
topics/api
|
||||
topics/topology/index
|
||||
topics/windows/index
|
||||
topics/development/index
|
||||
topics/releases/index
|
||||
topics/projects/index
|
||||
security/index
|
||||
faq
|
||||
glossary
|
||||
|
|
|
|||
312
doc/index.rst
312
doc/index.rst
|
|
@ -1,10 +1,8 @@
|
|||
:orphan:
|
||||
|
||||
.. _contents:
|
||||
.. _get-started:
|
||||
|
||||
=========
|
||||
SaltStack
|
||||
=========
|
||||
|
||||
Salt, a new approach to infrastructure management, is easy enough to get
|
||||
running in minutes, scalable enough to manage tens of thousands of servers,
|
||||
and fast enough to communicate with those servers in *seconds*.
|
||||
|
|
@ -12,62 +10,48 @@ and fast enough to communicate with those servers in *seconds*.
|
|||
Salt delivers a dynamic communication bus for infrastructures that can be used
|
||||
for orchestration, remote execution, configuration management and much more.
|
||||
|
||||
Download
|
||||
========
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Salt source releases are available for download via the following PyPI link:
|
||||
topics/index
|
||||
|
||||
* https://pypi.python.org/pypi/salt
|
||||
Get Started
|
||||
===========
|
||||
The Get Started Guide shows you how to:
|
||||
|
||||
* Install and configure SaltStack
|
||||
* Remotely execute commands across all managed systems
|
||||
* Design, develop, and deploy system configurations
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Get Started Guide <https://docs.saltstack.com/en/getstarted/>
|
||||
|
||||
If you just want to get Salt installed and start using it, *Salt in 10 minutes*
|
||||
gets you up and running quickly.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
topics/tutorials/walkthrough
|
||||
|
||||
Install Salt
|
||||
============
|
||||
**Latest Stable Release**: |current_release_doc|
|
||||
|
||||
The installation document, found in the following link, outlines where to
|
||||
obtain packages and installation specifics for platforms:
|
||||
|
||||
* :doc:`Installation </topics/installation/index>`
|
||||
* :ref:`Installation <installation>`
|
||||
|
||||
The Salt Bootstrap project, found in the following repository, is a single
|
||||
shell script, which automates the install correctly on multiple platforms:
|
||||
|
||||
* https://github.com/saltstack/salt-bootstrap
|
||||
|
||||
Get Started
|
||||
===============
|
||||
|
||||
A new `Get Started Guide <http://docs.saltstack.com/en/getstarted/>`_ walks you
|
||||
through the basics of getting SaltStack up and running. You'll learn how to:
|
||||
|
||||
* Install and configure SaltStack
|
||||
* Remotely execute commands across all managed systems
|
||||
* Design, develop, and deploy system configurations
|
||||
|
||||
Tutorials
|
||||
=========
|
||||
|
||||
This walkthrough is an additional tutorial to help you get started quickly and gain a
|
||||
foundational knowledge of Salt:
|
||||
|
||||
:doc:`Official Salt Walkthrough </topics/tutorials/walkthrough>`
|
||||
|
||||
The following getting started tutorials are also available:
|
||||
|
||||
States - Configuration Management with Salt:
|
||||
- :doc:`Getting Started with States <topics/tutorials/starting_states>`
|
||||
- :doc:`Basic config management <topics/tutorials/states_pt1>`
|
||||
- :doc:`Less basic config management <topics/tutorials/states_pt2>`
|
||||
- :doc:`Advanced techniques <topics/tutorials/states_pt3>`
|
||||
- :doc:`Salt Fileserver Path Inheritance <topics/tutorials/states_pt4>`
|
||||
|
||||
Masterless Quickstart:
|
||||
:doc:`Salt Quickstart </topics/tutorials/quickstart>`
|
||||
|
||||
Running Salt without root access in userland:
|
||||
:doc:`Salt Usermode <topics/tutorials/rooted>`
|
||||
|
||||
A list of all tutorials can be found here:
|
||||
:doc:`All Salt tutorials <topics/tutorials/index>`
|
||||
|
||||
Demo Environments
|
||||
=================
|
||||
|
||||
You can download one of the following `Vagrant <http://vagrantup.com>`_
|
||||
projects to quickly set up a Salt demo environment:
|
||||
|
||||
|
|
@ -76,7 +60,6 @@ projects to quickly set up a Salt demo environment:
|
|||
|
||||
Example Formulas
|
||||
================
|
||||
|
||||
A Github repo that contains a number of community-maintained formulas is
|
||||
available at https://github.com/saltstack-formulas. Contributions are welcome!
|
||||
|
||||
|
|
@ -85,222 +68,47 @@ applications is available at https://github.com/saltstack/salt-winrepo-ng. Note
|
|||
that Salt makes this repo :ref:`available <windows-package-manager>` to your
|
||||
Windows minions, and contributions are welcome!
|
||||
|
||||
Salt in depth
|
||||
=============
|
||||
Mailing List
|
||||
============
|
||||
Join the `salt-users mailing list`_. It is the best place to ask questions
|
||||
about Salt and see whats going on with Salt development! The Salt mailing list
|
||||
is hosted by Google Groups. It is open to new members.
|
||||
|
||||
While setting up, and using, Salt is a simple task, its capabilities run much
|
||||
deeper. These documents provide a greater understanding of how Salt
|
||||
empowers infrastructure management.
|
||||
https://groups.google.com/forum/#!forum/salt-users
|
||||
|
||||
Remote execution
|
||||
----------------
|
||||
.. _`salt-users mailing list`: https://groups.google.com/forum/#!forum/salt-users
|
||||
|
||||
Running pre-defined or arbitrary commands on remote hosts, also known as
|
||||
remote execution, is the core function of Salt. The following links explore
|
||||
modules and returners, which are two key elements of remote execution.
|
||||
There is also a low-traffic list used to announce new releases
|
||||
called `salt-announce`_
|
||||
|
||||
**Modules**
|
||||
Salt modules, fundamental to remote execution, provide
|
||||
functionality such as installing packages, restarting a service,
|
||||
running a remote command, transferring files, and so on.
|
||||
https://groups.google.com/forum/#!forum/salt-announce
|
||||
|
||||
:doc:`Full list of modules </ref/modules/all/index>`
|
||||
Contains: a list of core modules that ship with Salt.
|
||||
.. _`salt-announce`: https://groups.google.com/forum/#!forum/salt-announce
|
||||
|
||||
:doc:`Writing modules <ref/modules/index>`
|
||||
Contains: a guide on how to write Salt modules.
|
||||
|
||||
**Returners**
|
||||
Salt returners allow saving minion responses in various datastores, or
|
||||
to various locations, in addition to displaying the responses at the CLI.
|
||||
Returners can be used to extend Salt to communicate with new, or custom,
|
||||
interfaces and to support new databases.
|
||||
|
||||
:doc:`Full list of returners </ref/returners/all/index>`
|
||||
Contains: list of returner modules used to store minion responses
|
||||
in Redis, Mongo, Cassandra, SQL, and others.
|
||||
|
||||
:doc:`Writing returners <ref/returners/index>`
|
||||
Contains: instructions for writing returner modules.
|
||||
|
||||
Targeting
|
||||
---------
|
||||
|
||||
Use :ref:`targeting <targeting>` to specify which minions should
|
||||
execute commands and manage server configuration. The following links provide
|
||||
additional information about targeting and matching minions.
|
||||
|
||||
:ref:`Globbing and regex <targeting-glob>`
|
||||
Match minions using globbing and regular expressions.
|
||||
|
||||
:ref:`Grains <targeting-grains>`
|
||||
Match minions using grains, which are bits of static information about the
|
||||
minion such as OS, software version, virtualization, CPU, memory, and so on.
|
||||
|
||||
:ref:`Pillar <targeting-pillar>`
|
||||
Match minions using user-defined variables.
|
||||
|
||||
:ref:`Subnet/IP Address <targeting-ipcidr>`
|
||||
Match minions by subnet or IP address (currently IPv4 only).
|
||||
|
||||
:ref:`Compound matching <targeting-compound>`
|
||||
Combine any of the above matchers into a single expression.
|
||||
|
||||
:ref:`Node groups <targeting-nodegroups>`
|
||||
Statically define groups of minions in the master config file using the
|
||||
:ref:`compound <targeting-compound>` matching syntax.
|
||||
|
||||
:ref:`Batching execution <targeting-batch>`
|
||||
Loop through all matching minions so that only a subset are executing a
|
||||
command at one time.
|
||||
|
||||
Configuration management
|
||||
------------------------
|
||||
|
||||
Salt contains a robust and flexible configuration management framework, which
|
||||
is built on the remote execution core. This framework executes on the minions,
|
||||
allowing effortless, simultaneous configuration of tens of thousands of hosts,
|
||||
by rendering language specific state files. The following links provide
|
||||
resources to learn more about state and renderers.
|
||||
|
||||
**States**
|
||||
Express the state of a host using small, easy to read, easy to
|
||||
understand configuration files. *No programming required*.
|
||||
|
||||
:doc:`Full list of states <ref/states/all/index>`
|
||||
Contains: list of install packages, create users, transfer files, start
|
||||
services, and so on.
|
||||
|
||||
:doc:`Pillar System <topics/pillar/index>`
|
||||
Contains: description of Salt's Pillar system.
|
||||
|
||||
:doc:`States Overview<ref/states/index>`
|
||||
Contains: an overview of states and some of the core components.
|
||||
|
||||
:doc:`Highstate data structure <ref/states/highstate>`
|
||||
Contains: a dry vocabulary and technical representation of the
|
||||
configuration format that states represent.
|
||||
|
||||
:doc:`Writing states <ref/states/writing>`
|
||||
Contains: a guide on how to write Salt state modules, easily extending
|
||||
Salt to directly manage more software.
|
||||
|
||||
**Renderers**
|
||||
Renderers use state configuration files written in a variety of languages,
|
||||
templating engines, or files. Salt's configuration management system is,
|
||||
under the hood, language agnostic.
|
||||
|
||||
:doc:`Full list of renderers <ref/renderers/all/index>`
|
||||
Contains: a list of renderers.
|
||||
YAML is one choice, but many systems are available, from
|
||||
alternative templating engines to the PyDSL language for rendering
|
||||
sls formulas.
|
||||
|
||||
:doc:`Renderers <ref/renderers/index>`
|
||||
Contains: more information about renderers. Salt states are only
|
||||
concerned with the ultimate highstate data structure, not how the
|
||||
data structure was created.
|
||||
|
||||
Miscellaneous topics
|
||||
--------------------
|
||||
|
||||
The following links explore various Salt topics in depth.
|
||||
|
||||
:doc:`Salt Cloud <topics/cloud/index>`
|
||||
Salt Cloud is a public cloud provisioning tool that integrates Salt with
|
||||
many cloud providers.
|
||||
|
||||
:doc:`File Server <ref/file_server/index>`
|
||||
Salt can easily and quickly transfer files (in fact, that's how Salt
|
||||
states work). Even under heavy load, files are chunked and served.
|
||||
|
||||
:doc:`Syndic <topics/topology/syndic>`
|
||||
Syndic is a tool to allow one master host to manage many masters, which
|
||||
in turn manage many minions. Scale Salt to tens of thousands of hosts or
|
||||
across many different networks.
|
||||
|
||||
:doc:`Peer Communication <ref/peer>`
|
||||
Allow minions to communicate among themselves. For example, configure
|
||||
one minion by querying live data from all the others.
|
||||
|
||||
:doc:`Reactor System <topics/reactor/index>`
|
||||
The reactor system allows for Salt to create a self aware environment
|
||||
by hooking infrastructure events into actions.
|
||||
|
||||
:doc:`Firewall Settings and Salt <topics/tutorials/firewall>`
|
||||
This is a tutorial covering how to properly firewall a Salt Master server.
|
||||
|
||||
:doc:`Scheduling Executions (like states)<topics/jobs/schedule>`
|
||||
The schedule system in Salt allows for executions to be run from the master
|
||||
or minion at automatic intervals.
|
||||
|
||||
:doc:`Network topology <topics/topology/index>`
|
||||
At it's core, Salt is a highly scalable communication layer built on
|
||||
top of ZeroMQ, which enables remote execution and configuration
|
||||
management. The possibilities are endless and Salt's future looks
|
||||
bright.
|
||||
|
||||
:doc:`Testing Salt <topics/development/tests/index>`
|
||||
This is a tutorial for writing unit tests and integration tests.
|
||||
|
||||
:doc:`Salt Proxy Minions <topics/proxyminion/index>`
|
||||
Proxy minions allow for the control of devices and machines which are
|
||||
unable to run a salt-minion.
|
||||
|
||||
:ref:`Python API interface <python-api>`
|
||||
The Python API allows the developer to use Salt locally from scripts and
|
||||
programs easily via ``import salt``.
|
||||
|
||||
:ref:`External API interfaces <netapi-introduction>`
|
||||
Expose a Salt API such as REST, XMPP, WebSockets, or others using netapi
|
||||
modules. Run these modules using the ``salt-api`` daemon.
|
||||
See the :ref:`full list of netapi modules <all-netapi-modules>`.
|
||||
|
||||
:doc:`Automatic Updates and Frozen Binary Deployments <topics/tutorials/esky>`
|
||||
Use a frozen install to make deployments easier (even on Windows!). Or
|
||||
take advantage of automatic updates to keep minions running the latest
|
||||
builds.
|
||||
|
||||
:doc:`Windows Software Manager / Package Repository <topics/windows/windows-package-manager>`
|
||||
Looking for an easy way to manage software on Windows machines?
|
||||
Search no more! Salt has an integrated software package manager for
|
||||
Windows machines! Install software hosted on the master, anywhere on the
|
||||
network, including any HTTP, HTTPS, or ftp server.
|
||||
|
||||
Reference
|
||||
---------
|
||||
|
||||
:doc:`Command-line interface <ref/cli/index>`
|
||||
Read the Salt manpages.
|
||||
|
||||
:doc:`Full list of master settings <ref/configuration/master>`
|
||||
Read through the heavily-commented master configuration file.
|
||||
|
||||
:doc:`Full list of minion settings <ref/configuration/minion>`
|
||||
Read through the heavily-commented minion configuration file.
|
||||
|
||||
:doc:`Full table of contents </contents>`
|
||||
Read the table of contents of this document.
|
||||
|
||||
FAQ
|
||||
IRC
|
||||
===
|
||||
The ``#salt`` IRC channel is hosted on the popular `Freenode`__ network. You
|
||||
can use the `Freenode webchat client`__ right from your browser.
|
||||
|
||||
See :doc:`here <faq>` for a list of Frequently Asked Questions.
|
||||
`Logs of the IRC channel activity`__ are being collected courtesy of Moritz Lenz.
|
||||
|
||||
More information about the project
|
||||
==================================
|
||||
.. __: http://freenode.net/irc_servers.shtml
|
||||
.. __: http://webchat.freenode.net/?channels=salt&uio=Mj10cnVlJjk9dHJ1ZSYxMD10cnVl83
|
||||
.. __: http://irclog.perlgeek.de/salt/
|
||||
|
||||
:doc:`Release notes </topics/releases/index>`
|
||||
Living history of SaltStack.
|
||||
If you wish to discuss the development of Salt itself join us in
|
||||
``#salt-devel``.
|
||||
|
||||
:doc:`Salt Development </topics/development/index>`
|
||||
Information for Hacking on Salt
|
||||
Follow on GitHub
|
||||
================
|
||||
The Salt code is developed via GitHub. Follow Salt for constant updates on what
|
||||
is happening in Salt development:
|
||||
|
||||
:doc:`Translate Documentation </topics/development/translating>`
|
||||
How to help out translating Salt to your language.
|
||||
|saltrepo|
|
||||
|
||||
:ref:`Security disclosures <disclosure>`
|
||||
The SaltStack security disclosure policy
|
||||
Hack the Source
|
||||
===============
|
||||
If you want to get involved with the development of source code or the
|
||||
documentation efforts, please review the :ref:`Developing Salt Tutorial
|
||||
<developing-tutorial>`.
|
||||
|
||||
.. _`salt-contrib`: https://github.com/saltstack/salt-contrib
|
||||
.. _`salt-states`: https://github.com/saltstack/salt-states
|
||||
|
|
|
|||
|
|
@ -2,243 +2,6 @@
|
|||
Command Line Reference
|
||||
======================
|
||||
|
||||
Salt can be controlled by a command line client by the root user on the Salt
|
||||
master. The Salt command line client uses the Salt client API to communicate
|
||||
with the Salt master server. The Salt client is straightforward and simple
|
||||
to use.
|
||||
|
||||
Using the Salt client commands can be easily sent to the minions.
|
||||
|
||||
Each of these commands accepts an explicit `--config` option to point to either
|
||||
the master or minion configuration file. If this option is not provided and
|
||||
the default configuration file does not exist then Salt falls back to use the
|
||||
environment variables ``SALT_MASTER_CONFIG`` and ``SALT_MINION_CONFIG``.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`Configuration </ref/configuration/index>`
|
||||
|
||||
Using the Salt Command
|
||||
======================
|
||||
|
||||
The Salt command needs a few components to send information to the Salt
|
||||
minions. The target minions need to be defined, the function to call and any
|
||||
arguments the function requires.
|
||||
|
||||
Defining the Target Minions
|
||||
---------------------------
|
||||
|
||||
The first argument passed to salt, defines the target minions, the target
|
||||
minions are accessed via their hostname. The default target type is a bash
|
||||
glob:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*foo.com' sys.doc
|
||||
|
||||
|
||||
Salt can also define the target minions with regular expressions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt -E '.*' cmd.run 'ls -l | grep foo'
|
||||
|
||||
Or to explicitly list hosts, salt can take a list:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt -L foo.bar.baz,quo.qux cmd.run 'ps aux | grep foo'
|
||||
|
||||
More Powerful Targets
|
||||
---------------------
|
||||
|
||||
The simple target specifications, glob, regex, and list will cover many use
|
||||
cases, and for some will cover all use cases, but more powerful options exist.
|
||||
|
||||
Targeting with Grains
|
||||
`````````````````````
|
||||
|
||||
The Grains interface was built into Salt to allow minions to be targeted by
|
||||
system properties. So minions running on a particular operating system can
|
||||
be called to execute a function, or a specific kernel.
|
||||
|
||||
Calling via a grain is done by passing the -G option to salt, specifying
|
||||
a grain and a glob expression to match the value of the grain. The syntax for
|
||||
the target is the grain key followed by a globexpression: "os:Arch*".
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt -G 'os:Fedora' test.ping
|
||||
|
||||
Will return True from all of the minions running Fedora.
|
||||
|
||||
To discover what grains are available and what the values are, execute the
|
||||
grains.item salt function:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' grains.items
|
||||
|
||||
more info on using targeting with grains can be found :ref:`here
|
||||
<targeting-grains>`.
|
||||
|
||||
Targeting with Executions
|
||||
`````````````````````````
|
||||
|
||||
As of 0.8.8 targeting with executions is still under heavy development and this
|
||||
documentation is written to reference the behavior of execution matching in the
|
||||
future.
|
||||
|
||||
Execution matching allows for a primary function to be executed, and then based
|
||||
on the return of the primary function the main function is executed.
|
||||
|
||||
Execution matching allows for matching minions based on any arbitrary running
|
||||
data on the minions.
|
||||
|
||||
Compound Targeting
|
||||
``````````````````
|
||||
|
||||
.. versionadded:: 0.9.5
|
||||
|
||||
Multiple target interfaces can be used in conjunction to determine the command
|
||||
targets. These targets can then be combined using and or or statements. This
|
||||
is well defined with an example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt -C 'G@os:Debian and webser* or E@db.*' test.ping
|
||||
|
||||
In this example any minion who's id starts with ``webser`` and is running
|
||||
Debian, or any minion who's id starts with db will be matched.
|
||||
|
||||
The type of matcher defaults to glob, but can be specified with the
|
||||
corresponding letter followed by the ``@`` symbol. In the above example a grain
|
||||
is used with ``G@`` as well as a regular expression with ``E@``. The
|
||||
``webser*`` target does not need to be prefaced with a target type specifier
|
||||
because it is a glob.
|
||||
|
||||
more info on using compound targeting can be found :ref:`here
|
||||
<targeting-compound>`.
|
||||
|
||||
Node Group Targeting
|
||||
````````````````````
|
||||
|
||||
.. versionadded:: 0.9.5
|
||||
|
||||
For certain cases, it can be convenient to have a predefined group of minions
|
||||
on which to execute commands. This can be accomplished using what are called
|
||||
:ref:`nodegroups <targeting-nodegroups>`. Nodegroups allow for predefined
|
||||
compound targets to be declared in the master configuration file, as a sort of
|
||||
shorthand for having to type out complicated compound expressions.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodegroups:
|
||||
group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com'
|
||||
group2: 'G@os:Debian and foo.domain.com'
|
||||
group3: 'G@os:Debian and N@group1'
|
||||
|
||||
|
||||
Calling the Function
|
||||
--------------------
|
||||
|
||||
The function to call on the specified target is placed after the target
|
||||
specification.
|
||||
|
||||
.. versionadded:: 0.9.8
|
||||
|
||||
Functions may also accept arguments, space-delimited:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' cmd.exec_code python 'import sys; print sys.version'
|
||||
|
||||
Optional, keyword arguments are also supported:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' pip.install salt timeout=5 upgrade=True
|
||||
|
||||
They are always in the form of ``kwarg=argument``.
|
||||
|
||||
Arguments are formatted as YAML:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' cmd.run 'echo "Hello: $FIRST_NAME"' env='{FIRST_NAME: "Joe"}'
|
||||
|
||||
Note: dictionaries must have curly braces around them (like the ``env``
|
||||
keyword argument above). This was changed in 0.15.1: in the above example,
|
||||
the first argument used to be parsed as the dictionary
|
||||
``{'echo "Hello': '$FIRST_NAME"'}``. This was generally not the expected
|
||||
behavior.
|
||||
|
||||
If you want to test what parameters are actually passed to a module, use the
|
||||
``test.arg_repr`` command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' test.arg_repr 'echo "Hello: $FIRST_NAME"' env='{FIRST_NAME: "Joe"}'
|
||||
|
||||
Finding available minion functions
|
||||
``````````````````````````````````
|
||||
|
||||
The Salt functions are self documenting, all of the function documentation can
|
||||
be retried from the minions via the :func:`sys.doc` function:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' sys.doc
|
||||
|
||||
Compound Command Execution
|
||||
--------------------------
|
||||
|
||||
If a series of commands needs to be sent to a single target specification then
|
||||
the commands can be sent in a single publish. This can make gathering
|
||||
groups of information faster, and lowers the stress on the network for repeated
|
||||
commands.
|
||||
|
||||
Compound command execution works by sending a list of functions and arguments
|
||||
instead of sending a single function and argument. The functions are executed
|
||||
on the minion in the order they are defined on the command line, and then the
|
||||
data from all of the commands are returned in a dictionary. This means that
|
||||
the set of commands are called in a predictable way, and the returned data can
|
||||
be easily interpreted.
|
||||
|
||||
Executing compound commands if done by passing a comma delimited list of
|
||||
functions, followed by a comma delimited list of arguments:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' cmd.run,test.ping,test.echo 'cat /proc/cpuinfo',,foo
|
||||
|
||||
The trick to look out for here, is that if a function is being passed no
|
||||
arguments, then there needs to be a placeholder for the absent arguments. This
|
||||
is why in the above example, there are two commas right next to each other.
|
||||
``test.ping`` takes no arguments, so we need to add another comma, otherwise
|
||||
Salt would attempt to pass "foo" to ``test.ping``.
|
||||
|
||||
If you need to pass arguments that include commas, then make sure you add
|
||||
spaces around the commas that separate arguments. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' cmd.run,test.ping,test.echo 'echo "1,2,3"' , , foo
|
||||
|
||||
You may change the arguments separator using the ``--args-separator`` option:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt --args-separator=:: '*' some.fun,test.echo params with , comma :: foo
|
||||
|
||||
CLI Completion
|
||||
==============
|
||||
|
||||
Shell completion scripts for the Salt CLI are available in the ``pkg`` Salt
|
||||
`source directory`_.
|
||||
|
||||
.. _source directory: https://github.com/saltstack/salt/tree/develop/pkg
|
||||
|
||||
salt-call
|
||||
=========
|
||||
.. toctree::
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _configuring-salt:
|
||||
|
||||
================
|
||||
Configuring Salt
|
||||
================
|
||||
|
|
@ -212,7 +214,7 @@ Each of the Minions should send a ``True`` response as shown above.
|
|||
What's Next?
|
||||
============
|
||||
|
||||
Understanding :doc:`targeting </topics/targeting/index>` is important. From there,
|
||||
depending on the way you wish to use Salt, you should also proceed to learn
|
||||
about :doc:`States </topics/tutorials/starting_states>` and :doc:`Execution Modules
|
||||
</ref/modules/index>`.
|
||||
Understanding :ref:`targeting <targeting>` is important. From there, depending
|
||||
on the way you wish to use Salt, you should also proceed to learn about
|
||||
:ref:`Remote Execution <remote-execution>` and :ref:`Configuration Management
|
||||
<configuration-management>`.
|
||||
|
|
|
|||
|
|
@ -1,38 +1,29 @@
|
|||
Reference
|
||||
=========
|
||||
=====================
|
||||
Salt Module Reference
|
||||
=====================
|
||||
|
||||
This section contains a list of the Python modules that are used to extend the various subsystems within Salt.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
auth/all/index
|
||||
cli/index
|
||||
publisheracl
|
||||
clients/index
|
||||
clouds/all/index
|
||||
configuration/*
|
||||
configuration/logging/*
|
||||
configuration/logging/handlers/index
|
||||
file_server/index
|
||||
file_server/all/index
|
||||
internals/index
|
||||
modules/all/index
|
||||
netapi/all/index
|
||||
output/all/index
|
||||
peer
|
||||
pillar/index
|
||||
pillar/all/index
|
||||
proxy/all/index
|
||||
renderers/index
|
||||
returners/index
|
||||
roster/all/index
|
||||
runners/index
|
||||
states/index
|
||||
states/all/index
|
||||
modules/index
|
||||
tops/index
|
||||
tops/all/index
|
||||
wheel/all/index
|
||||
beacons/all/index
|
||||
engines/all/index
|
||||
sdb/all/index
|
||||
serializers/all/index
|
||||
queues/all/index
|
||||
../ref/auth/all/index
|
||||
../ref/beacons/all/index
|
||||
../ref/engines/all/index
|
||||
../ref/file_server/all/index
|
||||
../ref/modules/all/index
|
||||
../ref/netapi/all/index
|
||||
../ref/output/all/index
|
||||
../ref/pillar/all/index
|
||||
../ref/proxy/all/index
|
||||
../ref/queues/all/index
|
||||
../ref/renderers/all/index
|
||||
../ref/returners/all/index
|
||||
../ref/roster/all/index
|
||||
../ref/runners/all/index
|
||||
../ref/sdb/all/index
|
||||
../ref/serializers/all/index
|
||||
../ref/states/all/index
|
||||
../ref/tops/all/index
|
||||
../ref/wheel/all/index
|
||||
|
|
|
|||
|
|
@ -1,23 +1,11 @@
|
|||
.. _execution-modules:
|
||||
.. _writing-execution-modules:
|
||||
|
||||
=================
|
||||
Execution Modules
|
||||
=================
|
||||
=========================
|
||||
Writing Execution Modules
|
||||
=========================
|
||||
|
||||
Salt execution modules are the functions called by the :command:`salt` command.
|
||||
|
||||
.. note::
|
||||
|
||||
Salt execution modules are different from state modules and cannot be
|
||||
called directly within state files. You must use the :mod:`module <salt.states.module>`
|
||||
state module to call execution modules within state runs.
|
||||
|
||||
.. seealso:: :ref:`Full list of builtin modules <all-salt.modules>`
|
||||
|
||||
Salt ships with many modules that cover a wide variety of tasks.
|
||||
|
||||
.. _writing-execution-modules:
|
||||
|
||||
Modules Are Easy to Write!
|
||||
==========================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _publisher-acl:
|
||||
|
||||
====================
|
||||
Publisher ACL system
|
||||
====================
|
||||
|
|
@ -29,8 +31,7 @@ removed in the future releases. Use publisher_acl and publisher_acl_blacklist
|
|||
instead.
|
||||
|
||||
Permission Issues
|
||||
=================
|
||||
|
||||
-----------------
|
||||
Directories required for ``publisher_acl`` must be modified to be readable by
|
||||
the users specified:
|
||||
|
||||
|
|
@ -53,3 +54,12 @@ existing user keys and re-start the Salt master:
|
|||
|
||||
rm /var/cache/salt/.*key
|
||||
service salt-master restart
|
||||
|
||||
Whitelist and Blacklist
|
||||
-----------------------
|
||||
Salt's authentication systems can be configured by specifying what is allowed
|
||||
using a whitelist, or by specifying what is disallowed using a blacklist. If
|
||||
you specify a whitelist, only specified operations are allowed. If you specify
|
||||
a blacklist, all operations are allowed except those that are blacklisted.
|
||||
|
||||
See :conf_master:`publisher_acl` and :conf_master:`publisher_acl_blacklist`.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
============
|
||||
Salt Runners
|
||||
============
|
||||
=======
|
||||
Runners
|
||||
=======
|
||||
|
||||
Salt runners are convenience applications executed with the salt-run command.
|
||||
|
||||
|
|
@ -11,11 +11,6 @@ A Salt runner can be a simple client call or a complex application.
|
|||
|
||||
.. seealso:: :ref:`The full list of runners <all-salt.runners>`
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
all/index
|
||||
|
||||
Writing Salt Runners
|
||||
--------------------
|
||||
|
||||
|
|
@ -102,10 +97,6 @@ bus from the runner and then watching for them or by some other means.
|
|||
In synchronous mode, which is the default, control will not be returned until
|
||||
the runner has finished executing.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
To add custom runners, put them in a directory and add it to
|
||||
:conf_master:`runner_dirs` in the master configuration file.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
=================
|
||||
State Enforcement
|
||||
=================
|
||||
======================
|
||||
State System Reference
|
||||
======================
|
||||
|
||||
Salt offers an optional interface to manage the configuration or "state" of the
|
||||
Salt offers an interface to manage the configuration or "state" of the
|
||||
Salt minions. This interface is a fully capable mechanism used to enforce the
|
||||
state of systems from a central manager.
|
||||
|
||||
|
|
|
|||
11
doc/topics/api.rst
Normal file
11
doc/topics/api.rst
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
====
|
||||
APIs
|
||||
====
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
../ref/clients/index
|
||||
netapi/index
|
||||
|
||||
|
||||
|
|
@ -4,10 +4,11 @@
|
|||
Beacons
|
||||
=======
|
||||
|
||||
The beacon system allows the minion to hook into a variety of system processes
|
||||
and continually monitor these processes. When monitored activity occurs in
|
||||
a system process, an event is sent on the Salt event bus that can
|
||||
be used to trigger a :ref:`reactor <reactor>`.
|
||||
Beacons let you use the Salt event system to monitor non-Salt processes. The
|
||||
beacon system allows the minion to hook into a variety of system processes and
|
||||
continually monitor these processes. When monitored activity occurs in a system
|
||||
process, an event is sent on the Salt event bus that can be used to trigger
|
||||
a :ref:`reactor <reactor>`.
|
||||
|
||||
Salt beacons can currently monitor and send Salt events for many system
|
||||
activities, including:
|
||||
|
|
@ -231,7 +232,7 @@ The `beacon` Function
|
|||
The beacons system will look for a function named `beacon` in the module. If
|
||||
this function is not present then the beacon will not be fired. This function is
|
||||
called on a regular basis and defaults to being called on every iteration of the
|
||||
minion, which can be tens to hundreds of times a second. This means that the
|
||||
minion, which can be tens to hundreds of times a second. This means that the
|
||||
`beacon` function cannot block and should not be CPU or IO intensive.
|
||||
|
||||
The beacon function will be passed in the configuration for the executed
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _best-practices:
|
||||
|
||||
============================
|
||||
Salt :index:`Best Practices`
|
||||
============================
|
||||
|
|
|
|||
|
|
@ -170,6 +170,7 @@ Cloud Provider Specifics
|
|||
Getting Started With OpenNebula <opennebula>
|
||||
Getting Started With OpenStack <openstack>
|
||||
Getting Started With Parallels <parallels>
|
||||
Getting Started With Profitbricks <profitbricks>
|
||||
Getting Started With Proxmox <proxmox>
|
||||
Getting Started With Rackspace <rackspace>
|
||||
Getting Started With Saltify <saltify>
|
||||
|
|
|
|||
31
doc/topics/configuration/index.rst
Normal file
31
doc/topics/configuration/index.rst
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
================
|
||||
Configuring Salt
|
||||
================
|
||||
|
||||
This section explains how to configure user access, view and store job results,
|
||||
secure and troubleshoot, and how to perform many other administrative tasks.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
../../ref/configuration/master
|
||||
../../ref/configuration/minion
|
||||
../../ref/configuration/examples
|
||||
../eauth/access_control
|
||||
../jobs/index
|
||||
../jobs/job_cache
|
||||
../jobs/external_cache
|
||||
../../ref/configuration/logging/index
|
||||
../../ref/file_server/index
|
||||
../tutorials/gitfs
|
||||
../tutorials/minionfs
|
||||
../spm/index
|
||||
../sdb/index
|
||||
../../ref/configuration/nonroot
|
||||
../tutorials/cron
|
||||
../hardening
|
||||
../../security/index
|
||||
../transports/index
|
||||
../master_tops/index
|
||||
../../ref/returners/index
|
||||
../../ref/renderers/index
|
||||
|
|
@ -10,4 +10,7 @@ Developing Salt
|
|||
tests/index
|
||||
raet/index
|
||||
git/index
|
||||
conventions/index
|
||||
conventions/index
|
||||
../../ref/internals/index
|
||||
../projects/index
|
||||
../tutorials/writing_tests
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _developing-tutorial:
|
||||
|
||||
========================
|
||||
Developing Salt Tutorial
|
||||
========================
|
||||
|
|
|
|||
|
|
@ -9,7 +9,9 @@ Access Control System
|
|||
Salt maintains a standard system used to open granular control to non
|
||||
administrative users to execute Salt commands. The access control system
|
||||
has been applied to all systems used to configure access to non administrative
|
||||
control interfaces in Salt.These interfaces include, the ``peer`` system, the
|
||||
control interfaces in Salt.
|
||||
|
||||
These interfaces include, the ``peer`` system, the
|
||||
``external auth`` system and the ``publisher acl`` system.
|
||||
|
||||
The access control system mandated a standard configuration syntax used in
|
||||
|
|
@ -20,6 +22,31 @@ Now specific functions can be opened up to specific minions from specific users
|
|||
in the case of external auth and publisher ACLs, and for specific minions in the
|
||||
case of the peer system.
|
||||
|
||||
.. toctree::
|
||||
|
||||
../../ref/publisheracl
|
||||
index
|
||||
../../ref/peer
|
||||
|
||||
When to Use Each Authentication System
|
||||
======================================
|
||||
``publisher_acl`` is useful for allowing local system users to run Salt
|
||||
commands without giving them root access. If you can log into the Salt
|
||||
master directly, then ``publisher_acl`` allows you to use Salt without
|
||||
root privileges. If the local system is configured to authenticate against
|
||||
a remote system, like LDAP or Active Directory, then ``publisher_acl`` will
|
||||
interact with the remote system transparently.
|
||||
|
||||
``external_auth`` is useful for ``salt-api`` or for making your own scripts
|
||||
that use Salt's Python API. It can be used at the CLI (with the ``-a``
|
||||
flag) but it is more cumbersome as there are more steps involved. The only
|
||||
time it is useful at the CLI is when the local system is *not* configured
|
||||
to authenticate against an external service *but* you still want Salt to
|
||||
authenticate against an external service.
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
The access controls are manifested using matchers in these configurations:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -51,7 +78,6 @@ other minions based on standard targets.
|
|||
steve:
|
||||
- .*
|
||||
|
||||
|
||||
The above allows for all minions to be hit by test.ping by dave, and adds a
|
||||
few functions that dave can execute on other minions. It also allows steve
|
||||
unrestricted access to salt commands.
|
||||
|
|
|
|||
|
|
@ -12,25 +12,8 @@ command authorization to any external authentication system, such as PAM or LDAP
|
|||
eAuth using the PAM external auth system requires salt-master to be run as
|
||||
root as this system needs root access to check authentication.
|
||||
|
||||
Access Control System
|
||||
---------------------
|
||||
|
||||
.. note:: When to Use ``client_acl`` and ``external_auth``
|
||||
|
||||
``client_acl`` is useful for allowing local system users to run Salt
|
||||
commands without giving them root access. If you can log into the Salt
|
||||
master directly, then ``client_acl`` will allow you to use Salt without
|
||||
root privileges. If the local system is configured to authenticate against
|
||||
a remote system, like LDAP or Active Directory, then ``client_acl`` will
|
||||
interact with the remote system transparently.
|
||||
|
||||
``external_auth`` is useful for ``salt-api`` or for making your own scripts
|
||||
that use Salt's Python API. It can be used at the CLI (with the ``-a``
|
||||
flag) but it is more cumbersome as there are more steps involved. The only
|
||||
time it is useful at the CLI is when the local system is *not* configured
|
||||
to authenticate against an external service *but* you still want Salt to
|
||||
authenticate against an external service.
|
||||
|
||||
External Authentication System Configuration
|
||||
============================================
|
||||
The external authentication system allows for specific users to be granted
|
||||
access to execute specific functions on specific minions. Access is configured
|
||||
in the master configuration file and uses the :ref:`access control system
|
||||
|
|
@ -56,7 +39,8 @@ service to authenticate.
|
|||
|
||||
.. note:: The PAM module does not allow authenticating as ``root``.
|
||||
|
||||
.. note:: state.sls and state.highstate will return "Failed to authenticate!" if the request timeout is reached. Use -t flag to increase the timeout
|
||||
.. note:: state.sls and state.highstate will return "Failed to authenticate!"
|
||||
if the request timeout is reached. Use -t flag to increase the timeout
|
||||
|
||||
To allow access to :ref:`wheel modules <all-salt.wheel>` or :ref:`runner
|
||||
modules <all-salt.runners>` the following ``@`` syntax must be used:
|
||||
|
|
@ -108,7 +92,6 @@ append a ``%`` to the ID:
|
|||
|
||||
Tokens
|
||||
------
|
||||
|
||||
With external authentication alone, the authentication credentials will be
|
||||
required with every call to Salt. This can be alleviated with Salt tokens.
|
||||
|
||||
|
|
@ -131,7 +114,6 @@ Token expiration time can be set in the Salt master config file.
|
|||
|
||||
LDAP and Active Directory
|
||||
=========================
|
||||
|
||||
.. note::
|
||||
|
||||
LDAP usage requires that you have installed python-ldap.
|
||||
|
|
@ -141,7 +123,6 @@ accessed via its LDAP interface)
|
|||
|
||||
OpenLDAP and similar systems
|
||||
----------------------------
|
||||
|
||||
LDAP configuration happens in the Salt master configuration file.
|
||||
|
||||
Server configuration values and their defaults:
|
||||
|
|
|
|||
227
doc/topics/event/events.rst
Normal file
227
doc/topics/event/events.rst
Normal file
|
|
@ -0,0 +1,227 @@
|
|||
============
|
||||
Event System
|
||||
============
|
||||
|
||||
The Salt Event System is used to fire off events enabling third party
|
||||
applications or external processes to react to behavior within Salt.
|
||||
|
||||
The event system is comprised of a two primary components:
|
||||
|
||||
* The event sockets which publishes events.
|
||||
* The event library which can listen to events and send events into the salt system.
|
||||
|
||||
Event types
|
||||
===========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
master_events
|
||||
|
||||
Listening for Events
|
||||
====================
|
||||
|
||||
Salt's Event Bus is used heavily within Salt and it is also written to
|
||||
integrate heavily with existing tooling and scripts. There is a variety of
|
||||
ways to consume it.
|
||||
|
||||
From the CLI
|
||||
------------
|
||||
|
||||
The quickest way to watch the event bus is by calling the :py:func:`state.event
|
||||
runner <salt.runners.state.event>`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.event pretty=True
|
||||
|
||||
That runner is designed to interact with the event bus from external tools and
|
||||
shell scripts. See the documentation for more examples.
|
||||
|
||||
Remotely via the REST API
|
||||
-------------------------
|
||||
|
||||
Salt's event bus can be consumed
|
||||
:py:class:`salt.netapi.rest_cherrypy.app.Events` as an HTTP stream from
|
||||
external tools or services.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl -SsNk https://salt-api.example.com:8000/events?token=05A3
|
||||
|
||||
From Python
|
||||
-----------
|
||||
|
||||
Python scripts can access the event bus only as the same system user that Salt
|
||||
is running as.
|
||||
|
||||
The event system is accessed via the event library and can only be accessed
|
||||
by the same system user that Salt is running as. To listen to events a
|
||||
SaltEvent object needs to be created and then the get_event function needs to
|
||||
be run. The SaltEvent object needs to know the location that the Salt Unix
|
||||
sockets are kept. In the configuration this is the ``sock_dir`` option. The
|
||||
``sock_dir`` option defaults to "/var/run/salt/master" on most systems.
|
||||
|
||||
The following code will check for a single event:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import salt.config
|
||||
import salt.utils.event
|
||||
|
||||
opts = salt.config.client_config('/etc/salt/master')
|
||||
|
||||
event = salt.utils.event.get_event(
|
||||
'master',
|
||||
sock_dir=opts['sock_dir'],
|
||||
transport=opts['transport'],
|
||||
opts=opts)
|
||||
|
||||
data = event.get_event()
|
||||
|
||||
Events will also use a "tag". Tags allow for events to be filtered by prefix.
|
||||
By default all events will be returned. If only authentication events are
|
||||
desired, then pass the tag "salt/auth".
|
||||
|
||||
The ``get_event`` method has a default poll time assigned of 5 seconds. To
|
||||
change this time set the "wait" option.
|
||||
|
||||
The following example will only listen for auth events and will wait for 10 seconds
|
||||
instead of the default 5.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
data = event.get_event(wait=10, tag='salt/auth')
|
||||
|
||||
To retrieve the tag as well as the event data, pass ``full=True``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
evdata = event.get_event(wait=10, tag='salt/job', full=True)
|
||||
|
||||
tag, data = evdata['tag'], evdata['data']
|
||||
|
||||
|
||||
Instead of looking for a single event, the ``iter_events`` method can be used to
|
||||
make a generator which will continually yield salt events.
|
||||
|
||||
The iter_events method also accepts a tag but not a wait time:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for data in event.iter_events(tag='salt/auth'):
|
||||
print(data)
|
||||
|
||||
And finally event tags can be globbed, such as they can be in the Reactor,
|
||||
using the fnmatch library.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import fnmatch
|
||||
|
||||
import salt.config
|
||||
import salt.utils.event
|
||||
|
||||
opts = salt.config.client_config('/etc/salt/master')
|
||||
|
||||
sevent = salt.utils.event.get_event(
|
||||
'master',
|
||||
sock_dir=opts['sock_dir'],
|
||||
transport=opts['transport'],
|
||||
opts=opts)
|
||||
|
||||
while True:
|
||||
ret = sevent.get_event(full=True)
|
||||
if ret is None:
|
||||
continue
|
||||
|
||||
if fnmatch.fnmatch(ret['tag'], 'salt/job/*/ret/*'):
|
||||
do_something_with_job_return(ret['data'])
|
||||
|
||||
Firing Events
|
||||
=============
|
||||
|
||||
It is possible to fire events on either the minion's local bus or to fire
|
||||
events intended for the master.
|
||||
|
||||
To fire a local event from the minion on the command line call the
|
||||
:py:func:`event.fire <salt.modules.event.fire>` execution function:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-call event.fire '{"data": "message to be sent in the event"}' 'tag'
|
||||
|
||||
To fire an event to be sent up to the master from the minion call the
|
||||
:py:func:`event.send <salt.modules.event.send>` execution function. Remember
|
||||
YAML can be used at the CLI in function arguments:
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-call event.send 'myco/mytag/success' '{success: True, message: "It works!"}'
|
||||
|
||||
If a process is listening on the minion, it may be useful for a user on the
|
||||
master to fire an event to it:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Job on minion
|
||||
import salt.utils.event
|
||||
|
||||
event = salt.utils.event.MinionEvent(**__opts__)
|
||||
|
||||
for evdata in event.iter_events(tag='customtag/'):
|
||||
return evdata # do your processing here...
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt minionname event.fire '{"data": "message for the minion"}' 'customtag/african/unladen'
|
||||
|
||||
|
||||
Firing Events from Python
|
||||
=========================
|
||||
|
||||
From Salt execution modules
|
||||
---------------------------
|
||||
|
||||
Events can be very useful when writing execution modules, in order to inform
|
||||
various processes on the master when a certain task has taken place. This is
|
||||
easily done using the normal cross-calling syntax:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# /srv/salt/_modules/my_custom_module.py
|
||||
|
||||
def do_something():
|
||||
'''
|
||||
Do something and fire an event to the master when finished
|
||||
|
||||
CLI Example::
|
||||
|
||||
salt '*' my_custom_module:do_something
|
||||
'''
|
||||
# do something!
|
||||
__salt__['event.send']('myco/my_custom_module/finished', {
|
||||
'finished': True,
|
||||
'message': "The something is finished!",
|
||||
})
|
||||
|
||||
From Custom Python Scripts
|
||||
--------------------------
|
||||
|
||||
Firing events from custom Python code is quite simple and mirrors how it is
|
||||
done at the CLI:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import salt.client
|
||||
|
||||
caller = salt.client.Caller()
|
||||
|
||||
caller.sminion.functions['event.send'](
|
||||
'myco/myevent/success',
|
||||
{
|
||||
'success': True,
|
||||
'message': "It works!",
|
||||
}
|
||||
)
|
||||
|
|
@ -3,230 +3,14 @@
|
|||
|
||||
.. _events:
|
||||
|
||||
=================
|
||||
Salt Event System
|
||||
=================
|
||||
================
|
||||
Events & Reactor
|
||||
================
|
||||
|
||||
The Salt Event System is used to fire off events enabling third party
|
||||
applications or external processes to react to behavior within Salt.
|
||||
|
||||
The event system is comprised of a two primary components:
|
||||
|
||||
* The event sockets which publishes events.
|
||||
* The event library which can listen to events and send events into the salt system.
|
||||
|
||||
Event types
|
||||
===========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
master_events
|
||||
|
||||
Listening for Events
|
||||
====================
|
||||
|
||||
Salt's Event Bus is used heavily within Salt and it is also written to
|
||||
integrate heavily with existing tooling and scripts. There is a variety of
|
||||
ways to consume it.
|
||||
|
||||
From the CLI
|
||||
------------
|
||||
|
||||
The quickest way to watch the event bus is by calling the :py:func:`state.event
|
||||
runner <salt.runners.state.event>`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.event pretty=True
|
||||
|
||||
That runner is designed to interact with the event bus from external tools and
|
||||
shell scripts. See the documentation for more examples.
|
||||
|
||||
Remotely via the REST API
|
||||
-------------------------
|
||||
|
||||
Salt's event bus can be consumed
|
||||
:py:class:`salt.netapi.rest_cherrypy.app.Events` as an HTTP stream from
|
||||
external tools or services.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
curl -SsNk https://salt-api.example.com:8000/events?token=05A3
|
||||
|
||||
From Python
|
||||
-----------
|
||||
|
||||
Python scripts can access the event bus only as the same system user that Salt
|
||||
is running as.
|
||||
|
||||
The event system is accessed via the event library and can only be accessed
|
||||
by the same system user that Salt is running as. To listen to events a
|
||||
SaltEvent object needs to be created and then the get_event function needs to
|
||||
be run. The SaltEvent object needs to know the location that the Salt Unix
|
||||
sockets are kept. In the configuration this is the ``sock_dir`` option. The
|
||||
``sock_dir`` option defaults to "/var/run/salt/master" on most systems.
|
||||
|
||||
The following code will check for a single event:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import salt.config
|
||||
import salt.utils.event
|
||||
|
||||
opts = salt.config.client_config('/etc/salt/master')
|
||||
|
||||
event = salt.utils.event.get_event(
|
||||
'master',
|
||||
sock_dir=opts['sock_dir'],
|
||||
transport=opts['transport'],
|
||||
opts=opts)
|
||||
|
||||
data = event.get_event()
|
||||
|
||||
Events will also use a "tag". Tags allow for events to be filtered by prefix.
|
||||
By default all events will be returned. If only authentication events are
|
||||
desired, then pass the tag "salt/auth".
|
||||
|
||||
The ``get_event`` method has a default poll time assigned of 5 seconds. To
|
||||
change this time set the "wait" option.
|
||||
|
||||
The following example will only listen for auth events and will wait for 10 seconds
|
||||
instead of the default 5.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
data = event.get_event(wait=10, tag='salt/auth')
|
||||
|
||||
To retrieve the tag as well as the event data, pass ``full=True``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
evdata = event.get_event(wait=10, tag='salt/job', full=True)
|
||||
|
||||
tag, data = evdata['tag'], evdata['data']
|
||||
|
||||
|
||||
Instead of looking for a single event, the ``iter_events`` method can be used to
|
||||
make a generator which will continually yield salt events.
|
||||
|
||||
The iter_events method also accepts a tag but not a wait time:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for data in event.iter_events(tag='salt/auth'):
|
||||
print(data)
|
||||
|
||||
And finally event tags can be globbed, such as they can be in the Reactor,
|
||||
using the fnmatch library.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import fnmatch
|
||||
|
||||
import salt.config
|
||||
import salt.utils.event
|
||||
|
||||
opts = salt.config.client_config('/etc/salt/master')
|
||||
|
||||
sevent = salt.utils.event.get_event(
|
||||
'master',
|
||||
sock_dir=opts['sock_dir'],
|
||||
transport=opts['transport'],
|
||||
opts=opts)
|
||||
|
||||
while True:
|
||||
ret = sevent.get_event(full=True)
|
||||
if ret is None:
|
||||
continue
|
||||
|
||||
if fnmatch.fnmatch(ret['tag'], 'salt/job/*/ret/*'):
|
||||
do_something_with_job_return(ret['data'])
|
||||
|
||||
Firing Events
|
||||
=============
|
||||
|
||||
It is possible to fire events on either the minion's local bus or to fire
|
||||
events intended for the master.
|
||||
|
||||
To fire a local event from the minion on the command line call the
|
||||
:py:func:`event.fire <salt.modules.event.fire>` execution function:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-call event.fire '{"data": "message to be sent in the event"}' 'tag'
|
||||
|
||||
To fire an event to be sent up to the master from the minion call the
|
||||
:py:func:`event.send <salt.modules.event.send>` execution function. Remember
|
||||
YAML can be used at the CLI in function arguments:
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-call event.send 'myco/mytag/success' '{success: True, message: "It works!"}'
|
||||
|
||||
If a process is listening on the minion, it may be useful for a user on the
|
||||
master to fire an event to it:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Job on minion
|
||||
import salt.utils.event
|
||||
|
||||
event = salt.utils.event.MinionEvent(**__opts__)
|
||||
|
||||
for evdata in event.iter_events(tag='customtag/'):
|
||||
return evdata # do your processing here...
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt minionname event.fire '{"data": "message for the minion"}' 'customtag/african/unladen'
|
||||
|
||||
|
||||
Firing Events from Python
|
||||
=========================
|
||||
|
||||
From Salt execution modules
|
||||
---------------------------
|
||||
|
||||
Events can be very useful when writing execution modules, in order to inform
|
||||
various processes on the master when a certain task has taken place. This is
|
||||
easily done using the normal cross-calling syntax:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# /srv/salt/_modules/my_custom_module.py
|
||||
|
||||
def do_something():
|
||||
'''
|
||||
Do something and fire an event to the master when finished
|
||||
|
||||
CLI Example::
|
||||
|
||||
salt '*' my_custom_module:do_something
|
||||
'''
|
||||
# do something!
|
||||
__salt__['event.send']('myco/my_custom_module/finished', {
|
||||
'finished': True,
|
||||
'message': "The something is finished!",
|
||||
})
|
||||
|
||||
From Custom Python Scripts
|
||||
--------------------------
|
||||
|
||||
Firing events from custom Python code is quite simple and mirrors how it is
|
||||
done at the CLI:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import salt.client
|
||||
|
||||
caller = salt.client.Caller()
|
||||
|
||||
caller.sminion.functions['event.send'](
|
||||
'myco/myevent/success',
|
||||
{
|
||||
'success': True,
|
||||
'message': "It works!",
|
||||
}
|
||||
)
|
||||
events
|
||||
../beacons/index
|
||||
../reactor/index
|
||||
28
doc/topics/execution/index.rst
Normal file
28
doc/topics/execution/index.rst
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
.. _remote-execution:
|
||||
|
||||
================
|
||||
Remote Execution
|
||||
================
|
||||
|
||||
Running pre-defined or arbitrary commands on remote hosts, also known as
|
||||
remote execution, is the core function of Salt. The following links explore
|
||||
modules and returners, which are two key elements of remote execution.
|
||||
|
||||
**Salt Execution Modules**
|
||||
|
||||
Salt execution modules are called by the remote execution system to perform
|
||||
a wide variety of tasks. These modules provide functionality such as installing
|
||||
packages, restarting a service, running a remote command, transferring files,
|
||||
and so on.
|
||||
|
||||
:ref:`Full list of execution modules <all-salt_modules>`
|
||||
Contains: a list of core modules that ship with Salt.
|
||||
|
||||
:ref:`Writing execution modules <writing-execution-modules>`
|
||||
Contains: a guide on how to write Salt modules.
|
||||
|
||||
.. toctree::
|
||||
|
||||
../tutorials/modules
|
||||
remote_execution
|
||||
../../ref/modules/index
|
||||
158
doc/topics/execution/remote_execution.rst
Normal file
158
doc/topics/execution/remote_execution.rst
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
================================
|
||||
Running Commands on Salt Minions
|
||||
================================
|
||||
|
||||
Salt can be controlled by a command line client by the root user on the Salt
|
||||
master. The Salt command line client uses the Salt client API to communicate
|
||||
with the Salt master server. The Salt client is straightforward and simple
|
||||
to use.
|
||||
|
||||
Using the Salt client commands can be easily sent to the minions.
|
||||
|
||||
Each of these commands accepts an explicit `--config` option to point to either
|
||||
the master or minion configuration file. If this option is not provided and
|
||||
the default configuration file does not exist then Salt falls back to use the
|
||||
environment variables ``SALT_MASTER_CONFIG`` and ``SALT_MINION_CONFIG``.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`Configuration </ref/configuration/index>`
|
||||
|
||||
Using the Salt Command
|
||||
======================
|
||||
|
||||
The Salt command needs a few components to send information to the Salt
|
||||
minions. The target minions need to be defined, the function to call and any
|
||||
arguments the function requires.
|
||||
|
||||
Defining the Target Minions
|
||||
---------------------------
|
||||
|
||||
The first argument passed to salt, defines the target minions, the target
|
||||
minions are accessed via their hostname. The default target type is a bash
|
||||
glob:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*foo.com' sys.doc
|
||||
|
||||
|
||||
Salt can also define the target minions with regular expressions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt -E '.*' cmd.run 'ls -l | grep foo'
|
||||
|
||||
Or to explicitly list hosts, salt can take a list:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt -L foo.bar.baz,quo.qux cmd.run 'ps aux | grep foo'
|
||||
|
||||
More Powerful Targets
|
||||
---------------------
|
||||
|
||||
See :ref:`Targeting <targeting>`.
|
||||
|
||||
|
||||
Calling the Function
|
||||
--------------------
|
||||
|
||||
The function to call on the specified target is placed after the target
|
||||
specification.
|
||||
|
||||
.. versionadded:: 0.9.8
|
||||
|
||||
Functions may also accept arguments, space-delimited:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' cmd.exec_code python 'import sys; print sys.version'
|
||||
|
||||
Optional, keyword arguments are also supported:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' pip.install salt timeout=5 upgrade=True
|
||||
|
||||
They are always in the form of ``kwarg=argument``.
|
||||
|
||||
Arguments are formatted as YAML:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' cmd.run 'echo "Hello: $FIRST_NAME"' env='{FIRST_NAME: "Joe"}'
|
||||
|
||||
Note: dictionaries must have curly braces around them (like the ``env``
|
||||
keyword argument above). This was changed in 0.15.1: in the above example,
|
||||
the first argument used to be parsed as the dictionary
|
||||
``{'echo "Hello': '$FIRST_NAME"'}``. This was generally not the expected
|
||||
behavior.
|
||||
|
||||
If you want to test what parameters are actually passed to a module, use the
|
||||
``test.arg_repr`` command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' test.arg_repr 'echo "Hello: $FIRST_NAME"' env='{FIRST_NAME: "Joe"}'
|
||||
|
||||
Finding available minion functions
|
||||
``````````````````````````````````
|
||||
|
||||
The Salt functions are self documenting, all of the function documentation can
|
||||
be retried from the minions via the :func:`sys.doc` function:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' sys.doc
|
||||
|
||||
Compound Command Execution
|
||||
--------------------------
|
||||
|
||||
If a series of commands needs to be sent to a single target specification then
|
||||
the commands can be sent in a single publish. This can make gathering
|
||||
groups of information faster, and lowers the stress on the network for repeated
|
||||
commands.
|
||||
|
||||
Compound command execution works by sending a list of functions and arguments
|
||||
instead of sending a single function and argument. The functions are executed
|
||||
on the minion in the order they are defined on the command line, and then the
|
||||
data from all of the commands are returned in a dictionary. This means that
|
||||
the set of commands are called in a predictable way, and the returned data can
|
||||
be easily interpreted.
|
||||
|
||||
Executing compound commands if done by passing a comma delimited list of
|
||||
functions, followed by a comma delimited list of arguments:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' cmd.run,test.ping,test.echo 'cat /proc/cpuinfo',,foo
|
||||
|
||||
The trick to look out for here, is that if a function is being passed no
|
||||
arguments, then there needs to be a placeholder for the absent arguments. This
|
||||
is why in the above example, there are two commas right next to each other.
|
||||
``test.ping`` takes no arguments, so we need to add another comma, otherwise
|
||||
Salt would attempt to pass "foo" to ``test.ping``.
|
||||
|
||||
If you need to pass arguments that include commas, then make sure you add
|
||||
spaces around the commas that separate arguments. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' cmd.run,test.ping,test.echo 'echo "1,2,3"' , , foo
|
||||
|
||||
You may change the arguments separator using the ``--args-separator`` option:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt --args-separator=:: '*' some.fun,test.echo params with , comma :: foo
|
||||
|
||||
CLI Completion
|
||||
==============
|
||||
|
||||
Shell completion scripts for the Salt CLI are available in the ``pkg`` Salt
|
||||
`source directory`_.
|
||||
|
||||
.. _source directory: https://github.com/saltstack/salt/tree/develop/pkg
|
||||
|
||||
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
:orphan:
|
||||
.. _ext-processes:
|
||||
|
||||
===============================
|
||||
|
|
@ -15,14 +16,14 @@ it is possible to configure it to start additional custom processes.
|
|||
|
||||
This is useful if a dedicated process is needed that should run throughout
|
||||
the life of the Salt master. For periodic independent tasks, a
|
||||
:doc:`scheduled runner <../jobs/schedule.rst>` may be more appropriate.
|
||||
:ref:`scheduled runner <scheduling-jobs>` may be more appropriate.
|
||||
|
||||
Processes started in this way will be restarted if they die and will be
|
||||
killed when the Salt master is shut down.
|
||||
|
||||
|
||||
Example Configuration
|
||||
======================
|
||||
=====================
|
||||
|
||||
Processes are declared in the master config file with the `ext_processes`
|
||||
option. Processes will be started in the order they are declared.
|
||||
|
|
|
|||
273
doc/topics/grains/index.rst
Normal file
273
doc/topics/grains/index.rst
Normal file
|
|
@ -0,0 +1,273 @@
|
|||
.. _grains:
|
||||
|
||||
======
|
||||
Grains
|
||||
======
|
||||
|
||||
Salt comes with an interface to derive information about the underlying system.
|
||||
This is called the grains interface, because it presents salt with grains of
|
||||
information. Grains are collected for the operating system, domain name,
|
||||
IP address, kernel, OS type, memory, and many other system properties.
|
||||
|
||||
The grains interface is made available to Salt modules and components so that
|
||||
the right salt minion commands are automatically available on the right
|
||||
systems.
|
||||
|
||||
Grain data is relatively static, though if system information changes
|
||||
(for example, if network settings are changed), or if a new value is assigned
|
||||
to a custom grain, grain data is refreshed.
|
||||
|
||||
.. note::
|
||||
|
||||
Grains resolve to lowercase letters. For example, ``FOO``, and ``foo``
|
||||
target the same grain.
|
||||
|
||||
|
||||
Listing Grains
|
||||
==============
|
||||
|
||||
Available grains can be listed by using the 'grains.ls' module:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' grains.ls
|
||||
|
||||
Grains data can be listed by using the 'grains.items' module:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' grains.items
|
||||
|
||||
|
||||
.. _static-custom-grains:
|
||||
|
||||
Grains in the Minion Config
|
||||
===========================
|
||||
|
||||
Grains can also be statically assigned within the minion configuration file.
|
||||
Just add the option ``grains`` and pass options to it:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
grains:
|
||||
roles:
|
||||
- webserver
|
||||
- memcache
|
||||
deployment: datacenter4
|
||||
cabinet: 13
|
||||
cab_u: 14-15
|
||||
|
||||
Then status data specific to your servers can be retrieved via Salt, or used
|
||||
inside of the State system for matching. It also makes targeting, in the case
|
||||
of the example above, simply based on specific data about your deployment.
|
||||
|
||||
|
||||
Grains in /etc/salt/grains
|
||||
==========================
|
||||
|
||||
If you do not want to place your custom static grains in the minion config
|
||||
file, you can also put them in ``/etc/salt/grains`` on the minion. They are configured in the
|
||||
same way as in the above example, only without a top-level ``grains:`` key:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
roles:
|
||||
- webserver
|
||||
- memcache
|
||||
deployment: datacenter4
|
||||
cabinet: 13
|
||||
cab_u: 14-15
|
||||
|
||||
|
||||
Matching Grains in the Top File
|
||||
===============================
|
||||
|
||||
With correctly configured grains on the Minion, the :term:`top file` used in
|
||||
Pillar or during Highstate can be made very efficient. For example, consider
|
||||
the following configuration:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
'node_type:web':
|
||||
- match: grain
|
||||
- webserver
|
||||
|
||||
'node_type:postgres':
|
||||
- match: grain
|
||||
- database
|
||||
|
||||
'node_type:redis':
|
||||
- match: grain
|
||||
- redis
|
||||
|
||||
'node_type:lb':
|
||||
- match: grain
|
||||
- lb
|
||||
|
||||
For this example to work, you would need to have defined the grain
|
||||
``node_type`` for the minions you wish to match. This simple example is nice,
|
||||
but too much of the code is similar. To go one step further, Jinja templating
|
||||
can be used to simplify the :term:`top file`.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{% set the_node_type = salt['grains.get']('node_type', '') %}
|
||||
|
||||
{% if the_node_type %}
|
||||
'node_type:{{ the_node_type }}':
|
||||
- match: grain
|
||||
- {{ the_node_type }}
|
||||
{% endif %}
|
||||
|
||||
Using Jinja templating, only one match entry needs to be defined.
|
||||
|
||||
.. note::
|
||||
|
||||
The example above uses the :mod:`grains.get <salt.modules.grains.get>`
|
||||
function to account for minions which do not have the ``node_type`` grain
|
||||
set.
|
||||
|
||||
.. _writing-grains:
|
||||
|
||||
Writing Grains
|
||||
==============
|
||||
|
||||
The grains interface is derived by executing
|
||||
all of the "public" functions found in the modules located in the grains
|
||||
package or the custom grains directory. The functions in the modules of
|
||||
the grains must return a Python :ref:`dict <python2:typesmapping>`, where the
|
||||
keys in the :ref:`dict <python2:typesmapping>` are the names of the grains and
|
||||
the values are the values.
|
||||
|
||||
Custom grains should be placed in a ``_grains`` directory located under the
|
||||
:conf_master:`file_roots` specified by the master config file. The default path
|
||||
would be ``/srv/salt/_grains``. Custom grains will be
|
||||
distributed to the minions when :mod:`state.highstate
|
||||
<salt.modules.state.highstate>` is run, or by executing the
|
||||
:mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
|
||||
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
|
||||
|
||||
Grains are easy to write, and only need to return a dictionary. A common
|
||||
approach would be code something similar to the following:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
def yourfunction():
|
||||
# initialize a grains dictionary
|
||||
grains = {}
|
||||
# Some code for logic that sets grains like
|
||||
grains['yourcustomgrain'] = True
|
||||
grains['anothergrain'] = 'somevalue'
|
||||
return grains
|
||||
|
||||
Before adding a grain to Salt, consider what the grain is and remember that
|
||||
grains need to be static data. If the data is something that is likely to
|
||||
change, consider using :doc:`Pillar <../pillar/index>` instead.
|
||||
|
||||
.. warning::
|
||||
|
||||
Custom grains will not be available in the top file until after the first
|
||||
:ref:`highstate <running-highstate>`. To make custom grains available on a
|
||||
minion's first highstate, it is recommended to use :ref:`this example
|
||||
<minion-start-reactor>` to ensure that the custom grains are synced when
|
||||
the minion starts.
|
||||
|
||||
Loading Custom Grains
|
||||
---------------------
|
||||
|
||||
If you have multiple functions specifying grains that are called from a ``main``
|
||||
function, be sure to prepend grain function names with an underscore. This prevents
|
||||
Salt from including the loaded grains from the grain functions in the final
|
||||
grain data structure. For example, consider this custom grain file:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
def _my_custom_grain():
|
||||
my_grain = {'foo': 'bar', 'hello': 'world'}
|
||||
return my_grain
|
||||
|
||||
|
||||
def main():
|
||||
# initialize a grains dictionary
|
||||
grains = {}
|
||||
grains['my_grains'] = _my_custom_grain()
|
||||
return grains
|
||||
|
||||
The output of this example renders like so:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# salt-call --local grains.items
|
||||
local:
|
||||
----------
|
||||
<Snipped for brevity>
|
||||
my_grains:
|
||||
----------
|
||||
foo:
|
||||
bar
|
||||
hello:
|
||||
world
|
||||
|
||||
However, if you don't prepend the ``my_custom_grain`` function with an underscore,
|
||||
the function will be rendered twice by Salt in the items output: once for the
|
||||
``my_custom_grain`` call itself, and again when it is called in the ``main``
|
||||
function:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# salt-call --local grains.items
|
||||
local:
|
||||
----------
|
||||
<Snipped for brevity>
|
||||
foo:
|
||||
bar
|
||||
<Snipped for brevity>
|
||||
hello:
|
||||
world
|
||||
<Snipped for brevity>
|
||||
my_grains:
|
||||
----------
|
||||
foo:
|
||||
bar
|
||||
hello:
|
||||
world
|
||||
|
||||
|
||||
Precedence
|
||||
==========
|
||||
|
||||
Core grains can be overridden by custom grains. As there are several ways of
|
||||
defining custom grains, there is an order of precedence which should be kept in
|
||||
mind when defining them. The order of evaluation is as follows:
|
||||
|
||||
1. Core grains.
|
||||
2. Custom grains in ``/etc/salt/grains``.
|
||||
3. Custom grains in ``/etc/salt/minion``.
|
||||
4. Custom grain modules in ``_grains`` directory, synced to minions.
|
||||
|
||||
Each successive evaluation overrides the previous ones, so any grains defined
|
||||
by custom grains modules synced to minions that have the same name as a core
|
||||
grain will override that core grain. Similarly, grains from
|
||||
``/etc/salt/minion`` override both core grains and custom grain modules, and
|
||||
grains in ``_grains`` will override *any* grains of the same name.
|
||||
|
||||
|
||||
Examples of Grains
|
||||
==================
|
||||
|
||||
The core module in the grains package is where the main grains are loaded by
|
||||
the Salt minion and provides the principal example of how to write grains:
|
||||
|
||||
:blob:`salt/grains/core.py`
|
||||
|
||||
|
||||
Syncing Grains
|
||||
==============
|
||||
|
||||
Syncing grains can be done a number of ways, they are automatically synced when
|
||||
:mod:`state.highstate <salt.modules.state.highstate>` is called, or (as noted
|
||||
above) the grains can be manually synced and reloaded by calling the
|
||||
:mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
|
||||
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
|
||||
|
|
@ -6,7 +6,6 @@ Introduction to Salt
|
|||
|
||||
The 30 second summary
|
||||
=====================
|
||||
|
||||
Salt is:
|
||||
|
||||
* a configuration management system, capable of maintaining remote nodes
|
||||
|
|
@ -25,7 +24,6 @@ servers quickly through a simple and manageable interface.
|
|||
|
||||
Simplicity
|
||||
==========
|
||||
|
||||
Providing versatility between massive scale deployments and smaller systems may seem
|
||||
daunting, but Salt is very simple to set up and maintain, regardless of the
|
||||
size of the project. The architecture of Salt is designed to work with any
|
||||
|
|
@ -37,7 +35,6 @@ modification, Salt can be fine tuned to meet specific needs.
|
|||
|
||||
Parallel execution
|
||||
==================
|
||||
|
||||
The core functions of Salt:
|
||||
|
||||
* enable commands to remote systems to be called in parallel rather than serially
|
||||
|
|
@ -49,9 +46,8 @@ Salt also introduces more granular controls to the realm of remote
|
|||
execution, allowing systems to be targeted not just by hostname, but
|
||||
also by system properties.
|
||||
|
||||
Building on proven technology
|
||||
=============================
|
||||
|
||||
Builds on proven technology
|
||||
===========================
|
||||
Salt takes advantage of a number of technologies and techniques. The
|
||||
networking layer is built with the excellent `ZeroMQ`_ networking
|
||||
library, so the Salt daemon includes a viable and transparent AMQ
|
||||
|
|
@ -67,7 +63,6 @@ network traffic.
|
|||
|
||||
Python client interface
|
||||
=======================
|
||||
|
||||
In order to allow for simple expansion, Salt execution routines can be written
|
||||
as plain Python modules. The data collected from Salt executions can be sent
|
||||
back to the master server, or to any arbitrary program. Salt can be called from
|
||||
|
|
@ -77,7 +72,6 @@ application.
|
|||
|
||||
Fast, flexible, scalable
|
||||
========================
|
||||
|
||||
The result is a system that can execute commands at high speed on
|
||||
target server groups ranging from one to very many servers. Salt is
|
||||
very fast, easy to set up, amazingly malleable and provides a single
|
||||
|
|
@ -89,120 +83,9 @@ versatile as it is practical, suitable for any network.
|
|||
|
||||
Open
|
||||
====
|
||||
|
||||
Salt is developed under the `Apache 2.0 license`_, and can be used for
|
||||
open and proprietary projects. Please submit your expansions back to
|
||||
the Salt project so that we can all benefit together as Salt grows.
|
||||
Please feel free to sprinkle Salt around your systems and let the
|
||||
deliciousness come forth.
|
||||
|
||||
.. _salt-community:
|
||||
|
||||
Salt Community
|
||||
==============
|
||||
|
||||
Join the Salt!
|
||||
|
||||
There are many ways to participate in and communicate with the Salt community.
|
||||
|
||||
Salt has an active IRC channel and a mailing list.
|
||||
|
||||
Mailing List
|
||||
============
|
||||
|
||||
Join the `salt-users mailing list`_. It is the best place to ask questions
|
||||
about Salt and see whats going on with Salt development! The Salt mailing list
|
||||
is hosted by Google Groups. It is open to new members.
|
||||
|
||||
https://groups.google.com/forum/#!forum/salt-users
|
||||
|
||||
.. _`salt-users mailing list`: https://groups.google.com/forum/#!forum/salt-users
|
||||
|
||||
There is also a low-traffic list used to announce new releases
|
||||
called `salt-announce`_
|
||||
|
||||
https://groups.google.com/forum/#!forum/salt-announce
|
||||
|
||||
.. _`salt-announce`: https://groups.google.com/forum/#!forum/salt-announce
|
||||
|
||||
IRC
|
||||
===
|
||||
|
||||
The ``#salt`` IRC channel is hosted on the popular `Freenode`__ network. You
|
||||
can use the `Freenode webchat client`__ right from your browser.
|
||||
|
||||
`Logs of the IRC channel activity`__ are being collected courtesy of Moritz Lenz.
|
||||
|
||||
.. __: http://freenode.net/irc_servers.shtml
|
||||
.. __: http://webchat.freenode.net/?channels=salt&uio=Mj10cnVlJjk9dHJ1ZSYxMD10cnVl83
|
||||
.. __: http://irclog.perlgeek.de/salt/
|
||||
|
||||
If you wish to discuss the development of Salt itself join us in
|
||||
``#salt-devel``.
|
||||
|
||||
|
||||
Follow on GitHub
|
||||
================
|
||||
|
||||
The Salt code is developed via GitHub. Follow Salt for constant updates on what
|
||||
is happening in Salt development:
|
||||
|
||||
|saltrepo|
|
||||
|
||||
|
||||
Blogs
|
||||
=====
|
||||
|
||||
SaltStack Inc. keeps a `blog`_ with recent news and advancements:
|
||||
|
||||
http://www.saltstack.com/blog/
|
||||
|
||||
.. _`blog`: http://www.saltstack.com/blog/
|
||||
|
||||
Thomas Hatch also shares news and thoughts on Salt and related projects in his personal blog `The Red45`_:
|
||||
|
||||
http://red45.wordpress.com/
|
||||
|
||||
.. _`The Red45`: http://red45.wordpress.com/
|
||||
|
||||
|
||||
Example Salt States
|
||||
===================
|
||||
The official ``salt-states`` repository is:
|
||||
https://github.com/saltstack/salt-states
|
||||
|
||||
A few examples of salt states from the community:
|
||||
|
||||
* https://github.com/blast-hardcheese/blast-salt-states
|
||||
* https://github.com/kevingranade/kevingranade-salt-state
|
||||
* https://github.com/mattmcclean/salt-openstack/tree/master/salt
|
||||
* https://github.com/rentalita/ubuntu-setup/
|
||||
* https://github.com/brutasse/states
|
||||
* https://github.com/bclermont/states
|
||||
* https://github.com/pcrews/salt-data
|
||||
|
||||
Follow on ohloh
|
||||
===============
|
||||
|
||||
https://www.ohloh.net/p/salt
|
||||
|
||||
Other community links
|
||||
=====================
|
||||
|
||||
- `Salt Stack Inc. <http://www.saltstack.com>`_
|
||||
- `Subreddit <http://www.reddit.com/r/saltstack>`_
|
||||
- `Google+ <https://plus.google.com/114449193225626631691/posts>`_
|
||||
- `YouTube <http://www.youtube.com/user/SaltStack>`_
|
||||
- `Facebook <https://www.facebook.com/SaltStack>`_
|
||||
- `Twitter <https://twitter.com/SaltStackInc>`_
|
||||
- `Wikipedia page <http://en.wikipedia.org/wiki/Salt_(software)>`_
|
||||
|
||||
Hack the Source
|
||||
===============
|
||||
|
||||
If you want to get involved with the development of source code or the
|
||||
documentation efforts, please review the :doc:`hacking section
|
||||
<development/hacking>`!
|
||||
|
||||
|
||||
.. _`Apache 2.0 license`: http://www.apache.org/licenses/LICENSE-2.0.html
|
||||
|
|
|
|||
|
|
@ -3,23 +3,42 @@
|
|||
============
|
||||
Installation
|
||||
============
|
||||
.. seealso::
|
||||
This section contains instructions to install Salt. If you are setting up your
|
||||
environment for the first time, you should install a Salt master on
|
||||
a dedicated management server or VM, and then install a Salt minion on each
|
||||
system that you want to manage using Salt. For now you don't need to worry
|
||||
about your :ref:`architecture <architecture-overview>`, you can easily add
|
||||
components and modify your configuration later without needing to reinstall
|
||||
anything.
|
||||
|
||||
:doc:`Installing Salt for development </topics/development/hacking>` and
|
||||
contributing to the project.
|
||||
The general installation process is as follows:
|
||||
|
||||
1. Install a Salt master using the instructions for your platform or by running
|
||||
the Salt bootstrap script. If you use the bootstrap script, be sure to
|
||||
include the ``-M`` option to install the Salt master.
|
||||
|
||||
2. Make sure that your Salt minions can :ref:`find the Salt master
|
||||
<master-dns>`.
|
||||
|
||||
3. Install the Salt minion on each system that you want to manage.
|
||||
|
||||
4. Accept the Salt :ref:`minion keys <using-salt-key>` after the Salt minion
|
||||
connects.
|
||||
|
||||
After this, you should be able to run a simple command and receive returns from
|
||||
all connected Salt minions.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' test.ping
|
||||
|
||||
Quick Install
|
||||
-------------
|
||||
|
||||
On most distributions, you can set up a **Salt Minion** with the
|
||||
`Salt Bootstrap`_.
|
||||
|
||||
.. _`Salt Bootstrap`: https://github.com/saltstack/salt-bootstrap
|
||||
|
||||
:ref:`Salt bootstrap <salt-bootstrap>`.
|
||||
|
||||
Platform-specific Installation Instructions
|
||||
-------------------------------------------
|
||||
|
||||
These guides go into detail how to install Salt on a given platform.
|
||||
|
||||
.. toctree::
|
||||
|
|
@ -38,6 +57,28 @@ These guides go into detail how to install Salt on a given platform.
|
|||
windows
|
||||
suse
|
||||
|
||||
Initial Configuration
|
||||
---------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
../../ref/configuration/index
|
||||
|
||||
|
||||
Additional Installation Guides
|
||||
------------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
../tutorials/salt_bootstrap
|
||||
../tutorials/firewall
|
||||
../tutorials/preseed_key
|
||||
../tutorials/walkthrough_macosx
|
||||
../tutorials/rooted
|
||||
../tutorials/standalone_minion
|
||||
../tutorials/quickstart
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
|
@ -127,3 +168,8 @@ not guaranteed.
|
|||
Whenever possible, backward compatibility between new masters and old minions
|
||||
will be preserved. Generally, the only exception to this policy is in case of
|
||||
a security vulnerability.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`Installing Salt for development </topics/development/hacking>` and
|
||||
contributing to the project.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _jobs:
|
||||
|
||||
=======================
|
||||
:index:`Job Management`
|
||||
=======================
|
||||
|
|
@ -80,7 +82,7 @@ job invocation with the salt command would display.
|
|||
list_jobs
|
||||
---------
|
||||
|
||||
Before finding a historic job, it may be required to find the job id. list_jobs
|
||||
Before finding a historic job, it may be required to find the job id. ``list_jobs``
|
||||
will parse the cached execution data and display all of the job data for jobs
|
||||
that have already, or partially returned.
|
||||
|
||||
|
|
@ -88,11 +90,239 @@ that have already, or partially returned.
|
|||
|
||||
# salt-run jobs.list_jobs
|
||||
|
||||
:index:`Scheduling Jobs`
|
||||
========================
|
||||
.. include:: schedule.rst
|
||||
.. _scheduling-jobs:
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
Scheduling Jobs
|
||||
===============
|
||||
Salt's scheduling system allows incremental executions on minions or the
|
||||
master. The schedule system exposes the execution of any execution function on
|
||||
minions or any runner on the master.
|
||||
|
||||
Scheduling is enabled via the ``schedule`` option on either the master or minion
|
||||
config files, or via a minion's pillar data. Schedules that are implemented via
|
||||
pillar data, only need to refresh the minion's pillar data, for example by using
|
||||
``saltutil.refresh_pillar``. Schedules implemented in the master or minion config
|
||||
have to restart the application in order for the schedule to be implemented.
|
||||
|
||||
.. note::
|
||||
|
||||
The scheduler executes different functions on the master and minions. When
|
||||
running on the master the functions reference runner functions, when
|
||||
running on the minion the functions specify execution functions.
|
||||
|
||||
A scheduled run has no output on the minion unless the config is set to info level
|
||||
or higher. Refer to :conf_minion:`minion-logging-settings`.
|
||||
|
||||
Specify ``maxrunning`` to ensure that there are no more than N copies of
|
||||
a particular routine running. Use this for jobs that may be long-running
|
||||
and could step on each other or otherwise double execute. The default for
|
||||
``maxrunning`` is 1.
|
||||
|
||||
States are executed on the minion, as all states are. You can pass positional
|
||||
arguments and provide a yaml dict of named arguments.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
seconds: 3600
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
|
||||
This will schedule the command: state.sls httpd test=True every 3600 seconds
|
||||
(every hour)
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
seconds: 3600
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
splay: 15
|
||||
|
||||
This will schedule the command: state.sls httpd test=True every 3600 seconds
|
||||
(every hour) splaying the time between 0 and 15 seconds
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
seconds: 3600
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
splay:
|
||||
start: 10
|
||||
end: 15
|
||||
|
||||
This will schedule the command: state.sls httpd test=True every 3600 seconds
|
||||
(every hour) splaying the time between 10 and 15 seconds
|
||||
|
||||
.. versionadded:: 2014.7.0
|
||||
|
||||
Frequency of jobs can also be specified using date strings supported by
|
||||
the python dateutil library. This requires python-dateutil to be installed on
|
||||
the minion.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
when: 5:00pm
|
||||
|
||||
This will schedule the command: state.sls httpd test=True at 5:00pm minion
|
||||
localtime.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
when:
|
||||
- Monday 5:00pm
|
||||
- Tuesday 3:00pm
|
||||
- Wednesday 5:00pm
|
||||
- Thursday 3:00pm
|
||||
- Friday 5:00pm
|
||||
|
||||
This will schedule the command: state.sls httpd test=True at 5pm on Monday,
|
||||
Wednesday, and Friday, and 3pm on Tuesday and Thursday.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
seconds: 3600
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
range:
|
||||
start: 8:00am
|
||||
end: 5:00pm
|
||||
|
||||
This will schedule the command: state.sls httpd test=True every 3600 seconds
|
||||
(every hour) between the hours of 8am and 5pm. The range parameter must be a
|
||||
dictionary with the date strings using the dateutil format. This requires
|
||||
python-dateutil to be installed on the minion.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: pkg.install
|
||||
kwargs:
|
||||
pkgs: [{'bar': '>1.2.3'}]
|
||||
refresh: true
|
||||
once: '2016-01-07T14:30:00'
|
||||
|
||||
This will schedule the command pkg.install to be executed once at the specified
|
||||
time. The schedule entry ``job1`` will not be removed after the job completes,
|
||||
therefore use ``schedule.delete`` to manually remove it afterwards.
|
||||
|
||||
The default date format is ISO 8601 but can be overridden by also specifying the
|
||||
``once_fmt`` option.
|
||||
|
||||
.. versionadded:: 2014.7.0
|
||||
|
||||
The scheduler also supports ensuring that there are no more than N copies of
|
||||
a particular routine running. Use this for jobs that may be long-running
|
||||
and could step on each other or pile up in case of infrastructure outage.
|
||||
|
||||
The default for maxrunning is 1.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
long_running_job:
|
||||
function: big_file_transfer
|
||||
jid_include: True
|
||||
|
||||
Scheduling States
|
||||
-----------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
log-loadavg:
|
||||
function: cmd.run
|
||||
seconds: 3660
|
||||
args:
|
||||
- 'logger -t salt < /proc/loadavg'
|
||||
kwargs:
|
||||
stateful: False
|
||||
shell: /bin/sh
|
||||
|
||||
Scheduling Highstates
|
||||
---------------------
|
||||
To set up a highstate to run on a minion every 60 minutes set this in the
|
||||
minion config or pillar:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
highstate:
|
||||
function: state.highstate
|
||||
minutes: 60
|
||||
|
||||
Time intervals can be specified as seconds, minutes, hours, or days.
|
||||
|
||||
Scheduling Runners
|
||||
------------------
|
||||
Runner executions can also be specified on the master within the master
|
||||
configuration file:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
run_my_orch:
|
||||
function: state.orchestrate
|
||||
hours: 6
|
||||
splay: 600
|
||||
args:
|
||||
- orchestration.my_orch
|
||||
|
||||
The above configuration is analogous to running
|
||||
``salt-run state.orch orchestration.my_orch`` every 6 hours.
|
||||
|
||||
Scheduler With Returner
|
||||
-----------------------
|
||||
The scheduler is also useful for tasks like gathering monitoring data about
|
||||
a minion, this schedule option will gather status data and send it to a MySQL
|
||||
returner database:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
uptime:
|
||||
function: status.uptime
|
||||
seconds: 60
|
||||
returner: mysql
|
||||
meminfo:
|
||||
function: status.meminfo
|
||||
minutes: 5
|
||||
returner: mysql
|
||||
|
||||
Since specifying the returner repeatedly can be tiresome, the
|
||||
``schedule_returner`` option is available to specify one or a list of global
|
||||
returners to be used by the minions when scheduling.
|
||||
|
||||
schedule
|
||||
|
|
@ -1,235 +0,0 @@
|
|||
|
||||
In Salt versions greater than 0.12.0, the scheduling system allows incremental
|
||||
executions on minions or the master. The schedule system exposes the execution
|
||||
of any execution function on minions or any runner on the master.
|
||||
|
||||
Scheduling is enabled via the ``schedule`` option on either the master or minion
|
||||
config files, or via a minion's pillar data. Schedules that are impletemented via
|
||||
pillar data, only need to refresh the minion's pillar data, for example by using
|
||||
``saltutil.refresh_pillar``. Schedules implemented in the master or minion config
|
||||
have to restart the application in order for the schedule to be implemented.
|
||||
|
||||
.. note::
|
||||
|
||||
The scheduler executes different functions on the master and minions. When
|
||||
running on the master the functions reference runner functions, when
|
||||
running on the minion the functions specify execution functions.
|
||||
|
||||
A scheduled run has no output on the minion unless the config is set to info level
|
||||
or higher. Refer to :doc:`minion logging settings</ref/configuration/minion>`.
|
||||
|
||||
Specify ``maxrunning`` to ensure that there are no more than N copies of
|
||||
a particular routine running. Use this for jobs that may be long-running
|
||||
and could step on each other or otherwise double execute. The default for
|
||||
``maxrunning`` is 1.
|
||||
|
||||
States are executed on the minion, as all states are. You can pass positional
|
||||
arguments and provide a yaml dict of named arguments.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
seconds: 3600
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
|
||||
This will schedule the command: state.sls httpd test=True every 3600 seconds
|
||||
(every hour)
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
seconds: 3600
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
splay: 15
|
||||
|
||||
This will schedule the command: state.sls httpd test=True every 3600 seconds
|
||||
(every hour) splaying the time between 0 and 15 seconds
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
seconds: 3600
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
splay:
|
||||
start: 10
|
||||
end: 15
|
||||
|
||||
This will schedule the command: state.sls httpd test=True every 3600 seconds
|
||||
(every hour) splaying the time between 10 and 15 seconds
|
||||
|
||||
.. versionadded:: 2014.7.0
|
||||
|
||||
Frequency of jobs can also be specified using date strings supported by
|
||||
the python dateutil library. This requires python-dateutil to be installed on
|
||||
the minion.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
when: 5:00pm
|
||||
|
||||
This will schedule the command: state.sls httpd test=True at 5:00pm minion
|
||||
localtime.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
when:
|
||||
- Monday 5:00pm
|
||||
- Tuesday 3:00pm
|
||||
- Wednesday 5:00pm
|
||||
- Thursday 3:00pm
|
||||
- Friday 5:00pm
|
||||
|
||||
This will schedule the command: state.sls httpd test=True at 5pm on Monday,
|
||||
Wednesday, and Friday, and 3pm on Tuesday and Thursday.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: state.sls
|
||||
seconds: 3600
|
||||
args:
|
||||
- httpd
|
||||
kwargs:
|
||||
test: True
|
||||
range:
|
||||
start: 8:00am
|
||||
end: 5:00pm
|
||||
|
||||
This will schedule the command: state.sls httpd test=True every 3600 seconds
|
||||
(every hour) between the hours of 8am and 5pm. The range parameter must be a
|
||||
dictionary with the date strings using the dateutil format. This requires
|
||||
python-dateutil to be installed on the minion.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
job1:
|
||||
function: pkg.install
|
||||
kwargs:
|
||||
pkgs: [{'bar': '>1.2.3'}]
|
||||
refresh: true
|
||||
once: '2016-01-07T14:30:00'
|
||||
|
||||
This will schedule the command pkg.install to be executed once at the specified
|
||||
time. The schedule entry ``job1`` will not be removed after the job completes,
|
||||
therefore use ``schedule.delete`` to manually remove it afterwards.
|
||||
|
||||
The default date format is ISO 8601 but can be overridden by also specifying the
|
||||
``once_fmt`` option.
|
||||
|
||||
.. versionadded:: 2014.7.0
|
||||
|
||||
The scheduler also supports ensuring that there are no more than N copies of
|
||||
a particular routine running. Use this for jobs that may be long-running
|
||||
and could step on each other or pile up in case of infrastructure outage.
|
||||
|
||||
The default for maxrunning is 1.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
long_running_job:
|
||||
function: big_file_transfer
|
||||
jid_include: True
|
||||
|
||||
States
|
||||
======
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
log-loadavg:
|
||||
function: cmd.run
|
||||
seconds: 3660
|
||||
args:
|
||||
- 'logger -t salt < /proc/loadavg'
|
||||
kwargs:
|
||||
stateful: False
|
||||
shell: /bin/sh
|
||||
|
||||
Highstates
|
||||
==========
|
||||
|
||||
To set up a highstate to run on a minion every 60 minutes set this in the
|
||||
minion config or pillar:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
highstate:
|
||||
function: state.highstate
|
||||
minutes: 60
|
||||
|
||||
Time intervals can be specified as seconds, minutes, hours, or days.
|
||||
|
||||
Runners
|
||||
=======
|
||||
|
||||
Runner executions can also be specified on the master within the master
|
||||
configuration file:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
run_my_orch:
|
||||
function: state.orchestrate
|
||||
hours: 6
|
||||
splay: 600
|
||||
args:
|
||||
- orchestration.my_orch
|
||||
|
||||
The above configuration is analogous to running
|
||||
``salt-run state.orch orchestration.my_orch`` every 6 hours.
|
||||
|
||||
Scheduler With Returner
|
||||
=======================
|
||||
|
||||
The scheduler is also useful for tasks like gathering monitoring data about
|
||||
a minion, this schedule option will gather status data and send it to a MySQL
|
||||
returner database:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
schedule:
|
||||
uptime:
|
||||
function: status.uptime
|
||||
seconds: 60
|
||||
returner: mysql
|
||||
meminfo:
|
||||
function: status.meminfo
|
||||
minutes: 5
|
||||
returner: mysql
|
||||
|
||||
Since specifying the returner repeatedly can be tiresome, the
|
||||
``schedule_returner`` option is available to specify one or a list of global
|
||||
returners to be used by the minions when scheduling.
|
||||
|
|
@ -4,10 +4,6 @@
|
|||
``netapi`` modules
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
|
||||
writing
|
||||
|
||||
Introduction to netapi modules
|
||||
==============================
|
||||
|
||||
|
|
@ -43,3 +39,8 @@ own internals work!)
|
|||
|
||||
.. autoclass:: salt.netapi.NetapiClient
|
||||
:members: local, local_async, local_batch, local_subset, runner, wheel
|
||||
|
||||
.. toctree::
|
||||
|
||||
../tutorials/http
|
||||
writing
|
||||
|
|
|
|||
6
doc/topics/orchestrate/index.rst
Normal file
6
doc/topics/orchestrate/index.rst
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
=============
|
||||
Orchestration
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
orchestrate_runner
|
||||
175
doc/topics/orchestrate/orchestrate_runner.rst
Normal file
175
doc/topics/orchestrate/orchestrate_runner.rst
Normal file
|
|
@ -0,0 +1,175 @@
|
|||
.. _orchestrate-runner:
|
||||
|
||||
==================
|
||||
Orchestrate Runner
|
||||
==================
|
||||
|
||||
Orchestration is accomplished in salt primarily through the :ref:`Orchestrate
|
||||
Runner <orchestrate-runner>`. Added in version 0.17.0, this Salt :doc:`Runner
|
||||
</ref/runners/index>` can use the full suite of :doc:`requisites
|
||||
</ref/states/requisites>` available in states, and can also execute
|
||||
states/functions using salt-ssh.
|
||||
|
||||
The Orchestrate Runner
|
||||
----------------------
|
||||
|
||||
.. versionadded:: 0.17.0
|
||||
|
||||
.. note:: Orchestrate Deprecates OverState
|
||||
|
||||
The Orchestrate Runner (originally called the state.sls runner) offers all
|
||||
the functionality of the OverState, but with some advantages:
|
||||
|
||||
* All :doc:`requisites </ref/states/requisites>` available in states can be
|
||||
used.
|
||||
* The states/functions will also work on salt-ssh minions.
|
||||
|
||||
The Orchestrate Runner was added with the intent to eventually deprecate the
|
||||
OverState system, however the OverState will still be maintained until Salt
|
||||
Boron.
|
||||
|
||||
The orchestrate runner generalizes the Salt state system to a Salt master
|
||||
context. Whereas the ``state.sls``, ``state.highstate``, et al functions are
|
||||
concurrently and independently executed on each Salt minion, the
|
||||
``state.orchestrate`` runner is executed on the master, giving it a
|
||||
master-level view and control over requisites, such as state ordering and
|
||||
conditionals. This allows for inter minion requisites, like ordering the
|
||||
application of states on different minions that must not happen simultaneously,
|
||||
or for halting the state run on all minions if a minion fails one of its
|
||||
states.
|
||||
|
||||
If you want to setup a load balancer in front of a cluster of web servers, for
|
||||
example, you can ensure the load balancer is setup before the web servers or
|
||||
stop the state run altogether if one of the minions does not set up correctly.
|
||||
|
||||
The ``state.sls``, ``state.highstate``, et al functions allow you to statefully
|
||||
manage each minion and the ``state.orchestrate`` runner allows you to
|
||||
statefully manage your entire infrastructure.
|
||||
|
||||
Executing the Orchestrate Runner
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Orchestrate Runner command format is the same as for the ``state.sls``
|
||||
function, except that since it is a runner, it is executed with ``salt-run``
|
||||
rather than ``salt``. Assuming you have a state.sls file called
|
||||
``/srv/salt/orch/webserver.sls`` the following command run on the master will
|
||||
apply the states defined in that file.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orch.webserver
|
||||
|
||||
.. note::
|
||||
|
||||
``state.orch`` is a synonym for ``state.orchestrate``
|
||||
|
||||
.. versionchanged:: 2014.1.1
|
||||
|
||||
The runner function was renamed to ``state.orchestrate`` to avoid confusion
|
||||
with the :mod:`state.sls <salt.modules.state.sls>` execution function. In
|
||||
versions 0.17.0 through 2014.1.0, ``state.sls`` must be used.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
|
||||
Function
|
||||
^^^^^^^^
|
||||
|
||||
To execute a function, use :mod:`salt.function <salt.states.saltmod.function>`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# /srv/salt/orch/cleanfoo.sls
|
||||
cmd.run:
|
||||
salt.function:
|
||||
- tgt: '*'
|
||||
- arg:
|
||||
- rm -rf /tmp/foo
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orch.cleanfoo
|
||||
|
||||
State
|
||||
^^^^^
|
||||
|
||||
To execute a state, use :mod:`salt.state <salt.states.saltmod.state>`.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# /srv/salt/orch/webserver.sls
|
||||
install_nginx:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- sls:
|
||||
- nginx
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orch.webserver
|
||||
|
||||
Highstate
|
||||
^^^^^^^^^
|
||||
|
||||
To run a highstate, set ``highstate: True`` in your state config:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# /srv/salt/orch/web_setup.sls
|
||||
webserver_setup:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- highstate: True
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orch.web_setup
|
||||
|
||||
|
||||
More Complex Orchestration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Many states/functions can be configured in a single file, which when combined
|
||||
with the full suite of :doc:`requisites </ref/states/requisites>`, can be used
|
||||
to easily configure complex orchestration tasks. Additionally, the
|
||||
states/functions will be executed in the order in which they are defined,
|
||||
unless prevented from doing so by any :doc:`requisites
|
||||
</ref/states/requisites>`, as is the default in SLS files since 0.17.0.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
cmd.run:
|
||||
salt.function:
|
||||
- tgt: 10.0.0.0/24
|
||||
- tgt_type: ipcidr
|
||||
- arg:
|
||||
- bootstrap
|
||||
|
||||
storage_setup:
|
||||
salt.state:
|
||||
- tgt: 'role:storage'
|
||||
- tgt_type: grain
|
||||
- sls: ceph
|
||||
- require:
|
||||
- salt: webserver_setup
|
||||
|
||||
webserver_setup:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- highstate: True
|
||||
|
||||
Given the above setup, the orchestration will be carried out as follows:
|
||||
|
||||
1. The shell command ``bootstrap`` will be executed on all minions in the
|
||||
10.0.0.0/24 subnet.
|
||||
|
||||
2. A Highstate will be run on all minions whose ID starts with "web", since
|
||||
the ``storage_setup`` state requires it.
|
||||
|
||||
3. Finally, the ``ceph`` SLS target will be executed on all minions which have
|
||||
a grain called ``role`` with a value of ``storage``.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Remember, salt-run is always executed on the master.
|
||||
|
|
@ -411,3 +411,6 @@ protected data set ``pillar_safe_render_error`` to ``False``:
|
|||
.. code-block:: yaml
|
||||
|
||||
pillar_safe_render_error: False
|
||||
|
||||
.. toctree::
|
||||
../tutorials/pillar
|
||||
|
|
|
|||
|
|
@ -725,5 +725,8 @@ For more information please refer to class `SSHConnection`_.
|
|||
:glob:
|
||||
|
||||
ssh
|
||||
beacon
|
||||
state
|
||||
../tutorials/esxi_proxy_minion
|
||||
|
||||
.. _SSHConnection: https://github.com/saltstack/salt/blob/b8271c7512da7e048019ee26422be9e7d6b795ab/salt/utils/vt_helper.py#L28
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
=============
|
||||
Release notes
|
||||
Release Notes
|
||||
=============
|
||||
|
||||
See the :doc:`version numbers</topics/releases/version_numbers>` page for more
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
:orphan:
|
||||
|
||||
=============
|
||||
Release notes
|
||||
=============
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
.. _spm_development:
|
||||
.. _spm-development:
|
||||
|
||||
=====================
|
||||
SPM Development Guide
|
||||
|
|
@ -132,7 +132,7 @@ The arguments that are passed in, in order, are ``name`` (required), ``pkg``
|
|||
|
||||
``name`` is the path of the file, as it was installed on the filesystem.
|
||||
|
||||
``pkg`` is the name of the package that the file belongs to.
|
||||
``pkg`` is the name of the package that the file belongs to.
|
||||
|
||||
``conn`` is the connection object returned from ``init()``.
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Salt SSH
|
|||
Getting Started
|
||||
===============
|
||||
|
||||
Salt SSH is very easy to use, simply set up a basic `roster` file of the
|
||||
Salt SSH is very easy to use, simply set up a basic :ref:`roster <ssh-roster>` file of the
|
||||
systems to connect to and run ``salt-ssh`` commands in a similar way as
|
||||
standard ``salt`` commands.
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ Salt SSH Roster
|
|||
The roster system in Salt allows for remote minions to be easily defined.
|
||||
|
||||
.. note::
|
||||
See the :doc:`Roster documentation </topics/ssh/roster>` for more details.
|
||||
See the :ref:`SSH roster docs <ssh-roster>` for more details.
|
||||
|
||||
Simply create the roster file, the default location is `/etc/salt/roster`:
|
||||
|
||||
|
|
@ -142,7 +142,7 @@ systems still need to be implemented.
|
|||
|
||||
.. note::
|
||||
By default, Grains are settable through ``salt-ssh``. By
|
||||
default, these grains will *not* be persisted across reboots.
|
||||
default, these grains will *not* be persisted across reboots.
|
||||
|
||||
See the "thin_dir" setting in :doc:`Roster documentation </topics/ssh/roster>`
|
||||
for more details.
|
||||
|
|
@ -220,3 +220,7 @@ command that ``salt-ssh`` attempted to execute.
|
|||
|
||||
It is recommended that one modify this command a bit by removing the ``-l quiet``,
|
||||
``--metadata`` and ``--output json`` to get a better idea of what's going on on the target system.
|
||||
|
||||
.. toctree::
|
||||
|
||||
roster
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _ssh-roster:
|
||||
|
||||
============
|
||||
Salt Rosters
|
||||
============
|
||||
|
|
|
|||
64
doc/topics/states/index.rst
Normal file
64
doc/topics/states/index.rst
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
.. _configuration-management:
|
||||
|
||||
========================
|
||||
Configuration Management
|
||||
========================
|
||||
|
||||
Salt contains a robust and flexible configuration management framework, which
|
||||
is built on the remote execution core. This framework executes on the minions,
|
||||
allowing effortless, simultaneous configuration of tens of thousands of hosts,
|
||||
by rendering language specific state files. The following links provide
|
||||
resources to learn more about state and renderers.
|
||||
|
||||
**States**
|
||||
Express the state of a host using small, easy to read, easy to
|
||||
understand configuration files. *No programming required*.
|
||||
|
||||
:ref:`Full list of states <all-salt.states>`
|
||||
Contains: list of install packages, create users, transfer files, start
|
||||
services, and so on.
|
||||
|
||||
:doc:`Pillar System <../pillar/index>`
|
||||
Contains: description of Salt's Pillar system.
|
||||
|
||||
:doc:`Highstate data structure <../../ref/states/highstate>`
|
||||
Contains: a dry vocabulary and technical representation of the
|
||||
configuration format that states represent.
|
||||
|
||||
:doc:`Writing states <../../ref/states/writing>`
|
||||
Contains: a guide on how to write Salt state modules, easily extending
|
||||
Salt to directly manage more software.
|
||||
|
||||
.. note::
|
||||
|
||||
Salt execution modules are different from state modules and cannot be
|
||||
called directly within state files. You must use the :mod:`module <salt.states.module>`
|
||||
state module to call execution modules within state runs.
|
||||
|
||||
**Renderers**
|
||||
Renderers use state configuration files written in a variety of languages,
|
||||
templating engines, or files. Salt's configuration management system is,
|
||||
under the hood, language agnostic.
|
||||
|
||||
:doc:`Full list of renderers <../../ref/renderers/all/index>`
|
||||
Contains: a list of renderers.
|
||||
YAML is one choice, but many systems are available, from
|
||||
alternative templating engines to the PyDSL language for rendering
|
||||
sls formulas.
|
||||
|
||||
:doc:`Renderers <../../ref/renderers/index>`
|
||||
Contains: more information about renderers. Salt states are only
|
||||
concerned with the ultimate highstate data structure, not how the
|
||||
data structure was created.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
../tutorials/starting_states
|
||||
../tutorials/states_pt1
|
||||
../tutorials/states_pt2
|
||||
../tutorials/states_pt3
|
||||
../tutorials/states_pt4
|
||||
../../ref/states/index
|
||||
|
||||
|
|
@ -1,32 +1,12 @@
|
|||
.. _targeting-grains:
|
||||
|
||||
======
|
||||
Grains
|
||||
======
|
||||
======================
|
||||
Targeting using Grains
|
||||
======================
|
||||
|
||||
Salt comes with an interface to derive information about the underlying system.
|
||||
This is called the grains interface, because it presents salt with grains of
|
||||
information. Grains are collected for the operating system, domain name,
|
||||
IP address, kernel, OS type, memory, and many other system properties.
|
||||
Grain data can be used when targeting minions.
|
||||
|
||||
The grains interface is made available to Salt modules and components so that
|
||||
the right salt minion commands are automatically available on the right
|
||||
systems.
|
||||
|
||||
Grain data is relatively static, though if system information changes
|
||||
(for example, if network settings are changed), or if a new value is assigned
|
||||
to a custom grain, grain data is refreshed.
|
||||
|
||||
.. note::
|
||||
|
||||
Grains resolve to lowercase letters. For example, ``FOO``, and ``foo``
|
||||
target the same grain.
|
||||
|
||||
.. important::
|
||||
See :ref:`Is Targeting using Grain Data Secure? <faq-grain-security>` for
|
||||
important security information.
|
||||
|
||||
Match all CentOS minions:
|
||||
For example, the following matches all CentOS minions:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -50,252 +30,6 @@ has a value that contains the word ``production``:
|
|||
|
||||
salt -G 'ec2_tags:environment:*production*'
|
||||
|
||||
|
||||
Listing Grains
|
||||
==============
|
||||
|
||||
Available grains can be listed by using the 'grains.ls' module:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' grains.ls
|
||||
|
||||
Grains data can be listed by using the 'grains.items' module:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' grains.items
|
||||
|
||||
|
||||
.. _static-custom-grains:
|
||||
|
||||
Grains in the Minion Config
|
||||
===========================
|
||||
|
||||
Grains can also be statically assigned within the minion configuration file.
|
||||
Just add the option ``grains`` and pass options to it:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
grains:
|
||||
roles:
|
||||
- webserver
|
||||
- memcache
|
||||
deployment: datacenter4
|
||||
cabinet: 13
|
||||
cab_u: 14-15
|
||||
|
||||
Then status data specific to your servers can be retrieved via Salt, or used
|
||||
inside of the State system for matching. It also makes targeting, in the case
|
||||
of the example above, simply based on specific data about your deployment.
|
||||
|
||||
|
||||
Grains in /etc/salt/grains
|
||||
==========================
|
||||
|
||||
If you do not want to place your custom static grains in the minion config
|
||||
file, you can also put them in ``/etc/salt/grains`` on the minion. They are configured in the
|
||||
same way as in the above example, only without a top-level ``grains:`` key:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
roles:
|
||||
- webserver
|
||||
- memcache
|
||||
deployment: datacenter4
|
||||
cabinet: 13
|
||||
cab_u: 14-15
|
||||
|
||||
|
||||
Matching Grains in the Top File
|
||||
===============================
|
||||
|
||||
With correctly configured grains on the Minion, the :term:`top file` used in
|
||||
Pillar or during Highstate can be made very efficient. For example, consider
|
||||
the following configuration:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
'node_type:web':
|
||||
- match: grain
|
||||
- webserver
|
||||
|
||||
'node_type:postgres':
|
||||
- match: grain
|
||||
- database
|
||||
|
||||
'node_type:redis':
|
||||
- match: grain
|
||||
- redis
|
||||
|
||||
'node_type:lb':
|
||||
- match: grain
|
||||
- lb
|
||||
|
||||
For this example to work, you would need to have defined the grain
|
||||
``node_type`` for the minions you wish to match. This simple example is nice,
|
||||
but too much of the code is similar. To go one step further, Jinja templating
|
||||
can be used to simplify the :term:`top file`.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
{% set the_node_type = salt['grains.get']('node_type', '') %}
|
||||
|
||||
{% if the_node_type %}
|
||||
'node_type:{{ the_node_type }}':
|
||||
- match: grain
|
||||
- {{ the_node_type }}
|
||||
{% endif %}
|
||||
|
||||
Using Jinja templating, only one match entry needs to be defined.
|
||||
|
||||
.. note::
|
||||
|
||||
The example above uses the :mod:`grains.get <salt.modules.grains.get>`
|
||||
function to account for minions which do not have the ``node_type`` grain
|
||||
set.
|
||||
|
||||
.. _writing-grains:
|
||||
|
||||
Writing Grains
|
||||
==============
|
||||
|
||||
The grains interface is derived by executing
|
||||
all of the "public" functions found in the modules located in the grains
|
||||
package or the custom grains directory. The functions in the modules of
|
||||
the grains must return a Python :ref:`dict <python2:typesmapping>`, where the
|
||||
keys in the :ref:`dict <python2:typesmapping>` are the names of the grains and
|
||||
the values are the values.
|
||||
|
||||
Custom grains should be placed in a ``_grains`` directory located under the
|
||||
:conf_master:`file_roots` specified by the master config file. The default path
|
||||
would be ``/srv/salt/_grains``. Custom grains will be
|
||||
distributed to the minions when :mod:`state.highstate
|
||||
<salt.modules.state.highstate>` is run, or by executing the
|
||||
:mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
|
||||
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
|
||||
|
||||
Grains are easy to write, and only need to return a dictionary. A common
|
||||
approach would be code something similar to the following:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
def yourfunction():
|
||||
# initialize a grains dictionary
|
||||
grains = {}
|
||||
# Some code for logic that sets grains like
|
||||
grains['yourcustomgrain'] = True
|
||||
grains['anothergrain'] = 'somevalue'
|
||||
return grains
|
||||
|
||||
Before adding a grain to Salt, consider what the grain is and remember that
|
||||
grains need to be static data. If the data is something that is likely to
|
||||
change, consider using :doc:`Pillar <../pillar/index>` instead.
|
||||
|
||||
.. warning::
|
||||
|
||||
Custom grains will not be available in the top file until after the first
|
||||
:ref:`highstate <running-highstate>`. To make custom grains available on a
|
||||
minion's first highstate, it is recommended to use :ref:`this example
|
||||
<minion-start-reactor>` to ensure that the custom grains are synced when
|
||||
the minion starts.
|
||||
|
||||
Loading Custom Grains
|
||||
---------------------
|
||||
|
||||
If you have multiple functions specifying grains that are called from a ``main``
|
||||
function, be sure to prepend grain function names with an underscore. This prevents
|
||||
Salt from including the loaded grains from the grain functions in the final
|
||||
grain data structure. For example, consider this custom grain file:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
#!/usr/bin/env python
|
||||
def _my_custom_grain():
|
||||
my_grain = {'foo': 'bar', 'hello': 'world'}
|
||||
return my_grain
|
||||
|
||||
|
||||
def main():
|
||||
# initialize a grains dictionary
|
||||
grains = {}
|
||||
grains['my_grains'] = _my_custom_grain()
|
||||
return grains
|
||||
|
||||
The output of this example renders like so:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# salt-call --local grains.items
|
||||
local:
|
||||
----------
|
||||
<Snipped for brevity>
|
||||
my_grains:
|
||||
----------
|
||||
foo:
|
||||
bar
|
||||
hello:
|
||||
world
|
||||
|
||||
However, if you don't prepend the ``my_custom_grain`` function with an underscore,
|
||||
the function will be rendered twice by Salt in the items output: once for the
|
||||
``my_custom_grain`` call itself, and again when it is called in the ``main``
|
||||
function:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# salt-call --local grains.items
|
||||
local:
|
||||
----------
|
||||
<Snipped for brevity>
|
||||
foo:
|
||||
bar
|
||||
<Snipped for brevity>
|
||||
hello:
|
||||
world
|
||||
<Snipped for brevity>
|
||||
my_grains:
|
||||
----------
|
||||
foo:
|
||||
bar
|
||||
hello:
|
||||
world
|
||||
|
||||
|
||||
Precedence
|
||||
==========
|
||||
|
||||
Core grains can be overridden by custom grains. As there are several ways of
|
||||
defining custom grains, there is an order of precedence which should be kept in
|
||||
mind when defining them. The order of evaluation is as follows:
|
||||
|
||||
1. Core grains.
|
||||
2. Custom grains in ``/etc/salt/grains``.
|
||||
3. Custom grains in ``/etc/salt/minion``.
|
||||
4. Custom grain modules in ``_grains`` directory, synced to minions.
|
||||
|
||||
Each successive evaluation overrides the previous ones, so any grains defined
|
||||
by custom grains modules synced to minions that have the same name as a core
|
||||
grain will override that core grain. Similarly, grains from
|
||||
``/etc/salt/minion`` override both core grains and custom grain modules, and
|
||||
grains in ``_grains`` will override *any* grains of the same name.
|
||||
|
||||
|
||||
Examples of Grains
|
||||
==================
|
||||
|
||||
The core module in the grains package is where the main grains are loaded by
|
||||
the Salt minion and provides the principal example of how to write grains:
|
||||
|
||||
:blob:`salt/grains/core.py`
|
||||
|
||||
|
||||
Syncing Grains
|
||||
==============
|
||||
|
||||
Syncing grains can be done a number of ways, they are automatically synced when
|
||||
:mod:`state.highstate <salt.modules.state.highstate>` is called, or (as noted
|
||||
above) the grains can be manually synced and reloaded by calling the
|
||||
:mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
|
||||
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
|
||||
.. important::
|
||||
See :ref:`Is Targeting using Grain Data Secure? <faq-grain-security>` for
|
||||
important security information.
|
||||
|
|
|
|||
|
|
@ -21,6 +21,92 @@ the ``web1`` minion should execute the contents of ``webserver.sls``:
|
|||
'web1':
|
||||
- webserver
|
||||
|
||||
The simple target specifications, glob, regex, and list will cover many use
|
||||
cases, and for some will cover all use cases, but more powerful options exist.
|
||||
|
||||
Targeting with Grains
|
||||
=====================
|
||||
|
||||
The Grains interface was built into Salt to allow minions to be targeted by
|
||||
system properties. So minions running on a particular operating system can
|
||||
be called to execute a function, or a specific kernel.
|
||||
|
||||
Calling via a grain is done by passing the -G option to salt, specifying
|
||||
a grain and a glob expression to match the value of the grain. The syntax for
|
||||
the target is the grain key followed by a globexpression: "os:Arch*".
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt -G 'os:Fedora' test.ping
|
||||
|
||||
Will return True from all of the minions running Fedora.
|
||||
|
||||
To discover what grains are available and what the values are, execute the
|
||||
grains.item salt function:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' grains.items
|
||||
|
||||
more info on using targeting with grains can be found :ref:`here
|
||||
<targeting-grains>`.
|
||||
|
||||
Targeting with Executions
|
||||
=========================
|
||||
|
||||
As of 0.8.8 targeting with executions is still under heavy development and this
|
||||
documentation is written to reference the behavior of execution matching in the
|
||||
future.
|
||||
|
||||
Execution matching allows for a primary function to be executed, and then based
|
||||
on the return of the primary function the main function is executed.
|
||||
|
||||
Execution matching allows for matching minions based on any arbitrary running
|
||||
data on the minions.
|
||||
|
||||
Compound Targeting
|
||||
==================
|
||||
|
||||
.. versionadded:: 0.9.5
|
||||
|
||||
Multiple target interfaces can be used in conjunction to determine the command
|
||||
targets. These targets can then be combined using and or or statements. This
|
||||
is well defined with an example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt -C 'G@os:Debian and webser* or E@db.*' test.ping
|
||||
|
||||
In this example any minion who's id starts with ``webser`` and is running
|
||||
Debian, or any minion who's id starts with db will be matched.
|
||||
|
||||
The type of matcher defaults to glob, but can be specified with the
|
||||
corresponding letter followed by the ``@`` symbol. In the above example a grain
|
||||
is used with ``G@`` as well as a regular expression with ``E@``. The
|
||||
``webser*`` target does not need to be prefaced with a target type specifier
|
||||
because it is a glob.
|
||||
|
||||
more info on using compound targeting can be found :ref:`here
|
||||
<targeting-compound>`.
|
||||
|
||||
Node Group Targeting
|
||||
====================
|
||||
|
||||
.. versionadded:: 0.9.5
|
||||
|
||||
For certain cases, it can be convenient to have a predefined group of minions
|
||||
on which to execute commands. This can be accomplished using what are called
|
||||
:ref:`nodegroups <targeting-nodegroups>`. Nodegroups allow for predefined
|
||||
compound targets to be declared in the master configuration file, as a sort of
|
||||
shorthand for having to type out complicated compound expressions.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
nodegroups:
|
||||
group1: 'L@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com'
|
||||
group2: 'G@os:Debian and foo.domain.com'
|
||||
group3: 'G@os:Debian and N@group1'
|
||||
|
||||
There are many ways to target individual minions or groups of minions in Salt:
|
||||
|
||||
.. toctree::
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
.. _targeting-pillar:
|
||||
|
||||
=====================
|
||||
Targeting with Pillar
|
||||
=====================
|
||||
======================
|
||||
Targeting using Pillar
|
||||
======================
|
||||
|
||||
Pillar data can be used when targeting minions. This allows for ultimate
|
||||
control and flexibility when targeting minions.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,27 @@
|
|||
.. toctree::
|
||||
.. _architecture-overview:
|
||||
|
||||
============
|
||||
Architecture
|
||||
============
|
||||
|
||||
If you are used to configuration management tools that require you to plan
|
||||
down to the last detail before you install anything, you are probably wondering
|
||||
why this section doesn't appear before the installation instructions. With
|
||||
Salt, you can switch to a high availability architecture at any time, and add
|
||||
additional components to scale your deployment as you go.
|
||||
|
||||
Since a single Salt master can manage thousands of systems, we usually
|
||||
recommend that you start by deploying a single Salt master, and then modifying
|
||||
your deployment as needed for redundancy, geographical distribution, and scale.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
../highavailability/index
|
||||
syndic
|
||||
../tutorials/intro_scale
|
||||
../tutorials/multimaster
|
||||
../tutorials/multimaster_pki
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _firewall:
|
||||
|
||||
================================
|
||||
Opening the Firewall up for Salt
|
||||
================================
|
||||
|
|
|
|||
|
|
@ -1,82 +1,35 @@
|
|||
=========
|
||||
Tutorials
|
||||
=========
|
||||
|
||||
Introduction
|
||||
============
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart
|
||||
|
||||
Basics
|
||||
======
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
standalone_minion
|
||||
firewall
|
||||
cron
|
||||
modules
|
||||
pillar
|
||||
|
||||
States
|
||||
======
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
starting_states
|
||||
states_pt1
|
||||
states_pt2
|
||||
states_pt3
|
||||
states_pt4
|
||||
states_pt5
|
||||
syslog_ng-state-usage
|
||||
|
||||
Advanced Topics
|
||||
===============
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
Tutorials Index
|
||||
===============
|
||||
|
||||
walkthrough
|
||||
rooted
|
||||
minionfs
|
||||
esky
|
||||
multimaster
|
||||
multimaster_pki
|
||||
preseed_key
|
||||
salt_bootstrap
|
||||
gitfs
|
||||
walkthrough_macosx
|
||||
writing_tests
|
||||
http
|
||||
lxc
|
||||
stormpath
|
||||
* :doc:`Salt as a Cloud Controller <cloud_controller>`
|
||||
* :doc:`Using Cron with Salt <cron>`
|
||||
* :doc:`Automatic Updates / Frozen Deployments <esky>`
|
||||
* :doc:`ESXi Proxy Minion <esxi_proxy_minion>`
|
||||
* :doc:`Opening the Firewall up for Salt <firewall>`
|
||||
* :doc:`Git Fileserver Backend Walkthrough <gitfs>`
|
||||
* :doc:`Halite <halite>`
|
||||
* :doc:`HTTP Modules <http>`
|
||||
* :doc:`Using Salt at Scale <intro_scale>`
|
||||
* :doc:`LXC Management with Salt <lxc>`
|
||||
* :doc:`MinionFS Backend Walkthrough <minionfs>`
|
||||
* :doc:`Remote Execution Tutorial <modules>`
|
||||
* :doc:`Multi-Master-PKI Tutorial With Failover <multimaster_pki>`
|
||||
* :doc:`Multi Master Tutorial <multimaster>`
|
||||
* :doc:`Pillar Walkthrough <pillar>`
|
||||
* :doc:`Preseed Minion with Accepted Key <preseed_key>`
|
||||
* :doc:`Salt Masterless Quickstart <quickstart>`
|
||||
* :doc:`running salt as normal user tutorial <rooted>`
|
||||
* :doc:`Salt Bootstrap <salt_bootstrap>`
|
||||
* :doc:`Standalone Minion <standalone_minion>`
|
||||
* :doc:`How Do I Use Salt States? <starting_states>`
|
||||
* :doc:`States tutorial, part 1 - Basic Usage <states_pt1>`
|
||||
* :doc:`States tutorial, part 2 - More Complex States, Requisites <states_pt2>`
|
||||
* :doc:`States tutorial, part 3 - Templating, Includes, Extends <states_pt3>`
|
||||
* :doc:`States tutorial, part 4 <states_pt4>`
|
||||
* :doc:`Using Salt with Stormpath <stormpath>`
|
||||
* :doc:`Syslog-ng usage <syslog_ng-state-usage>`
|
||||
* :doc:`The MacOS X (Maverick) Developer Step By Step Guide To Salt Installation <walkthrough_macosx>`
|
||||
* :doc:`SaltStack Walk-through <walkthrough>`
|
||||
* :doc:`Writing Salt Tests <writing_tests>`
|
||||
|
||||
Salt Virt
|
||||
=========
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
cloud_controller
|
||||
|
||||
LXC
|
||||
===
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
lxc
|
||||
|
||||
ESXi Proxy Minion
|
||||
=================
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
esxi_proxy_minion
|
||||
|
||||
Using Salt at scale
|
||||
===================
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
intro_scale
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
=================================
|
||||
================================
|
||||
Preseed Minion with Accepted Key
|
||||
=================================
|
||||
================================
|
||||
|
||||
In some situations, it is not convenient to wait for a minion to start before
|
||||
accepting its key on the master. For instance, you may want the minion to
|
||||
|
|
@ -65,4 +65,4 @@ You will want to place the minion keys before starting the salt-minion daemon:
|
|||
|
||||
Once in place, you should be able to start salt-minion and run
|
||||
``salt-call state.highstate`` or any other salt commands that require master
|
||||
authentication.
|
||||
authentication.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
.. _salt-bootstrap:
|
||||
|
||||
==============
|
||||
Salt Bootstrap
|
||||
==============
|
||||
|
|
|
|||
|
|
@ -1,181 +1,7 @@
|
|||
:orphan:
|
||||
|
||||
=================================================
|
||||
States Tutorial, Part 5 - Orchestration with Salt
|
||||
=================================================
|
||||
|
||||
.. note::
|
||||
|
||||
This tutorial builds on some of the topics covered in the earlier
|
||||
:doc:`States Walkthrough <states_pt1>` pages. It is recommended to start with
|
||||
:doc:`Part 1 <states_pt1>` if you are not familiar with how to use states.
|
||||
|
||||
Orchestration is accomplished in salt primarily through the :ref:`Orchestrate
|
||||
Runner <orchestrate-runner>`. Added in version 0.17.0, this Salt :doc:`Runner
|
||||
</ref/runners/index>` can use the full suite of :doc:`requisites
|
||||
</ref/states/requisites>` available in states, and can also execute
|
||||
states/functions using salt-ssh.
|
||||
|
||||
.. _orchestrate-runner:
|
||||
|
||||
The Orchestrate Runner
|
||||
----------------------
|
||||
|
||||
.. versionadded:: 0.17.0
|
||||
|
||||
.. note:: Orchestrate Deprecates OverState
|
||||
|
||||
The Orchestrate Runner (originally called the state.sls runner) offers all
|
||||
the functionality of the OverState, but with some advantages:
|
||||
|
||||
* All :doc:`requisites </ref/states/requisites>` available in states can be
|
||||
used.
|
||||
* The states/functions will also work on salt-ssh minions.
|
||||
|
||||
The Orchestrate Runner was added with the intent to eventually deprecate the
|
||||
OverState system, however the OverState will still be maintained until Salt
|
||||
Boron.
|
||||
|
||||
The orchestrate runner generalizes the Salt state system to a Salt master
|
||||
context. Whereas the ``state.sls``, ``state.highstate``, et al functions are
|
||||
concurrently and independently executed on each Salt minion, the
|
||||
``state.orchestrate`` runner is executed on the master, giving it a
|
||||
master-level view and control over requisites, such as state ordering and
|
||||
conditionals. This allows for inter minion requisites, like ordering the
|
||||
application of states on different minions that must not happen simultaneously,
|
||||
or for halting the state run on all minions if a minion fails one of its
|
||||
states.
|
||||
|
||||
If you want to setup a load balancer in front of a cluster of web servers, for
|
||||
example, you can ensure the load balancer is setup before the web servers or
|
||||
stop the state run altogether if one of the minions does not set up correctly.
|
||||
|
||||
The ``state.sls``, ``state.highstate``, et al functions allow you to statefully
|
||||
manage each minion and the ``state.orchestrate`` runner allows you to
|
||||
statefully manage your entire infrastructure.
|
||||
|
||||
Executing the Orchestrate Runner
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Orchestrate Runner command format is the same as for the ``state.sls``
|
||||
function, except that since it is a runner, it is executed with ``salt-run``
|
||||
rather than ``salt``. Assuming you have a state.sls file called
|
||||
``/srv/salt/orch/webserver.sls`` the following command run on the master will
|
||||
apply the states defined in that file.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orch.webserver
|
||||
|
||||
.. note::
|
||||
|
||||
``state.orch`` is a synonym for ``state.orchestrate``
|
||||
|
||||
.. versionchanged:: 2014.1.1
|
||||
|
||||
The runner function was renamed to ``state.orchestrate`` to avoid confusion
|
||||
with the :mod:`state.sls <salt.modules.state.sls>` execution function. In
|
||||
versions 0.17.0 through 2014.1.0, ``state.sls`` must be used.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
|
||||
Function
|
||||
^^^^^^^^
|
||||
|
||||
To execute a function, use :mod:`salt.function <salt.states.saltmod.function>`:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# /srv/salt/orch/cleanfoo.sls
|
||||
cmd.run:
|
||||
salt.function:
|
||||
- tgt: '*'
|
||||
- arg:
|
||||
- rm -rf /tmp/foo
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orch.cleanfoo
|
||||
|
||||
State
|
||||
^^^^^
|
||||
|
||||
To execute a state, use :mod:`salt.state <salt.states.saltmod.state>`.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# /srv/salt/orch/webserver.sls
|
||||
install_nginx:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- sls:
|
||||
- nginx
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orch.webserver
|
||||
|
||||
Highstate
|
||||
^^^^^^^^^
|
||||
|
||||
To run a highstate, set ``highstate: True`` in your state config:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# /srv/salt/orch/web_setup.sls
|
||||
webserver_setup:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- highstate: True
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt-run state.orchestrate orch.web_setup
|
||||
|
||||
|
||||
More Complex Orchestration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Many states/functions can be configured in a single file, which when combined
|
||||
with the full suite of :doc:`requisites </ref/states/requisites>`, can be used
|
||||
to easily configure complex orchestration tasks. Additionally, the
|
||||
states/functions will be executed in the order in which they are defined,
|
||||
unless prevented from doing so by any :doc:`requisites
|
||||
</ref/states/requisites>`, as is the default in SLS files since 0.17.0.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
cmd.run:
|
||||
salt.function:
|
||||
- tgt: 10.0.0.0/24
|
||||
- tgt_type: ipcidr
|
||||
- arg:
|
||||
- bootstrap
|
||||
|
||||
storage_setup:
|
||||
salt.state:
|
||||
- tgt: 'role:storage'
|
||||
- tgt_type: grain
|
||||
- sls: ceph
|
||||
- require:
|
||||
- salt: webserver_setup
|
||||
|
||||
webserver_setup:
|
||||
salt.state:
|
||||
- tgt: 'web*'
|
||||
- highstate: True
|
||||
|
||||
Given the above setup, the orchestration will be carried out as follows:
|
||||
|
||||
1. The shell command ``bootstrap`` will be executed on all minions in the
|
||||
10.0.0.0/24 subnet.
|
||||
|
||||
2. A Highstate will be run on all minions whose ID starts with "web", since
|
||||
the ``storage_setup`` state requires it.
|
||||
|
||||
3. Finally, the ``ceph`` SLS target will be executed on all minions which have
|
||||
a grain called ``role`` with a value of ``storage``.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Remember, salt-run is always executed on the master.
|
||||
This was moved to :ref:`Orchestrate Runner <orchestrate-runner>`.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
======================
|
||||
SaltStack Walk-through
|
||||
======================
|
||||
==================
|
||||
Salt in 10 Minutes
|
||||
==================
|
||||
|
||||
.. note::
|
||||
Welcome to SaltStack! I am excited that you are interested in Salt and
|
||||
|
|
@ -87,24 +87,13 @@ The Salt Master needs to bind to two TCP network ports on the system. These port
|
|||
are ``4505`` and ``4506``. For more in depth information on firewalling these ports,
|
||||
the firewall tutorial is available :doc:`here </topics/tutorials/firewall>`.
|
||||
|
||||
.. _master-dns:
|
||||
|
||||
Setting up a Salt Minion
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. note::
|
||||
|
||||
The Salt Minion can operate with or without a Salt Master. This walk-through
|
||||
assumes that the minion will be connected to the master, for information on
|
||||
how to run a master-less minion please see the master-less quick-start guide:
|
||||
|
||||
:doc:`Masterless Minion Quickstart </topics/tutorials/quickstart>`
|
||||
|
||||
The Salt Minion only needs to be aware of one piece of information to run, the
|
||||
network location of the master.
|
||||
|
||||
By default the minion will look for the DNS name ``salt`` for the master,
|
||||
making the easiest approach to set internal DNS to resolve the name ``salt``
|
||||
back to the Salt Master IP.
|
||||
Finding the Salt Master
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
When a minion starts, by default it searches for a system that resolves to the ``salt`` hostname`` on the network.
|
||||
If found, the minion initiates the handshake and key authentication process with the Salt master.
|
||||
This means that the easiest configuration approach is to set internal DNS to resolve the name ``salt`` back to the Salt Master IP.
|
||||
|
||||
Otherwise, the minion configuration file will need to be edited so that the
|
||||
configuration option ``master`` points to the DNS name or the IP of the Salt Master:
|
||||
|
|
@ -121,6 +110,16 @@ configuration option ``master`` points to the DNS name or the IP of the Salt Mas
|
|||
|
||||
master: saltmaster.example.com
|
||||
|
||||
Setting up a Salt Minion
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. note::
|
||||
|
||||
The Salt Minion can operate with or without a Salt Master. This walk-through
|
||||
assumes that the minion will be connected to the master, for information on
|
||||
how to run a master-less minion please see the master-less quick-start guide:
|
||||
|
||||
:doc:`Masterless Minion Quickstart </topics/tutorials/quickstart>`
|
||||
|
||||
Now that the master can be found, start the minion in the same way as the
|
||||
master; with the platform init system or via the command line directly:
|
||||
|
||||
|
|
@ -167,6 +166,7 @@ Now that the minion is started, it will generate cryptographic keys and attempt
|
|||
to connect to the master. The next step is to venture back to the master server
|
||||
and accept the new minion's public key.
|
||||
|
||||
.. _using-salt-key:
|
||||
|
||||
Using salt-key
|
||||
~~~~~~~~~~~~~~
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
========================================================================
|
||||
The MacOS X (Maverick) Developer Step By Step Guide To Salt Installation
|
||||
========================================================================
|
||||
|
||||
|
|
|
|||
19
doc/topics/using_salt.rst
Normal file
19
doc/topics/using_salt.rst
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
==========
|
||||
Using Salt
|
||||
==========
|
||||
|
||||
This section describes the fundamental components and concepts that you need to understand to use Salt.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
grains/index
|
||||
pillar/index
|
||||
targeting/index
|
||||
mine/index
|
||||
../ref/runners/index
|
||||
engines/index
|
||||
yaml/index
|
||||
troubleshooting/index
|
||||
../faq
|
||||
best_practices
|
||||
|
|
@ -62,3 +62,4 @@ Deploy from Network or Disk
|
|||
.. toctree::
|
||||
disk
|
||||
nic
|
||||
../tutorials/cloud_controller
|
||||
|
|
|
|||
|
|
@ -1,3 +1,10 @@
|
|||
=======
|
||||
Windows
|
||||
=======
|
||||
|
||||
This section contains details on the Windows Package Manager, and specific information you need
|
||||
to use Salt on Windows.
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue