如何创建自定义平台角色

1. 概述 2. 核心概念 3. 技术变更 4. 支持的配置方式 5. 配置 5.1 RoleTemplate YAML FunctionResource 方式（支持至 v4.5）ClusterRole 聚合方式（v4.2+）customRules 方式 5.2 获取 RoleTemplate 生成的 ClusterRoles 6. 复制与裁剪（示例）6.1 裁剪系统 RoleTemplate YAML 6.2 将 namespace-developer-system 裁剪为审计员角色

1. 概述

本文档介绍自定义角色的核心概念及如何配置 RoleTemplate。

2. 核心概念

RoleTemplate：自定义角色模板，定义角色语义和权限集合，由控制器转换为 ClusterRoles。
FunctionResource：产品功能使用的 K8s 资源抽象；在 RoleTemplate 中通过 functionResourceRef 引用。
ClusterRole：RBAC 规则集；可通过标签聚合到系统角色中。
UserBinding：用户与角色/作用域的绑定；控制器根据 UserBinding 生成 RoleBinding/ClusterRoleBinding 以实现最终授权。

NOTE

functionResourceRef 的值来自 FunctionResource 的 metadata.name。
显示名称通常存放在 metadata.annotations 中，可用于映射 UI 模块。

3. 技术变更

从 ACP v4.3 开始，功能权限逐步从 FunctionResource 迁移到原生 K8s ClusterRole 管理。RoleTemplate 模块权限将通过 ClusterRole 标签聚合到系统角色中。基于 FunctionResource 的管理将在 v4.5 版本废弃。

4. 支持的配置方式

FunctionResource 方式：按产品模块选择权限，细粒度控制动词。
ClusterRole 聚合方式（aggregationRules）：通过 ClusterRole 标签集中聚合，推荐 v4.2+ 使用。
customRules：使用原生 K8s RBAC 语法配置权限，规则格式与 ClusterRole rules 相同。

5. 配置

5.1 RoleTemplate YAML

FunctionResource 方式（支持至 v4.5）

apiVersion: auth.alauda.io/v1beta1
kind: RoleTemplate
metadata:
  name: demo-funcrole
  annotations:
    cpaas.io/display-name: 示例功能角色
    cpaas.io/description: FunctionResource 示例
  labels:
    auth.cpaas.io/roletemplate.level: namespace
spec:
  rules:
    - functionResourceRef: acp-app
      verbs: [get, list, watch]

FunctionResource 示例：

apiVersion: auth.alauda.io/v1beta1
kind: FunctionResource
metadata:
  name: acp-app
  annotations:
    cpaas.io/functionresource.module.display-name: 容器平台
    cpaas.io/functionresource.function.display-name: Application
  labels:
    auth.cpaas.io/functionresource.module: acp
    auth.cpaas.io/functionresource.function: app
    auth.cpaas.io/product: console-acp
spec:
  rules:
    - apiGroup: app.k8s.io
      resources: ["*"]
      bindScope: namespace
      bindCluster: unlimit
      bindNamespacePart: common

ClusterRole 聚合方式（v4.2+）

apiVersion: auth.alauda.io/v1beta1
kind: RoleTemplate
metadata:
  name: demo-aggrole
  annotations:
    cpaas.io/display-name: 示例聚合角色
    cpaas.io/description: ClusterRole 聚合示例
  labels:
    auth.cpaas.io/roletemplate.level: namespace
spec:
  aggregationRules:
    - clusterRoleSelectors:
        - matchLabels:
            rbac.cpaas.io/aggregate-to-namespace-developer: "true"
            rbac.cpaas.io/aggregate-to-scope-business-ns: "true"
      scope: business-ns
  rules: []

带聚合标签的 ClusterRole 示例：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cpaas:demo:business-ns:view
  labels:
    rbac.cpaas.io/aggregate-to-namespace-developer: "true"
    rbac.cpaas.io/aggregate-to-scope-business-ns: "true"
