saltstack手册（含官方pdf）

官方手册

https://docs.saltstack.com/en/pdf/Salt-2019.2.1.pdf

快速入门

SALTSTACK是什么？

Salt是一种和以往不同的基础设施管理方法，它是建立在大规模系统高速通讯能力可以大幅提升的想法上。这种方法使得Salt成为一个强大的能够解决基础设施中许多特定问题的多任务系统。远程执行引擎是Salt的核心，它能够为多组系统创建高速、安全的双向通讯网络。基于这个通许系统，Salt提供了一个非常快速、灵活并且容易使用的配置管理系统，称之为“Salt States”。

The backbone of Salt is the remote execution engine, which creates a high-speed, secure and bi-directional communication net for groups of systems. On top of this communication system, Salt provides an extremely fast, flexible, and easy-to-use configuration management system called Salt States.

安装SALT

SaltStack has been made to be very easy to install and get started. The installation documents contain instructions for all supported platforms.

SALT入门

Salt functions on a master/minion topology. A master server acts as a central control bus for the clients, which are called minions. The minions connect back to the master.

设置SALT MASTER

运行Salt Master很容易，就是执行它！默认配置适用于大多数不同安装。Salt Master能够由Linux/Unix本地服务管理器控制。

On Systemd based platforms (newer Debian, OpenSuse, Fedora):

systemctl start salt-master

在基于Upstart的系统上(Ubuntu, Older Fedora/RHEL):

service salt-master start

On SysV Init systems (Gentoo, older Debian etc.):

/etc/init.d/salt-master start

另一种方式，Master可以直接在命令行启动:

salt-master -d

Salt Master也能够在前台以debug模式启动，这样会极大增加命令输出:

salt-master -l debug

Salt Master需要绑定系统上2个TCP端口，分别是4505和4506。更多这些端口更深入的关于防火墙信息，参见防火墙教程。here.

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.

否则，需要编辑minion配置文件配置 master 选项指向Salt Master的DNS名或IP:

注解

默认配置文件路径位于/etc/salt下。大多数平台会遵守这个约定，但是像FreeBSD和Microsoft Windows这样的平台会将这个文件放在不同的路径。

/etc/salt/minion:

master: saltmaster.example.com

设置SALT MINION

注解

Salt Minion有无Salt Master时都可以运作。本演练将假定minion可以连接到master，想了解如何运行一个无master的minion的资料请参考master-less quick-start guide:

Masterless Minion 快速入门

现在已经能够找到master了，同master一样以相同方式启动minion；使用平台init系统或者直接通过命令行。

以daemon模式运行

salt-minion -d

在前台以debug模式运行

salt-minion -l debug

当minion启动后，它会产生一个 id 值，除非已经在之前的运行过程中产生过并且缓存在配置路径下，默认是 /etc/salt 。minion用这个值作为名称尝试去master进行验证。尝试下面几步操作，以便找到一个不是 localhost 的值:

1. 运行Python函数"socket.getfqdn()"
2. 核对"/etc/hostname"(仅针对非Windows系统)
3. 核对"/etc/hosts"(在Windows主机上是"%WINDIR%system32driversetchosts") 上的包括"127.0.0.0/8"在内的所有主机名。

如果以上都不能产生除"localhost"以外的id，那么就会按顺序检测minion上的IP地址列表(排除"127.0.0.0/8"在内)。如果存在，就会使用第一个公网路由IP地址，否则就会使用第一个私网路由IP地址。

如果所有这些都失败了，那么就会使用"localhost"作为备选。

注解

覆盖"id"值

minion的id也可以通过minion配置文件中 :conf_minion:`id`选项手动指定。如果指定这个配置值，它会覆盖所有其他来源的"id"值。

现在minion已经运行了，它会产生秘钥对并且尝试连接master。下一步就是折回master服务器接受新minion的公钥。

使用SALT-KEY

Salt通过公钥加密和认证minions。想要让minion从master端接受命令，minions的密钥需要被master接受。

salt-key 命令时用来管理master上所有的密钥的。列出master上的密钥:

salt-key -L

The keys that have been rejected, accepted, and pending acceptance are listed. The easiest way to accept the minion key is to accept all pending keys:

salt-key -A

注解

Keys should be verified! Print the master key fingerprint by running salt-key -F master on the Salt master. Copy the master.pub fingerprint from the Local Keys section, and then set this value as the master_finger in the minion configuration file. Restart the Salt minion.

On the master, run salt-key -f minion-id to print the fingerprint of the minion's public key that was received by the master. On the minion, run salt-call key.finger --local to print the fingerprint of the minion key.

On the master:

# salt-key -f foo.domain.com
Unaccepted Keys:
foo.domain.com:  39:f9:e4:8a:aa:74:8d:52:1a:ec:92:03:82:09:c8:f9

On the minion:

# salt-call key.finger --local
local:
    39:f9:e4:8a:aa:74:8d:52:1a:ec:92:03:82:09:c8:f9

If they match, approve the key with salt-key -a foo.domain.com.

发送第一个命令

