THE TOP FILE(top文件详解)

INTRODUCTION

（1）top能实现一组机器部署不同业务环境，达到相互协调配合的工作。
（2）top文件包含了计算机之间的映射关系以及配置文件角色的文件。
（3）默认top文件被命名为top.sls，总是存在于包含state文件的目录层顶部，这种目录结构被称为目录树。

A BASIC EXAMPLE

Top文件包含3个组件：
　　Environment：包含一组状态文件的状态树目录配置系统
　　Target：一组机器将有一组状态适用于他们。
　　State files：应用于target匹配机器的一组state文件列表，
上面3个组件之间的关系；
　　Environment包含Target，Target包含state files
示例场景：
　　base: #从定义好的base环境的根目录里面加载sls文件
　　　'web*': #从所有minion里面匹配到minion_id以web开头的minion
　　　　- apache #应用apache.sls文件里面定义的状态配置

ENVIRONMENTS

包含一组sls文件的目录结构，通常只使用一个base环境，如果你需要使用多个版本的状态树的话建议你使用多环境

GETTING STARTED WITH TOP FILES

开始使用top文件，每一个environment环境被定义在file_roots这个配置项里面
示例：

1 file_roots:
2   base:
3     - /srv/salt
4 top文件内容定义：
5 base:
6   '*':
7     - core
8     - edit

View Code

top文件定义的路径在/srv/salt下面，core和edit也应当位于该目录下

MULTIPLE ENVIRONMENTS

在一些生产环境中，它需要不同版本的state状态文件，实现分级部署，譬如测试，预发布，线上等
示例：

file_roots:

1   dev:
2     - /srv/salt/dev
3   qa:
4     - /srv/salt/qa
5   prod:
6     - /srv/salt/prod

View Code

top文件内容示例：

 1 dev:
 2   'webserver*':
 3     - webserver
 4   'db*':
 5     - db
 6 qa:
 7   'webserver*':
 8     - webserver
 9   'db*':
10     - db
11 prod:
12   'webserver*':
13     - webserver
14   'db*':
15     - db

View Code

在上面的例子中，每一个environment都需要配置一个目录，里面都包含一个top文件，里面配置有target与sls的映射关系。
如果需要从dev环境逐步配置到prod环境，只需要将sls文件逐级进行拷贝到对应的环境目录中即可。

CHOOSING AN ENVIRONMENT TO TARGET

为environment指定匹配一个或一组有效的minion，设置合理的match规则，确保指定的minion应用指定的sls配置，使用state.show_top可以查看minion上的environment适配情况
在salt, salt-call or salt-ssh命令行中，可以在运行时指定salt environment，利用saltenv参数来指定，如果只是在单一环境中运行可以使用这样的运行方式：salt '*' state.highstate saltenv=prod。
注意：不是所有的函数都接收saltenv作为参数

SHORTHAND

如果在一组target中只分配了一个sls文件，可以使用如下简洁的配置方法

 1 base:
 2   '*': global
 3 dev:
 4   'webserver*': webserver
 5   'db*':        db
 6 qa:
 7   'webserver*': webserver
 8   'db*':        db
 9 prod:
10   'webserver*': webserver
11   'db*':        db

View Code

ADVANCED MINION TARGETING

minion target进阶使用
上面的例子中minion的匹配上是使用glob的，top文件中默认的匹配是复合类型匹配的，大多数情况下二者是不可区分的，但有一种minion ID中包含空格的时候，由于复合表达式是逐字进行匹配的，所以会匹配异常，这种情况下需要声明glob
示例：

1 base:
2   'minion 1':
3     - match: glob
4     - foo

View Code

