安装并配置主节点插件

作为安装后过程的一部分，需要安装、配置和升级主节点插件。通过主节点插件，Salt 主节点能够与 Automation Config 进行通信。主节点插件包含各种可调整以提高性能的设置，这些设置对于大型或繁忙环境尤为有用。

通常，在环境中与 Automation Config 进行通信的每个 Salt 主节点上安装主节点插件。例如，如果使用具有多个 Salt 主节点的配置（有时称为多主节点设置），必须在每个 Salt 主节点上安装主节点插件。

开始前

安装并配置主节点插件是一系列步骤中的安装后步骤，这些步骤应按特定顺序执行。首先，完成其中一个安装方案，然后阅读安装许可证密钥安装后页面。

必须使用以下命令在 Salt 主节点上安装 PyJWT 库：

pip3 install pyjwt==2.3.0

何时需要安装主节点插件？

在全新安装 Automation Config 后，需要在所有 Salt 主节点上安装主节点插件。在不需要与 Automation Config 进行通信的 Salt 主节点上，不需要安装主节点插件。

如果使用的是在节点少于 1000 个的情况下安装 SaltStack Config 安装方案，则无需在安装了 Automation Config 及其相关架构的节点上安装主节点插件。安装程序会自动在 Salt 主节点安装主节点插件。但是，仅在运行安装程序的 Salt 主节点上安装主节点插件。如果具有多个主节点，仍需要在其他主节点上安装主节点插件。

如果手动安装 Automation Config（不建议），则应先完成以下操作，然后再安装主节点插件：

• 安装并配置 PostgreSQL 数据库
• 安装和配置 Redis 数据库
• 启用 SSL（可选）

重要说明： 对于任何版本，都建议通过生成默认配置文件然后应用现有配置中要保留的任何设置来更新主节点插件配置。例如：

# sseapi-config --default >/tmp/raas.conf 
# cd /etc/salt/master.d 
# vim -d raas.conf /tmp/raas.conf 
...

如果使用 onedir 安装的 Salt，则此可执行文件的路径为 /opt/saltstack/salt/extras-3.10/bin/sseapi-config。

使用主插件工作区安装主插件

注： Automation Config 版本 8.11.2 或更高版本支持此功能。

注： Salt 主节点必须以 root 用户身份运行。

可以从 Automation Config 用户界面，导航到管理 > 主节点插件，下载并安装最新的主节点插件版本。从“主节点插件”选项卡，可以下载插件或下载客户端。

下载主节点插件后，必须配置主节点插件。

使用 CLI 安装主节点插件

要在 Salt 主节点上安装主节点插件，请执行以下操作：

从 8.13.0 版本开始，主节点插件包括一个 tgtmatch 引擎，该引擎现在可将目标组匹配从 RaaS 服务器卸载到 Salt 主节点。建议启用并配置 tgtmatch 引擎，以使目标组匹配响应更快，尤其是在具有以下条件的环境中：

• 大量目标组（100 个或更多）
• 大量工作节点（3000 个或更多）
• 频繁更改工作节点 Grain（每日或更频繁）
• 频繁创建和删除工作节点（每日或更频繁）

要配置 RaaS 以期望 Salt 主节点提供目标匹配数据，请确保 RaaS 配置文件 (/etc/raas/raas) 中存在以下设置：

target_groups_from_master_only: true

1. 登录到 Salt 主节点。
2. （如有必要）从 Customer Connect 下载主节点插件 wheel。

   主节点插件包含在自动安装程序 .tar.gz 文件中。下载并提取 .tar.gz 文件后，可以在 sse-installer/salt/sse/eapi_plugin/files 目录中找到主节点插件。

3. 通过手动卸载并重新安装更新的 Python wheel 来升级主节点插件。使用以下示例命令，并替换为 wheel 文件的确切名称：
   注： 必须卸载现有插件，以防止 sseapi-config 的多个实例。

   pip3 uninstall SSEAPE-8.12.1.3-py3-none-any.whl
   mv /etc/salt/master.d/raas.conf /tmp
   salt-call pip.install SSEAPE-8.12.1.3-py3-none-any.whl
   cp /tmp/raas.conf /etc/salt/master.d/raas.conf
   systemctl restart salt-master