现在minion已经连接到master并且通过认证，master可以发送命令到minion。

Salt命令允许执行海量的函数库，并且可以针对特殊的minions和minions组为目标执行。

salt 命令包含命令选项，目标说明，要执行的函数，和函数的参数。

一个简单的入门级命令看起来像是这样:

salt '*' test.ping

* 是指向所有minions的目标。

test.ping 告诉minon运行 test.ping 函数。

In the case of test.ping, test refers to a execution module. ping refers to the ping function contained in the aforementioned test module.

注解

Execution modules are the workhorses of Salt. They do the work on the system to perform various tasks, such as manipulating files and restarting services.

运行这条命令的结果将会是master指示所有的minions并行执行 test.ping 并返回结果。

这不是真正的ICMP ping，而是一个简单的函数返回 True。使用 test.ping 是确认一个minion是否连接正常的好方法。

注解

每个minion使用唯一的minion ID注册自身，但是也能够通过使用minion配置中的 id 选项来明确定义。

Of course, there are hundreds of other modules that can be called just as test.ping can. For example, the following would return disk usage on all targeted minions:

salt '*' disk.usage

函数概况

Salt拥有一个巨大的函数库可用于执行，而且Salt函数是自带文档说明的。在minions上执行 sys.doc 函数可以查看哪些函数可用：

salt '*' sys.doc

这会显示一个非常大的可用函数和函数文档列表。

注解

模块文档也可以 在线 查看。

这些函数覆盖从shell命令到包管理到数据库服务器操作等所有内容。它们包含强大的系统管理API，而这则是Salt配置管理和很多其他部分的核心。

注解

Salt拥有很多插件系统。这些函数通过文档:`执行模块 </ref/modules/all/index>`的"salt"命令可用。

了解一些有帮助的函数

文档`cmd </ref/modules/all/salt.modules.cmdmod>`模块包含在minions上执行shell命令的函数，比如模块`cmd.run <salt.modules.cmdmod.run>`和模块`cmd.run_all <salt.modules.cmdmod.run_all>`：

salt '*' cmd.run 'ls -l /etc'

pkg 函数会自动将本地系统包管理器映射到相同的salt函数。这意味着 pkg.install 在基于Red Hat系统上将使用 yum 而在Debian系统上则使用 apt 来安装包，等等。

salt '*' pkg.install vim

注解

一些自定义的Linux和其他发行版的衍生版可能不能被Salt正确检测。如果上述命令返回 pkg.install is not available的错误信息，那么你可能就需要重写pkg provider。这个过程在 这里 有详解。

模块函数`network.interfaces <salt.modules.network.interfaces>` 将会列出minion上的所有接口，以及它们的IP地址，子网掩码，MAC地址等：

salt '*' network.interfaces

CHANGING THE OUTPUT FORMAT

The default output format used for most Salt commands is called the nested outputter, but there are several other outputters that can be used to change the way the output is displayed. For instance, the pprint outputter can be used to display the return data using Python's pprint module:

root@saltmaster:~# salt myminion grains.item pythonpath --out=pprint
{'myminion': {'pythonpath': ['/usr/lib64/python2.7',
                             '/usr/lib/python2.7/plat-linux2',
                             '/usr/lib64/python2.7/lib-tk',
                             '/usr/lib/python2.7/lib-tk',
                             '/usr/lib/python2.7/site-packages',
                             '/usr/lib/python2.7/site-packages/gst-0.10',
                             '/usr/lib/python2.7/site-packages/gtk-2.0']}}

The full list of Salt outputters, as well as example output, can be found here.

SALT-CALL

The examples so far have described running commands from the Master using the salt command, but when troubleshooting it can be more beneficial to login to the minion directly and use salt-call.

Doing so allows you to see the minion log messages specific to the command you are running (which are not part of the return data you see when running the command from the Master using salt), making it unnecessary to tail the minion log. More information on salt-call and how to use it can be found here.

GRAINS是MINION启动时加载的，在运行过程中不会发生变化，所以是静态数据。GRAINS中包含诸如运行的内核版本，操作系统等信息。

Salt使用一个叫做 :doc:`Grains <../targeting/grains>`的系统来建立关于minions的静态数据。这个数据包含了关于操作系统运行状态，CPU架构等信息。grains系统贯穿Salt用于发送平台数据到许多组件和用户。

Grains can also be statically set, this makes it easy to assign values to minions for grouping and managing.

A common practice is to assign grains to minions to specify what the role or roles a minion might be. These static grains can be set in the minion configuration file or via the grains.setval function.

TARGETING

Salt allows for minions to be targeted based on a wide range of criteria. The default targeting system uses globular expressions to match minions, hence if there are minions named larry1, larry2, curly1, and curly2, a glob of larry* will match larry1 and larry2, and a glob of *1 will match larry1 and curly1.

除了通配符之外还有许多其他的目标系统可以使用，这些系统包括:

正则表达式

使用PCRE引擎的正则表达式的目标

grains是minion启动时加载的，在运行过程中不会发生变化，所以是静态数据。grains中包含诸如运行的内核版本，操作系统等信息。

