Kubernetes RBAC API

openapi: 3.2.0
info:
  title: Kubernetes RBAC API
  description: The Kubernetes API lets you query and manipulate the state of objects in Kubernetes.
  version: v1.32.0
  contact:
    name: Kubernetes Community
    url: https://kubernetes.io/community/
  termsOfService: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://kubernetes.default.svc
  description: In-cluster Kubernetes API Server
security:
- bearerAuth: []
- clientCertificate: []
tags:
- name: RBAC
  description: Role-based access control resources including Roles, RoleBindings, ClusterRoles, and ClusterRoleBindings for managing authorization.
paths:
  /apis/rbac.authorization.k8s.io/v1/clusterroles:
    get:
      operationId: listClusterRoles
      summary: Kubernetes List ClusterRoles
      description: Returns a list of all ClusterRoles in the cluster. ClusterRoles define a set of permissions applicable across the entire cluster, unlike namespace-scoped Roles.
      tags:
      - RBAC
      parameters:
      - $ref: '#/components/parameters/LabelSelector'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Watch'
      responses:
        '200':
          description: List of ClusterRoles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterRoleList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createClusterRole
      summary: Kubernetes Create a ClusterRole
      description: Creates a new ClusterRole defining cluster-wide permissions. ClusterRoles are bound to subjects (users, groups, service accounts) via ClusterRoleBindings to grant cluster-wide access.
      tags:
      - RBAC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterRole'
      responses:
        '201':
          description: ClusterRole created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterRole'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
    BadRequest:
      description: Bad request — invalid resource specification
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Status'
  schemas:
    ListMeta:
      type: object
      description: Metadata that all list responses include, containing pagination state and the resource version of the list.
      properties:
        resourceVersion:
          type: string
          description: Resource version of the list for use in watch operations.
        continue:
          type: string
          description: Token used to retrieve the next page of results in a paginated list request.
        remainingItemCount:
          type: integer
          description: Number of items remaining in the list if pagination is in effect.
    ClusterRoleList:
      type: object
      description: A list of ClusterRoles returned by list operations.
      required:
      - items
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          const: ClusterRoleList
        metadata:
          $ref: '#/components/schemas/ListMeta'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ClusterRole'
    OwnerReference:
      type: object
      description: Reference to an owning resource that manages this object's lifecycle via garbage collection.
      required:
      - apiVersion
      - kind
      - name
      - uid
      properties:
        apiVersion:
          type: string
          description: API version of the owner resource.
        kind:
          type: string
          description: Kind of the owner resource.
        name:
          type: string
          description: Name of the owner resource.
        uid:
          type: string
          description: UID of the owner resource.
        controller:
          type: boolean
          description: Whether this reference points to the managing controller.
    PolicyRule:
      type: object
      description: A rule that grants a set of verbs on a set of resources within an API group. All fields are combined with AND logic.
      properties:
        verbs:
          type: array
          items:
            type: string
          description: 'Verbs allowed on the resources. Common: get, list, watch, create, update, patch, delete, deletecollection.'
        apiGroups:
          type: array
          items:
            type: string
          description: API groups the resources belong to. Use "" for the core group.
        resources:
          type: array
          items:
            type: string
          description: Resources this rule applies to. Use "*" to match all resources.
        resourceNames:
          type: array
          items:
            type: string
          description: List of resource names the rule applies to. Empty means all.
    ClusterRole:
      type: object
      description: A ClusterRole defines a set of permissions applicable across the entire cluster. Rules grant access to specific API groups, resources, and verbs. ClusterRoles are bound to subjects via ClusterRoleBindings.
      properties:
        apiVersion:
          type: string
          const: rbac.authorization.k8s.io/v1
        kind:
          type: string
          const: ClusterRole
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        rules:
          type: array
          description: List of policy rules granting permissions.
          items:
            $ref: '#/components/schemas/PolicyRule'
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata included on all persistent resources. Contains identifying information, ownership references, and system-managed fields like resourceVersion and uid.
      properties:
        name:
          type: string
          description: Unique name of the object within a namespace or cluster scope.
        namespace:
          type: string
          description: Namespace that scopes the resource name. Not all resource types are namespaced.
        uid:
          type: string
          description: Unique identifier generated by the server for this object. Remains constant for the lifetime of the object.
        resourceVersion:
          type: string
          description: Opaque string that identifies an internal server version of the object. Used for optimistic concurrency control and watch operations.
        generation:
          type: integer
          description: Sequence number representing the generation of the desired state. Incremented by the server on spec changes.
        creationTimestamp:
          type: string
          format: date-time
          description: Timestamp when the object was created.
        deletionTimestamp:
          type: string
          format: date-time
          description: Time at which the object will be deleted. Set by the server when a delete is requested.
        labels:
          type: object
          additionalProperties:
            type: string
          description: Map of string keys and values to organize and select resources. Labels are queryable via label selectors.
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Map of non-identifying metadata. Annotations may contain arbitrary data and are not queryable by the API.
        ownerReferences:
          type: array
          description: List of objects that own this object. Garbage collection will delete this object when all owners are deleted.
          items:
            $ref: '#/components/schemas/OwnerReference'
    Status:
      type: object
      description: Status is a return value for calls that don't return other objects. It is used to convey error messages, reasons, and codes for both success and failure responses.
      properties:
        apiVersion:
          type: string
        kind:
          type: string
          const: Status
        code:
          type: integer
          description: HTTP status code.
        message:
          type: string
          description: Human-readable description of the status.
        reason:
          type: string
          description: Machine-readable description of why the operation is in this status.
        status:
          type: string
          enum:
          - Success
          - Failure
          description: Outcome of the operation.
  parameters:
    Watch:
      name: watch
      in: query
      description: Watch for changes to the described resources and return them as a stream of add, update, and remove notifications. Specify resourceVersion to watch from a specific version.
      schema:
        type: boolean
    LabelSelector:
      name: labelSelector
      in: query
      description: 'Selector expression to filter resources by label. Supports equality (=, ==, !=), set-based (in, notin, exists) operations. Example: app=nginx,tier=frontend'
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: Maximum number of resources to return in a single response. Use with the continue parameter to paginate through large result sets.
      schema:
        type: integer
        minimum: 1
        maximum: 500
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Kubernetes service account token or user token issued by the cluster's authentication provider. Include in the Authorization header as 'Bearer <token>'.
    clientCertificate:
      type: mutualTLS
      description: Client certificate authentication using a TLS certificate issued by the cluster's certificate authority.
externalDocs:
  description: Kubernetes API Reference Documentation
  url: https://kubernetes.io/docs/reference/kubernetes-api/