• Using RBAC Authorization
    • API Overview
      • Role and ClusterRole
      • RoleBinding and ClusterRoleBinding
      • Referring to Resources
      • Aggregated ClusterRoles
        • Role Examples
      • Referring to Subjects
        • Role Binding Examples
    • Default Roles and Role Bindings
      • Auto-reconciliation
      • Discovery Roles
      • User-facing Roles
      • Core Component Roles
      • Other Component Roles
      • Controller Roles
    • Privilege Escalation Prevention and Bootstrapping
    • Command-line Utilities
      • kubectl create role
      • kubectl create clusterrole
      • kubectl create rolebinding
      • kubectl create clusterrolebinding
      • kubectl auth reconcile
    • Service Account Permissions
    • Upgrading from 1.5
      • Parallel Authorizers
    • Permissive RBAC Permissions
    • Feedback

    Using RBAC Authorization

    Role-based access control (RBAC) is a method of regulating access to computer or network resources based on the roles of individual users within an enterprise.

    RBAC uses the rbac.authorization.k8s.io API GroupA set of related paths in the Kubernetes API.to drive authorization decisions, allowing admins to dynamically configure policiesthrough the Kubernetes API.

    As of 1.8, RBAC mode is stable and backed by the rbac.authorization.k8s.io/v1 API.

    To enable RBAC, start the apiserver with —authorization-mode=RBAC.

    API Overview

    The RBAC API declares four top-level types which will be covered in thissection. Users can interact with these resources as they would with any otherAPI resource (via kubectl, API calls, etc.). For instance,kubectl apply -f (resource).yml can be used with any of these examples,though readers who wish to follow along should review the section onbootstrapping first.

    Role and ClusterRole

    In the RBAC API, a role contains rules that represent a set of permissions.Permissions are purely additive (there are no “deny” rules).A role can be defined within a namespace with a Role, or cluster-wide with a ClusterRole.

    A Role can only be used to grant access to resources within a single namespace.Here’s an example Role in the “default” namespace that can be used to grant read access to pods:

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: Role
    3. metadata:
    4. namespace: default
    5. name: pod-reader
    6. rules:
    7. - apiGroups: [""] # "" indicates the core API group
    8. resources: ["pods"]
    9. verbs: ["get", "watch", "list"]

    A ClusterRole can be used to grant the same permissions as a Role,but because they are cluster-scoped, they can also be used to grant access to:

    • cluster-scoped resources (like nodes)
    • non-resource endpoints (like “/healthz”)
    • namespaced resources (like pods) across all namespaces (needed to run kubectl get pods —all-namespaces, for example)

    The following ClusterRole can be used to grant read access to secrets in any particular namespace,or across all namespaces (depending on how it is bound):

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: ClusterRole
    3. metadata:
    4. # "namespace" omitted since ClusterRoles are not namespaced
    5. name: secret-reader
    6. rules:
    7. - apiGroups: [""]
    8. resources: ["secrets"]
    9. verbs: ["get", "watch", "list"]

    RoleBinding and ClusterRoleBinding

    A role binding grants the permissions defined in a role to a user or set of users.It holds a list of subjects (users, groups, or service accounts), and a reference to the role being granted.Permissions can be granted within a namespace with a RoleBinding, or cluster-wide with a ClusterRoleBinding.

    A RoleBinding may reference a Role in the same namespace.The following RoleBinding grants the “pod-reader” role to the user “jane” within the “default” namespace.This allows “jane” to read pods in the “default” namespace.

    roleRef is how you will actually create the binding. The kind will be either Role or ClusterRole, and the name will reference the name of the specific Role or ClusterRole you want. In the example below, this RoleBinding is using roleRef to bind the user “jane” to the Role created above named pod-reader.

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. # This role binding allows "jane" to read pods in the "default" namespace.
    3. kind: RoleBinding
    4. metadata:
    5. name: read-pods
    6. namespace: default
    7. subjects:
    8. - kind: User
    9. name: jane # Name is case sensitive
    10. apiGroup: rbac.authorization.k8s.io
    11. roleRef:
    12. kind: Role #this must be Role or ClusterRole
    13. name: pod-reader # this must match the name of the Role or ClusterRole you wish to bind to
    14. apiGroup: rbac.authorization.k8s.io

    A RoleBinding may also reference a ClusterRole to grant the permissions to namespacedresources defined in the ClusterRole within the RoleBinding’s namespace.This allows administrators to define a set of common roles for the entire cluster,then reuse them within multiple namespaces.

    For instance, even though the following RoleBinding refers to a ClusterRole,“dave” (the subject, case sensitive) will only be able to read secrets in the “development”namespace (the namespace of the RoleBinding).

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. # This role binding allows "dave" to read secrets in the "development" namespace.
    3. kind: RoleBinding
    4. metadata:
    5. name: read-secrets
    6. namespace: development # This only grants permissions within the "development" namespace.
    7. subjects:
    8. - kind: User
    9. name: dave # Name is case sensitive
    10. apiGroup: rbac.authorization.k8s.io
    11. roleRef:
    12. kind: ClusterRole
    13. name: secret-reader
    14. apiGroup: rbac.authorization.k8s.io

    Finally, a ClusterRoleBinding may be used to grant permission at the cluster level and in allnamespaces. The following ClusterRoleBinding allows any user in the group “manager” to readsecrets in any namespace.

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. # This cluster role binding allows anyone in the "manager" group to read secrets in any namespace.
    3. kind: ClusterRoleBinding
    4. metadata:
    5. name: read-secrets-global
    6. subjects:
    7. - kind: Group
    8. name: manager # Name is case sensitive
    9. apiGroup: rbac.authorization.k8s.io
    10. roleRef:
    11. kind: ClusterRole
    12. name: secret-reader
    13. apiGroup: rbac.authorization.k8s.io

    You cannot modify which Role or ClusterRole a binding object refers to.Attempts to change the roleRef field of a binding object will result in a validation error.To change the roleRef field on an existing binding object, the binding object must be deleted and recreated.There are two primary reasons for this restriction:

    • A binding to a different role is a fundamentally different binding.Requiring a binding to be deleted/recreated in order to change the roleRefensures the full list of subjects in the binding is intended to be grantedthe new role (as opposed to enabling accidentally modifying just the roleRefwithout verifying all of the existing subjects should be given the new role’s permissions).
    • Making roleRef immutable allows giving update permission on an existing binding objectto a user, which lets them manage the list of subjects, without being able to change therole that is granted to those subjects.The kubectl auth reconcile command-line utility creates or updates a manifest file containing RBAC objects,and handles deleting and recreating binding objects if required to change the role they refer to.See command usage and examples for more information.

    Referring to Resources

    Most resources are represented by a string representation of their name, such as “pods”, just as itappears in the URL for the relevant API endpoint. However, some Kubernetes APIs involve a“subresource”, such as the logs for a pod. The URL for the pods logs endpoint is:

    1. GET /api/v1/namespaces/{namespace}/pods/{name}/log

    In this case, “pods” is the namespaced resource, and “log” is a subresource of pods. To representthis in an RBAC role, use a slash to delimit the resource and subresource. To allow a subjectto read both pods and pod logs, you would write:

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: Role
    3. metadata:
    4. namespace: default
    5. name: pod-and-pod-logs-reader
    6. rules:
    7. - apiGroups: [""]
    8. resources: ["pods", "pods/log"]
    9. verbs: ["get", "list"]

    Resources can also be referred to by name for certain requests through the resourceNames list.When specified, requests can be restricted to individual instances of a resource. To restrict asubject to only “get” and “update” a single configmap, you would write:

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: Role
    3. metadata:
    4. namespace: default
    5. name: configmap-updater
    6. rules:
    7. - apiGroups: [""]
    8. resources: ["configmaps"]
    9. resourceNames: ["my-configmap"]
    10. verbs: ["update", "get"]

    Note that create requests cannot be restricted by resourceName, as the object name is not known atauthorization time. The other exception is deletecollection.

    Aggregated ClusterRoles

    As of 1.9, ClusterRoles can be created by combining other ClusterRoles using an aggregationRule. Thepermissions of aggregated ClusterRoles are controller-managed, and filled in by unioning the rules of anyClusterRole that matches the provided label selector. An example aggregated ClusterRole:

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: ClusterRole
    3. metadata:
    4. name: monitoring
    5. aggregationRule:
    6. clusterRoleSelectors:
    7. - matchLabels:
    8. rbac.example.com/aggregate-to-monitoring: "true"
    9. rules: [] # Rules are automatically filled in by the controller manager.

    Creating a ClusterRole that matches the label selector will add rules to the aggregated ClusterRole. In this caserules can be added to the “monitoring” ClusterRole by creating another ClusterRole that has the labelrbac.example.com/aggregate-to-monitoring: true.

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: ClusterRole
    3. metadata:
    4. name: monitoring-endpoints
    5. labels:
    6. rbac.example.com/aggregate-to-monitoring: "true"
    7. # These rules will be added to the "monitoring" role.
    8. rules:
    9. - apiGroups: [""]
    10. resources: ["services", "endpoints", "pods"]
    11. verbs: ["get", "list", "watch"]

    The default user-facing roles (described below) use ClusterRole aggregation. This lets admins include rulesfor custom resources, such as those served by CustomResourceDefinitions or Aggregated API servers, on thedefault roles.

    For example, the following ClusterRoles let the “admin” and “edit” default roles manage the custom resource“CronTabs” and the “view” role perform read-only actions on the resource.

    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: ClusterRole
    3. metadata:
    4. name: aggregate-cron-tabs-edit
    5. labels:
    6. # Add these permissions to the "admin" and "edit" default roles.
    7. rbac.authorization.k8s.io/aggregate-to-admin: "true"
    8. rbac.authorization.k8s.io/aggregate-to-edit: "true"
    9. rules:
    10. - apiGroups: ["stable.example.com"]
    11. resources: ["crontabs"]
    12. verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
    13. ---
    14. kind: ClusterRole
    15. apiVersion: rbac.authorization.k8s.io/v1
    16. metadata:
    17. name: aggregate-cron-tabs-view
    18. labels:
    19. # Add these permissions to the "view" default role.
    20. rbac.authorization.k8s.io/aggregate-to-view: "true"
    21. rules:
    22. - apiGroups: ["stable.example.com"]
    23. resources: ["crontabs"]
    24. verbs: ["get", "list", "watch"]

    Role Examples

    Only the rules section is shown in the following examples.

    Allow reading the resource “pods” in the core API GroupA set of related paths in the Kubernetes API.:

    1. rules:
    2. - apiGroups: [""]
    3. resources: ["pods"]
    4. verbs: ["get", "list", "watch"]

    Allow reading/writing “deployments” in both the “extensions” and “apps” API groups:

    1. rules:
    2. - apiGroups: ["extensions", "apps"]
    3. resources: ["deployments"]
    4. verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

    Allow reading “pods” and reading/writing “jobs”:

    1. rules:
    2. - apiGroups: [""]
    3. resources: ["pods"]
    4. verbs: ["get", "list", "watch"]
    5. - apiGroups: ["batch", "extensions"]
    6. resources: ["jobs"]
    7. verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

    Allow reading a ConfigMap named “my-config” (must be bound with a RoleBinding to limit to a single ConfigMap in a single namespace):

    1. rules:
    2. - apiGroups: [""]
    3. resources: ["configmaps"]
    4. resourceNames: ["my-config"]
    5. verbs: ["get"]

    Allow reading the resource “nodes” in the core group (because a Node is cluster-scoped, this must be in a ClusterRole bound with a ClusterRoleBinding to be effective):

    1. rules:
    2. - apiGroups: [""]
    3. resources: ["nodes"]
    4. verbs: ["get", "list", "watch"]

    Allow “GET” and “POST” requests to the non-resource endpoint “/healthz” and all subpaths (must be in a ClusterRole bound with a ClusterRoleBinding to be effective):

    1. rules:
    2. - nonResourceURLs: ["/healthz", "/healthz/*"] # '*' in a nonResourceURL is a suffix glob match
    3. verbs: ["get", "post"]

    Referring to Subjects

    A RoleBinding or ClusterRoleBinding binds a role to subjects.Subjects can be groups, users or service accounts.

    Users are represented by strings. These can be plain usernames, like“alice”, email-style names, like “bob@example.com”, or numeric IDsrepresented as a string. It is up to the Kubernetes admin to configurethe authentication modules to produceusernames in the desired format. The RBAC authorization system doesnot require any particular format. However, the prefix system: isreserved for Kubernetes system use, and so the admin should ensureusernames do not contain this prefix by accident.

    Group information in Kubernetes is currently provided by the Authenticatormodules. Groups, like users, are represented as strings, and that stringhas no format requirements, other than that the prefix system: is reserved.

    Service Accounts have usernames with the system:serviceaccount: prefix and belongto groups with the system:serviceaccounts: prefix.

    Role Binding Examples

    Only the subjects section of a RoleBinding is shown in the following examples.

    For a user named “alice@example.com”:

    1. subjects:
    2. - kind: User
    3. name: "alice@example.com"
    4. apiGroup: rbac.authorization.k8s.io

    For a group named “frontend-admins”:

    1. subjects:
    2. - kind: Group
    3. name: "frontend-admins"
    4. apiGroup: rbac.authorization.k8s.io

    For the default service account in the kube-system namespace:

    1. subjects:
    2. - kind: ServiceAccount
    3. name: default
    4. namespace: kube-system

    For all service accounts in the “qa” namespace:

    1. subjects:
    2. - kind: Group
    3. name: system:serviceaccounts:qa
    4. apiGroup: rbac.authorization.k8s.io

    For all service accounts everywhere:

    1. subjects:
    2. - kind: Group
    3. name: system:serviceaccounts
    4. apiGroup: rbac.authorization.k8s.io

    For all authenticated users (version 1.5+):

    1. subjects:
    2. - kind: Group
    3. name: system:authenticated
    4. apiGroup: rbac.authorization.k8s.io

    For all unauthenticated users (version 1.5+):

    1. subjects:
    2. - kind: Group
    3. name: system:unauthenticated
    4. apiGroup: rbac.authorization.k8s.io

    For all users (version 1.5+):

    1. subjects:
    2. - kind: Group
    3. name: system:authenticated
    4. apiGroup: rbac.authorization.k8s.io
    5. - kind: Group
    6. name: system:unauthenticated
    7. apiGroup: rbac.authorization.k8s.io

    Default Roles and Role Bindings

    API servers create a set of default ClusterRole and ClusterRoleBinding objects.Many of these are system: prefixed, which indicates that the resource is “owned” by the infrastructure.Modifications to these resources can result in non-functional clusters. One example is the system:node ClusterRole.This role defines permissions for kubelets. If the role is modified, it can prevent kubelets from working.

    All of the default cluster roles and rolebindings are labeled with kubernetes.io/bootstrapping=rbac-defaults.

    Auto-reconciliation

    At each start-up, the API server updates default cluster roles with any missing permissions,and updates default cluster role bindings with any missing subjects.This allows the cluster to repair accidental modifications,and to keep roles and rolebindings up-to-date as permissions and subjects change in new releases.

    To opt out of this reconciliation, set the rbac.authorization.kubernetes.io/autoupdateannotation on a default cluster role or rolebinding to false.Be aware that missing default permissions and subjects can result in non-functional clusters.

    Auto-reconciliation is enabled in Kubernetes version 1.6+ when the RBAC authorizer is active.

    Discovery Roles

    Default role bindings authorize unauthenticated and authenticated users to read API information that is deemed safe to be publicly accessible (including CustomResourceDefinitions). To disable anonymous unauthenticated access add —anonymous-auth=false to the API server configuration.

    To view the configuration of these roles via kubectl run:

    1. kubectl get clusterroles system:discovery -o yaml

    NOTE: editing the role is not recommended as changes will be overwritten on API server restart via auto-reconciliation (see above).

    Default ClusterRoleDefault ClusterRoleBindingDescription
    system:basic-usersystem:authenticated groupAllows a user read-only access to basic information about themselves. Prior to 1.14, this role was also bound to system:unauthenticated by default.
    system:discoverysystem:authenticated groupAllows read-only access to API discovery endpoints needed to discover and negotiate an API level. Prior to 1.14, this role was also bound to system:unauthenticated by default.
    system:public-info-viewersystem:authenticated and system:unauthenticated groupsAllows read-only access to non-sensitive information about the cluster. Introduced in 1.14.

    User-facing Roles

    Some of the default roles are not system: prefixed. These are intended to be user-facing roles.They include super-user roles (cluster-admin),roles intended to be granted cluster-wide using ClusterRoleBindings (cluster-status),and roles intended to be granted within particular namespaces using RoleBindings (admin, edit, view).

    As of 1.9, user-facing roles use ClusterRole Aggregation to allow admins to includerules for custom resources on these roles. To add rules to the “admin”, “edit”, or “view” role, create aClusterRole with one or more of the following labels:

    1. metadata:
    2. labels:
    3. rbac.authorization.k8s.io/aggregate-to-admin: "true"
    4. rbac.authorization.k8s.io/aggregate-to-edit: "true"
    5. rbac.authorization.k8s.io/aggregate-to-view: "true"
    Default ClusterRoleDefault ClusterRoleBindingDescription
    cluster-adminsystem:masters groupAllows super-user access to perform any action on any resource.When used in a ClusterRoleBinding, it gives full control over every resource in the cluster and in all namespaces.When used in a RoleBinding, it gives full control over every resource in the rolebinding's namespace, including the namespace itself.
    adminNoneAllows admin access, intended to be granted within a namespace using a RoleBinding.If used in a RoleBinding, allows read/write access to most resources in a namespace,including the ability to create roles and rolebindings within the namespace.It does not allow write access to resource quota or to the namespace itself.
    editNoneAllows read/write access to most objects in a namespace.It does not allow viewing or modifying roles or rolebindings.
    viewNoneAllows read-only access to see most objects in a namespace.It does not allow viewing roles or rolebindings.It does not allow viewing secrets, since those are escalating.

    Core Component Roles

    Default ClusterRoleDefault ClusterRoleBindingDescription
    system:kube-schedulersystem:kube-scheduler userAllows access to the resources required by the kube-scheduler component.
    system:volume-schedulersystem:kube-scheduler userAllows access to the volume resources required by the kube-scheduler component.
    system:kube-controller-managersystem:kube-controller-manager userAllows access to the resources required by the kube-controller-manager component.The permissions required by individual control loops are contained in the controller roles.
    system:nodeNone in 1.8+Allows access to resources required by the kubelet component, including read access to all secrets, and write access to all pod status objects.As of 1.7, use of the Node authorizer and NodeRestriction admission plugin is recommended instead of this role, and allow granting API access to kubelets based on the pods scheduled to run on them.Prior to 1.7, this role was automatically bound to the system:nodes group.In 1.7, this role was automatically bound to the system:nodes group if the Node authorization mode is not enabled.In 1.8+, no binding is automatically created.
    system:node-proxiersystem:kube-proxy userAllows access to the resources required by the kube-proxy component.

    Other Component Roles

    Default ClusterRoleDefault ClusterRoleBindingDescription
    system:auth-delegatorNoneAllows delegated authentication and authorization checks.This is commonly used by add-on API servers for unified authentication and authorization.
    system:heapsterNoneRole for the Heapster component.
    system:kube-aggregatorNoneRole for the kube-aggregator component.
    system:kube-dnskube-dns service account in the kube-system namespaceRole for the kube-dns component.
    system:kubelet-api-adminNoneAllows full access to the kubelet API.
    system:node-bootstrapperNoneAllows access to the resources required to performKubelet TLS bootstrapping.
    system:node-problem-detectorNoneRole for the node-problem-detector component.
    system:persistent-volume-provisionerNoneAllows access to the resources required by most dynamic volume provisioners.

    Controller Roles

    The Kubernetes controller manager runs core control loops.When invoked with —use-service-account-credentials, each control loop is started using a separate service account.Corresponding roles exist for each control loop, prefixed with system:controller:.If the controller manager is not started with —use-service-account-credentials,it runs all control loops using its own credential, which must be granted all the relevant roles.These roles include:

    • system:controller:attachdetach-controller
    • system:controller:certificate-controller
    • system:controller:clusterrole-aggregation-controller
    • system:controller:cronjob-controller
    • system:controller:daemon-set-controller
    • system:controller:deployment-controller
    • system:controller:disruption-controller
    • system:controller:endpoint-controller
    • system:controller:expand-controller
    • system:controller:generic-garbage-collector
    • system:controller:horizontal-pod-autoscaler
    • system:controller:job-controller
    • system:controller:namespace-controller
    • system:controller:node-controller
    • system:controller:persistent-volume-binder
    • system:controller:pod-garbage-collector
    • system:controller:pv-protection-controller
    • system:controller:pvc-protection-controller
    • system:controller:replicaset-controller
    • system:controller:replication-controller
    • system:controller:resourcequota-controller
    • system:controller:root-ca-cert-publisher
    • system:controller:route-controller
    • system:controller:service-account-controller
    • system:controller:service-controller
    • system:controller:statefulset-controller
    • system:controller:ttl-controller

    Privilege Escalation Prevention and Bootstrapping

    The RBAC API prevents users from escalating privileges by editing roles or role bindings.Because this is enforced at the API level, it applies even when the RBAC authorizer is not in use.

    A user can only create/update a role if at least one of the following things is true:

    • They already have all the permissions contained in the role, at the same scope as the object being modified(cluster-wide for a ClusterRole, within the same namespace or cluster-wide for a Role)
    • They are given explicit permission to perform the escalate verb on the roles or clusterroles resource in the rbac.authorization.k8s.io API group (Kubernetes 1.12 and newer)For example, if “user-1” does not have the ability to list secrets cluster-wide, they cannot create a ClusterRolecontaining that permission. To allow a user to create/update roles:

    • Grant them a role that allows them to create/update Role or ClusterRole objects, as desired.

    • Grant them permission to include specific permissions in the roles the create/update:

      • implicitly, by giving them those permissions (if they attempt to create or modify a Role or ClusterRole with permissions they themselves have not been granted, the API request will be forbidden)
      • or explicitly allow specifying any permission in a Role or ClusterRole by giving them permission to perform the escalate verb on roles or clusterroles resources in the rbac.authorization.k8s.io API group (Kubernetes 1.12 and newer)A user can only create/update a role binding if they already have all the permissions contained in the referenced role(at the same scope as the role binding) or if they’ve been given explicit permission to perform the bind verb on the referenced role.For example, if “user-1” does not have the ability to list secrets cluster-wide, they cannot create a ClusterRoleBindingto a role that grants that permission. To allow a user to create/update role bindings:
    • Grant them a role that allows them to create/update RoleBinding or ClusterRoleBinding objects, as desired.

    • Grant them permissions needed to bind a particular role:
      • implicitly, by giving them the permissions contained in the role.
      • explicitly, by giving them permission to perform the bind verb on the particular role (or cluster role).For example, this cluster role and role binding would allow “user-1” to grant other users the admin, edit, and view roles in the “user-1-namespace” namespace:
    1. apiVersion: rbac.authorization.k8s.io/v1
    2. kind: ClusterRole
    3. metadata:
    4. name: role-grantor
    5. rules:
    6. - apiGroups: ["rbac.authorization.k8s.io"]
    7. resources: ["rolebindings"]
    8. verbs: ["create"]
    9. - apiGroups: ["rbac.authorization.k8s.io"]
    10. resources: ["clusterroles"]
    11. verbs: ["bind"]
    12. resourceNames: ["admin","edit","view"]
    13. ---
    14. apiVersion: rbac.authorization.k8s.io/v1
    15. kind: RoleBinding
    16. metadata:
    17. name: role-grantor-binding
    18. namespace: user-1-namespace
    19. roleRef:
    20. apiGroup: rbac.authorization.k8s.io
    21. kind: ClusterRole
    22. name: role-grantor
    23. subjects:
    24. - apiGroup: rbac.authorization.k8s.io
    25. kind: User
    26. name: user-1

    When bootstrapping the first roles and role bindings, it is necessary for the initial user to grant permissions they do not yet have.To bootstrap initial roles and role bindings:

    • Use a credential with the system:masters group, which is bound to the cluster-admin super-user role by the default bindings.
    • If your API server runs with the insecure port enabled (—insecure-port), you can also make API calls via that port, which does not enforce authentication or authorization.

    Command-line Utilities

    kubectl create role

    Creates a Role object defining permissions within a single namespace. Examples:

    • Create a Role named “pod-reader” that allows user to perform “get”, “watch” and “list” on pods:
    1. kubectl create role pod-reader --verb=get --verb=list --verb=watch --resource=pods
    • Create a Role named “pod-reader” with resourceNames specified:
    1. kubectl create role pod-reader --verb=get --resource=pods --resource-name=readablepod --resource-name=anotherpod
    • Create a Role named “foo” with apiGroups specified:
    1. kubectl create role foo --verb=get,list,watch --resource=replicasets.apps
    • Create a Role named “foo” with subresource permissions:
    1. kubectl create role foo --verb=get,list,watch --resource=pods,pods/status
    • Create a Role named “my-component-lease-holder” with permissions to get/update a resource with a specific name:
    1. kubectl create role my-component-lease-holder --verb=get,list,watch,update --resource=lease --resource-name=my-component

    kubectl create clusterrole

    Creates a ClusterRole object. Examples:

    • Create a ClusterRole named “pod-reader” that allows user to perform “get”, “watch” and “list” on pods:
    1. kubectl create clusterrole pod-reader --verb=get,list,watch --resource=pods
    • Create a ClusterRole named “pod-reader” with resourceNames specified:
    1. kubectl create clusterrole pod-reader --verb=get --resource=pods --resource-name=readablepod --resource-name=anotherpod
    • Create a ClusterRole named “foo” with apiGroups specified:
    1. kubectl create clusterrole foo --verb=get,list,watch --resource=replicasets.apps
    • Create a ClusterRole named “foo” with subresource permissions:
    1. kubectl create clusterrole foo --verb=get,list,watch --resource=pods,pods/status
    • Create a ClusterRole name “foo” with nonResourceURL specified:
    1. kubectl create clusterrole "foo" --verb=get --non-resource-url=/logs/*
    • Create a ClusterRole name “monitoring” with aggregationRule specified:
    1. kubectl create clusterrole monitoring --aggregation-rule="rbac.example.com/aggregate-to-monitoring=true"

    kubectl create rolebinding

    Grants a Role or ClusterRole within a specific namespace. Examples:

    • Within the namespace “acme”, grant the permissions in the admin ClusterRole to a user named “bob”:
    1. kubectl create rolebinding bob-admin-binding --clusterrole=admin --user=bob --namespace=acme
    • Within the namespace “acme”, grant the permissions in the view ClusterRole to the service account in the namespace “acme” named “myapp” :
    1. kubectl create rolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp --namespace=acme
    • Within the namespace “acme”, grant the permissions in the view ClusterRole to a service account in the namespace “myappnamespace” named “myapp”:
    1. kubectl create rolebinding myappnamespace-myapp-view-binding --clusterrole=view --serviceaccount=myappnamespace:myapp --namespace=acme

    kubectl create clusterrolebinding

    Grants a ClusterRole across the entire cluster, including all namespaces. Examples:

    • Across the entire cluster, grant the permissions in the cluster-admin ClusterRole to a user named “root”:
    1. kubectl create clusterrolebinding root-cluster-admin-binding --clusterrole=cluster-admin --user=root
    • Across the entire cluster, grant the permissions in the system:node-proxier ClusterRole to a user named “system:kube-proxy”:
    1. kubectl create clusterrolebinding kube-proxy-binding --clusterrole=system:node-proxier --user=system:kube-proxy
    • Across the entire cluster, grant the permissions in the view ClusterRole to a service account named “myapp” in the namespace “acme”:
    1. kubectl create clusterrolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp

    kubectl auth reconcile

    Creates or updates rbac.authorization.k8s.io/v1 API objects from a manifest file.

    Missing objects are created, and the containing namespace is created for namespaced objects, if required.

    Existing roles are updated to include the permissions in the input objects,and remove extra permissions if —remove-extra-permissions is specified.

    Existing bindings are updated to include the subjects in the input objects,and remove extra subjects if —remove-extra-subjects is specified.

    Examples:

    • Test applying a manifest file of RBAC objects, displaying changes that would be made:
    1. kubectl auth reconcile -f my-rbac-rules.yaml --dry-run
    • Apply a manifest file of RBAC objects, preserving any extra permissions (in roles) and any extra subjects (in bindings):
    1. kubectl auth reconcile -f my-rbac-rules.yaml
    • Apply a manifest file of RBAC objects, removing any extra permissions (in roles) and any extra subjects (in bindings):
    1. kubectl auth reconcile -f my-rbac-rules.yaml --remove-extra-subjects --remove-extra-permissions

    See the CLI help for detailed usage.

    Service Account Permissions

    Default RBAC policies grant scoped permissions to control-plane components, nodes,and controllers, but grant no permissions to service accounts outside the kube-system namespace(beyond discovery permissions given to all authenticated users).

    This allows you to grant particular roles to particular service accounts as needed.Fine-grained role bindings provide greater security, but require more effort to administrate.Broader grants can give unnecessary (and potentially escalating) API access to service accounts, but are easier to administrate.

    In order from most secure to least secure, the approaches are:

    • Grant a role to an application-specific service account (best practice)

    This requires the application to specify a serviceAccountName in its pod spec,and for the service account to be created (via the API, application manifest, kubectl create serviceaccount, etc.).

    For example, grant read-only permission within “my-namespace” to the “my-sa” service account:

    1. kubectl create rolebinding my-sa-view \
    2. --clusterrole=view \
    3. --serviceaccount=my-namespace:my-sa \
    4. --namespace=my-namespace
    • Grant a role to the “default” service account in a namespace

    If an application does not specify a serviceAccountName, it uses the “default” service account.

    Note: Permissions given to the “default” serviceaccount are available to any pod in the namespace that does notspecify a serviceAccountName.

    For example, grant read-only permission within “my-namespace” to the “default” service account:

    1. kubectl create rolebinding default-view \
    2. --clusterrole=view \
    3. --serviceaccount=my-namespace:default \
    4. --namespace=my-namespace

    Many add-ons currently run as the “default” service account in the kube-system namespace.To allow those add-ons to run with super-user access, grant cluster-admin permissions to the “default” service account in the kube-system namespace.

    Note: Enabling this means the kube-systemnamespace contains secrets that grant super-user access to theAPI.
    1. kubectl create clusterrolebinding add-on-cluster-admin \
    2. --clusterrole=cluster-admin \
    3. --serviceaccount=kube-system:default
    • Grant a role to all service accounts in a namespace

    If you want all applications in a namespace to have a role, no matter what service account they use,you can grant a role to the service account group for that namespace.

    For example, grant read-only permission within “my-namespace” to all service accounts in that namespace:

    1. kubectl create rolebinding serviceaccounts-view \
    2. --clusterrole=view \
    3. --group=system:serviceaccounts:my-namespace \
    4. --namespace=my-namespace
    • Grant a limited role to all service accounts cluster-wide (discouraged)

    If you don’t want to manage permissions per-namespace, you can grant a cluster-wide role to all service accounts.

    For example, grant read-only permission across all namespaces to all service accounts in the cluster:

    1. kubectl create clusterrolebinding serviceaccounts-view \
    2. --clusterrole=view \
    3. --group=system:serviceaccounts
    • Grant super-user access to all service accounts cluster-wide (strongly discouraged)

    If you don’t care about partitioning permissions at all, you can grant super-user access to all service accounts.

    Warning: This allows any user with read accessto secrets or the ability to create a pod to access super-usercredentials.
    1. kubectl create clusterrolebinding serviceaccounts-cluster-admin \
    2. --clusterrole=cluster-admin \
    3. --group=system:serviceaccounts

    Upgrading from 1.5

    Prior to Kubernetes 1.6, many deployments used very permissive ABAC policies,including granting full API access to all service accounts.

    Default RBAC policies grant scoped permissions to control-plane components, nodes,and controllers, but grant no permissions to service accounts outside the kube-system namespace(beyond discovery permissions given to all authenticated users).

    While far more secure, this can be disruptive to existing workloads expecting to automatically receive API permissions.Here are two approaches for managing this transition:

    Parallel Authorizers

    Run both the RBAC and ABAC authorizers, and specify a policy file that containsthe legacy ABAC policy:

    1. --authorization-mode=RBAC,ABAC --authorization-policy-file=mypolicy.json

    The RBAC authorizer will attempt to authorize requests first. If it denies an API request,the ABAC authorizer is then run. This means that any request allowed by either the RBACor ABAC policies is allowed.

    When the apiserver is run with a log level of 5 or higher for the RBAC component (—vmodule=rbac*=5 or —v=5),you can see RBAC denials in the apiserver log (prefixed with RBAC DENY:).You can use that information to determine which roles need to be granted to which users, groups, or service accounts.Once you have granted roles to service accounts and workloads are running with no RBAC denial messagesin the server logs, you can remove the ABAC authorizer.

    Permissive RBAC Permissions

    You can replicate a permissive policy using RBAC role bindings.

    Warning:

    The following policy allows ALL service accounts to act as cluster administrators.Any application running in a container receives service account credentials automatically,and could perform any action against the API, including viewing secrets and modifying permissions.This is not a recommended policy.

    1. kubectl create clusterrolebinding permissive-binding \ clusterrole=cluster-admin \ user=admin \ user=kubelet \ group=system:serviceaccounts

    Feedback

    Was this page helpful?

    Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it onStack Overflow.Open an issue in the GitHub repo if you want toreport a problemorsuggest an improvement.