Skip to main content

​
Permission Plugin

The permission plugin enables documentation of Kubernetes RBAC (Role-Based Access Control) permissions, function resources, and role templates.

​
Features

  • Function Resources - Document available API resources and permissions
  • Role Templates - Generate docs for RBAC role templates
  • Kubernetes Integration - Native support for K8s RBAC patterns
  • Runtime Access - Access permission data in your components

​
Configuration

Configure the permission plugin in your doom.config.ts: 
import { defineConfig } from '@alauda/doom'

export default defineConfig({
  permission: {
    // Path to function resource YAML files
    functionresources: [
      'permissions/function-resources.yaml'
    ],
    
    // Path to role template YAML files
    roletemplates: [
      'permissions/role-templates.yaml'
    ]
  }
})

​
Function Resources

Function resources define what API resources are available and how they can be accessed.

​
Structure

permissions/function-resources.yaml
apiVersion: v1
kind: List
items:
  - apiVersion: app.alauda.io/v1
    kind: FunctionResource
    metadata:
      name: deployments-view
    spec:
      rules:
        - apiGroup: apps
          bindCluster: unlimit
          bindNamespacePart: project_ns
          bindScope: namespace
          resources:
            - deployments
            - deployments/status

​
TypeScript Types

packages/doom/src/plugins/permission/types.ts:3-16
export interface FunctionResource extends K8sTypeMeta {
  kind: 'FunctionResource'
  spec: {
    rules: FunctionResourceRule[]
  }
}

export interface FunctionResourceRule {
  apiGroup: string
  bindCluster: 'bussiness' | 'global' | 'unlimit'
  bindNamespacePart: '' | 'common' | 'kube-public' | 'project_ns' | 'system'
  bindScope: 'cluster' | 'namespace'
  resources: string[]
}

​
Bind Cluster Options

  • business - Business cluster only
  • global - Global cluster only
  • unlimit - Any cluster

​
Bind Namespace Options

  • ” (empty) - No namespace restriction
  • common - Common namespaces
  • kube-public - Public Kubernetes namespace
  • project_ns - Project namespaces
  • system - System namespaces

​
Role Templates

Role templates define collections of permissions that can be assigned to users.

​
Structure

permissions/role-templates.yaml
apiVersion: v1
kind: List
items:
  - apiVersion: app.alauda.io/v1
    kind: RoleTemplate
    metadata:
      name: developer
      annotations:
        displayName: "Developer"
        description: "Can view and manage application resources"
    spec:
      rules:
        - functionResourceRef: deployments-view
          verbs:
            - get
            - list
            - watch
        - functionResourceRef: deployments-manage
          verbs:
            - create
            - update
            - patch
            - delete

​
TypeScript Types

packages/doom/src/plugins/permission/types.ts:24-45
export interface RoleTemplate extends K8sTypeMeta {
  kind: 'RoleTemplate'
  spec: {
    rules: RoleTemplateRule[]
  }
}

export interface RoleTemplateRule {
  functionResourceRef: string
  verbs: RoleTemplateRuleVerb[]
}

export type RoleTemplateRuleVerb =
  | '*'
  | 'create'
  | 'delete'
  | 'deletecollection'
  | 'get'
  | 'list'
  | 'patch'
  | 'update'
  | 'watch'

​
Supported Verbs

  • * - All operations
  • create - Create new resources
  • get - Retrieve a resource
  • list - List resources
  • watch - Watch for resource changes
  • update - Update a resource (full replace)
  • patch - Partially update a resource
  • delete - Delete a resource
  • deletecollection - Delete multiple resources

​
Runtime Access

Access permission data in your components: 
import functionResourcesMap from 'doom-@permission-functionResourcesMap'
import roleTemplatesMap from 'doom-@permission-roleTemplatesMap'

// Access function resources
const deploymentPerms = functionResourcesMap['deployments-view']

// Access role templates
const developerRole = roleTemplatesMap['developer']

​
Creating Permission Docs

