什么是 Speedle 策略?
策略管理服务(PMS)管理服务、授权策略、角色策略与自定义函数,由已注册的存储后端持久化这些对象。

服务与授权策略
服务限定策略的作用范围。授权策略允许或拒绝主体对资源执行操作,并可附带条件。除全局角色策略外,一个服务的策略不会自动在另一个服务中生效。

grant group Administrators list,watch,get expr:^c1/default/core/pods/.*$此正则只匹配 c1/default/core/pods/ 下的资源,不匹配 c1/default/core/podssecret 或带额外前缀的路径。expr: 使用正则表达式,不是 shell 通配符:任意字符使用 .*,需要匹配完整标识符时加 ^、$。
角色策略

grant user alan manager on res1
grant role manager update res1第一行把指定资源上的角色分配给 Alan,第二行才为该角色授予操作权限。仅分配角色不会自动产生权限。适用的显式拒绝优先于允许。
主体与条件
主体可以是用户、组、实体或角色。实体表示服务等非人身份,集成代码必须从可信来源获取这些身份。

AND 主体组要求组内所有身份均匹配,多组之间为 OR。以下例子要求两个角色都有效:

grant (role designer, role dba) update db_design_doc资源指需要保护的对象,操作是应用定义的动作。条件是由可信属性、常量、运算符和受支持函数构成的布尔表达式。