基于grains数据的目标: Targeting with Grains

Pilar

基于pilar数据的目标: Targeting with Pillar

IP

基于IP地址/子网/范围的目标

杂合

创建基于多个目标的逻辑目标规则: Targeting with Compound

节点组

节点组目标: Targeting with Nodegroup

目标的概念不仅在可以Salt命令行上使用，而且在很多其他的区域同样可以运行，包括state系统和用于ACLs和用户权限的系统。

传递参数

很多函数可以通过命令行接收参数:

salt '*' pkg.install vim

This example passes the argument vim to the pkg.install function. Since many functions can accept more complex input than just a string, the arguments are parsed through YAML, allowing for more complex data to be sent on the command line:

salt '*' test.echo 'foo: bar'

一般Salt将这种字符串'foo: bar'翻译为字典"{'foo': 'bar'}"

注解

任何包含一个换行符的行不会通过YAML解析。

SALT STATES

Now that the basics are covered the time has come to evaluate States. Salt States, or the State System is the component of Salt made for configuration management.

The state system is already available with a basic Salt setup, no additional configuration is required. States can be set up immediately.

注解

Before diving into the state system, a brief overview of how states are constructed will make many of the concepts clearer. Salt states are based on data modeling and build on a low level data structure that is used to execute each state function. Then more logical layers are built on top of each other.

The high layers of the state system which this tutorial will cover consists of everything that needs to be known to use states, the two high layers covered here are the sls layer and the highest layer highstate.

Understanding the layers of data management in the State System will help with understanding states, but they never need to be used. Just as understanding how a compiler functions assists when learning a programming language, understanding what is going on under the hood of a configuration management system will also prove to be a valuable asset.

第一个SLS公式

The state system is built on SLS formulas. These formulas are built out in files on Salt's file server. To make a very basic SLS formula open up a file under /srv/salt named vim.sls. The following state ensures that vim is installed on a system to which that state has been applied.

/srv/salt/vim.sls:

vim:
  pkg.installed

Now install vim on the minions by calling the SLS directly:

salt '*' state.sls vim

This command will invoke the state system and run the vim SLS.

Now, to beef up the vim SLS formula, a vimrc can be added:

/srv/salt/vim.sls:

vim:
  pkg.installed: []

/etc/vimrc:
  file.managed:
    - source: salt://vimrc
    - mode: 644
    - user: root
    - group: root

Now the desired vimrc needs to be copied into the Salt file server to /srv/salt/vimrc. In Salt, everything is a file, so no path redirection needs to be accounted for. The vimrc file is placed right next to the vim.sls file. The same command as above can be executed to all the vim SLS formulas and now include managing the file.

注解

Salt does not need to be restarted/reloaded or have the master manipulated in any way when changing SLS formulas. They are instantly available.

增加一些深度

Obviously maintaining SLS formulas right in a single directory at the root of the file server will not scale out to reasonably sized deployments. This is why more depth is required. Start by making an nginx formula a better way, make an nginx subdirectory and add an init.sls file:

/srv/salt/nginx/init.sls:

nginx:
  pkg.installed: []
  service.running:
    - require:
      - pkg: nginx

A few concepts are introduced in this SLS formula.

First is the service statement which ensures that the nginx service is running.

Of course, the nginx service can't be started unless the package is installed -- hence the require statement which sets up a dependency between the two.

The require statement makes sure that the required component is executed before and that it results in success.

注解

The require option belongs to a family of options called requisites. Requisites are a powerful component of Salt States, for more information on how requisites work and what is available see: Requisites

Also evaluation ordering is available in Salt as well: Ordering States

This new sls formula has a special name -- init.sls. When an SLS formula is named init.sls it inherits the name of the directory path that contains it. This formula can be referenced via the following command:

salt '*' state.sls nginx

注解

Reminder!

Just as one could call the test.ping or disk.usage execution modules, state.sls is simply another execution module. It simply takes the name of an SLS file as an argument.

Now that subdirectories can be used, the vim.sls formula can be cleaned up. To make things more flexible, move the vim.sls and vimrc into a new subdirectory called edit and change the vim.sls file to reflect the change:

/srv/salt/edit/vim.sls:

vim:
  pkg.installed

/etc/vimrc:
  file.managed:
    - source: salt://edit/vimrc
    - mode: 644
    - user: root
    - group: root

Only the source path to the vimrc file has changed. Now the formula is referenced as edit.vim because it resides in the edit subdirectory. Now the edit subdirectory can contain formulas for emacs, nano, joe or any other editor that may need to be deployed.

接下来阅读

Two walk-throughs are specifically recommended at this point. First, a deeper run through States, followed by an explanation of Pillar.

1. States 入门
2. Pillar 演练

一个对于理解Pilar的非常有用的方式是使用States。

更加深入STATES

两个更深入的States教程已经存在，用以更加深入学习States功能。

1. How Do I Use Salt States?, covers much more to get off the ground with States.
2. The States Tutorial also provides a fantastic introduction.

These tutorials include much more in-depth information including templating SLS formulas etc.