CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pulumi--kubernetes

A comprehensive Pulumi resource provider for creating and managing Kubernetes resources and workloads in a running cluster

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

rbac-resources.mddocs/

RBAC Resources (rbac.authorization.k8s.io)

The RBAC API group provides role-based access control resources for security and permissions management in Kubernetes clusters. These resources enable fine-grained authorization policies for users, service accounts, and groups.

Package Import

import { rbac } from "@pulumi/kubernetes";
import * as k8s from "@pulumi/kubernetes";

// Direct RBAC imports
import { Role, RoleBinding, ClusterRole, ClusterRoleBinding } from "@pulumi/kubernetes/rbac/v1";

Role (rbac/v1)

Role contains rules that represent a set of permissions within a particular namespace.

class Role extends pulumi.CustomResource {
    constructor(name: string, args?: RoleArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): Role
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"rbac.authorization.k8s.io/v1">;
    public readonly kind!: pulumi.Output<"Role">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly rules!: pulumi.Output<outputs.rbac.v1.PolicyRule[]>;
}

interface RoleArgs {
    apiVersion?: pulumi.Input<"rbac.authorization.k8s.io/v1">;
    kind?: pulumi.Input<"Role">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    rules?: pulumi.Input<pulumi.Input<inputs.rbac.v1.PolicyRule>[]>;
}

PolicyRule Structure

interface PolicyRule {
    apiGroups?: pulumi.Input<pulumi.Input<string>[]>;      // API groups (e.g., "", "apps", "extensions")
    resources?: pulumi.Input<pulumi.Input<string>[]>;      // Resources (e.g., "pods", "services", "deployments")
    verbs: pulumi.Input<pulumi.Input<string>[]>;           // Actions (e.g., "get", "list", "create", "update", "delete")
    resourceNames?: pulumi.Input<pulumi.Input<string>[]>;  // Specific resource names (optional)
    nonResourceURLs?: pulumi.Input<pulumi.Input<string>[]>; // Non-resource URLs (for ClusterRoles)
}

Role Usage Examples

// Pod reader role - read-only access to pods
const podReaderRole = new k8s.rbac.v1.Role("pod-reader", {
    rules: [{
        apiGroups: [""],
        resources: ["pods"],
        verbs: ["get", "list", "watch"],
    }],
});

// Deployment manager role - full access to deployments
const deploymentManagerRole = new k8s.rbac.v1.Role("deployment-manager", {
    rules: [{
        apiGroups: ["apps"],
        resources: ["deployments", "replicasets"],
        verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
    }, {
        apiGroups: [""],
        resources: ["pods"],
        verbs: ["get", "list", "watch"],
    }],
});

// ConfigMap editor role - manage configuration
const configEditorRole = new k8s.rbac.v1.Role("config-editor", {
    rules: [{
        apiGroups: [""],
        resources: ["configmaps", "secrets"],
        verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
    }],
});

// Service account manager role - manage specific service accounts
const saManagerRole = new k8s.rbac.v1.Role("sa-manager", {
    rules: [{
        apiGroups: [""],
        resources: ["serviceaccounts"],
        verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
    }, {
        apiGroups: [""],
        resources: ["serviceaccounts/token"],
        verbs: ["create"],
    }],
});

// Limited resource access role - access specific named resources
const limitedAccessRole = new k8s.rbac.v1.Role("limited-access", {
    rules: [{
        apiGroups: [""],
        resources: ["configmaps"],
        resourceNames: ["app-config", "feature-flags"], // Only these specific ConfigMaps
        verbs: ["get", "update"],
    }],
});

RoleBinding (rbac/v1)

RoleBinding grants the permissions defined in a Role to users, groups, or service accounts within a specific namespace.

class RoleBinding extends pulumi.CustomResource {
    constructor(name: string, args?: RoleBindingArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): RoleBinding
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"rbac.authorization.k8s.io/v1">;
    public readonly kind!: pulumi.Output<"RoleBinding">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly subjects!: pulumi.Output<outputs.rbac.v1.Subject[]>;
    public readonly roleRef!: pulumi.Output<outputs.rbac.v1.RoleRef>;
}