运行示例前
先按快速入门编译仓库根目录下的 ./bin/spctl、./bin/speedle-pms 和 ./bin/speedle-ads,需要 Go 1.26.10 或 Go 1.27.3(也可使用同一大版本的更新补丁版本)、Bash、curl 和 Python 3。下面各终端都从仓库根目录运行。为本页使用一个新的策略文件;仅在两个服务都停止后重建该文件。
初始化空策略文件:
printf '{}\n' > docs-policies.jsonmacOS:
/usr/sbin/spctl是 Apple 的 Gatekeeper 工具,直接运行spctl时可能会选中它。请使用 Speedle CLI 的完整路径,或在其所在目录中用./spctl调用;下面的示例统一使用./bin/spctl。运行command -v spctl可查看 shell 实际选择的可执行程序。如果下载的发布版本包含speedle-spctl_<os>_<arch>文件,它就是同一个 CLI,只是名称不会与 Apple 的工具冲突。
终端一启动 PMS,并保持运行:
./bin/speedle-pms --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6733 --grpc-endpoint 127.0.0.1:0 --insecure=true终端二启动 ADS,并保持运行:
./bin/speedle-ads --store-type file --filestore-loc ./docs-policies.json --endpoint 127.0.0.1:6734 --grpc-endpoint 127.0.0.1:0 --insecure=true在第三个终端运行后续命令。PMS/ADS 共享同一个文件,策略更新通过 watch 异步到达 ADS;先查询确认已更新,再依赖新策略做决策。--insecure=true 仅用于回环地址上的本地示例,生产连接见安全配置。示例显式指定 PMS 地址,不修改 ~/.spctlconfig。完成后在两个服务终端按 Ctrl-C。
使用 spctl 管理服务与策略
在新存储上按顺序执行。ID 从实际查询响应中取得,不使用历史输出里的固定值。所有依赖服务的操作完成后,再删除服务。
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ create service test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get service test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get service --all
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ create policy policy1 -c "grant user alan read book" --service-name test
policy_id=$(./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get policy --all --service-name test | python3 -c 'import json,sys; print(next(p["id"] for p in json.load(sys.stdin) if p.get("name")=="policy1"))')
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get policy "$policy_id" --service-name test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ create rolepolicy rolepolicy01 -c "grant user alan manager on res1" --service-name test
role_policy_id=$(./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get rolepolicy --all --service-name test | python3 -c 'import json,sys; print(next(p["id"] for p in json.load(sys.stdin) if p.get("name")=="rolepolicy01"))')
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ get rolepolicy "$role_policy_id" --service-name test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ delete policy "$policy_id" --service-name test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ delete rolepolicy "$role_policy_id" --service-name test
./bin/spctl --pms-endpoint http://127.0.0.1:6733/policy-mgmt/v1/ delete service testSpeedle Cloud
Speedle Cloud 登录即将开放。API 令牌开放后,spctl 可以通过与自托管 PMS 相同的命令管理 Cloud 中的 service 和策略。管理端点为:
https://cloud.speedle.io/policy-mgmt/v1请根据命令选择具有相应 scope 的 API 令牌。pms:read 用于 get 和 discover 查询,pms:write 用于 create、delete 和发现记录重置。只有 ADS scope 的令牌不能管理策略,服务端会返回 403 insufficient_scope。
通过全局命令行参数指定端点,并从 SPCTL_TOKEN 环境变量读取令牌。在交互式 shell 中,以下方式可避免将 secret 写入命令参数和 shell 历史:
read -rsp 'API token: ' SPCTL_TOKEN; echo
export SPCTL_TOKEN
./bin/spctl --pms-endpoint https://cloud.speedle.io/policy-mgmt/v1 get service --all
unset SPCTL_TOKEN--token 参数仍为兼容现有用法而保留,但环境变量可避免通过命令参数暴露令牌。每个全局参数都有对应的环境变量:添加 SPCTL_ 前缀,将参数名转为大写,并把连字符替换为下划线。例如,SPCTL_PMS_ENDPOINT 对应 pms-endpoint,SPCTL_SKIPVERIFY 对应 skipverify。
如需保存配置,请使用 ~/.speedle。文件每行包含一个 名称=值 配置项,名称与命令行参数一致:
pms-endpoint=https://cloud.speedle.io/policy-mgmt/v1
token=<api-token>以下方式可在不把令牌写入命令参数的情况下创建或更新此文件:
read -rsp 'API token: ' SPCTL_TOKEN; echo
printf '%s\n' "$SPCTL_TOKEN" | ./bin/spctl config token --stdin
unset SPCTL_TOKENspctl config token --stdin 会以 0600 权限写入 ~/.speedle。手动编辑此文件时,先用 install -m 600 /dev/null ~/.speedle 创建文件,或在编辑后运行 chmod 0600 ~/.speedle。如果 spctl 从允许 group 或其他用户访问的文件中读取令牌,会向标准错误输出警告。spctl config --list 会把已配置的令牌显示为 ********。
显式命令行参数优先于环境变量,环境变量优先于两个配置文件。在配置文件中,~/.speedle 优先于 ~/.spctlconfig。通过 spctl config 设置非令牌配置时,新值写入 ~/.spctlconfig,同时删除 ~/.speedle 中会覆盖新值的同名配置。
令牌仅在启用证书验证的 HTTPS 连接中以 Authorization: Bearer 凭据发送。只有 127.0.0.1、::1 或 localhost 等回环主机可以在携带令牌时使用纯 HTTP;对于远程 HTTP 端点以及从 HTTPS 降级到 HTTP 的重定向,spctl 会在发送凭据前拒绝请求。对于 HTTPS 端点,spctl 也拒绝在 --skipverify=true 时发送令牌;对于私有或自签名证书颁发机构,请使用 --cacert 配置信任。正常命令输出和错误信息不会包含令牌。
Cloud 返回错误时,命令以非零状态退出。遇到 401 请检查令牌,遇到 403 insufficient_scope 请检查 scope。404 表示资源不存在,409 service_exists 和 409 policy_exists 表示资源重复。遇到 429 时,请遵循响应中的 Retry-After,并采用有界退避。每日额度或策略额度错误需要等待额度重置或减少用量,不要紧密循环重试。
其他管理接口
PMS REST API使用 JSON,返回包含字符串 ID 的扁平策略对象。Go 应用可直接使用 PMS 接口,gRPC 客户端使用公开的 PMS proto。管理操作必须配置传输安全与调用方访问控制。