以下是target可设置的匹配类型：
　　glob 通配符，glob表示式匹配一个或多个minion，根据minion ID匹配，例如minion123或minion*。
　　pcre perl正则表达式匹配，例如web[0-3].domain.com
　　grain 匹配grains变量，使用通配符的方式，例如kernel:Linux or kernel:*BSD
　　grain_pcre 使用pcre的方式匹配grains变量，kernel:(Free|Open)BSD
　　list 使用逗号分隔的minion列表清单，minion1,minion2,minion3
　　pillar 使用通配符的方式匹配pillar变量，role:webserver or role:web*
　　pillar_pcre 使用pcre的方式匹配pillar变量，role:web(server|proxy
　　pillar_exact不使用pcre和通配的方式匹配pillar，例如：role:webserver
　　ipcidr 根据子网或IP地址进行匹配，例如172.17.0.0/16 or 10.2.9.80
　　data 匹配值保持在目标数据库里面，需要创建和使用data执行模块
　　range 使用范围值匹配，依赖额外的模块
　　compound 使用复合类型匹配模式
　　nodegroup 定义在master配置文件中的复合表达式组

示例：

 1 base:
 2     'nag1* or G@role:monitoring':    #glob匹配以nag1开头的minion和grains role设置为monitoring的minion
 3         - nagios.server
 4 
 5     '*':                            #匹配所有minion
 6         - ldap-client
 7         - networking
 8         - salt.minion
 9                             
10     '^(memcache|web).(qa|prod).loc$':    #使用正则方式匹配，以memcache或web开头，中间qa|prod，以loc结尾的minion ID匹配
11         - match: pcre
12         - nagios.mon.web
13         - apache.server    
14 
15     'os:Ubuntu':                    #使用grains的变量匹配方法
16         - match: grain
17         - repos.ubuntu
18     
19     'os:(RedHat|CentOS)':            #使用grains正则的匹配方式
20         - match: grain_pcre
21         - repos.epel    
22 
23     'foo,bar,baz':                    #使用列表的方式
24         - match: list
25         - database
26 
27     'somekey:abc':                    #使用pillar变量的方式
28         - match: pillar
29         - xyz

View Code

HOW TOP FILES ARE COMPILED

运行指定salt environment的highstate时，master会从top文件中分配指定的minion配置数据，minion再负责具体执行。
当不指定salt运行环境的时候，minion会遍历每一个environment，每一个顶层文件都会被处理以确定哪些sls将要运行在哪些minion上，默认情况下每个环境中的sls配置都会被合并在一起。
当时用gitfs的时候，利用分支作为环境目录，可能会导致意外的情况发生，这时候可以使用top_file_merging_strategy置same强制每一个环境使用自己使用自己的top文件，而不是合并掉。
参考链接：http://hxzqlh.com/2016/05/07/Salt-States-%E5%9F%BA%E6%9C%AC%E6%B3%95-%E5%9B%9B/

当使用多个环境时，不必为每个环境创建一个顶级文件。最容易维护的方法是将一个单独的top文件放在基本环境中。下面的minion配置选项如何影响top文件编译时没有环境指定，建议遵循以下四个环节来了解这些选项的工作：

　　state_top_saltenv
　　top_file_merging_strategy
　　env_order
　　default_top

TOP FILE COMPILATION EXAMPLES

/etc/salt/master:

1 file_roots:
2   base:
3     - /srv/salt/base
4   dev:
5     - /srv/salt/dev
6   qa:
7     - /srv/salt/qa

View Code

/srv/salt/base/top.sls:

1 base:
2   '*':
3     - base1
4 dev:
5   '*':
6     - dev1
7 qa:
8   '*':
9     - qa1

View Code

/srv/salt/dev/top.sls:

 1 base:
 2   'minion1':
 3     - base2
 4 dev:
 5   'minion2':
 6     - dev2
 7 qa:
 8   '*':
 9     - qa1
10     - qa2

View Code

注意：qa环境没有配置top文件

SCENARIO 1 - 指定dev环境
　　指定dev环境运行，仅dev2 sls文件运行在minion2上，minion1无sls文件应用
　　指定base环境运行，base2 sls文件将运行在所有minion上
　　如果指定qa环境运行，执行high将会出现错误

SCENARIO 2 - 不指定环境运行，TOP_FILE_MERGING_STRATEGY设置为merge
　　base1, dev1, and qa1 state状态文件将会被应用到所有的minion中，如果qa环境没有被定义在/srv/salt/base/top.sls中，那么qa环境中将不会有任何state文件被应用

SCENARIO 3 - 不指定环境运行，TOP_FILE_MERGING_STRATEGY设置为same
　　在2016.11.0这一版中，same没有描述中的那么有效，新的版本已经修复
　　base1将应用于所有minion中，相应的dev2将应用于minion2
　　如果不设置default_top或设置为base，那么qa1 sls将应用在所有minion上，如果default_top设置为dev，那么qa1和qa2将应用到所有minion中

SCENARIO 4 - 不指定环境运行，TOP_FILE_MERGING_STRATEGY设置为MERGE_ALL
　　那么所有环境中的top都会被应用，base1被应用在所有minion上，base2将被应用在minion1上，对于dev环境，dev1会被应用在所有minion中，dev2将被应用在minion2中，qa1和qa2将被应用在所有minion中，注意qa1不会被应用两次