Convert site to Hugo (#8316)
This commit converts content and layout to use Hugo.
This commit is contained in:
Bjørn Erik Pedersen
committed by
k8s-ci-robot
k8s-ci-robot
parent
7745f0e0c5
commit
7f3b633aa0
@@ -0,0 +1,184 @@
|
||||
---
|
||||
reviewers:
|
||||
- erictune
|
||||
- lavalamp
|
||||
- deads2k
|
||||
- liggitt
|
||||
title: Overview
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
Learn more about Kubernetes authorization, including details about creating
|
||||
policies using the supported authorization modules.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
In Kubernetes, you must be authenticated (logged in) before your request can be
|
||||
authorized (granted permission to access). For information about authentication,
|
||||
see [Accessing Control Overview](/docs/admin/accessing-the-api/).
|
||||
|
||||
Kubernetes expects attributes that are common to REST API requests. This means
|
||||
that Kubernetes authorization works with existing organization-wide or
|
||||
cloud-provider-wide access control systems which may handle other APIs besides
|
||||
the Kubernetes API.
|
||||
|
||||
## Determine Whether a Request is Allowed or Denied
|
||||
Kubernetes authorizes API requests using the API server. It evaluates all of the
|
||||
request attributes against all policies and allows or denies the request. All
|
||||
parts of an API request must be allowed by some policy in order to proceed. This
|
||||
means that permissions are denied by default.
|
||||
|
||||
(Although Kubernetes uses the API server, access controls and policies that
|
||||
depend on specific fields of specific kinds of objects are handled by Admission
|
||||
Controllers.)
|
||||
|
||||
When multiple authorization modules are configured, each is checked in sequence.
|
||||
If any authorizer approves or denies a request, that decision is immediately
|
||||
returned and no other authorizer is consulted. If all modules have no opinion on
|
||||
the request, then the request is denied. A deny returns an HTTP status code 403.
|
||||
|
||||
## Review Your Request Attributes
|
||||
Kubernetes reviews only the following API request attributes:
|
||||
|
||||
* **user** - The `user` string provided during authentication.
|
||||
* **group** - The list of group names to which the authenticated user belongs.
|
||||
* **"extra"** - A map of arbitrary string keys to string values, provided by the authentication layer.
|
||||
* **API** - Indicates whether the request is for an API resource.
|
||||
* **Request path** - Path to miscellaneous non-resource endpoints like `/api` or `/healthz`.
|
||||
* **API request verb** - API verbs `get`, `list`, `create`, `update`, `patch`, `watch`, `proxy`, `redirect`, `delete`, and `deletecollection` are used for resource requests. To determine the request verb for a resource API endpoint, see **Determine the request verb** below.
|
||||
* **HTTP request verb** - HTTP verbs `get`, `post`, `put`, and `delete` are used for non-resource requests.
|
||||
* **Resource** - The ID or name of the resource that is being accessed (for resource requests only) -- For resource requests using `get`, `update`, `patch`, and `delete` verbs, you must provide the resource name.
|
||||
* **Subresource** - The subresource that is being accessed (for resource requests only).
|
||||
* **Namespace** - The namespace of the object that is being accessed (for namespaced resource requests only).
|
||||
* **API group** - The API group being accessed (for resource requests only). An empty string designates the [core API group](/docs/concepts/overview/kubernetes-api/).
|
||||
|
||||
## Determine the Request Verb
|
||||
To determine the request verb for a resource API endpoint, review the HTTP verb
|
||||
used and whether or not the request acts on an individual resource or a
|
||||
collection of resources:
|
||||
|
||||
HTTP verb | request verb
|
||||
----------|---------------
|
||||
POST | create
|
||||
GET, HEAD | get (for individual resources), list (for collections)
|
||||
PUT | update
|
||||
PATCH | patch
|
||||
DELETE | delete (for individual resources), deletecollection (for collections)
|
||||
|
||||
Kubernetes sometimes checks authorization for additional permissions using specialized verbs. For example:
|
||||
|
||||
* [PodSecurityPolicy](/docs/concepts/policy/pod-security-policy/) checks for authorization of the `use` verb on `podsecuritypolicies` resources in the `policy` API group.
|
||||
* [RBAC](/docs/admin/authorization/rbac/#privilege-escalation-prevention-and-bootstrapping) checks for authorization
|
||||
of the `bind` verb on `roles` and `clusterroles` resources in the `rbac.authorization.k8s.io` API group.
|
||||
* [Authentication](/docs/admin/authentication/) layer checks for authorization of the `impersonate` verb on `users`, `groups`, and `serviceaccounts` in the core API group, and the `userextras` in the `authentication.k8s.io` API group.
|
||||
|
||||
## Authorization Modules
|
||||
* **Node** - A special-purpose authorizer that grants permissions to kubelets based on the pods they are scheduled to run. To learn more about using the Node authorization mode, see [Node Authorization](/docs/admin/authorization/node/).
|
||||
* **ABAC** - Attribute-based access control (ABAC) defines an access control paradigm whereby access rights are granted to users through the use of policies which combine attributes together. The policies can use any type of attributes (user attributes, resource attributes, object, environment attributes, etc). To learn more about using the ABAC mode, see [ABAC Mode](/docs/admin/authorization/abac/).
|
||||
* **RBAC** - 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. In this context, access is the ability of an individual user to perform a specific task, such as view, create, or modify a file. To learn more about using the RBAC mode, see [RBAC Mode](/docs/admin/authorization/rbac/)
|
||||
* When specified "RBAC" (Role-Based Access Control) uses the "rbac.authorization.k8s.io" API group to drive authorization decisions, allowing admins to dynamically configure permission policies through the Kubernetes API.
|
||||
* To enable RBAC, start the apiserver with `--authorization-mode=RBAC`.
|
||||
* **Webhook** - A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen. To learn more about using the Webhook mode, see [Webhook Mode](/docs/admin/authorization/webhook/).
|
||||
|
||||
#### Checking API Access
|
||||
|
||||
`kubectl` provides the `auth can-i` subcommand for quickly querying the API authorization layer.
|
||||
The command uses the `SelfSubjectAccessReview` API to determine if the current user can perform
|
||||
a given action, and works regardless of the authorization mode used.
|
||||
|
||||
|
||||
```bash
|
||||
$ kubectl auth can-i create deployments --namespace dev
|
||||
yes
|
||||
$ kubectl auth can-i create deployments --namespace prod
|
||||
no
|
||||
```
|
||||
|
||||
Administrators can combine this with ["user impersonation"](/docs/admin/authentication/#user-impersonation)
|
||||
to determine what action other users can perform.
|
||||
|
||||
```bash
|
||||
$ kubectl auth can-i list secrets --namespace dev --as dave
|
||||
no
|
||||
```
|
||||
|
||||
`SelfSubjectAccessReview` is part of the `authorization.k8s.io` API group, which
|
||||
exposes the API server authorization to external services. Other resources in
|
||||
this group include:
|
||||
|
||||
* `SubjectAccessReview` - Access review for any user, not just the current one. Useful for delegating authorization decisions to the API server. For example, the kubelet and extension API servers use this to determine user access to their own APIs.
|
||||
* `LocalSubjectAccessReview` - Like `SubjectAccessReview` but restricted to a specific namespace.
|
||||
* `SelfSubjectRulesReview` - A review which returns the set of actions a user can perform within a namespace. Useful for users to quickly summarize their own access, or for UIs to hide/show actions.
|
||||
|
||||
These APIs can be queried by creating normal Kubernetes resources, where the response "status"
|
||||
field of the returned object is the result of the query.
|
||||
|
||||
```bash
|
||||
$ kubectl create -f - -o yaml << EOF
|
||||
apiVersion: authorization.k8s.io/v1
|
||||
kind: SelfSubjectAccessReview
|
||||
spec:
|
||||
resourceAttributes:
|
||||
group: apps
|
||||
name: deployments
|
||||
verb: create
|
||||
namespace: dev
|
||||
EOF
|
||||
|
||||
apiVersion: authorization.k8s.io/v1
|
||||
kind: SelfSubjectAccessReview
|
||||
metadata:
|
||||
creationTimestamp: null
|
||||
spec:
|
||||
resourceAttributes:
|
||||
group: apps
|
||||
name: deployments
|
||||
namespace: dev
|
||||
verb: create
|
||||
status:
|
||||
allowed: true
|
||||
denied: false
|
||||
```
|
||||
|
||||
## Using Flags for Your Authorization Module
|
||||
|
||||
You must include a flag in your policy to indicate which authorization module
|
||||
your policies include:
|
||||
|
||||
The following flags can be used:
|
||||
|
||||
* `--authorization-mode=ABAC` Attribute-Based Access Control (ABAC) mode allows you to configure policies using local files.
|
||||
* `--authorization-mode=RBAC` Role-based access control (RBAC) mode allows you to create and store policies using the Kubernetes API.
|
||||
* `--authorization-mode=Webhook` WebHook is an HTTP callback mode that allows you to manage authorization using a remote REST endpoint.
|
||||
* `--authorization-mode=Node` Node authorization is a special-purpose authorization mode that specifically authorizes API requests made by kubelets.
|
||||
* `--authorization-mode=AlwaysDeny` This flag blocks all requests. Use this flag only for testing.
|
||||
* `--authorization-mode=AlwaysAllow` This flag allows all requests. Use this flag only if you do not require authorization for your API requests.
|
||||
|
||||
You can choose more than one authorization module. Modules are checked in order
|
||||
so an earlier module has higher priority to allow or deny a request.
|
||||
|
||||
{{% /capture %}}
|
||||
{{% capture whatsnext %}}
|
||||
* To learn more about Authentication, see **Authentication** in [Controlling Access to the Kubernetes API](/docs/admin/accessing-the-api/).
|
||||
* To learn more about Admission Control, see [Using Admission Controllers](/docs/admin/admission-controllers/).
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
||||
## Privilege escalation via pod creation
|
||||
|
||||
Users who have the ability to create pods in a namespace can potentially
|
||||
escalate their privileges within that namespace. They can create pods that
|
||||
access their privileges within that namespace. They can create pods that access
|
||||
secrets the user cannot themselves read, or that run under a service account
|
||||
with different/greater permissions.
|
||||
|
||||
{{< caution >}}
|
||||
**Caution:** System administrators, use care when granting access to pod
|
||||
creation. A user granted permission to create pods (or controllers that create
|
||||
pods) in the namespace can: read all secrets in the namespace; read all config
|
||||
maps in the namespace; and impersonate any service account in the namespace and
|
||||
take any action the account could take. This applies regardless of authorization
|
||||
mode.
|
||||
{{< /caution >}}
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
reviewers:
|
||||
- erictune
|
||||
- lavalamp
|
||||
- deads2k
|
||||
- liggitt
|
||||
title: ABAC Mode
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
Attribute-based access control (ABAC) defines an access control paradigm whereby access rights are granted to users through the use of policies which combine attributes together.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
## Policy File Format
|
||||
|
||||
For mode `ABAC`, also specify `--authorization-policy-file=SOME_FILENAME`.
|
||||
|
||||
The file format is [one JSON object per line](http://jsonlines.org/). There
|
||||
should be no enclosing list or map, just one map per line.
|
||||
|
||||
Each line is a "policy object". A policy object is a map with the following
|
||||
properties:
|
||||
|
||||
- Versioning properties:
|
||||
- `apiVersion`, type string; valid values are "abac.authorization.kubernetes.io/v1beta1". Allows versioning and conversion of the policy format.
|
||||
- `kind`, type string: valid values are "Policy". Allows versioning and conversion of the policy format.
|
||||
- `spec` property set to a map with the following properties:
|
||||
- Subject-matching properties:
|
||||
- `user`, type string; the user-string from `--token-auth-file`. If you specify `user`, it must match the username of the authenticated user.
|
||||
- `group`, type string; if you specify `group`, it must match one of the groups of the authenticated user. `system:authenticated` matches all authenticated requests. `system:unauthenticated` matches all unauthenticated requests.
|
||||
- Resource-matching properties:
|
||||
- `apiGroup`, type string; an API group.
|
||||
- Ex: `extensions`
|
||||
- Wildcard: `*` matches all API groups.
|
||||
- `namespace`, type string; a namespace.
|
||||
- Ex: `kube-system`
|
||||
- Wildcard: `*` matches all resource requests.
|
||||
- `resource`, type string; a resource type
|
||||
- Ex: `pods`
|
||||
- Wildcard: `*` matches all resource requests.
|
||||
- Non-resource-matching properties:
|
||||
- `nonResourcePath`, type string; non-resource request paths.
|
||||
- Ex: `/version` or `/apis`
|
||||
- Wildcard:
|
||||
- `*` matches all non-resource requests.
|
||||
- `/foo/*` matches all subpaths of `/foo/`.
|
||||
- `readonly`, type boolean, when true, means that the Resource-matching policy only applies to get, list, and watch operations, Non-resource-matching policy only applies to get operation.
|
||||
|
||||
**NOTES:** An unset property is the same as a property set to the zero value for its type
|
||||
(e.g. empty string, 0, false). However, unset should be preferred for
|
||||
readability.
|
||||
|
||||
In the future, policies may be expressed in a JSON format, and managed via a
|
||||
REST interface.
|
||||
|
||||
## Authorization Algorithm
|
||||
|
||||
A request has attributes which correspond to the properties of a policy object.
|
||||
|
||||
When a request is received, the attributes are determined. Unknown attributes
|
||||
are set to the zero value of its type (e.g. empty string, 0, false).
|
||||
|
||||
A property set to `"*"` will match any value of the corresponding attribute.
|
||||
|
||||
The tuple of attributes is checked for a match against every policy in the
|
||||
policy file. If at least one line matches the request attributes, then the
|
||||
request is authorized (but may fail later validation).
|
||||
|
||||
To permit any authenticated user to do something, write a policy with the
|
||||
group property set to `"system:authenticated"`.
|
||||
|
||||
To permit any unauthenticated user to do something, write a policy with the
|
||||
group property set to `"system:unauthenticated"`.
|
||||
|
||||
To permit a user to do anything, write a policy with the apiGroup, namespace,
|
||||
resource, and nonResourcePath properties set to `"*"`.
|
||||
|
||||
## Kubectl
|
||||
|
||||
Kubectl uses the `/api` and `/apis` endpoints of api-server to negotiate
|
||||
client/server versions. To validate objects sent to the API by create/update
|
||||
operations, kubectl queries certain swagger resources. For API version `v1`
|
||||
those would be `/swaggerapi/api/v1` & `/swaggerapi/experimental/v1`.
|
||||
|
||||
When using ABAC authorization, those special resources have to be explicitly
|
||||
exposed via the `nonResourcePath` property in a policy (see [examples](#examples) below):
|
||||
|
||||
* `/api`, `/api/*`, `/apis`, and `/apis/*` for API version negotiation.
|
||||
* `/version` for retrieving the server version via `kubectl version`.
|
||||
* `/swaggerapi/*` for create/update operations.
|
||||
|
||||
To inspect the HTTP calls involved in a specific kubectl operation you can turn
|
||||
up the verbosity:
|
||||
|
||||
kubectl --v=8 version
|
||||
|
||||
## Examples
|
||||
|
||||
1. Alice can do anything to all resources:
|
||||
|
||||
```json
|
||||
{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}}
|
||||
```
|
||||
2. Kubelet can read any pods:
|
||||
|
||||
```json
|
||||
{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "pods", "readonly": true}}
|
||||
```
|
||||
3. Kubelet can read and write events:
|
||||
|
||||
```json
|
||||
{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "events"}}
|
||||
```
|
||||
4. Bob can just read pods in namespace "projectCaribou":
|
||||
|
||||
```json
|
||||
{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "bob", "namespace": "projectCaribou", "resource": "pods", "readonly": true}}
|
||||
```
|
||||
5. Anyone can make read-only requests to all non-resource paths:
|
||||
|
||||
```json
|
||||
{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"group": "system:authenticated", "readonly": true, "nonResourcePath": "*"}}
|
||||
{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"group": "system:unauthenticated", "readonly": true, "nonResourcePath": "*"}}
|
||||
```
|
||||
|
||||
[Complete file example](http://releases.k8s.io/{{< param "githubbranch" >}}/pkg/auth/authorizer/abac/example_policy_file.jsonl)
|
||||
|
||||
## A quick note on service accounts
|
||||
|
||||
A service account automatically generates a user. The user's name is generated
|
||||
according to the naming convention:
|
||||
|
||||
```shell
|
||||
system:serviceaccount:<namespace>:<serviceaccountname>
|
||||
```
|
||||
Creating a new namespace also causes a new service account to be created, of
|
||||
this form:
|
||||
|
||||
```shell
|
||||
system:serviceaccount:<namespace>:default
|
||||
```
|
||||
|
||||
For example, if you wanted to grant the default service account in the
|
||||
kube-system full privilege to the API, you would add this line to your policy
|
||||
file:
|
||||
|
||||
```json
|
||||
{"apiVersion":"abac.authorization.kubernetes.io/v1beta1","kind":"Policy","spec":{"user":"system:serviceaccount:kube-system:default","namespace":"*","resource":"*","apiGroup":"*"}}
|
||||
```
|
||||
|
||||
The apiserver will need to be restarted to pickup the new policy lines.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
reviewers:
|
||||
- timstclair
|
||||
- deads2k
|
||||
- liggitt
|
||||
- ericchiang
|
||||
title: Using Node Authorization
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
Node authorization is a special-purpose authorization mode that specifically authorizes API requests made by kubelets.
|
||||
|
||||
## Overview
|
||||
|
||||
The Node authorizer allows a kubelet to perform API operations. This includes:
|
||||
|
||||
Read operations:
|
||||
|
||||
* services
|
||||
* endpoints
|
||||
* nodes
|
||||
* pods
|
||||
* secrets, configmaps, persistent volume claims and persistent volumes related to pods bound to the kubelet's node
|
||||
|
||||
Write operations:
|
||||
|
||||
* nodes and node status (enable the `NodeRestriction` admission plugin to limit a kubelet to modify its own node)
|
||||
* pods and pod status (enable the `NodeRestriction` admission plugin to limit a kubelet to modify pods bound to itself)
|
||||
* events
|
||||
|
||||
Auth-related operations:
|
||||
|
||||
* read/write access to the certificationsigningrequests API for TLS bootstrapping
|
||||
* the ability to create tokenreviews and subjectaccessreviews for delegated authentication/authorization checks
|
||||
|
||||
In future releases, the node authorizer may add or remove permissions to ensure kubelets
|
||||
have the minimal set of permissions required to operate correctly.
|
||||
|
||||
In order to be authorized by the Node authorizer, kubelets must use a credential that identifies them as
|
||||
being in the `system:nodes` group, with a username of `system:node:<nodeName>`.
|
||||
This group and user name format match the identity created for each kubelet as part of
|
||||
[kubelet TLS bootstrapping](/docs/admin/kubelet-tls-bootstrapping/).
|
||||
|
||||
To enable the Node authorizer, start the apiserver with `--authorization-mode=Node`.
|
||||
|
||||
To limit the API objects kubelets are able to write, enable the [NodeRestriction](/docs/admin/admission-controllers#NodeRestriction) admission plugin by starting the apiserver with `--enable-admission-plugins=...,NodeRestriction,...`
|
||||
|
||||
## Migration considerations
|
||||
|
||||
### Kubelets outside the `system:nodes` group
|
||||
|
||||
Kubelets outside the `system:nodes` group would not be authorized by the `Node` authorization mode,
|
||||
and would need to continue to be authorized via whatever mechanism currently authorizes them.
|
||||
The node admission plugin would not restrict requests from these kubelets.
|
||||
|
||||
### Kubelets with undifferentiated usernames
|
||||
|
||||
In some deployments, kubelets have credentials that place them in the `system:nodes` group,
|
||||
but do not identify the particular node they are associated with,
|
||||
because they do not have a username in the `system:node:...` format.
|
||||
These kubelets would not be authorized by the `Node` authorization mode,
|
||||
and would need to continue to be authorized via whatever mechanism currently authorizes them.
|
||||
|
||||
The `NodeRestriction` admission plugin would ignore requests from these kubelets,
|
||||
since the default node identifier implementation would not consider that a node identity.
|
||||
|
||||
### Upgrades from previous versions using RBAC
|
||||
|
||||
Upgraded pre-1.7 clusters using [RBAC](/docs/admin/authorization/rbac/) will continue functioning as-is because the `system:nodes` group binding will already exist.
|
||||
|
||||
If a cluster admin wishes to start using the `Node` authorizer and `NodeRestriction` admission plugin
|
||||
to limit node access to the API, that can be done non-disruptively:
|
||||
|
||||
1. Enable the `Node` authorization mode (`--authorization-mode=Node,RBAC`) and the `NodeRestriction` admission plugin
|
||||
2. Ensure all kubelets' credentials conform to the group/username requirements
|
||||
3. Audit apiserver logs to ensure the `Node` authorizer is not rejecting requests from kubelets (no persistent `NODE DENY` messages logged)
|
||||
4. Delete the `system:node` cluster role binding
|
||||
|
||||
### RBAC Node Permissions
|
||||
|
||||
In 1.6, the `system:node` cluster role was automatically bound to the `system:nodes` group when using the [RBAC Authorization mode](/docs/admin/authorization/rbac/).
|
||||
|
||||
In 1.7, the automatic binding of the `system:nodes` group to the `system:node` role is deprecated
|
||||
because the node authorizer accomplishes the same purpose with the benefit of additional restrictions
|
||||
on secret and configmap access. If the `Node` and `RBAC` authorization modes are both enabled,
|
||||
the automatic binding of the `system:nodes` group to the `system:node` role is not created in 1.7.
|
||||
|
||||
In 1.8, the binding will not be created at all.
|
||||
|
||||
When using RBAC, the `system:node` cluster role will continue to be created,
|
||||
for compatibility with deployment methods that bind other users or groups to that role.
|
||||
@@ -0,0 +1,872 @@
|
||||
---
|
||||
reviewers:
|
||||
- erictune
|
||||
- deads2k
|
||||
- liggitt
|
||||
title: Using RBAC Authorization
|
||||
---
|
||||
|
||||
{{< 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:
|
||||
|
||||
```yaml
|
||||
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](#rolebinding-and-clusterrolebinding)):
|
||||
|
||||
```yaml
|
||||
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.
|
||||
|
||||
```yaml
|
||||
# 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 # Name is case sensitive
|
||||
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, case sensitive) will only be able to read secrets in the "development"
|
||||
namespace (the namespace of the `RoleBinding`).
|
||||
|
||||
```yaml
|
||||
# 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 # Name is case sensitive
|
||||
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.
|
||||
|
||||
```yaml
|
||||
# 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 # Name is case sensitive
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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`.
|
||||
|
||||
```yaml
|
||||
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.
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- apiGroups: [""]
|
||||
resources: ["pods"]
|
||||
verbs: ["get", "list", "watch"]
|
||||
```
|
||||
|
||||
Allow reading/writing "deployments" in both the "extensions" and "apps" API groups:
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- apiGroups: ["extensions", "apps"]
|
||||
resources: ["deployments"]
|
||||
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
|
||||
```
|
||||
|
||||
Allow reading "pods" and reading/writing "jobs":
|
||||
|
||||
```yaml
|
||||
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):
|
||||
|
||||
```yaml
|
||||
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):
|
||||
|
||||
```yaml
|
||||
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):
|
||||
|
||||
```yaml
|
||||
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](/docs/admin/authentication/) 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](/docs/tasks/configure-pod-container/configure-service-account/) 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":
|
||||
|
||||
```yaml
|
||||
subjects:
|
||||
- kind: User
|
||||
name: "alice@example.com"
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
```
|
||||
|
||||
For a group named "frontend-admins":
|
||||
|
||||
```yaml
|
||||
subjects:
|
||||
- kind: Group
|
||||
name: "frontend-admins"
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
```
|
||||
|
||||
For the default service account in the kube-system namespace:
|
||||
|
||||
```yaml
|
||||
subjects:
|
||||
- kind: ServiceAccount
|
||||
name: default
|
||||
namespace: kube-system
|
||||
```
|
||||
|
||||
For all service accounts in the "qa" namespace:
|
||||
|
||||
```yaml
|
||||
subjects:
|
||||
- kind: Group
|
||||
name: system:serviceaccounts:qa
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
```
|
||||
|
||||
For all service accounts everywhere:
|
||||
|
||||
```yaml
|
||||
subjects:
|
||||
- kind: Group
|
||||
name: system:serviceaccounts
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
```
|
||||
|
||||
For all authenticated users (version 1.5+):
|
||||
|
||||
```yaml
|
||||
subjects:
|
||||
- kind: Group
|
||||
name: system:authenticated
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
```
|
||||
|
||||
For all unauthenticated users (version 1.5+):
|
||||
|
||||
```yaml
|
||||
subjects:
|
||||
- kind: Group
|
||||
name: system:unauthenticated
|
||||
apiGroup: rbac.authorization.k8s.io
|
||||
```
|
||||
|
||||
For all users (version 1.5+):
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
<table>
|
||||
<colgroup><col width="25%"><col width="25%"><col></colgroup>
|
||||
<tr>
|
||||
<th>Default ClusterRole</th>
|
||||
<th>Default ClusterRoleBinding</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:basic-user</b></td>
|
||||
<td><b>system:authenticated</b> and <b>system:unauthenticated</b> groups</td>
|
||||
<td>Allows a user read-only access to basic information about themselves.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:discovery</b></td>
|
||||
<td><b>system:authenticated</b> and <b>system:unauthenticated</b> groups</td>
|
||||
<td>Allows read-only access to API discovery endpoints needed to discover and negotiate an API level.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### 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](#aggregated-clusterroles) 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:
|
||||
|
||||
```yaml
|
||||
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"
|
||||
```
|
||||
|
||||
<table>
|
||||
<colgroup><col width="25%"><col width="25%"><col></colgroup>
|
||||
<tr>
|
||||
<th>Default ClusterRole</th>
|
||||
<th>Default ClusterRoleBinding</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>cluster-admin</b></td>
|
||||
<td><b>system:masters</b> group</td>
|
||||
<td>Allows super-user access to perform any action on any resource.
|
||||
When used in a <b>ClusterRoleBinding</b>, it gives full control over every resource in the cluster and in all namespaces.
|
||||
When used in a <b>RoleBinding</b>, it gives full control over every resource in the rolebinding's namespace, including the namespace itself.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>admin</b></td>
|
||||
<td>None</td>
|
||||
<td>Allows admin access, intended to be granted within a namespace using a <b>RoleBinding</b>.
|
||||
If used in a <b>RoleBinding</b>, 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.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>edit</b></td>
|
||||
<td>None</td>
|
||||
<td>Allows read/write access to most objects in a namespace.
|
||||
It does not allow viewing or modifying roles or rolebindings.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>view</b></td>
|
||||
<td>None</td>
|
||||
<td>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.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### Core Component Roles
|
||||
|
||||
<table>
|
||||
<colgroup><col width="25%"><col width="25%"><col></colgroup>
|
||||
<tr>
|
||||
<th>Default ClusterRole</th>
|
||||
<th>Default ClusterRoleBinding</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:kube-scheduler</b></td>
|
||||
<td><b>system:kube-scheduler</b> user</td>
|
||||
<td>Allows access to the resources required by the kube-scheduler component.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:kube-controller-manager</b></td>
|
||||
<td><b>system:kube-controller-manager</b> user</td>
|
||||
<td>Allows access to the resources required by the kube-controller-manager component.
|
||||
The permissions required by individual control loops are contained in the <a href="#controller-roles">controller roles</a>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:node</b></td>
|
||||
<td>None in 1.8+</td>
|
||||
<td>Allows access to resources required by the kubelet component, <b>including read access to all secrets, and write access to all pod status objects</b>.
|
||||
As of 1.7, use of the <a href="/docs/admin/authorization/node/">Node authorizer</a> and <a href="/docs/admin/admission-controllers/#noderestriction">NodeRestriction admission plugin</a> 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.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:node-proxier</b></td>
|
||||
<td><b>system:kube-proxy</b> user</td>
|
||||
<td>Allows access to the resources required by the kube-proxy component.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### Other Component Roles
|
||||
|
||||
<table>
|
||||
<colgroup><col width="25%"><col width="25%"><col></colgroup>
|
||||
<tr>
|
||||
<th>Default ClusterRole</th>
|
||||
<th>Default ClusterRoleBinding</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:auth-delegator</b></td>
|
||||
<td>None</td>
|
||||
<td>Allows delegated authentication and authorization checks.
|
||||
This is commonly used by add-on API servers for unified authentication and authorization.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:heapster</b></td>
|
||||
<td>None</td>
|
||||
<td>Role for the <a href="https://github.com/kubernetes/heapster">Heapster</a> component.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:kube-aggregator</b></td>
|
||||
<td>None</td>
|
||||
<td>Role for the <a href="https://github.com/kubernetes/kube-aggregator">kube-aggregator</a> component.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:kube-dns</b></td>
|
||||
<td><b>kube-dns</b> service account in the <b>kube-system</b> namespace</td>
|
||||
<td>Role for the <a href="/docs/concepts/services-networking/dns-pod-service/">kube-dns</a> component.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:node-bootstrapper</b></td>
|
||||
<td>None</td>
|
||||
<td>Allows access to the resources required to perform <a href="/docs/admin/kubelet-tls-bootstrapping/">Kubelet TLS bootstrapping</a>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:node-problem-detector</b></td>
|
||||
<td>None</td>
|
||||
<td>Role for the <a href="https://github.com/kubernetes/node-problem-detector">node-problem-detector</a> component.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><b>system:persistent-volume-provisioner</b></td>
|
||||
<td>None</td>
|
||||
<td>Allows access to the resources required by most <a href="/docs/concepts/storage/persistent-volumes/#provisioner">dynamic volume provisioners</a>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### Controller Roles
|
||||
|
||||
The [Kubernetes controller manager](/docs/admin/kube-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:pv-protection-controller
|
||||
* 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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
kubectl create rolebinding default-view \
|
||||
--clusterrole=view \
|
||||
--serviceaccount=my-namespace:default \
|
||||
--namespace=my-namespace
|
||||
```
|
||||
|
||||
Many [add-ons](/docs/concepts/cluster-administration/addons/) 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.
|
||||
|
||||
```shell
|
||||
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 all service accounts in that namespace:
|
||||
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
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.
|
||||
|
||||
```shell
|
||||
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 specify a policy file that contains
|
||||
[the legacy ABAC policy](/docs/admin/authorization/abac#policy-file-format):
|
||||
|
||||
```
|
||||
--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](#service-account-permissions) 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 >}}
|
||||
**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.
|
||||
{{< /warning >}}
|
||||
|
||||
```
|
||||
kubectl create clusterrolebinding permissive-binding \
|
||||
--clusterrole=cluster-admin \
|
||||
--user=admin \
|
||||
--user=kubelet \
|
||||
--group=system:serviceaccounts
|
||||
```
|
||||
@@ -0,0 +1,151 @@
|
||||
---
|
||||
reviewers:
|
||||
- erictune
|
||||
- lavalamp
|
||||
- deads2k
|
||||
- liggitt
|
||||
title: Webhook Mode
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
When specified, mode `Webhook` causes Kubernetes to query an outside REST
|
||||
service when determining user privileges.
|
||||
|
||||
## Configuration File Format
|
||||
|
||||
Mode `Webhook` requires a file for HTTP configuration, specify by the
|
||||
`--authorization-webhook-config-file=SOME_FILENAME` flag.
|
||||
|
||||
The configuration file uses the [kubeconfig](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
|
||||
file format. Within the file "users" refers to the API Server webhook and
|
||||
"clusters" refers to the remote service.
|
||||
|
||||
A configuration example which uses HTTPS client auth:
|
||||
|
||||
```yaml
|
||||
# clusters refers to the remote service.
|
||||
clusters:
|
||||
- name: name-of-remote-authz-service
|
||||
cluster:
|
||||
# CA for verifying the remote service.
|
||||
certificate-authority: /path/to/ca.pem
|
||||
# URL of remote service to query. Must use 'https'. May not include parameters.
|
||||
server: https://authz.example.com/authorize
|
||||
|
||||
# users refers to the API Server's webhook configuration.
|
||||
users:
|
||||
- name: name-of-api-server
|
||||
user:
|
||||
client-certificate: /path/to/cert.pem # cert for the webhook plugin to use
|
||||
client-key: /path/to/key.pem # key matching the cert
|
||||
|
||||
# kubeconfig files require a context. Provide one for the API Server.
|
||||
current-context: webhook
|
||||
contexts:
|
||||
- context:
|
||||
cluster: name-of-remote-authz-service
|
||||
user: name-of-api-server
|
||||
name: webhook
|
||||
```
|
||||
|
||||
## Request Payloads
|
||||
|
||||
When faced with an authorization decision, the API Server POSTs a JSON-
|
||||
serialized `authorization.k8s.io/v1beta1` `SubjectAccessReview` object describing the
|
||||
action. This object contains fields describing the user attempting to make the
|
||||
request, and either details about the resource being accessed or requests
|
||||
attributes.
|
||||
|
||||
Note that webhook API objects are subject to the same [versioning compatibility rules](/docs/concepts/overview/kubernetes-api/)
|
||||
as other Kubernetes API objects. Implementers should be aware of looser
|
||||
compatibility promises for beta objects and check the "apiVersion" field of the
|
||||
request to ensure correct deserialization. Additionally, the API Server must
|
||||
enable the `authorization.k8s.io/v1beta1` API extensions group (`--runtime-config=authorization.k8s.io/v1beta1=true`).
|
||||
|
||||
An example request body:
|
||||
|
||||
```json
|
||||
{
|
||||
"apiVersion": "authorization.k8s.io/v1beta1",
|
||||
"kind": "SubjectAccessReview",
|
||||
"spec": {
|
||||
"resourceAttributes": {
|
||||
"namespace": "kittensandponies",
|
||||
"verb": "get",
|
||||
"group": "unicorn.example.org",
|
||||
"resource": "pods"
|
||||
},
|
||||
"user": "jane",
|
||||
"group": [
|
||||
"group1",
|
||||
"group2"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The remote service is expected to fill the `status` field of
|
||||
the request and respond to either allow or disallow access. The response body's
|
||||
`spec` field is ignored and may be omitted. A permissive response would return:
|
||||
|
||||
```json
|
||||
{
|
||||
"apiVersion": "authorization.k8s.io/v1beta1",
|
||||
"kind": "SubjectAccessReview",
|
||||
"status": {
|
||||
"allowed": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To disallow access, the remote service would return:
|
||||
|
||||
```json
|
||||
{
|
||||
"apiVersion": "authorization.k8s.io/v1beta1",
|
||||
"kind": "SubjectAccessReview",
|
||||
"status": {
|
||||
"allowed": false,
|
||||
"reason": "user does not have read access to the namespace"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Access to non-resource paths are sent as:
|
||||
|
||||
```json
|
||||
{
|
||||
"apiVersion": "authorization.k8s.io/v1beta1",
|
||||
"kind": "SubjectAccessReview",
|
||||
"spec": {
|
||||
"nonResourceAttributes": {
|
||||
"path": "/debug",
|
||||
"verb": "get"
|
||||
},
|
||||
"user": "jane",
|
||||
"group": [
|
||||
"group1",
|
||||
"group2"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Non-resource paths include: `/api`, `/apis`, `/metrics`, `/resetMetrics`,
|
||||
`/logs`, `/debug`, `/healthz`, `/swagger-ui/`, `/swaggerapi/`, `/ui`, and
|
||||
`/version.` Clients require access to `/api`, `/api/*`, `/apis`, `/apis/*`,
|
||||
and `/version` to discover what resources and versions are present on the server.
|
||||
Access to other non-resource paths can be disallowed without restricting access
|
||||
to the REST api.
|
||||
|
||||
For further documentation refer to the authorization.v1beta1 API objects and
|
||||
[webhook.go](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/staging/src/k8s.io/apiserver/plugin/pkg/authorizer/webhook/webhook.go).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user