rules:
  - apiGroups: ["apps"]
    resources: ["deployments"]
    verbs: ["get", "list", "watch"]

customRules 方式

apiVersion: auth.alauda.io/v1beta1
kind: RoleTemplate
metadata:
  name: demo-customrules
  annotations:
    cpaas.io/display-name: 示例自定义规则角色
    cpaas.io/description: customRules 示例
  labels:
    auth.cpaas.io/roletemplate.level: namespace
spec:
  customRules:
    - apiGroups: [""]
      resources: ["configmaps"]
      verbs: ["get", "list", "watch"]

RoleTemplate 字段参考（含取值范围）：

字段	说明	取值/范围
`metadata.name`	角色名称	自定义字符串
`metadata.labels.auth.cpaas.io/roletemplate.level`	角色层级	`platform / cluster / project / namespace`
`metadata.annotations.cpaas.io/(display-name/description)`	显示名称和描述	自定义字符串
`spec.rules[].functionResourceRef`	FunctionResource 引用	参见索引（FunctionResource `metadata.name`）
`spec.rules[].verbs`	动词	`get / list / watch / create / update / patch / delete / deletecollection`
`spec.aggregationRules[].scope`	聚合作用域	`cluster / project-ns / business-ns / system-ns / kube-public`
`spec.aggregationRules[].clusterRoleSelectors`	标签选择器	`matchLabels` / `matchExpressions`
`spec.aggregationRules[].clusterRoleSelectors.matchLabels`	标签键值	`key: value`
`spec.aggregationRules[].clusterRoleSelectors.matchExpressions`	表达式	`key + operator + values`（operator: `In / NotIn / Exists / DoesNotExist`）
`spec.customRules[].apiGroups`	API 组	`""` 核心组，`"*"` 全部
`spec.customRules[].resources`	资源	`"*"` 全部
`spec.customRules[].verbs`	动词	同上
`spec.customRules[].resourceNames`	资源名称	可选
`spec.customRules[].nonResourceURLs`	非资源 URL	可选（通常用于 ClusterRole）

NOTE

spec.rules 与 spec.aggregationRules 互斥。

系统匹配标签

系统角色聚合标签：

rbac.cpaas.io/aggregate-to-platform-admin: "true"
rbac.cpaas.io/aggregate-to-platform-auditor: "true"
rbac.cpaas.io/aggregate-to-cluster-admin: "true"
rbac.cpaas.io/aggregate-to-project-admin: "true"
rbac.cpaas.io/aggregate-to-namespace-admin: "true"
rbac.cpaas.io/aggregate-to-namespace-developer: "true"
rbac.cpaas.io/aggregate-to-basic-user: "true"

作用域聚合标签：

rbac.cpaas.io/aggregate-to-scope-cluster: "true"
rbac.cpaas.io/aggregate-to-scope-project-ns: "true"
rbac.cpaas.io/aggregate-to-scope-business-ns: "true"
rbac.cpaas.io/aggregate-to-scope-system-ns: "true"
rbac.cpaas.io/aggregate-to-scope-kube-public: "true"

NOTE

也支持自定义标签进行聚合。

FunctionResource 字段参考：

字段	说明
`metadata.name`	FunctionResource 标识（用于 `functionResourceRef`）
`metadata.annotations`	显示名称（用于 UI 映射）
`metadata.labels`	模块/功能元数据（用于索引）
`spec.rules[].apiGroup`	API 组（`""` 表示核心组）
`spec.rules[].resources`	资源类型
`spec.rules[].bindScope`	作用域（`cluster / namespace`）
`spec.rules[].bindCluster`	集群作用域（`global / unlimit / business`）
`spec.rules[].bindNamespacePart`	命名空间部分（`common / system / kube-public / project_ns / cluster / ""`）

NOTE

自定义角色中不允许使用 acp-namespace-resource-manage。

5.2 获取 RoleTemplate 生成的 ClusterRoles

通过标签查询 RoleTemplate 生成的 ClusterRoles：

kubectl get clusterrole -l auth.cpaas.io/role.relative=<roletemplate-name>