Create a page that documents permissions:
docs/permissions/rbac.mdx
---
title: RBAC Permissions
---

import { PermissionTable } from '@alauda/doom/runtime'
import roleTemplatesMap from 'doom-@permission-roleTemplatesMap'

# RBAC Permissions

## Developer Role

The developer role provides access to application resources.

<PermissionTable roleTemplate={roleTemplatesMap['developer']} />

​
Plugin Implementation

The plugin loads and processes permission files:
packages/doom/src/plugins/permission/index.ts:24-56
export const permissionPlugin = ({
  localBasePath,
}: PermissionPluginOptions): RspressPlugin => {
  return {
    name: 'doom-permission',
    async addRuntimeModules(config, isProd) {
      return {
        ...(await generateRuntimeModule<
          K8sTypeList<FunctionResource>,
          FunctionResource[]
        >(
          config.permission?.functionresources,
          'permission-functionResources',
          config.root!,
          localBasePath,
          isProd,
          ({ items }) => items,
        )),
        ...(await generateRuntimeModule<
          K8sTypeList<RoleTemplate>,
          RoleTemplate[]
        >(
          config.permission?.roletemplates,
          'permission-roleTemplates',
          config.root!,
          localBasePath,
          isProd,
          ({ items }) => items,
        )),
      }
    },
  }
}

​
Use Cases

​
Document Custom Roles

# Custom Roles

Our platform provides several predefined roles:

- **Viewer** - Read-only access to resources
- **Developer** - Full access to application resources
- **Admin** - Full cluster administration

​
Permission Matrix

Create a permission comparison table: 
| Resource | Viewer | Developer | Admin |
|----------|--------|-----------|-------|
| Pods | get, list | * | * |
| Deployments | get, list | * | * |
| Secrets | - | get, list | * |

​
API Access Documentation

Document what APIs each role can access: 
## Developer API Access

Developers can access:
- `/api/v1/namespaces/{namespace}/pods`
- `/apis/apps/v1/namespaces/{namespace}/deployments`
- `/apis/batch/v1/namespaces/{namespace}/jobs`

​
Best Practices

  1. Principle of Least Privilege - Grant minimum necessary permissions
  2. Document Clearly - Explain what each role can do
  3. Use Descriptive Names - Name roles based on job functions
  4. Group Related Permissions - Create function resources by feature area
  5. Version Control - Track permission changes in git
  6. Regular Audits - Review and update permissions periodically

​
Example Configuration

Complete example with multiple roles:
permissions/complete-example.yaml
apiVersion: v1
kind: List
items:
  # Function Resources
  - apiVersion: app.alauda.io/v1
    kind: FunctionResource
    metadata:
      name: pods-read
    spec:
      rules:
        - apiGroup: ""
          bindCluster: unlimit
          bindScope: namespace
          resources: [pods, pods/log, pods/status]
          
  - apiVersion: app.alauda.io/v1
    kind: FunctionResource
    metadata:
      name: pods-write
    spec:
      rules:
        - apiGroup: ""
          bindCluster: unlimit
          bindScope: namespace
          resources: [pods, pods/exec]
          
  # Role Templates
  - apiVersion: app.alauda.io/v1
    kind: RoleTemplate
    metadata:
      name: viewer
      annotations:
        displayName: Viewer
    spec:
      rules:
        - functionResourceRef: pods-read
          verbs: [get, list, watch]
          
  - apiVersion: app.alauda.io/v1
    kind: RoleTemplate
    metadata:
      name: developer
      annotations:
        displayName: Developer
    spec:
      rules:
        - functionResourceRef: pods-read
          verbs: ['*']
        - functionResourceRef: pods-write
          verbs: [create, delete, update]

​
Plugin Options

export interface PermissionPluginOptions {
  functionresources?: string[]  // Glob patterns for function resource files
  localBasePath: string         // Base path for resolving local files
  roletemplates?: string[]      // Glob patterns for role template files
}

Build docs developers (and LLMs) love

Get started for freeTalk to us