From ddb9561fb081ff8e28987154dad221b7c5f27aa4 Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Thu, 25 Feb 2016 16:14:51 -0800 Subject: [PATCH] Revert "Admin docs import: a files" This reverts commit 74e83717d5121362e2452040c08887ee9cd87a2d. --- .../docs/admin/accessing-the-api.md | 10 ++- .../docs/admin/admission-controllers.md | 12 +-- .../masterdocs/docs/admin/authentication.md | 11 +-- .../masterdocs/docs/admin/authorization.md | 80 +++++++------------ 4 files changed, 38 insertions(+), 75 deletions(-) diff --git a/_includes/masterdocs/docs/admin/accessing-the-api.md b/_includes/masterdocs/docs/admin/accessing-the-api.md index 6f93a782b52..9c00b5d51c9 100644 --- a/_includes/masterdocs/docs/admin/accessing-the-api.md +++ b/_includes/masterdocs/docs/admin/accessing-the-api.md @@ -54,7 +54,9 @@ variety of uses cases: 2. Processes running in Containers on Kubernetes that need to read from the apiserver. Currently, these can use a [service account](/{{page.version}}/docs/user-guide/service-accounts). 3. Scheduler and Controller-manager processes, which need to do read-write - API operations, using service accounts to avoid the need to be co-located. + API operations. Currently, these have to run on the same host as the + apiserver and use the Localhost Port. In the future, these will be + switched to using service accounts to avoid the need to be co-located. 4. Kubelets, which need to do read-write API operations and are necessarily on different machines than the apiserver. Kubelet uses the Secure Port to get their pods, to find the services that a pod can see, and to @@ -64,4 +66,8 @@ variety of uses cases: ## Expected changes - - Policy will limit the actions kubelets can do via the authed port. \ No newline at end of file + - Policy will limit the actions kubelets can do via the authed port. + - Scheduler and Controller-manager will use the Secure Port too. They + will then be able to run on different machines than the apiserver. + + diff --git a/_includes/masterdocs/docs/admin/admission-controllers.md b/_includes/masterdocs/docs/admin/admission-controllers.md index c16d1a4773d..460b1556978 100644 --- a/_includes/masterdocs/docs/admin/admission-controllers.md +++ b/_includes/masterdocs/docs/admin/admission-controllers.md @@ -35,16 +35,6 @@ ordered list of admission control choices to invoke prior to modifying objects i Use this plugin by itself to pass-through all requests. -### AlwaysPullImages - -This plug-in modifies every new Pod to force the image pull policy to Always. This is useful in a -multitenant cluster so that users can be assured that their private images can only be used by those -who have the credentials to pull them. Without this plug-in, once an image has been pulled to a -node, any pod from any user can use it simply by knowing the image's name (assuming the Pod is -scheduled onto the right node), without any authorization check against the image. When this plug-in -is enabled, images are always pulled prior to starting containers, which means valid credentials are -required. - ### AlwaysDeny Rejects all requests. Used for testing. @@ -125,7 +115,7 @@ We strongly recommend `NamespaceLifecycle` over `NamespaceAutoProvision`. ### NamespaceLifecycle This plug-in enforces that a `Namespace` that is undergoing termination cannot have new objects created in it, -and ensures that requests in a non-existent `Namespace` are rejected. +and ensures that requests in a non-existant `Namespace` are rejected. A `Namespace` deletion kicks off a sequence of operations that remove all objects (pods, services, etc.) in that namespace. In order to enforce integrity of that process, we strongly recommend running this plug-in. diff --git a/_includes/masterdocs/docs/admin/authentication.md b/_includes/masterdocs/docs/admin/authentication.md index dc0df25c65d..fee71dbb18a 100644 --- a/_includes/masterdocs/docs/admin/authentication.md +++ b/_includes/masterdocs/docs/admin/authentication.md @@ -12,12 +12,7 @@ to apiserver. Currently, tokens last indefinitely, and the token list cannot be changed without restarting apiserver. The token file format is implemented in `plugin/pkg/auth/authenticator/token/tokenfile/...` -and is a csv file with a minimum of 3 columns: token, user name, user uid, followed by -optional group names. Note, if you have more than one group the column must be double quoted e.g. - -``` -token,user,uid,"group1,group2,group3" -``` +and is a csv file with 3 columns: token, user name, user uid. When using token authentication from an http client the apiserver expects an `Authorization` header with a value of `Bearer SOMETOKEN`. @@ -25,15 +20,13 @@ header with a value of `Bearer SOMETOKEN`. **OpenID Connect ID Token** is enabled by passing the following options to the apiserver: - `--oidc-issuer-url` (required) tells the apiserver where to connect to the OpenID provider. Only HTTPS scheme will be accepted. - `--oidc-client-id` (required) is used by apiserver to verify the audience of the token. -A valid [ID token](http://openid.net/specs/openid-connect-core-1_0.html#IDToken) MUST have this +A valid [ID token](http://openid.net/specs/openid-connect-core-1_0/#IDToken) MUST have this client-id in its `aud` claims. - `--oidc-ca-file` (optional) is used by apiserver to establish and verify the secure connection to the OpenID provider. - `--oidc-username-claim` (optional, experimental) specifies which OpenID claim to use as the user name. By default, `sub` will be used, which should be unique and immutable under the issuer's domain. Cluster administrator can choose other claims such as `email` to use as the user name, but the uniqueness and immutability is not guaranteed. -- `--oidc-groups-claim` (optional, experimental) the name of a custom OpenID Connect claim for specifying user groups. The claim -value is expected to be an array of strings. Please note that this flag is still experimental until we settle more on how to handle the mapping of the OpenID user to the Kubernetes user. Thus further changes are possible. diff --git a/_includes/masterdocs/docs/admin/authorization.md b/_includes/masterdocs/docs/admin/authorization.md index db3f7c161d5..ef61e03caf8 100644 --- a/_includes/masterdocs/docs/admin/authorization.md +++ b/_includes/masterdocs/docs/admin/authorization.md @@ -23,18 +23,17 @@ The following implementations are available, and are selected by flag: ### Request Attributes -A request has the following attributes that can be considered for authorization: +A request has 5 attributes that can be considered for authorization: + - user (the user-string which a user was authenticated as). - group (the list of group names the authenticated user is a member of). - - whether the request is for an API resource. - - the request path. - - allows authorizing access to miscellaneous endpoints like `/api` or `/healthz` (see [kubectl](#kubectl)). - - the request verb. - - API verbs like `get`, `list`, `create`, `update`, `watch`, `delete`, and `deletecollection` are used for API requests - - HTTP verbs like `get`, `post`, `put`, and `delete` are used for non-API requests - - what resource is being accessed (for API requests only) - - the namespace of the object being accessed (for namespaced API requests only) - - the API group being accessed (for API requests only) + - whether the request is readonly (GETs are readonly). + - what resource is being accessed. + - applies only to the API endpoints, such as + `/api/v1/namespaces/default/pods`. For miscellaneous endpoints, like `/version`, the + resource is the empty string. + - the namespace of the object being access, or the empty string if the + endpoint does not support namespaced objects. We anticipate adding more attributes to allow finer grained access control and to assist in policy management. @@ -47,29 +46,19 @@ The file format is [one JSON object per line](http://jsonlines.org/). There sho 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. `*` matches all requests. - - `group`, type string; if you specify `group`, it must match one of the groups of the authenticated user. `*` matches all requests. - - - `readonly`, type boolean, when true, means that the policy only applies to get, list, and watch operations. - - - Resource-matching properties: - - `apiGroup`, type string; an API group, such as `extensions`. `*` matches all API groups. - - `namespace`, type string; a namespace string. `*` matches all resource requests. - - `resource`, type string; a resource, such as `pods`. `*` matches all resource requests. - - - Non-resource-matching properties: - - `nonResourcePath`, type string; matches the non-resource request paths (like `/version` and `/apis`). `*` matches all non-resource requests. `/foo/*` matches `/foo/` and all of its subpaths. + - `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. + - `readonly`, type boolean, when true, means that the policy only applies to GET + operations. + - `resource`, type string; a resource from an URL, such as `pods`. + - `namespace`, type string; a namespace string. 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. +In the future, policies may be expressed in a JSON format, and managed via a REST +interface. ### Authorization Algorithm @@ -78,37 +67,23 @@ 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. +An unset property will match any value of the corresponding +attribute. An unset attribute will match any value of the corresponding property. 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 user to do something, write a policy with the user property set to "*". -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 +To permit any user to do something, write a policy with the user property unset. +To permit an action Policy with an unset namespace applies regardless of namespace. ### Examples - 1. Alice can do anything to all resources: `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}}` - 2. Kubelet can read any pods: `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "pods", "readonly": true}}` - 3. Kubelet can read and write events: `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "events"}}` - 4. Bob can just read pods in namespace "projectCaribou": `{"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-API paths: `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "*", "readonly": true, "nonResourcePath": "*"}}` + 1. Alice can do anything: `{"user":"alice"}` + 2. Kubelet can read any pods: `{"user":"kubelet", "resource": "pods", "readonly": true}` + 3. Kubelet can read and write events: `{"user":"kubelet", "resource": "events"}` + 4. Bob can just read pods in namespace "projectCaribou": `{"user":"bob", "resource": "pods", "readonly": true, "namespace": "projectCaribou"}` -[Complete file example](http://releases.k8s.io/HEAD/pkg/auth/authorizer/abac/example_policy_file.jsonl) +[Complete file example](http://releases.k8s.io/{{page.githubbranch}}/pkg/auth/authorizer/abac/example_policy_file.jsonl) ### A quick note on service accounts @@ -117,7 +92,6 @@ A service account automatically generates a user. The user's name is generated a ```shell system:serviceaccount:: ``` - Creating a new namespace also causes a new service account to be created, of this form:* ```shell @@ -127,7 +101,7 @@ system:serviceaccount::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","user":"system:serviceaccount:kube-system:default","namespace":"*","resource":"*","apiGroup":"*"} +{"user":"system:serviceaccount:kube-system:default"} ``` The apiserver will need to be restarted to pickup the new policy lines.