配置主插件

要在安装主节点插件后配置 Salt 主节点，请执行以下操作：

1. 登录到 Salt 主节点并验证 /etc/salt/master.d 目录是否存在，如果不存在，则创建该目录。
2. 生成主配置设置。
   小心： 如果要在升级安装时保留设置，请备份现有的主节点插件配置文件，然后再运行此步骤。之后，将相关设置从现有配置复制到新生成的文件中。

   sudo sseapi-config --all > /etc/salt/master.d/raas.conf

   重要说明： 如果使用 onedir 安装的 Salt，则此可执行文件的路径为 /opt/saltstack/salt/extras-3.10/bin/sseapi-config。
3. 编辑生成的 raas.conf 文件，并按以下方式更新值：

   值	说明
   sseapi_ssl_validate_cert	验证 API (RaaS) 使用的证书。默认值为 True。 如果使用自己 CA 颁发的证书，请将此值设置为 True 并配置 sseapi_ssl_ca、sseapi_ssl_cert 和 sseapi_ssl_cert: 设置。 否则，请将此值设置为 False，不验证证书。 sseapi_ssl_validate_cert:False
   sseapi_server	RaaS 节点的 HTTP IP 地址，例如，http://example.com 或 https://example.com（如果启用了 SSL）。
   sseapi_command_age_limit	设置跳过可能失效的旧作业的期限（以秒为单位）。例如，要跳过一天前的作业，请设置为： sseapi_command_age_limit:86400 跳过的作业将继续存在于数据库中，并在 Automation Config 用户界面中显示状态 Completed。 某些环境可能需要 Salt 主节点长时间脱机，并且需要 Salt 主节点在重新联机后运行排队的任何作业。如果此情况适用于您的环境，请将期限设置为 0。
   sseapi_windows_minion_deploy_delay	设置延迟以允许所有必需的 Windows 服务变为活动状态。默认值为 180 秒。
   sseapi_linux_minion_deploy_delay	设置延迟以允许所有必需的 Linux 服务变为活动状态。默认值为 90 秒。
   sseapi_local_cache load: 3600 tgt: 86400 pillar: 3600 exprmatch: 86400 tgtmatch: 86400	设置某些数据在每个 Salt 主节点上本地缓存的时长。值以秒为单位。示例值是建议的值。 load- salt save_load（） 负载 tgt- SSE 目标组 pillar - SSE pillar 数据（已加密） exprmatch - SSE 目标表达式匹配数据 tgtmatch- SSE 目标组匹配数据

4. 可选：仅手动安装需要执行此步骤。要验证是否可以在连接主节点插件之前连接到 SSL，请编辑生成的 raas.conf 文件，更新以下值。如果不更新这些值，则主节点插件将使用默认生成的证书。

   值	说明
   sseapi_ssl_ca	CA 文件的路径。
   sseapi_ssl_cert	证书的路径。默认值为 /etc/pki/raas/certs/localhost.crt。
   sseapi_ssl_key	证书私钥的路径。默认值为 /etc/pki/raas/certs/localhost.key。
   id	在开头添加 #，注释掉此行。不需要此项。