interface RoleBindingArgs {
    apiVersion?: pulumi.Input<"rbac.authorization.k8s.io/v1">;
    kind?: pulumi.Input<"RoleBinding">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    subjects?: pulumi.Input<pulumi.Input<inputs.rbac.v1.Subject>[]>;
    roleRef: pulumi.Input<inputs.rbac.v1.RoleRef>;
}

Subject and RoleRef Types

interface Subject {
    kind: pulumi.Input<"User" | "Group" | "ServiceAccount">;
    name: pulumi.Input<string>;
    namespace?: pulumi.Input<string>; // Required for ServiceAccount subjects
    apiGroup?: pulumi.Input<string>;  // Required for User and Group subjects
}

interface RoleRef {
    apiGroup: pulumi.Input<string>;   // Usually "rbac.authorization.k8s.io"
    kind: pulumi.Input<"Role" | "ClusterRole">;
    name: pulumi.Input<string>;
}

RoleBinding Usage Examples

// Bind service account to pod reader role
const podReaderBinding = new k8s.rbac.v1.RoleBinding("pod-reader-binding", {
    subjects: [{
        kind: "ServiceAccount",
        name: "pod-reader-sa",
        namespace: "default",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "Role",
        name: podReaderRole.metadata.name,
    },
});

// Bind user to deployment manager role
const deploymentManagerBinding = new k8s.rbac.v1.RoleBinding("deployment-manager-binding", {
    subjects: [{
        kind: "User",
        name: "alice@example.com",
        apiGroup: "rbac.authorization.k8s.io",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "Role",
        name: deploymentManagerRole.metadata.name,
    },
});

// Bind multiple subjects to config editor role
const configEditorBinding = new k8s.rbac.v1.RoleBinding("config-editor-binding", {
    subjects: [
        {
            kind: "User",
            name: "developer-1",
            apiGroup: "rbac.authorization.k8s.io",
        },
        {
            kind: "User", 
            name: "developer-2",
            apiGroup: "rbac.authorization.k8s.io",
        },
        {
            kind: "ServiceAccount",
            name: "config-manager-sa",
            namespace: "default",
        },
    ],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "Role",
        name: configEditorRole.metadata.name,
    },
});

// Bind group to role
const devTeamBinding = new k8s.rbac.v1.RoleBinding("dev-team-binding", {
    subjects: [{
        kind: "Group",
        name: "dev-team",
        apiGroup: "rbac.authorization.k8s.io",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "Role",
        name: deploymentManagerRole.metadata.name,
    },
});

ClusterRole (rbac/v1)

ClusterRole contains rules that represent a set of permissions across the entire cluster or for cluster-scoped resources.

class ClusterRole extends pulumi.CustomResource {
    constructor(name: string, args?: ClusterRoleArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): ClusterRole
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"rbac.authorization.k8s.io/v1">;
    public readonly kind!: pulumi.Output<"ClusterRole">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly rules!: pulumi.Output<outputs.rbac.v1.PolicyRule[]>;
    public readonly aggregationRule!: pulumi.Output<outputs.rbac.v1.AggregationRule>;
}

interface ClusterRoleArgs {
    apiVersion?: pulumi.Input<"rbac.authorization.k8s.io/v1">;
    kind?: pulumi.Input<"ClusterRole">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    rules?: pulumi.Input<pulumi.Input<inputs.rbac.v1.PolicyRule>[]>;
    aggregationRule?: pulumi.Input<inputs.rbac.v1.AggregationRule>;
}

ClusterRole Usage Examples

// Cluster reader role - read access to most resources
const clusterReaderRole = new k8s.rbac.v1.ClusterRole("cluster-reader", {
    rules: [
        {
            apiGroups: [""],
            resources: ["pods", "services", "endpoints", "persistentvolumeclaims", "events", "configmaps", "secrets"],
            verbs: ["get", "list", "watch"],
        },
        {
            apiGroups: ["apps"],
            resources: ["deployments", "daemonsets", "replicasets", "statefulsets"],
            verbs: ["get", "list", "watch"],
        },
        {
            apiGroups: ["networking.k8s.io"],
            resources: ["ingresses", "networkpolicies"],
            verbs: ["get", "list", "watch"],
        },
    ],
});

// Node management role - manage nodes and node-related resources
const nodeManagerRole = new k8s.rbac.v1.ClusterRole("node-manager", {
    rules: [
        {
            apiGroups: [""],
            resources: ["nodes", "nodes/status", "nodes/metrics"],
            verbs: ["get", "list", "watch", "patch", "update"],
        },
        {
            apiGroups: ["metrics.k8s.io"],
            resources: ["nodes", "pods"],
            verbs: ["get", "list"],
        },
    ],
});

// Persistent volume admin role - manage storage
const pvAdminRole = new k8s.rbac.v1.ClusterRole("pv-admin", {
    rules: [
        {
            apiGroups: [""],
            resources: ["persistentvolumes", "persistentvolumeclaims"],
            verbs: ["*"], // All verbs
        },
        {
            apiGroups: ["storage.k8s.io"],
            resources: ["storageclasses", "volumeattachments", "csidrivers", "csinodes"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
    ],
});

// Monitoring role - access metrics and monitoring endpoints
const monitoringRole = new k8s.rbac.v1.ClusterRole("monitoring", {
    rules: [
        {
            apiGroups: [""],
            resources: ["nodes", "nodes/metrics", "services", "endpoints", "pods"],
            verbs: ["get", "list", "watch"],
        },
        {
            nonResourceURLs: ["/metrics", "/metrics/*"],
            verbs: ["get"],
        },
        {
            apiGroups: ["metrics.k8s.io"],
            resources: ["*"],
            verbs: ["get", "list"],
        },
    ],
});

// Custom resource manager role
const crdManagerRole = new k8s.rbac.v1.ClusterRole("crd-manager", {
    rules: [
        {
            apiGroups: ["apiextensions.k8s.io"],
            resources: ["customresourcedefinitions"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        {
            apiGroups: ["example.com"],
            resources: ["*"],
            verbs: ["*"],
        },
    ],
});

// Aggregated role example - combines other roles
const aggregatedAdminRole = new k8s.rbac.v1.ClusterRole("aggregated-admin", {
    aggregationRule: {
        clusterRoleSelectors: [{
            matchLabels: {
                "rbac.example.com/aggregate-to-admin": "true",
            },
        }],
    },
});

ClusterRoleBinding (rbac/v1)

ClusterRoleBinding grants the permissions defined in a ClusterRole to users, groups, or service accounts across the entire cluster.

class ClusterRoleBinding extends pulumi.CustomResource {
    constructor(name: string, args?: ClusterRoleBindingArgs, opts?: pulumi.CustomResourceOptions)
    
    public static get(name: string, id: pulumi.Input<pulumi.ID>, opts?: pulumi.CustomResourceOptions): ClusterRoleBinding
    
    // Output properties
    public readonly apiVersion!: pulumi.Output<"rbac.authorization.k8s.io/v1">;
    public readonly kind!: pulumi.Output<"ClusterRoleBinding">;
    public readonly metadata!: pulumi.Output<outputs.meta.v1.ObjectMeta>;
    public readonly subjects!: pulumi.Output<outputs.rbac.v1.Subject[]>;
    public readonly roleRef!: pulumi.Output<outputs.rbac.v1.RoleRef>;
}

interface ClusterRoleBindingArgs {
    apiVersion?: pulumi.Input<"rbac.authorization.k8s.io/v1">;
    kind?: pulumi.Input<"ClusterRoleBinding">;
    metadata?: pulumi.Input<inputs.meta.v1.ObjectMeta>;
    subjects?: pulumi.Input<pulumi.Input<inputs.rbac.v1.Subject>[]>;
    roleRef: pulumi.Input<inputs.rbac.v1.RoleRef>;
}

ClusterRoleBinding Usage Examples

// Bind service account to cluster reader role
const clusterReaderBinding = new k8s.rbac.v1.ClusterRoleBinding("cluster-reader-binding", {
    subjects: [{
        kind: "ServiceAccount",
        name: "monitoring-sa",
        namespace: "monitoring",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "ClusterRole",
        name: clusterReaderRole.metadata.name,
    },
});

// Bind admin user to cluster admin role
const clusterAdminBinding = new k8s.rbac.v1.ClusterRoleBinding("cluster-admin-binding", {
    subjects: [{
        kind: "User",
        name: "admin@example.com",
        apiGroup: "rbac.authorization.k8s.io",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "ClusterRole",
        name: "cluster-admin", // Built-in cluster role
    },
});

// Bind SRE team to node manager role
const sreNodeManagerBinding = new k8s.rbac.v1.ClusterRoleBinding("sre-node-manager", {
    subjects: [{
        kind: "Group",
        name: "sre-team",
        apiGroup: "rbac.authorization.k8s.io",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "ClusterRole",
        name: nodeManagerRole.metadata.name,
    },
});

Complete RBAC Setup Examples

Application Service Account with Minimal Permissions

// Create namespace for application
const appNamespace = new k8s.core.v1.Namespace("my-app");

// Create service account
const appServiceAccount = new k8s.core.v1.ServiceAccount("app-sa", {
    metadata: {
        namespace: appNamespace.metadata.name,
    },
});

// Create role with minimal required permissions
const appRole = new k8s.rbac.v1.Role("app-role", {
    metadata: {
        namespace: appNamespace.metadata.name,
    },
    rules: [
        {
            apiGroups: [""],
            resources: ["configmaps"],
            resourceNames: ["app-config"], // Only specific ConfigMap
            verbs: ["get"],
        },
        {
            apiGroups: [""],
            resources: ["secrets"],
            resourceNames: ["app-secrets"], // Only specific Secret
            verbs: ["get"],
        },
    ],
});

// Bind service account to role
const appRoleBinding = new k8s.rbac.v1.RoleBinding("app-role-binding", {
    metadata: {
        namespace: appNamespace.metadata.name,
    },
    subjects: [{
        kind: "ServiceAccount",
        name: appServiceAccount.metadata.name,
        namespace: appNamespace.metadata.name,
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "Role",
        name: appRole.metadata.name,
    },
});

// Deployment using the service account
const appDeployment = new k8s.apps.v1.Deployment("my-app", {
    metadata: {
        namespace: appNamespace.metadata.name,
    },
    spec: {
        replicas: 3,
        selector: {
            matchLabels: { app: "my-app" },
        },
        template: {
            metadata: {
                labels: { app: "my-app" },
            },
            spec: {
                serviceAccountName: appServiceAccount.metadata.name,
                containers: [{
                    name: "app",
                    image: "myapp:v1.0",
                    ports: [{ containerPort: 8080 }],
                }],
            },
        },
    },
});

DevOps Team RBAC Setup

// DevOps cluster role with broad permissions
const devopsClusterRole = new k8s.rbac.v1.ClusterRole("devops-role", {
    rules: [
        // Core resources
        {
            apiGroups: [""],
            resources: ["*"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // Apps resources
        {
            apiGroups: ["apps"],
            resources: ["*"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // Networking
        {
            apiGroups: ["networking.k8s.io"],
            resources: ["*"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // Storage
        {
            apiGroups: ["storage.k8s.io"],
            resources: ["*"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // RBAC (limited)
        {
            apiGroups: ["rbac.authorization.k8s.io"],
            resources: ["roles", "rolebindings"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // Metrics
        {
            apiGroups: ["metrics.k8s.io"],
            resources: ["*"],
            verbs: ["get", "list"],
        },
    ],
});

// DevOps team binding
const devopsBinding = new k8s.rbac.v1.ClusterRoleBinding("devops-binding", {
    subjects: [{
        kind: "Group",
        name: "devops-team@example.com",
        apiGroup: "rbac.authorization.k8s.io",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "ClusterRole",
        name: devopsClusterRole.metadata.name,
    },
});

// Development team namespace-scoped permissions
const devRole = new k8s.rbac.v1.Role("dev-role", {
    metadata: {
        namespace: "development",
    },
    rules: [
        {
            apiGroups: ["", "apps", "networking.k8s.io"],
            resources: ["*"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // Exclude secrets for security
        {
            apiGroups: [""],
            resources: ["secrets"],
            verbs: ["get", "list"], // Read-only access to secrets
        },
    ],
});

const devBinding = new k8s.rbac.v1.RoleBinding("dev-binding", {
    metadata: {
        namespace: "development",
    },
    subjects: [{
        kind: "Group",
        name: "dev-team@example.com",
        apiGroup: "rbac.authorization.k8s.io",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "Role",
        name: devRole.metadata.name,
    },
});

CI/CD Pipeline Service Account

// CI/CD service account
const cicdServiceAccount = new k8s.core.v1.ServiceAccount("cicd-sa", {
    metadata: {
        namespace: "cicd-system",
    },
});

// CI/CD cluster role with deployment permissions
const cicdClusterRole = new k8s.rbac.v1.ClusterRole("cicd-role", {
    rules: [
        // Core resources needed for deployments
        {
            apiGroups: [""],
            resources: ["pods", "services", "configmaps", "secrets"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // Apps resources for deployments
        {
            apiGroups: ["apps"],
            resources: ["deployments", "daemonsets", "statefulsets", "replicasets"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // Ingress for traffic routing
        {
            apiGroups: ["networking.k8s.io"],
            resources: ["ingresses"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
        // Service accounts for application deployments
        {
            apiGroups: [""],
            resources: ["serviceaccounts"],
            verbs: ["get", "list", "watch", "create", "update", "patch"],
        },
        // RBAC for application service accounts
        {
            apiGroups: ["rbac.authorization.k8s.io"],
            resources: ["roles", "rolebindings"],
            verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
        },
    ],
});

const cicdClusterRoleBinding = new k8s.rbac.v1.ClusterRoleBinding("cicd-binding", {
    subjects: [{
        kind: "ServiceAccount",
        name: cicdServiceAccount.metadata.name,
        namespace: "cicd-system",
    }],
    roleRef: {
        apiGroup: "rbac.authorization.k8s.io",
        kind: "ClusterRole",
        name: cicdClusterRole.metadata.name,
    },
});

Resource Variants

All RBAC resources include the following variants:

List Resources

  • RoleList, RoleBindingList, ClusterRoleList, ClusterRoleBindingList

Patch Resources

  • RolePatch, RoleBindingPatch, ClusterRolePatch, ClusterRoleBindingPatch
// Example patch operation
const rolePatch = new k8s.rbac.v1.RolePatch("update-role", {
    metadata: {
        name: "existing-role",
    },
    rules: [{
        apiGroups: [""],
        resources: ["pods", "services"], // Add services to existing role
        verbs: ["get", "list", "watch", "create", "update"],
    }],
});

Best Practices

RBAC Security Best Practices

  1. Principle of Least Privilege: Grant minimum necessary permissions
  2. Use ServiceAccounts: Create dedicated service accounts for applications
  3. Namespace Isolation: Use Roles and RoleBindings for namespace-scoped permissions
  4. Regular Audits: Regularly review and audit RBAC permissions
  5. Avoid Wildcards: Be specific with resources and verbs instead of using "*"

Permission Management

  1. Separate Concerns: Create separate roles for different functions
  2. Group Management: Use groups for managing team permissions
  3. Resource Names: Use resourceNames for fine-grained access control
  4. Test Permissions: Test RBAC configurations in development environments
  5. Documentation: Document permission requirements and role purposes

The RBAC API group provides comprehensive authorization capabilities, enabling secure and fine-grained access control for Kubernetes clusters while supporting both application and administrative use cases.

Install with Tessl CLI

npx tessl i tessl/npm-pulumi--kubernetes

docs

core-resources.md

helm-integration.md

index.md

kustomize-integration.md

networking-resources.md

provider-configuration.md

rbac-resources.md

storage-resources.md

workload-resources.md

yaml-deployment.md

tile.json