perses-project-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Perses Project Management

Perses 项目管理

Create and manage projects with RBAC configuration.

创建并管理带有RBAC配置的项目。

Operator Context

操作器上下文

This skill operates as the lifecycle manager for Perses projects and their RBAC configuration, handling project creation, role definitions, and role bindings. A Project in Perses is an organizational container that groups dashboards, datasources, variables, and other resources. When running via the Perses Operator on Kubernetes, each project maps to a K8s namespace.

该技能作为Perses项目及其RBAC配置的生命周期管理器，处理项目创建、角色定义和角色绑定。Perses中的项目是一个组织容器，用于分组仪表板、数据源、变量和其他资源。当在Kubernetes上通过Perses Operator运行时，每个项目对应一个K8s Namespace。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

MCP-first: Use Perses MCP tools when available, percli as fallback
RBAC awareness: When creating projects in production, always set up roles and bindings — an unprotected project allows any authenticated user full access
Project context: Always verify/set active project with
```
percli project
```
before operating on project-scoped resources — wrong project context silently applies resources to the wrong project
Verify before declare: After creating any resource (project, role, binding), verify it exists with a list or describe command before reporting success

MCP优先：优先使用可用的Perses MCP工具，fallback为percli
RBAC感知：在生产环境中创建项目时，始终设置角色和绑定——未受保护的项目允许任何已认证用户拥有完全访问权限
项目上下文：在操作项目范围的资源之前，始终使用
```
percli project
```
验证/设置活动项目——错误的项目上下文会将资源静默应用到错误的项目
先验证再声明：创建任何资源（项目、角色、绑定）后，在报告成功之前，使用列表或描述命令验证其存在

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则启用）

Simple create: Create project with default settings unless RBAC is requested
Set active: After creating a project, set it as the active project context

简单创建：除非请求RBAC，否则使用默认设置创建项目
设置为活动项目：创建项目后，将其设置为活动项目上下文

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则关闭）

RBAC setup: Create roles and role bindings alongside project creation
Multi-project: Create multiple projects in batch for team onboarding

RBAC设置：在创建项目的同时创建角色和角色绑定
多项目批量创建：批量创建多个项目用于团队入职

What This Skill CAN Do

该技能可以完成的操作

Create, list, describe, and delete projects
Set up roles with granular permissions (read/create/update/delete on specific resource types)
Create role bindings to assign users or groups to roles
Switch active project context
Manage global roles and global role bindings

创建、列出、描述和删除项目
设置具有细粒度权限的角色（对特定资源类型的读/创建/更新/删除权限）
创建角色绑定以将用户或组分配到角色
切换活动项目上下文
管理全局角色和全局角色绑定

What This Skill CANNOT Do

该技能无法完成的操作