6. 复制与裁剪（示例）

自定义角色建议复制内置系统模板并裁剪，避免遗漏模块权限。

6.1 裁剪系统 RoleTemplate YAML

步骤：

保留必要的 FunctionResources。
将动词减少为只读（get/list/watch）。
删除未使用模块。

角色示例：无 Secret 权限的开发人员审计员

NOTE

自定义角色中不配置命名空间资源管理（FunctionResource：acp-namespace-resource-manage）。
删除用户 Secret 字典（FunctionResource：acp-user-secret）。
所有动词设置为 get/list/watch。

示例 YAML：

apiVersion: auth.alauda.io/v1beta1
kind: RoleTemplate
metadata:
  annotations:
    cpaas.io/description: 负责命名空间内的开发、部署和维护。
    cpaas.io/display-name: 开发人员副本
  labels:
    auth.cpaas.io/roletemplate.level: namespace
  name: namespace-developer-system-copy
spec:
  rules:
    - functionResourceRef: views-acp-userview
      verbs:
        - get
        - list
        - watch
    - functionResourceRef: infrastructure-clusters
      verbs:
        - get
        - list
        - watch
    - functionResourceRef: infrastructure-nodesmanage
      verbs:
        - get
        - list
        - watch
    - functionResourceRef: infrastructure-domains
      verbs:
        - get
        - list
        - watch
    - functionResourceRef: acp-subnet
      verbs:
        - get
        - list
        - watch
    - functionResourceRef: acp-networkpolicies
      verbs:
        - get
        - list
        - watch
    - functionResourceRef: infrastructure-storageclasses
      verbs:
        - get
        - list
        - watch
    - functionResourceRef: infrastructure-persistentvolumes
      verbs:
        - get
        - list
        - watch
    - functionResourceRef: acp-virtualmachineimagetemplates
      verbs:
        - get
        - list
        - watch

6.2 将 namespace-developer-system 裁剪为审计员角色

思路：

保持作用域结构（cluster / project-ns / business-ns / system-ns / kube-public）。
用审计员标签替换聚合标签（需对应 ClusterRoles 已打标签）。

示例（节选）：

apiVersion: auth.alauda.io/v1beta1
kind: RoleTemplate
metadata:
  name: namespace-auditor
  annotations:
    cpaas.io/display-name: 命名空间审计员
    cpaas.io/description: 只读审计
  labels:
    auth.cpaas.io/roletemplate.level: namespace
spec:
  aggregationRules:
    - clusterRoleSelectors:
        - matchLabels:
            rbac.cpaas.io/aggregate-to-namespace-auditor: "true"
            rbac.cpaas.io/aggregate-to-scope-business-ns: "true"
      scope: business-ns
  rules: []

NOTE

aggregate-to-namespace-auditor 必须匹配已有 ClusterRoles 的标签，否则请先创建只读 ClusterRole 并添加该标签。

#如何创建自定义平台角色

#目录

#1. 概述

#2. 核心概念

#3. 技术变更

#4. 支持的配置方式

#5. 配置

#5.1 RoleTemplate YAML

#FunctionResource 方式（支持至 v4.5）

#ClusterRole 聚合方式（v4.2+）

#customRules 方式

#5.2 获取 RoleTemplate 生成的 ClusterRoles

#6. 复制与裁剪（示例）

#6.1 裁剪系统 RoleTemplate YAML

#6.2 将 namespace-developer-system 裁剪为审计员角色

如何创建自定义平台角色

目录

1. 概述

2. 核心概念

3. 技术变更

4. 支持的配置方式

5. 配置

5.1 RoleTemplate YAML

FunctionResource 方式（支持至 v4.5）

ClusterRole 聚合方式（v4.2+）

customRules 方式

5.2 获取 RoleTemplate 生成的 ClusterRoles

6. 复制与裁剪（示例）

6.1 裁剪系统 RoleTemplate YAML

6.2 将 namespace-developer-system 裁剪为审计员角色