Fusion Roles CLI
用途
当需要从配置文件创建或更新 Fusion Roles V2 资源（角色、绑定、分配、范围类型），或者需要检查、导出已有角色状态时使用。该工具仅针对 Roles V2。
典型触发场景包括：部署某个服务的角色配置、从 JSON 文件创建角色、导出 fusion-myservice 当前的角色配置、了解角色配置文件的形式、为某个 Entra 组添加绑定、检查某个账户被分配了哪些角色、对角色部署进行预演。
不适用场景：数据库配置（应使用 fusion-infra-cli）、管理 Azure AD 组本身（应使用 Azure 门户或 Graph API）、Roles V1（旧系统）、应用代码变更。
先决条件
安装 froles 为 .NET 全局工具：
dotnet tool install --global
--add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json"
Fusion.Roles.Cli
更新到最新版本：
froles --update
认证默认自动使用 DefaultAzureCredential（会沿用 az login 会话）。可通过 -t <token> 覆盖。
核心工作流：部署角色配置
- 创建配置文件
配置文件是一个 JSON 文件，用于声明系统的所有角色资源。请始终包含 $schema 引用，以便编辑器进行校验和自动补全。
最小示例（roles-config.json）：
{ "$schema": "https://rolesv2.api.fusion.equinor.com/public/schemas/role-config.schema.json", "accessRoles": [ { "systemIdentifier": "my-service", "name": "MyService.Project.Read", "description": "Read access to project resources" } ], "roles": [ { "name": "project-viewer", "displayName": "Project Viewer", "accessRoleMappings": [ { "accessRoleIdentifier": "MyService.Project.Read" } ] } ] }
完整 schema 及所有资源类型和字段定义见 references/role-config-schema.md。
- 预演以验证变更
部署前务必先预演，以发现意外变更：
froles create -e ci --file roles-config.json --dry-run
预演会精确显示将要创建、修补或保持不变的内容，包括显示角色增删的绑定差异。
- 部署
CI
froles create -e ci --file roles-config.json
QA
froles create -e fqa --file roles-config.json
生产
froles create -e fprd --file roles-config.json
create 是幂等的，可安全反复运行。资源按自然键匹配，仅对发生变化的字段进行修补。
- 导出当前状态（可选）
导出某个系统的当前配置（适用于初始接入或审计）：
froles export my-service -e ci -o current-state.json
导出文件可修改后再通过 create 提交。
协调行为
create 命令按自然键对每种资源类型进行协调：
- 范围类型：自然键为 name；缺失则创建，描述变化则修补。
- 访问角色：自然键为 systemIdentifier + name；缺失则创建，变化则修补。
- 角色/可声明角色：自然键为 name；缺失则创建，变化则修补，访问角色映射完整协调。
- 绑定：自然键为 identifier；修补所有字段，差异显示角色/组的增删。
- 角色分配：自然键为 roleIdentifier + source + externalIdentifier；缺失则创建，已存在则跳过。
重要：角色/可声明角色上的访问角色映射会被完整协调，配置中缺失的映射会被移除。仅管理配置文件中声明系统的访问角色。
环境
- ci：持续集成
- fqa：QA/预生产
- fprd：生产
- tr：培训环境
完整参考
查完完整命令和参数参考，可运行：
froles --help froles create --help
或查看源文档：README.md、USING_CREATE_COMMAND.md。来源：tooling/fusion-roles-cli。
安全注意事项
- 部署到生产前务必先预演。
- 访问角色映射协调会移除未映射的角色，请仔细检查预演输出。
- 切勿将令牌存入配置文件；在流水线中应始终从密钥变量通过 -t <token> 传入。
- delete role-assignments 是破坏性操作，请先与用户确认并预演。