5. 可选：更新与性能相关的设置。对于大型或繁忙环境，可以通过调整以下设置提高 Salt 主节点与 Automation Config 之间通信的性能。
   • 配置主插件引擎：

     主节点插件 eventqueue 和 rpcqueue 引擎会将与 Automation Config 的某些通信从性能关键型代码路径卸载到专用进程。当这些引擎正在等待与 Automation Config 通信时，负载会存储在 Salt 主节点的本地文件系统中，以便数据可以在 Salt 主节点重新启动后持久保留。tgtmatch 引擎会将工作节点目标组匹配的计算从 RaaS 服务器移至 Salt 主节点。

     要启用引擎，请确保 Salt 主节点插件配置文件 （raas.conf） 中存在以下设置：

     engines: 
          - sseapi: {} 
          - eventqueue: {} 
          - rpcqueue: {} 
          - jobcompletion: {} 
          - keyauth: {} 
          - tgtmatch: {}

     要配置 eventqueue 引擎，请确认存在以下设置：

     sseapi_event_queue: 
       name: sseapi-events 
       strategy: always 
       push_interval: 5 
       batch_limit: 2000 
       age_limit: 86400 
       size_limit: 35000000 
       vacuum_interval: 86400 
       vacuum_limit: 350000 

     可以根据队列参数的协同工作方式调整这些队列参数。例如，假设 Salt 事件总线上每秒平均 400 个事件，上述设置允许在 Salt 主节点上收集约 24 小时的已排队事件流量，之后由于大小或期限限制而放弃最早的事件。

     要配置 rpcqueue 引擎，请验证 raas.conf 中的以下设置：

     sseapi_rpc_queue: 
       name: sseapi-rpc 
       strategy: always 
       push_interval: 5 
       batch_limit: 500 
       age_limit: 3600 
       size_limit: 360000 
       vacuum_interval: 86400 
       vacuum_limit: 100000 

     要配置 tgtmatch 引擎，请确保主节点插件配置文件 (/etc/salt/master.d/raas.conf) 中存在以下设置：

     engines: 
         - sseapi: {} 
         - eventqueue: {} 
         - rpcqueue: {} 
         - jobcompletion: {} 
         - keyauth: {} 
         - tgtmatch: {} 
     
     sseapi_local_cache:     
         load: 3600 
         tgt: 86400 
         pillar: 3600 
         exprmatch: 86400 
         tgtmatch: 86400 
     
     sseapi_tgt_match: 
         poll_interval: 60     
         workers: 0 
         nice: 19

     注： 要在 Salt 主节点上利用目标匹配，RaaS 配置中还必须存在以下配置设置： target_groups_from_master_only: true。
   • 限制工作节点颗粒负载大小：

     sseapi_max_minion_grains_payload: 2000

   • 启用跳过早于定义时间（以秒为单位）的作业。例如，使用 86400 会将其设置为跳过一天前的作业。如果设置为 0，将禁用此功能：

     sseapi_command_age_limit:0

     注：

     在系统升级过程中，启用此设置有助于防止数据库中存储的旧命令意外运行。

   Salt 中的事件队列以及 Salt 主节点插件中的队列引擎、Salt 主节点目标匹配、Grain 负载大小限制和命令期限限制协同工作，不仅增加了吞吐量，而且减少了在对性能最敏感的代码路径中 Salt 主节点与 Automation Config 之间的通信延迟。

6. 重新启动主服务。

   sudo systemctl restart salt-master

7. 可选：可能希望运行测试作业以确保主节点插件现在支持在主节点与 RaaS 节点之间进行通信。

   salt -v '*' test.ping

即使没有显示任何活动（例如未连接任何工作节点），也可能表示配置正确。

配置设置参考

配置文件中的这些设置使每个 Salt 主节点都能够连接到 API (RaaS)。可以在 /etc/salt/master.d/raas.conf 配置文件中找到这些设置。

重要说明：

raas.conf 文件中的 Salt 主节点设置优先于 /etc/salt/master 中的现有设置。如果在 /etc/salt/master 中对 fileserver_backend 或 ext_pillar 设置进行了自定义，则需要手动合并这些设置，以便它们只显示在一个文件中。可以选择对后端重新排序以更改优先级。

下表介绍了常规配置设置：

选项	说明
id	Salt 主节点 ID，如果未设置，则自动生成
sseapi_server	SSEAPI 服务器的 URL，例如 https://sse.example.com:443
engines	要启用的 Salt 引擎，建议使用 sseapi、eventqueue、rpcqueue、jobcompletion 和 keyauth。
master_job_cache	建议使用 sseapi，以使用 Automation Config 主节点作业缓存
event_return	Salt 事件返回程序，建议使用 sseapi，以使用 Automation Config 事件返回程序
ext_pillar	外部 pillar 源，建议使用 sseapi
fileserver_backend	文件服务器后端，建议使用 sseapi 和 roots
sseapi_update_interval	从文件服务器更新的频率（以秒为单位，默认为 60）
sseapi_poll_interval	在 Automation Config 中轮询新数据的频率（以秒为单位，默认为 30）
sseapi_jce_poll_interval	在 jobcompletion 引擎中的迭代之间增加了延迟，因此，每天每个 Salt 主节点最多发送 5760 个 find_job 命令（以秒为单位，默认为 15）
sseapi_timeout	API (RaaS) 调用超时（以秒为单位，默认为 200）
sseapi_pubkey_path	用于向 Automation Config 验证 Salt 主节点身份的公钥文件的路径
sseapi_key_rotation	Salt 主节点 Automation Config 身份验证密钥轮换时间间隔（以秒为单位，默认为 86400）
sseapi_cache_pillar	是否在 Automation Config 中缓存 pillar 数据（True 或 False，默认为 False）
sseapi_cluster_id	（可选）Salt 主节点集群名称，用于在 Automation Config 中将 Salt 主节点分组到集群
sseapi_failover_master	此 Salt 主节点是否为故障切换 Salt 主节点（True 或 False，默认为 False）
sseapi_command_age_limit	是否跳过早于定义时间的 API (RaaS) 命令（以秒为单位，0 表示禁用，默认为 0）

