fusion-roles-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fusion Roles CLI

When to use

适用场景

Use when Fusion Roles V2 resources (roles, bindings, assignments, scope types) need to be created or updated from a config file, or when existing role state needs to be inspected or exported.

Typical triggers:

"Deploy the roles config for my service"
"Create roles from this JSON file"
"Export the current role config for fusion-myservice"
"What does a roles config file look like?"
"Add a binding for this Entra group"
"Check what roles are assigned to this account"
"Dry-run the role deployment"

当需要从配置文件创建或更新Fusion Roles V2资源（角色、绑定、分配、作用域类型），或者需要查看或导出现有角色状态时使用。

典型触发场景：

"部署我的服务的角色配置"
"从这个JSON文件创建角色"
"导出fusion-myservice的当前角色配置"
"角色配置文件是什么样的？"
"为这个Entra组添加绑定"
"查看该账户被分配了哪些角色"
"试运行角色部署"

When not to use

不适用场景

Database provisioning — use
```
fusion-infra-cli
```
Managing Azure AD groups themselves — use the Azure portal or Graph API
Roles V1 (legacy system) — this tool targets Roles V2 only
Application code changes

数据库配置 — 使用
```
fusion-infra-cli
```
管理Azure AD组本身 — 使用Azure门户或Graph API
Roles V1（旧系统） — 本工具仅针对Roles V2
应用代码变更

Prerequisites

前置条件

Install

froles

as a .NET global tool:

bash

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

Update to latest:

bash

froles --update

Auth uses

DefaultAzureCredential

automatically (picks up

az login

session). Pass

-t <token>

to override.

将

froles

安装为.NET全局工具：

bash

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

更新至最新版本：

bash

froles --update

认证自动使用

DefaultAzureCredential

（会获取

az login

会话）。可通过传递

-t <token>

来覆盖默认设置。

Core workflow — deploy a role config

核心工作流 — 部署角色配置

1. Create the config file

1. 创建配置文件

The config file is a JSON file declaring all role resources for your system. Always include the

$schema

reference — it enables editor validation and autocompletion.

Minimal example (

roles-config.json

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" }
      ]
    }
  ]
}

See references/role-config-schema.md for the full schema with all resource types and field definitions.

配置文件是一个JSON文件，声明系统的所有角色资源。务必包含

$schema

引用 — 它能启用编辑器验证和自动补全功能。

极简示例（

roles-config.json

）：

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" }
      ]
    }
  ]
}

查看references/role-config-schema.md获取包含所有资源类型和字段定义的完整 schema。

2. Dry-run to verify changes

2. 试运行以验证变更

Always dry-run before deploying to catch unexpected changes:

bash

froles create -e ci --file roles-config.json --dry-run

The dry-run shows exactly what will be created, patched, or left unchanged — including binding diffs showing added/removed roles.

部署前务必进行试运行，以发现意外变更：

bash

froles create -e ci --file roles-config.json --dry-run

试运行会准确显示将要创建、修补或保持不变的内容 — 包括显示新增/移除角色的绑定差异。

3. Deploy

3. 部署

bash

undefined

bash

undefined

CI

froles create -e ci --file roles-config.json

QA

froles create -e fqa --file roles-config.json

Production

froles create -e fprd --file roles-config.json


`create` is **idempotent** — safe to run repeatedly. Resources are matched on natural keys; only changed fields are patched.

froles create -e fprd --file roles-config.json


`create`命令具有**幂等性** — 可安全重复运行。资源通过自然键匹配；仅修补已更改的字段。

4. Export current state (optional)

4. 导出当前状态（可选）

To export the current configuration for a system (useful for initial onboarding or auditing):

bash

froles export my-service -e ci -o current-state.json

The export file can be modified and fed back into

create

要导出某个系统的当前配置（适用于初始接入或审计）：

bash

froles export my-service -e ci -o current-state.json

导出的文件可修改后重新传入

create

命令使用。

Reconciliation behaviour

协调行为

The

create

command reconciles each resource type against its natural key:

Resource	Natural key	Behaviour
Scope types	`name`	Create if missing; patch `description` if changed
Access roles	`systemIdentifier` + `name`	Create if missing; patch if changed
Roles / claimable roles	`name`	Create if missing; patch if changed; access role mappings fully reconciled
Bindings	`identifier`	Patch all fields; diff shows role/group additions and removals
Role assignments	`roleIdentifier` + `source` + `externalIdentifier`	Create if missing; skip if exists

Important: Access role mappings on roles/claimable roles are fully reconciled — mappings absent from the config are removed. Only access roles belonging to systems declared in the config file are managed.

create

命令会根据自然键协调每种资源类型：

资源	自然键	行为
作用域类型	`name`	不存在则创建；若 `description` 变更则修补
访问角色	`systemIdentifier` + `name`	不存在则创建；变更则修补
角色 / 可申领角色	`name`	不存在则创建；变更则修补；访问角色映射会被完全协调
绑定	`identifier`	修补所有字段；差异会显示角色/组的新增和移除
角色分配	`roleIdentifier` + `source` + `externalIdentifier`	不存在则创建；已存在则跳过

重要提示：角色/可申领角色的访问角色映射会被完全协调 — 配置文件中未包含的映射会被移除。仅管理配置文件中声明的系统所属的访问角色。

Environments

环境

Key	Purpose
`ci`	Continuous integration
`fqa`	QA / pre-production
`fprd`	Production
`tr`	Training environment

键	用途
`ci`	持续集成
`fqa`	QA / 预生产
`fprd`	生产
`tr`	培训环境

Full reference

完整参考

For complete command and flag reference, run:

bash

froles --help
froles create --help

Or see the source documentation:

如需完整的命令和参数参考，运行：

bash

froles --help
froles create --help

或查看源文档：

Safety

安全注意事项

Always dry-run before deploying to production
Access role mapping reconciliation removes unmapped roles — review the dry-run output carefully
Never store tokens in config files; always use
```
-t <token>
```
from a secret variable in pipelines
```
delete role-assignments
```
is destructive — confirm with user and dry-run first

部署到生产环境前务必进行试运行
访问角色映射协调会移除未映射的角色 — 请仔细检查试运行输出
切勿将令牌存储在配置文件中；始终从流水线的秘密变量中使用
```
-t <token>
```
```
delete role-assignments
```
具有破坏性 — 请先确认用户操作并进行试运行

{ "$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" } ] } ] }

Resource

Natural key

Behaviour

Scope types

name

Create if missing; patch

description

if changed

Access roles

systemIdentifier

name

Create if missing; patch if changed

Roles / claimable roles

name

Create if missing; patch if changed; access role mappings fully reconciled

Bindings

identifier

Patch all fields; diff shows role/group additions and removals

Role assignments

roleIdentifier

source

externalIdentifier

Create if missing; skip if exists

资源

自然键

行为

作用域类型

name

不存在则创建；若

description

变更则修补

访问角色

systemIdentifier

name

不存在则创建；变更则修补

角色 / 可申领角色

name

不存在则创建；变更则修补；访问角色映射会被完全协调

绑定

identifier

修补所有字段；差异会显示角色/组的新增和移除

角色分配

roleIdentifier

source

externalIdentifier

不存在则创建；已存在则跳过

Key

Purpose

ci

Continuous integration

fqa

QA / pre-production

fprd

Production

tr

Training environment

键

用途

ci

持续集成

fqa

QA / 预生产

fprd

生产

tr

培训环境