您也可以參考在Github上維護的這一篇技術資料：The Top File
Introduction - 介紹
大多數技術系統的基礎架構是由計算機組成，該架構中的每臺計算機都扮演着與其他計算機相似的角色。 這些機器相互協作以創建應用程序的技術棧。
爲了有效地管理這些計算機設備，管理員需要能夠爲這些計算機或計算機分組創建角色。 例如，一組爲前端Web流量提供服務的計算機可能具有某些角色，這些角色指示這些計算機都應都安裝了Apache Web服務器軟件包，並且Apache服務應始終處於運行狀態。
在Salt中，包含網絡上的計算機分組與應用於它們的配置角色之間的映射關係的文件稱爲top file文件。
默認情況下，頂級文件的名稱爲top.sls，之所以如此命名是因爲它們始終存在於包含狀態文件的目錄層次結構的“頂部”中。 該目錄層次結構稱爲state tree狀態樹。
A Basic Example - 一個基礎示例
Top file文件包含三個組成部分：
- 環境：狀態樹目錄，其中包含一組用於配置系統的狀態文件。
- 目標：一組機器，將對它們應用一組狀態。
- 狀態文件：應用於目標的狀態文件列表。 每個狀態文件都描述了要在目標計算機上配置和實施的一個或多個狀態。
這三個組件之間的關係如下：
- 環境包含目標
- 目標包含狀態
將這些概念放在一起，我們可以描述一個場景，在該場景中，所有以web開頭的ID的minions都被應用了apache狀態：
base: # Apply SLS files from the directory root for the 'base' environment
'web*': # All minions with a minion_id that begins with 'web'
- apache # Apply the state file named 'apache.sls'
Environments - 環境
環境是目錄層次結構，其中包含頂級文件和一組狀態文件。
環境可以以多種方式使用，但是也可以根本不需要使用它們。 實際上，部署Salt的最常見方法是使用稱爲base的單一環境。 建議用戶僅在有一個用例專門要求多個狀態樹版本的用例場景時才創建多個環境。
Getting Started with Top Files - 開始學習使用top file
每個環境都是在Salt master配置文件變量file_roots中定義。
在最常見的單環境設置中，只有基本環境在file_roots中定義，並且狀態樹只有一個目錄路徑。
file_roots:
base:
- /srv/salt
在上面的示例中，頂級文件將只有一個要提取的環境。
接下來是放在/srv/salt/top.sls中的一個簡單的單環境頂層文件，說明了對於名爲base的環境，所有minions都將應用名爲core.sls和edit.sls的狀態文件。
base:
'*':
- core
- edit
假設像上面配置了file_roots，Salt將在/srv/salt目錄中查找core.sls和edit.sls。
Multiple Environments - 多環境並存的場景
在某些情況下，團隊可能希望創建版本化的狀態樹，這些狀態樹可用於在將狀態部署到生產中之前在隔離的系統集（例如暫存環境）中測試Salt配置。
對於這種情況，可以使用多個環境來完成此任務。
要創建多個環境，可以擴展file_roots選項：
file_roots:
dev:
- /srv/salt/dev
qa:
- /srv/salt/qa
prod:
- /srv/salt/prod
在上面，我們聲明瞭三種環境：dev，qa和prod。 每個環境都有一個分配給它的目錄。
我們的頂級文件引用了以下環境：
dev:
'webserver*':
- webserver
'db*':
- db
qa:
'webserver*':
- webserver
'db*':
- db
prod:
'webserver*':
- webserver
'db*':
- db
如上所示，頂層文件現在聲明瞭三個環境，並且爲每個環境定義了目標表達式，以將minions映射到狀態文件。 例如，所有具有以字符串webserver開頭的ID的minions都將爲其分配所請求環境中的webserver狀態。
通過這種方式，可以先在/srv/salt/dev中的狀態文件中對狀態進行建議的更改，然後將其複製到/srv/salt/qa將該狀態文件移至QA，然後將其應用於開發Web服務器 。
Choosing an Environment to Target - 選擇一個目標環境
除非使用以下描述的方法覆蓋，否則頂層文件默認會將minions分配到一個環境中。頂層文件中的環境必須匹配有效的文件服務器環境（也就是saltenv），以便將任何狀態應用於該minion。使用默認的文件服務器後端時，環境是在file_roots中定義。
可以使用state.show_top函數查看將在給定環境中應用於minion的狀態。
通過在minion配置文件中設置環境值，可以將minions固定到特定環境。這樣，一個minion只會從其分配到的環境請求文件。
也可以在運行時通過將環境傳遞給salt，salt-call或salt-ssh命令來動態選擇環境。最常見的做法是使用saltenv參數對狀態模塊中的函數進行處理。例如，要在prod環境中僅使用頂層文件和SLS文件對所有minions運行highstate狀態，請運行：salt '*' state.highstate saltenv = prod。
注意：並非所有函數都支持將saltenv用作參數，請參見文檔中的各個函數文檔進行驗證。
Shorthand - 簡寫形式
如果僅將一個SLS分配給系統，如本例所示，則可使用下面的簡寫方法：
base:
'*': global
dev:
'webserver*': webserver
'db*': db
qa:
'webserver*': webserver
'db*': db
prod:
'webserver*': webserver
'db*': db
Advanced Minion Targeting
在上面的示例中，請注意所有目標表達式都使用了glob匹配。 Top file文件（自版本2014.7.0起）中的默認匹配類型實際上是 compound matcher（複合匹配器），而不是CLI中的全局匹配器。
單個glob通過複合匹配器時，其行爲與glob匹配相同，因此在大多數情況下，兩者是無法區分的。 但是，在某些情況下，一個minion ID中包含空格。 雖然不建議在minion ID中包含空格，但是Salt不會阻止您這樣做。 但是，由於複合表達式是逐詞進行解析的，因此，如果一個minion ID包含空格，它將無法匹配。 在這種情況下，有必要明確使用全局匹配器：
base:
'minion 1':
- match: glob
- foo
可以在top file文件中爲目標表達式設置的可用匹配類型如下表所示：
| Match Type | Description |
|---|---|
| glob | Full minion ID or glob expression to match multiple minions (e.g. minion123 or minion*) |
| pcre | Perl-compatible regular expression (PCRE) matching a minion ID (e.g. web[0-3].domain.com) |
| grain | Match a grain, optionally using globbing (e.g. kernel:Linux or kernel:*BSD) |
| grain_pcre | Match a grain using PCRE (e.g. kernel:(Free |
| list | Comma-separated list of minions (e.g. minion1,minion2,minion3) |
| pillar | Pillar match, optionally using globbing (e.g. role:webserver or role:web*) |
| pillar_pcre | Pillar match using PCRE (e.g. role:web(server |
| pillar_exact | Pillar match with no globbing or PCRE (e.g. role:webserver) |
| ipcidr | Subnet or IP address (e.g. 172.17.0.0/16 or 10.2.9.80) |
| data | Match values kept in the minion’s datastore (created using the data execution module) |
| range | Range cluster |
| compound | Complex expression combining multiple match types (see here) |
| nodegroup | Pre-defined compound expressions in the master config file (see here) |
下面是一個稍微複雜一些的top file文件示例，其中應用了上述一些匹配類型：
# All files will be taken from the file path specified in the base
# environment in the ``file_roots`` configuration value.
base:
# All minions which begin with the strings 'nag1' or any minion with
# a grain set called 'role' with the value of 'monitoring' will have
# the 'server.sls' state file applied from the 'nagios/' directory.
'nag1* or G@role:monitoring':
- nagios.server
# All minions get the following three state files applied
'*':
- ldap-client
- networking
- salt.minion
# All minions which have an ID that begins with the phrase
# 'salt-master' will have an SLS file applied that is named
# 'master.sls' and is in the 'salt' directory, underneath
# the root specified in the ``base`` environment in the
# configuration value for ``file_roots``.
'salt-master*':
- salt.master
# Minions that have an ID matching the following regular
# expression will have the state file called 'web.sls' in the
# nagios/mon directory applied. Additionally, minions matching
# the regular expression will also have the 'server.sls' file
# in the apache/ directory applied.
# NOTE!
#
# Take note of the 'match' directive here, which tells Salt
# to treat the target string as a regex to be matched!
'^(memcache|web).(qa|prod).loc$':
- match: pcre
- nagios.mon.web
- apache.server
# Minions that have a grain set indicating that they are running
# the Ubuntu operating system will have the state file called
# 'ubuntu.sls' in the 'repos' directory applied.
#
# Again take note of the 'match' directive here which tells
# Salt to match against a grain instead of a minion ID.
'os:Ubuntu':
- match: grain
- repos.ubuntu
# Minions that are either RedHat or CentOS should have the 'epel.sls'
# state applied, from the 'repos/' directory.
'os:(RedHat|CentOS)':
- match: grain_pcre
- repos.epel
# The three minions with the IDs of 'foo', 'bar' and 'baz' should
# have 'database.sls' applied.
'foo,bar,baz':
- match: list
- database
# Any minion for which the pillar key 'somekey' is set and has a value
# of that key matching 'abc' will have the 'xyz.sls' state applied.
'somekey:abc':
- match: pillar
- xyz
How Top Files Are Compiled - top file 文件是怎麼編譯的
當執行highstate狀態並指定環境時（使用環境配置選項或在執行highstate狀態時通過傳遞saltenv），則該環境的頂層文件是唯一用於將狀態分配給minions的頂層文件，並且僅有來自狀態指定的環境將運行。
本節的其餘部分適用於在未指定環境的情況下執行highstate狀態的情況。
在未指定環境的情況下，minion將在每個環境中查找頂級文件，並且將處理每個頂級文件以確定在minions上運行哪些的SLS文件。默認情況下，來自每個環境的top file文件將合併在一起。在具有許多環境的配置中（例如，在GitFS中，每個分支和標籤都被視爲不同的環境），這可能會導致意外結果，因爲來自舊標籤的SLS文件會導致失效的SLS文件包含在highstate狀態中。在這種情況下，將top_file_merging_strategy設置爲same以強制每個環境使用其自己的頂層top file文件可能會有所幫助。
top_file_merging_strategy: same
另一種選擇是將state_top_saltenv設置爲特定環境，以確保不考慮其他環境中的任何頂級文件：
state_top_saltenv: base
使用GitFS，可以簡單地分別管理每個環境的頂層文件，和/或在執行highstate狀態時手動指定環境，以避免任何複雜的合併場景，也可能會有所幫助。 gitfs_env_whitelist和gitfs_env_blacklist也可以用於從GitFS隱藏不需要的分支和標籤，以減少正在活躍的top files文件的數量。
當使用多個環境時，不必爲每個環境創建一個頂層文件。最容易維護的方法是使用放置在base環境中的單個頂級文件。但是，這在GitFS中通常是不可行的，因爲分支/標記很容易導致額外的頂級文件。但是，當僅使用默認（根）文件服務器後端時，base環境中的單個頂級文件是配置highstate狀態的最常見方法。
以下minion配置選項會影響未指定環境時top file文件的編譯方式，建議遵循以下四個鏈接的解釋以瞭解有關這些選項如何工作的更多信息：
Top File Compilation Examples - top file文件編譯的示例
對於以下方案，請進行以下配置：
/etc/salt/master:
file_roots:
base:
- /srv/salt/base
dev:
- /srv/salt/dev
qa:
- /srv/salt/qa
/srv/salt/base/top.sls:
base:
'*':
- base1
dev:
'*':
- dev1
qa:
'*':
- qa1
/srv/salt/dev/top.sls:
base:
'minion1':
- base2
dev:
'minion2':
- dev2
qa:
'*':
- qa1
- qa2
注意：就這些示例而言，在
qa環境中沒有top file文件。
Scenario 1 - dev Environment Specified - 指定使用dev環境時
在這種情況下，highstate是使用saltenv=dev調用的，或者是minion具有環境屬性：在minion配置文件中設置的dev。 結果將是隻有來自dev環境的dev2 SLS成爲highstate狀態的一部分，並將其應用於minion2，而minion1將不對其應用任何狀態。
如果指定了base環境，則結果將是隻有base環境中的base1 SLS會成爲highstate狀態的一部分，並且它將應用於所有minions。
如果指定了qa環境，則highstate狀態將退出並顯示錯誤。
Scenario 2 - No Environment Specified, top_file_merging_strategy is “merge”
在這種情況下，假設首先評估了base環境的top file文件，則base1，dev1和qa1狀態將應用於所有minions。 例如，如果未在/srv/salt/base/top.sls中定義qa環境，則由於沒有用於qa環境的頂層文件，因此不會應用來自qa環境的狀態。
Scenario 3 - No Environment Specified, top_file_merging_strategy is “same”
在版本2016.11.0中進行了更改： 在以前的版本中，“same”並不能完全按照以下說明工作（請參閱 此處）。 現在，此問題已得到糾正。
在這種情況下，base環境中的base1將應用於所有minions。 另外，來自dev環境的dev2應用於minion2。
如果未設置default_top（或將其設置爲base，這恰好是默認值），則來自qa環境的qa1將應用於所有minions。 如果將default_top設置爲dev，則來自qa環境的qa1和qa2都將應用於所有minions。
Scenario 4 - No Environment Specified, top_file_merging_strategy is “merge_all”
New in version 2016.11.0.
在這種情況下，將應用所有top files文件中的所有配置狀態。 從base環境來看，base1將應用於所有minions，而base2僅應用於minion1。 從dev環境中，dev1將應用於所有minions，而dev2僅應用於minion2。 最後，在qa環境中，qa1和qa2狀態都將應用於所有minions。 請注意，即使qa1出現兩次，也不會兩次應用qa1狀態。