Manage user accounts (that's Perses server admin configuration)
Configure authentication providers (use perses-deploy)
Create dashboards or datasources (use perses-dashboard-create, perses-datasource-manage)

管理用户账户（这属于Perses服务器管理员配置的范畴）
配置认证提供商（请使用perses-deploy）
创建仪表板或数据源（请使用perses-dashboard-create、perses-datasource-manage）

Error Handling

错误处理

Project creation fails

项目创建失败

Symptom	Cause	Fix
"already exists" / 409 Conflict	Project name is already taken	List existing projects with `percli get project` or `perses_list_projects()` and use a different name, or operate on the existing project
"invalid name" / 400 Bad Request	Project name contains invalid characters (uppercase, spaces, special chars)	Use lowercase alphanumeric names with hyphens only (e.g., `my-project` ). Perses follows DNS label conventions
"unauthorized" / 401	Not authenticated or session token expired	Run `percli login` first, or verify MCP server auth config has valid credentials
"forbidden" / 403	Authenticated user lacks permission to create projects	User needs a GlobalRole with `create` action on Project scope, or admin access

症状	原因	解决方法
"already exists" / 409 Conflict	项目名称已被占用	使用 `percli get project` 或 `perses_list_projects()` 列出现有项目，使用不同名称或操作现有项目
"invalid name" / 400 Bad Request	项目名称包含无效字符（大写、空格、特殊字符）	仅使用小写字母数字和连字符（例如： `my-project` ）。Perses遵循DNS标签规范
"unauthorized" / 401	未认证或会话令牌过期	先运行 `percli login` ，或验证MCP服务器认证配置是否有有效凭据
"forbidden" / 403	已认证用户缺少创建项目的权限	用户需要具有Project范围 `create` 操作权限的GlobalRole，或管理员访问权限

Role and RoleBinding creation fails

角色和角色绑定创建失败

Symptom	Cause	Fix
"role not found" in RoleBinding apply	The role referenced in `spec.role` does not exist	Create the Role first, then create the RoleBinding. Verify role exists with `percli get role --project <name>`
"subject not found" / binding has no effect	User or group name in subjects does not match any identity in the auth provider	Verify user identity with the configured auth provider (Native, OIDC, OAuth). For native auth, the username is the login name
"project not found" in role metadata	The project specified in `metadata.project` does not exist	Create the project first, or fix the project name in the role definition
GlobalRole apply returns 403	User does not have cluster-level admin permissions	GlobalRole and GlobalRoleBinding require admin-level access; escalate to a Perses admin

症状	原因	解决方法
RoleBinding应用时出现"role not found"	`spec.role` 中引用的角色不存在	先创建Role，再创建RoleBinding。使用 `percli get role --project <name>` 验证角色是否存在
"subject not found" / 绑定无效果	主体中的用户或组名称与认证提供商中的任何身份不匹配	与配置的认证提供商（Native、OIDC、OAuth）验证用户身份。对于原生认证，用户名是登录名
角色元数据中出现"project not found"	`metadata.project` 中指定的项目不存在	先创建项目，或修正角色定义中的项目名称
应用GlobalRole返回403	用户缺少集群级管理员权限	GlobalRole和GlobalRoleBinding需要管理员级访问权限；请联系Perses管理员提升权限

Wrong project context

错误的项目上下文

Symptom	Cause	Fix
Resources appear in wrong project	`percli project` was set to a different project than intended	Always run `percli project <name>` immediately before applying project-scoped resources
"project not set" error	No active project context configured	Run `percli project <name>` to set the active project
Role/binding created but permissions don't work	RoleBinding references a role from a different project	Ensure role and binding are in the same project; check `metadata.project` on both

症状	原因	解决方法
资源出现在错误的项目中	`percli project` 被设置为其他项目	在应用项目范围的资源之前，始终立即运行 `percli project <name>`
"project not set"错误	未配置活动项目上下文	运行 `percli project <name>` 设置活动项目
角色/绑定已创建但权限不生效	RoleBinding引用了其他项目的角色	确保角色和绑定在同一个项目中；检查两者的 `metadata.project`

MCP tool failures

MCP工具故障

Symptom	Cause	Fix
`perses_create_project` returns read-only error	Perses server has `security.readonly: true` in config	Ask user to disable read-only mode, or switch to a writable instance
MCP tool returns connection refused	MCP server cannot reach Perses API	Check MCP server config URL and ensure Perses server is running at that address
MCP list returns empty but projects exist	MCP auth credentials lack read permission	Verify MCP server auth config; the configured user needs at least read access

症状	原因	解决方法
`perses_create_project` 返回只读错误	Perses服务器配置中 `security.readonly: true`	请用户禁用只读模式，或切换到可写实例
MCP工具返回连接拒绝	MCP服务器无法连接到Perses API	检查MCP服务器配置URL，确保Perses服务器在该地址运行
MCP列表返回空但项目实际存在	MCP认证凭据缺少读权限	验证MCP服务器认证配置；配置的用户至少需要读访问权限

Anti-Patterns

反模式

Anti-Pattern	Why It Fails	Correct Approach
Creating projects without RBAC in production — skipping role and binding setup	Any authenticated user gets full read/write/delete access to the project's resources	Always create at least a viewer role and an admin role with bindings for production projects
Not setting active project before applying resources — relying on "whatever was last set"	Resources silently apply to the wrong project; no error is raised	Run `percli project <name>` immediately before every `percli apply` for project-scoped resources
Using GlobalRole for project-scoped permissions — granting org-wide access when project-level suffices	Violates principle of least privilege; users get access to all projects instead of just one	Use project-scoped Role for project-specific permissions; reserve GlobalRole for truly organization-wide needs
Creating RoleBindings without verifying the role exists — assuming role was created in a prior step	Binding references a non-existent role; no permissions are granted; no error may surface until access is denied	Always verify role existence with `percli get role --project <name>` before creating bindings
Deleting a project without checking for active dashboards — removing a project that contains resources	All dashboards, datasources, variables, and other resources in the project are permanently deleted	List project contents with `percli get dashboard --project <name>` before deletion; confirm with user

反模式	失败原因	正确做法
生产环境中创建项目不配置RBAC — 跳过角色和绑定设置	任何已认证用户都可以对项目资源进行完全的读/写/删除操作	对于生产项目，始终至少创建一个查看者角色和一个管理员角色并配置绑定
应用资源前不设置活动项目 — 依赖“上次设置的项目”	资源被静默应用到错误的项目；不会引发错误	在每次应用项目范围资源的 `percli apply` 之前，立即运行 `percli project <name>`
使用GlobalRole实现项目范围权限 — 需要项目级权限时授予全组织访问权限	违反最小权限原则；用户将获得所有项目的访问权限，而不仅仅是一个	对项目特定权限使用项目范围的Role；仅在确实需要全组织范围权限时使用GlobalRole
不验证角色是否存在就创建RoleBindings — 假设角色已在之前的步骤中创建	绑定引用不存在的角色；不会授予权限；直到访问被拒绝时才会发现问题	在创建绑定之前，始终使用 `percli get role --project <name>` 验证角色是否存在
不检查活动仪表板就删除项目 — 删除包含资源的项目	项目中的所有仪表板、数据源、变量和其他资源将被永久删除	删除前使用 `percli get dashboard --project <name>` 列出项目内容；并与用户确认

Anti-Rationalization

常见错误借口

Rationalization	Why It's Wrong	Required Action
"The project was just created, RBAC can wait"	In the gap between creation and RBAC setup, any authenticated user has full access to the project	Set up RBAC immediately after project creation for production environments
"I already set the project context earlier"	Context may have changed if other commands ran between setting it and applying resources	Re-run `percli project <name>` before every apply — it costs nothing and prevents silent misapplication
"The role name looks right, skip the verify step"	Typos in role names fail silently in RoleBindings — the binding is created but grants nothing	Run `percli get role --project <name>` and confirm the exact role name before creating bindings
"GlobalRole is simpler than per-project roles"	Simpler setup, but violates least-privilege and gives access across every project	Use project-scoped Roles unless the permission genuinely needs to span all projects
"MCP created it so it must exist"	MCP tool may return success on a stale or cached response; network issues can cause partial creates	Verify with a list or describe command after every create operation

错误借口	错误原因	必要操作
"项目刚创建，RBAC可以稍后再配置"	在创建和RBAC设置之间的空档期，任何已认证用户都拥有项目的完全访问权限	生产环境中创建项目后立即配置RBAC
"我之前已经设置过项目上下文了"	如果在设置和应用资源之间运行了其他命令，上下文可能已更改	每次应用前重新运行 `percli project <name>` — 这不会产生任何成本，且能防止静默错误应用
"角色名称看起来正确，跳过验证步骤"	角色名称中的拼写错误会导致RoleBindings静默失败 — 绑定会被创建但不授予任何权限	创建绑定前运行 `percli get role --project <name>` 并确认角色名称完全正确
"GlobalRole比每个项目单独配置Role更简单"	设置更简单，但违反最小权限原则，会授予用户所有项目的访问权限	使用项目范围的Role 除非权限确实需要覆盖所有项目
"MCP创建了它，所以它肯定存在"	MCP工具可能返回缓存的成功响应；网络问题可能导致部分创建失败	每次创建操作后使用列表或描述命令验证

FORBIDDEN Patterns

禁止模式

NEVER apply project-scoped resources without first confirming the active project context — silent wrong-project application is the most common error
NEVER create production projects without at least one Role and RoleBinding — unprotected projects are open to all authenticated users
NEVER use wildcard (
```
"*"
```
) in GlobalRole scopes without explicit user approval — this grants access to every resource type across every project
NEVER hardcode user email addresses or identities in skill output — always use placeholder values and let the user supply real identities
NEVER delete projects without listing their contents first and confirming with the user

绝对不要在未确认活动项目上下文的情况下应用项目范围的资源 — 静默错误应用到错误项目是最常见的错误
绝对不要在生产环境中创建没有至少一个Role和RoleBinding的项目 — 未受保护的项目对所有已认证用户开放
绝对不要在未获得用户明确批准的情况下在GlobalRole范围中使用通配符（
```
"*"
```
） — 这会授予所有项目所有资源类型的访问权限
绝对不要在技能输出中硬编码用户邮箱地址或身份 — 始终使用占位符值，让用户提供真实身份
绝对不要在未先列出项目内容并与用户确认的情况下删除项目

Blocker Criteria

阻塞条件

Stop and ask the user before proceeding if:

Auth provider type is unknown — role binding subject
```
kind
```
(User vs Group) depends on auth configuration
Target environment (dev vs production) is ambiguous — determines whether RBAC setup is required
Project name conflicts with an existing project — user must decide: reuse existing or rename
User wants GlobalRole with wildcard scopes — requires explicit confirmation due to security implications
MCP server is in read-only mode — cannot create projects or roles; user must change server config

在继续之前，请先询问用户如果：

认证提供商类型未知 — 角色绑定主体
```
kind
```
（User vs Group）取决于认证配置
目标环境（开发 vs 生产）不明确 — 决定是否需要配置RBAC
项目名称与现有项目冲突 — 用户必须决定：重用现有项目或重命名
用户想要带有通配符范围的GlobalRole — 由于安全影响，需要明确确认
MCP服务器处于只读模式 — 无法创建项目或角色；用户必须更改服务器配置

Instructions

操作步骤

Phase 1: CREATE PROJECT

阶段1：创建项目

Goal: Create a new Perses project.

Via percli:

bash

percli apply -f - <<EOF
kind: Project
metadata:
  name: <project-name>
spec: {}
EOF

目标：创建一个新的Perses项目。

通过percli:

bash

percli apply -f - <<EOF
kind: Project
metadata:
  name: <project-name>
spec: {}
EOF

Set as active project

设置为活动项目

percli project <project-name>


**Via MCP** (preferred):

perses_create_project(project="<project-name>")


**Gate**: Project created and set as active context. Proceed to Phase 2 if RBAC is needed, otherwise task complete.

percli project <project-name>


**通过MCP**（优先）:

perses_create_project(project="<project-name>")


**检查点**：项目已创建并设置为活动上下文。如果需要RBAC，继续到阶段2，否则任务完成。

Phase 2: CONFIGURE RBAC (optional)

阶段2：配置RBAC（可选）

Goal: Set up roles and role bindings for access control.

Step 1: Create a role

Roles define what actions are allowed on which resource types within a project:

bash

percli apply -f - <<EOF
kind: Role
metadata:
  name: dashboard-editor
  project: <project-name>
spec:
  permissions:
    - actions: [read, create, update]
      scopes: [Dashboard, Datasource, Variable]
EOF

Available actions: read, create, update, delete

Available scopes (resource types): Dashboard, Datasource, EphemeralDashboard, Folder, Role, RoleBinding, Secret, Variable

For organization-wide roles, use GlobalRole:

bash

percli apply -f - <<EOF
kind: GlobalRole
metadata:
  name: org-viewer
spec:
  permissions:
    - actions: [read]
      scopes: ["*"]
EOF

Step 2: Create a role binding

Role bindings assign users or groups to roles:

bash

percli apply -f - <<EOF
kind: RoleBinding
metadata:
  name: team-editors
  project: <project-name>
spec:
  role: dashboard-editor
  subjects:
    - kind: User
      name: user@example.com
EOF

For global role bindings:

bash

percli apply -f - <<EOF
kind: GlobalRoleBinding
metadata:
  name: org-viewers
spec:
  role: org-viewer
  subjects:
    - kind: User
      name: viewer@example.com
EOF

Gate: Roles and bindings created. Proceed to Phase 3.

目标：设置用于访问控制的角色和角色绑定。

步骤1：创建角色

角色定义了项目内对特定资源类型允许的操作：

bash

percli apply -f - <<EOF
kind: Role
metadata:
  name: dashboard-editor
  project: <project-name>
spec:
  permissions:
    - actions: [read, create, update]
      scopes: [Dashboard, Datasource, Variable]
EOF

可用操作：read, create, update, delete

可用范围（资源类型）：Dashboard, Datasource, EphemeralDashboard, Folder, Role, RoleBinding, Secret, Variable

对于全组织范围的角色，使用GlobalRole:

bash

percli apply -f - <<EOF
kind: GlobalRole
metadata:
  name: org-viewer
spec:
  permissions:
    - actions: [read]
      scopes: ["*"]
EOF

步骤2：创建角色绑定

角色绑定用于将用户或组分配到角色：

bash

percli apply -f - <<EOF
kind: RoleBinding
metadata:
  name: team-editors
  project: <project-name>
spec:
  role: dashboard-editor
  subjects:
    - kind: User
      name: user@example.com
EOF

对于全局角色绑定:

bash

percli apply -f - <<EOF
kind: GlobalRoleBinding
metadata:
  name: org-viewers
spec:
  role: org-viewer
  subjects:
    - kind: User
      name: viewer@example.com
EOF

检查点：角色和绑定已创建。继续到阶段3。

Phase 3: VERIFY

阶段3：验证

Goal: Confirm project, roles, and bindings are correctly configured.

bash

undefined

目标：确认项目、角色和绑定已正确配置。

bash

undefined

List projects

列出项目

percli get project

Describe project

描述项目

percli describe project <project-name>

List roles in project

列出项目中的角色

percli get role --project <project-name>

List role bindings in project

列出项目中的角色绑定

percli get rolebinding --project <project-name>

List global roles

列出全局角色

percli get globalrole

List global role bindings

列出全局角色绑定

percli get globalrolebinding


Or via MCP:

perses_list_projects() perses_list_project_roles(project="<project-name>") perses_list_project_role_bindings(project="<project-name>") perses_list_global_roles()


**Gate**: Project listed, roles and bindings confirmed. Task complete.

---

percli get globalrolebinding


或通过MCP:

perses_list_projects() perses_list_project_roles(project="<project-name>") perses_list_project_role_bindings(project="<project-name>") perses_list_global_roles()


**检查点**：项目已列出，角色和绑定已确认。任务完成。

---

References

参考资料

Resource	URL
Perses Project API docs	https://perses.dev/docs/api/project/
Perses RBAC documentation	https://perses.dev/docs/user-guides/security/rbac/
Perses Authentication docs	https://perses.dev/docs/user-guides/security/authentication/
percli CLI reference	https://perses.dev/docs/user-guides/percli/
Perses MCP server	https://github.com/perses/perses-mcp-server
Perses Operator (project-to-namespace mapping)	https://github.com/perses/perses-operator

资源	URL
Perses Project API文档	https://perses.dev/docs/api/project/
Perses RBAC文档	https://perses.dev/docs/user-guides/security/rbac/
Perses认证文档	https://perses.dev/docs/user-guides/security/authentication/
percli CLI参考	https://perses.dev/docs/user-guides/percli/
Perses MCP服务器	https://github.com/perses/perses-mcp-server
Perses Operator（项目到Namespace的映射）	https://github.com/perses/perses-operator