下表介绍了 SSL 设置：

选项	说明
sseapi_ssl_key	证书私钥的路径
sseapi_ssl_cert	证书的路径
sseapi_ssl_validate_cert	是否验证 Automation Config SSL 证书（True 或 False，默认为 True）

下表介绍了事件队列引擎设置，这些设置显示在 sseapi_event_queue 标题下：

选项	说明
name	事件队列名称（默认为 sseapi-events，无需更改）
strategy	何时对事件进行排队（always、on_failure 或 never，默认为 never）
push_interval	将事件推送到 Automation Config 的频率（以秒为单位，默认为 5）
batch_limit	每时间间隔要推送到 Automation Config 的最大事件数量（默认为 2000）
age_limit	最长排队事件期限；丢弃最早的事件（以秒为单位，默认为 86400）
size_limit	最大队列大小；丢弃最早的事件（事件数，默认为 35000000）
vacuum_interval	对队列数据库进行 vacuum 操作的频繁（以秒为单位，默认为 86400）
vacuum_limit	对队列数据库进行 vacuum 操作时的最大队列大小（事件数，默认为 350000）

下表介绍了 RPC 队列引擎设置，这些设置显示在 sseapi_rpc_queue 标题下：

选项	说明
name	事件队列名称（默认为 sseapi-rpc，无需更改）
strategy	何时对事件进行排队（always、on_failure 或 never，默认为 never）
push_interval	将调用发送到 Automation Config 的频率（以秒为单位，默认为 5）
batch_limit	每时间间隔要推送到 Automation Config 的最大调用数量（默认为 500）
age_limit	最长排队调用期限；丢弃最早的条目（以秒为单位，默认为 3600）
size_limit	最大队列大小；丢弃最早的条目（事件数，默认为 360000）
vacuum_interval	对队列数据库进行 vacuum 操作的频繁（以秒为单位，默认为 86400）
vacuum_limit	对队列数据库进行 vacuum 操作时的最大队列大小（条目数，默认为 100000）

下表介绍了目标匹配引擎设置，这些设置显示在 sseapi_tgt_match 标题下：

选项	说明
poll_interval	引擎从 RaaS 请求更新的目标组信息的频率（以秒为单位）（默认为 60）
workers	应创建多少个工作线程进程才能执行目标组匹配计算。默认值 （0） 为每个 CPU 内核创建一个进程，上限为 8。
nice	目标组匹配工作线程的优先级。默认值 （19） 为 Worker 提供最低调度优先级，以防止干扰 salt 主节点上运行的其他进程。

下表介绍了路径设置。生成初始配置后，请谨慎更改这些设置。模块将在安装过程中复制到这些目录。但是，添加额外路径不会造成不利影响。

选项	说明
beacons_dirs	信标外部模块路径
engines_dirs	引擎外部模块路径
fileserver_dirs	文件服务器外部模块路径
pillar_dirs	pillar 外部模块路径
returner_dirs	返回程序外部模块路径
roster_dirs	名单外部模块路径
runner_dirs	运行程序外部模块路径
module_dirs	Salt 外部模块路径
proxy_dirs	代理外部模块路径
metaproxy_dirs	元代理外部模块路径
states_dirs	状态外部模块路径

后续操作

安装并配置主节点插件后，必须完成其他安装后步骤。下一步是配置 RaaS 节点。要继续执行安装后过程，请参见检查 RaaS 配置文件。