Files
website/docs/admin/authorization/rbac.md
T
Zach Corleissen 08af95d42e Release 1.9 (#5978)
* Trivial change to open release branch

* Undo trivial change

* add service ipvs overview

* Add instructions on how to setup kubectl

* Document conntrack dependency for kube-proxy

* Add an a

This is kind of jarring / missing an article. I'm guessing it should either be ' to a rack of bare metal servers.' or '...to racks of bare metal servers.'.

* adding example responses for common issues

 - support request
 - code bug report

* Trivial change to open release branch

* Undo trivial change

* Signed-off-by: Ziqi Zhao <zhaoziqi@qiniu.com> (#5366)

Fix the not-working test case yaml for /doc/concepts/storage/volumes.md

* kubectl-overview

* temp fix for broken pod and deployment links

* Update Table of Solutions for Juju

* Revise certificates documentation (#5965)

* Update review-issues.md

Some edits for clarity and condensed language.

* Update init-containers.md

Fix leading spaces in commands.

* Update kubectl-overview.md

Fix format.

* Update clc.md

Fix format.

* Update openstack-heat.md

The url no need. just  highlight.

* Typo

I believe this should be "users" not "uses"

* making explicit hostname uniq requirement

* Update scheduling-hugepages.md

* Update update-daemon-set.md

* fix redirection of PersistentVolume

* Update hpa.md

* update kubectl instruction

* Use the format of kubeadm init

* fix spelling error

guarnatees  to guarantees

* add matchLabels description (#6020)

* search and replace for k8s.github.io to website (#6019)

* fix scale command of object-management (#6011)

* Update replicaset.md (#6009)

* Update secret.md (#6008)

* specify password for mysql image (#5990)

* specify password for mysql image

* specify password for mysql image

* link error for run-stateless-application-deployment.md (#5985)

* link error for run-stateless-application-deployment.md

* link error for run-stateless-application-deployment.md

* Add performance implications of inter-pod affinity/anti-affinity (#5979)

* 404 monthly maintenance - October 2017 (#5977)

* Updated redirects

* More redirects

* Add conjure-up to Turnkey Cloud Solutions list (#5973)

* Add conjure-up to Turnkey Cloud Solutions list

* Changed wording slightly

* change the StatefulSet to ReplicaSet in reference (#5968)

* Clarification of failureThreshold of probes (#5963)

* Mention usage of block storage version param (#5925)

Mention usage of block storage version (bs-version) parameter to
workaround attachment issues using older K8S versions on an OpenStack
cloud with path-based endpoints.

Resolves: https://github.com/kubernetes/kubernetes.github.io/issues/5924

* Update sysctl-cluster.md (#5894)

Include guide on enabling unsafe sysctls in minikube

* Avoid Latin phrases & format note (#5889)

* Avoid Latin phrases & format note

according the Documentation Style Guide

* Update scratch.md

* Update scratch.md

* resolves jekyll rendering error (#5976)

- chinese isn't understood for keys in YAML frontmatter in jekyll, so
   replaced it with the english equivalent that doesn't throw the
following error on rendering:

Error reading file src/kubernetes.github.io/cn/docs/concepts/cluster-administration/device-plugins.md: (<unknown>): could not find expected ':' while scanning a simple key at line 4 column 1

* Change VM to pod. (#6022)

* Add link to custom metrics. (#6023)

* Rephrase core group. (#6024)

* Added explanation on context to when joining (#6018)

* Update create-cluster-kubeadm.md (#5761)

Update Canal version in pod network apply commands

* Fixes issue #5620 (#5869)

* Fixes issue #5620

Signed-off-by: Brad Topol <btopol@us.ibm.com>

* Restructured so that review process is for both current and upcoming
releases.  Added content describing the use of tech reviewers.

* Removed incorrect Kubernetes reviewer link.

* Fixed tech reviewer URL to now use website

* Update pod-priority-preemption.md

fix-wrong-link-to-pod-preemption

* pod-security-policy.md: add links to the page about admission plugins.

* Adding all files for BlaBlaCar case study (#5857)

* Adding all files for BlaBlaCar case study

* Update blablacar.html

* Fix changed URL for google containers

* Add /docs/reference/auto-generated directory

* correct the downwardapi redirect

* Remove links using "here"

* Rename to /docs/reference/generated directory

* add Concept template

* Change title to just Ingress

* Link mistake (#6038)

* link mistake

* link mistake

* skip title check for skip_title_check.txt

* skip title check for skip_title_check.txt

* remove doesn't exist link.

* Fix podpreset task (#5705)

* Add a simple pod manifest to pod overview (#5986)

* Split PodPreset concept out from task doc (#5984)

* Add selector spec description (#5789)

* Add selector spec description

* Fix selector field explanation

* Put orphaned topics in TOC. (#6051)

* static-pod example bad format in the final page (#6050)

* static-pod example bad format in the final page

* static-pod example bad format in the final page

* static-pod example bad format in the final page

* static-pod example bad format in the final page

* static-pod example bad format in the final page

* Fix `backoffLimit` field misplacement (#6042)

It should be placed in JobSpec according to:
https://github.com/kubernetes/kubernetes/blob/master/api/swagger-spec/batch_v1.json#L1488-L1514

* Update addons.md (#6061)

* add info about VMware NSX-T CNI plugin (#5987)

* add info about VMware NSX-T CNI plugin

Hello,

I'm VMware Networking and Security Architect and would like to include short information about our CNI plugin implementation similar to what other vendors did

Best regards

Emil Gagala

* Update networking.md

* Update networking.md

* Update networking.md

* Update: Using universal zsh configuration (#5669)

* Update install-kubectl.md

Zsh is not only oh-my-zsh, so I added universal configuration for zsh that also can be used in prezto.

* fix merge error after rebase

* Operating etcd cluster for Kubernetes bad format in the final page (#6056)

* Operating etcd cluster for Kubernetes bad format in the final page

* Update configure-upgrade-etcd.md

* Update configure-upgrade-etcd.md

* Usage note and warning tags. (#6053)

* Usage note and warning tags.

* Update configure-upgrade-etcd.md

* Update configure-upgrade-etcd.md

* Document jekyll includes snippets

* Add jekyll includes to docs home toc

- Remove extra kubernetes home in toc

* document docker cgroupdriver req (#5937)

* Update test blacklists (#6063)

* Update toc check blacklist

* Update title check blacklist

* wip

* wip

* Fix typo

* Document unconfined apparmor profile

* Revert "Document the unconfined profile for AppArmor" (#6268)

* CRD Validation: remove alpha warning, change enable instructions to (#6066)

disable

* Documented service annotation for AWS ELB SSL policy

* kubeadm: add a note about the new `--print-join-command` flag.

This is a new flag for the `kubeadm token create` command.

* Add a note to PDB page

* Improve Kubeadm reference doc (#6103)

* automatically-generated kubeadm reference doc

* user-mantained kubeadm reference doc

* Documentation for CSIPersistentVolume

* change replicaset documentation to use apps/v1 APIs

* Update service.md

ipvs alpha version -> beta version

* Updated Deployment concept docs (#6494)

* Updated Deployment concept docs

* Addressed comments

* Documentation for volume scheduling alpha feature

* Update admission control docs for webhooks

* Improve DNS documentation (#6479)

* update ds for 1.9

* Update service.md

* Update service.md

* Revert "begin updating webhook documentation" (#6575)

* Update version numbers to include 1.9 (#6518)

* Update site versions for 1.9

* Removed 1.4 docs

* Update _config.yml

* Update _config.yml

* updates for raw block devices

* rbac: docs for aggregated cluster roles (#6474)

* Added IPv6 information for Kubelet arguments (#6498)

* Added IPv6 info to kube-proxy arguments

* Added IPv6 information for argument for kubelet

* Update PVC resizing documentation (#6487)

* Updates for Windows Server version 1709 with K8s v1.8 (#6180)

* Updated for WSv1709 and K8s v1.8

* Updated picture and CNI config

* Fixed formatting on CNI Config

* Updated docs to reference Microsoft/SDN GitHub docs

* fix typo

* Workaround for Jekyllr frontmatter

* Added section on features and limitations, with example yaml files.

* Update index.md

* Added kubeadm section, few other small fixes

* Few minor grammar fixes

* Update access-cluster.md with a comment that for IPv6
the user should use [::1] for the localhost

* Addressed a number of issues brought up against the base PR

* Fixed windows-host-setup link

* Rewrite PodSecurityPolicy guide

* Update index.md

Signed-off-by: Alin Balutoiu <abalutoiu@cloudbasesolutions.com>
Signed-off-by: Alin Gabriel Serdean <aserdean@ovn.org>

* Spelling correction and sentence capitalization.

- Corrected the spelling error for storing, was put in as 'stoing'.
- Capitalized list items.
- Added '.' at end of sentences in the list items.

* Update index.md

* Update index.md

* Addressed comments and rebased

* Fixed formatting

* Fixed formatting

* Updated header link

* Updated hyperlinks

* Updated warning

* formatting

* formatting

* formatting

* Revert "Update access-cluster.md with a comment that for IPv6"

This reverts commit 31e4dbdc25.

* Revert "fix typo"

This reverts commit c05678752d.

* Revert "Workaround for Jekyllr frontmatter"

This reverts commit b84ac59624.

* Fixed grammatical issues and reverted non-related commits

* Revert "Rewrite PodSecurityPolicy guide"

This reverts commit 5d39cfeae4.

* Revert "Spelling correction and sentence capitalization."

This reverts commit 47eed4346e.

* Fixed auto-numbering

* Minor formatting updates

* CoreDNS feature documentation (#6463)

* Initial placeholder PR for CoreDNS feature documentation

* Remove from admin, add content

* Fix missing endcapture

* Add to tasks.yml

* Review feedback

* Postpone Deletion of a Persistent Volume Claim in case It Is Used by a Pod (#6415)

* Postpone Deletion of a Persistent Volume Claim in case It Is Used by a Pod

A new feature PVC Protection was added into K8s 1.9 that's why this documentation change is needed.

* Added tag at the top of each new area.

* Fix typo

* Fix: switched on in (all kubelets) -> (all K8s components).

* Added link to admission controller

* Moved PVC Protection configuration into Before you begin section.

* Added steps how to verify PVC Protection feature.

* Fixes for admission controller plugin description and for PVC Protection description in PVC lifecycle.

* Testing official rendering of enumerations (1., 2., 3., etc.)

* Re-write to address comments from review.

* Fixed definition when a PVC is in active use by a pod.

* Change auditing docs page for 1.9 release (#6427)

* Change auditing docs page for 1.9 release

Signed-off-by: Mik Vyatskov <vmik@google.com>

* Address review comments

Signed-off-by: Mik Vyatskov <vmik@google.com>

* Address review comments

Signed-off-by: Mik Vyatskov <vmik@google.com>

* Address review comments

Signed-off-by: Mik Vyatskov <vmik@google.com>

* Fix broken link

Signed-off-by: Mik Vyatskov <vmik@google.com>

* short circuit deny docs (#6536)

* line wrap

* short circuit deny

* address comments

* Add kubeadm 1.9 upgrade docs (#6485)

* kubeadm: Improve kubeadm documentation for v1.9 (#6645)

* Update admission control docs for webhooks (re-send #6368) (#6650)

* Update admission control docs for webhooks

* update in response to comments

* Revamp rkt and add CRI-O as alternative runtime (#6371)

Signed-off-by: Lorenzo Fontana <lo@linux.com>

* Documented NLB for Kubernetes 1.9 (#6260)

* Added IPV6 information to setup cluster using kubeadm (#6465)

* Added IPV6 information to setup cluster using kubeadm

* Updated kubeadm.md & create-cluster-kubeadm.md with IPv6 related information

* Added IPv6 options for kubeadm --init  & automated address binding for kube-proxy based on version of IP configured for API server)

* Changes to kubeadm.md as per comments

* Modified kubeadm.md and create-cluster-kubeadm.md

* Implemented changes requested by zacharysarah

* Removed autogenerated kubeadm.md changes

* StatefulSet 1.9 updates. (#6550)

* updates sts concept and tutorials to use 1.9 apps/v1

* Update statefulset.md

* clarify pod name label

* Garbage collection updates for 1.9 (#6555)

* 1.9 gc policy update

* carify deletion

* Couple nits for dnsConfig doc (#6652)

* Add doc for AllowedFlexVolume (#6563)

* Update OpenStack Cloud Provider API support for v1.9 (#6638)

* Flex volume is GA. Remove alpha notation. (#6666)

* Update generated ref docs for Kubernetes and Federation components. (#6658)

* Update generated ref docs for Kubernetes and Federation components.

* Rename kubectl-options to kubectl.

* Add title to kubectl.

* Fix double synopsis.

* Update Federation API ref docs for 1.9. (#6636)

* Update federation API ref docs.

* Move and redirect.

* Move generated Federation docs to the generated directory.

* Fix titles.

* Type

* Fix titles

* Update auto-generated Kubernetes APi ref docs. (#6646)

* Update kubectl commands for 1.9 (#6635)

* add ExtendedResourceToleration admission controller (#6618)

* Update API reference paths for v1.9 (#6681)
2017-12-15 17:36:13 -06:00

32 KiB

approvers, title
approvers title
erictune
deads2k
liggitt
Using RBAC Authorization
  • TOC {:toc}

Role-Based Access Control ("RBAC") uses the "rbac.authorization.k8s.io" API group to drive authorization decisions, allowing admins to dynamically configure policies through 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 this section. Users can interact with these resources as they would with any other API resource (via kubectl, API calls, etc.). For instance, kubectl create -f (resource).yml can be used with any of these examples, though readers who wish to follow along should review the section on bootstrapping 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:

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  namespace: default
  name: pod-reader
rules:
- apiGroups: [""] # "" indicates the core API group
  resources: ["pods"]
  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):

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  # "namespace" omitted since ClusterRoles are not namespaced
  name: secret-reader
rules:
- apiGroups: [""]
  resources: ["secrets"]
  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.

# This role binding allows "jane" to read pods in the "default" namespace.
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: read-pods
  namespace: default
subjects:
- kind: User
  name: jane
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

A RoleBinding may also reference a ClusterRole to grant the permissions to namespaced resources 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) will only be able to read secrets in the "development" namespace (the namespace of the RoleBinding).

# This role binding allows "dave" to read secrets in the "development" namespace.
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: read-secrets
  namespace: development # This only grants permissions within the "development" namespace.
subjects:
- kind: User
  name: dave
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Finally, a ClusterRoleBinding may be used to grant permission at the cluster level and in all namespaces. The following ClusterRoleBinding allows any user in the group "manager" to read secrets in any namespace.

# This cluster role binding allows anyone in the "manager" group to read secrets in any namespace.
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: read-secrets-global
subjects:
- kind: Group
  name: manager
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Referring to Resources

Most resources are represented by a string representation of their name, such as "pods", just as it appears 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:

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

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

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  namespace: default
  name: pod-and-pod-logs-reader
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "list"]

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

kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  namespace: default
  name: configmap-updater
rules:
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["my-configmap"]
  verbs: ["update", "get"]

Notably, if resourceNames are set, then the verb must not be list, watch, create, or deletecollection. Because resource names are not present in the URL for create, list, watch, and deletecollection API requests, those verbs would not be allowed by a rule with resourceNames set, since the resourceNames portion of the rule would not match the request.

Aggregated ClusterRoles

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

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: monitoring
aggregationRule:
  clusterRoleSelectors:
  - matchLabels:
      rbac.example.com/aggregate-to-monitoring: "true"
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 case rules can be added to the "monitoring" ClusterRole by creating another ClusterRole that has the label rbac.example.com/aggregate-to-monitoring: true.

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: monitoring-endpoints
  labels:
    rbac.example.com/aggregate-to-monitoring: "true"
# These rules will be added to the "monitoring" role.
rules:
- apiGroups: [""]
  Resources: ["services", "endpoints", "pods"]
  verbs: ["get", "list", "watch"]

The default user-facing roles (described below) use ClusterRole aggregation. This lets admins include rules for custom resources, such as those served by CustomResourceDefinitions or Aggregated API servers, on the default 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.

kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: aggregate-cron-tabs-edit
  labels:
    # Add these permissions to the "admin" and "edit" default roles.
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
rules:
- apiGroups: ["stable.example.com"]
  resources: ["crontabs"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: aggregate-cron-tabs-view
  labels:
    # Add these permissions to the "view" default role.
    rbac.authorization.k8s.io/aggregate-to-view: "true"
rules:
- apiGroups: ["stable.example.com"]
  resources: ["crontabs"]
  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 group:

rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]

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

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

Allow reading "pods" and reading/writing "jobs":

rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch", "extensions"]
  resources: ["jobs"]
  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):

rules:
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["my-config"]
  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):

rules:
- apiGroups: [""]
  resources: ["nodes"]
  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):

rules:
- nonResourceURLs: ["/healthz", "/healthz/*"] # '*' in a nonResourceURL is a suffix glob match
  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 IDs represented as a string. It is up to the Kubernetes admin to configure the authentication modules to produce usernames in the desired format. The RBAC authorization system does not require any particular format. However, the prefix system: is reserved for Kubernetes system use, and so the admin should ensure usernames do not contain this prefix by accident.

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

Service Accounts have usernames with the system:serviceaccount: prefix and belong to 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":

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

For a group named "frontend-admins":

subjects:
- kind: Group
  name: "frontend-admins"
  apiGroup: rbac.authorization.k8s.io

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

subjects:
- kind: ServiceAccount
  name: default
  namespace: kube-system

For all service accounts in the "qa" namespace:

subjects:
- kind: Group
  name: system:serviceaccounts:qa
  apiGroup: rbac.authorization.k8s.io

For all service accounts everywhere:

subjects:
- kind: Group
  name: system:serviceaccounts
  apiGroup: rbac.authorization.k8s.io

For all authenticated users (version 1.5+):

subjects:
- kind: Group
  name: system:authenticated
  apiGroup: rbac.authorization.k8s.io

For all unauthenticated users (version 1.5+):

subjects:
- kind: Group
  name: system:unauthenticated
  apiGroup: rbac.authorization.k8s.io

For all users (version 1.5+):

subjects:
- kind: Group
  name: system:authenticated
  apiGroup: rbac.authorization.k8s.io
- kind: Group
  name: system:unauthenticated
  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/autoupdate annotation 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 ClusterRole Default ClusterRoleBinding Description
system:basic-user system:authenticated and system:unauthenticated groups Allows a user read-only access to basic information about themselves.
system:discovery system:authenticated and system:unauthenticated groups Allows read-only access to API discovery endpoints needed to discover and negotiate an API level.

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 include rules for custom resources on these roles. To add rules to the "admin", "edit", or "view" role, create a ClusterRole with one or more of the following labels:

metadata:
  labels:
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
    rbac.authorization.k8s.io/aggregate-to-view: "true"
Default ClusterRole Default ClusterRoleBinding Description
cluster-admin system:masters group Allows 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.
admin None Allows 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.
edit None Allows read/write access to most objects in a namespace. It does not allow viewing or modifying roles or rolebindings.
view None Allows 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 ClusterRole Default ClusterRoleBinding Description
system:kube-scheduler system:kube-scheduler user Allows access to the resources required by the kube-scheduler component.
system:kube-controller-manager system:kube-controller-manager user Allows 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:node None 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-proxier system:kube-proxy user Allows access to the resources required by the kube-proxy component.

Other Component Roles

Default ClusterRole Default ClusterRoleBinding Description
system:auth-delegator None Allows delegated authentication and authorization checks. This is commonly used by add-on API servers for unified authentication and authorization.
system:heapster None Role for the Heapster component.
system:kube-aggregator None Role for the kube-aggregator component.
system:kube-dns kube-dns service account in the kube-system namespace Role for the kube-dns component.
system:node-bootstrapper None Allows access to the resources required to perform Kubelet TLS bootstrapping.
system:node-problem-detector None Role for the node-problem-detector component.
system:persistent-volume-provisioner None Allows 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:cronjob-controller
  • system:controller:daemon-set-controller
  • system:controller:deployment-controller
  • system:controller:disruption-controller
  • system:controller:endpoint-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:pvc-protection-controller
  • system:controller:replicaset-controller
  • system:controller:replication-controller
  • system:controller:resourcequota-controller
  • 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 they already have all the permissions contained in the role, at the same scope as the role (cluster-wide for a ClusterRole, within the same namespace or cluster-wide for a Role). For example, if "user-1" does not have the ability to list secrets cluster-wide, they cannot create a ClusterRole containing that permission. To allow a user to create/update roles:

  1. Grant them a role that allows them to create/update Role or ClusterRole objects, as desired.
  2. Grant them roles containing the permissions you would want them to be able to set in a Role or ClusterRole. 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.

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 ClusterRoleBinding to a role that grants that permission. To allow a user to create/update role bindings:

  1. Grant them a role that allows them to create/update RoleBinding or ClusterRoleBinding objects, as desired.
  2. 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:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: role-grantor
rules:
- apiGroups: ["rbac.authorization.k8s.io"]
  resources: ["rolebindings"]
  verbs: ["create"]
- apiGroups: ["rbac.authorization.k8s.io"]
  resources: ["clusterroles"]
  verbs: ["bind"]
  resourceNames: ["admin","edit","view"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: role-grantor-binding
  namespace: user-1-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: role-grantor
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  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

Two kubectl commands exist to grant roles within a namespace or across the entire cluster.

kubectl create rolebinding

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

  • Grant the admin ClusterRole to a user named "bob" in the namespace "acme":

    kubectl create rolebinding bob-admin-binding --clusterrole=admin --user=bob --namespace=acme

  • Grant the view ClusterRole to a service account named "myapp" in the namespace "acme":

    kubectl create rolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp --namespace=acme

kubectl create clusterrolebinding

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

  • Grant the cluster-admin ClusterRole to a user named "root" across the entire cluster:

    kubectl create clusterrolebinding root-cluster-admin-binding --clusterrole=cluster-admin --user=root

  • Grant the system:node ClusterRole to a user named "kubelet" across the entire cluster:

    kubectl create clusterrolebinding kubelet-node-binding --clusterrole=system:node --user=kubelet

  • Grant the view ClusterRole to a service account named "myapp" in the namespace "acme" across the entire cluster:

    kubectl create clusterrolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp

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:

  1. 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:

    kubectl create rolebinding my-sa-view \
      --clusterrole=view \
      --serviceaccount=my-namespace:my-sa \
      --namespace=my-namespace
    
  2. 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" service account are available to any pod in the namespace that does not specify a serviceAccountName.

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

    kubectl create rolebinding default-view \
      --clusterrole=view \
      --serviceaccount=my-namespace:default \
      --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-system" namespace contains secrets that grant super-user access to the API.

    kubectl create clusterrolebinding add-on-cluster-admin \
      --clusterrole=cluster-admin \
      --serviceaccount=kube-system:default
    
  3. 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 to all service accounts in that namespace:

    kubectl create rolebinding serviceaccounts-view \
      --clusterrole=view \
      --group=system:serviceaccounts:my-namespace \
      --namespace=my-namespace
    
  4. 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:

    kubectl create clusterrolebinding serviceaccounts-view \
      --clusterrole=view \
      --group=system:serviceaccounts
    
  5. 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 access to secrets or the ability to create a pod to access super-user credentials.

    kubectl create clusterrolebinding serviceaccounts-cluster-admin \
      --clusterrole=cluster-admin \
      --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 include the legacy ABAC policy:

--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 RBAC or ABAC policies is allowed.

When run with a log level of 2 or higher (--v=2), 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 messages in 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.

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