salt-api 镜像文档

镜像概述与主要用途

本镜像包含SaltStack的salt-api组件，salt-api是SaltStack的REST API接口实现，用于通过HTTP请求与SaltStack生态系统交互。其核心功能包括执行Salt命令、获取minion节点状态、管理基础设施配置等，主要用途是将SaltStack的自动化能力集成到第三方系统或通过API实现远程运维操作。

核心功能与特性

• REST API接口：提供标准HTTP/HTTPS接口，支持JSON格式请求与响应，便于系统集成。
• 认证机制：支持多种认证方式（如PAM、LDAP、用户名密码等），保障接口访问安全。
• SaltStack集成：与salt-master无缝协作，共享SaltStack配置与状态数据。
• 加密通信：支持HTTPS协议，通过SSL/TLS证书加密API通信内容。
• 灵活配置：可通过配置文件自定义端口、认证策略、访问权限等参数。

使用场景与适用范围

• 自动化运维平台：作为后端服务，为自定义运维平台提供基础设施管理接口。
• 第三方系统集成：与监控、CI/CD、工单系统等集成，实现自动化操作触发。
• 远程管理：管理员通过API远程执行命令、批量配置minion节点。
• 脚本化操作：通过脚本调用API实现重复性运维任务的自动化。

使用方法与配置说明

前提条件

• 已部署运行的salt-master服务，且容器网络可访问salt-master（建议使用Docker网络或宿主网络）。
• 若启用HTTPS，需准备SSL证书文件（可通过openssl自行生成或使用CA签发证书）。

基本运行命令

docker run -d \
  --name salt-api \
  --network salt-net \  # 与salt-master共享网络（需提前创建）
  -v /host/path/to/config:/etc/salt/master.d \  # 挂载本地配置目录
  -v /host/path/to/certs:/etc/salt/certs \  # 挂载SSL证书（若启用HTTPS）
  -e SALT_MASTER=salt-master \  # 指定salt-master地址（默认值：salt-master）
  -p 8000:8000 \  # 映射API端口（宿主端口:容器端口）
  salt-api

配置文件说明

salt-api的核心配置通过/etc/salt/master.d/api.conf文件定义，示例配置（挂载到/etc/salt/master.d/api.conf）：

# /etc/salt/master.d/api.conf 示例
rest_cherrypy:
  port: 8000  # API监听端口
  host: 0.0.0.0  # 监听地址（0.0.0.0表示允许所有网络访问）
  ssl_crt: /etc/salt/certs/server.crt  # SSL证书路径
  ssl_key: /etc/salt/certs/server.key  # SSL私钥路径
  disable_ssl: False  # 启用HTTPS（设为True则禁用）
external_auth:
  pam:  # 使用PAM认证（其他选项：ldap、file等）
    admin:  # 允许认证的用户（需在容器内存在对应系统用户）
      - .*  # 允许执行所有Salt命令
      - '@runner'  # 允许访问runner模块
      - '@wheel'  # 允许访问wheel模块

配置参数说明

核心配置项（api.conf）

环境变量

认证与API调用示例

启用PAM认证（容器内配置）

1. 进入容器并创建测试用户：

   docker exec -it salt-api bash
   useradd -m saltuser && passwd saltuser  # 设置密码（如：saltpass123）
   

2. 更新/etc/salt/master.d/api.conf，添加用户权限：

   external_auth:
     pam:
       saltuser:  # 新增用户
         - '*'  # 允许执行所有命令
   

3. 重启容器使配置生效：docker restart salt-api

调用API示例（获取minion列表）

# 使用curl发送HTTPS请求（-k忽略证书验证，生产环境建议使用可信证书）
curl -k -X GET "https://localhost:8000/minions" \
  -H "Accept: application/json" \
  -u saltuser:saltpass123  # PAM认证用户密码

执行Salt命令示例（测试minion连通性）

curl -k -X POST "https://localhost:8000/run" \
  -H "Content-Type: application/json" \
  -u saltuser:saltpass123 \
  -d '{
    "client": "local", 
    "tgt": "*",  # 目标minion（*表示所有）
    "fun": "test.ping"  # Salt模块函数（测试连通性）
  }'

成功响应示例：

{
  "return": [
    {
      "minion1": true,
      "minion2": true
    }
  ]
}