From 5aef96a20f8ea38a6e0a92a7399f5a7f87dcd030 Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Thu, 25 Feb 2016 16:00:18 -0800 Subject: [PATCH 1/5] doc fix --- _includes/masterdocs/docs/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_includes/masterdocs/docs/api.md b/_includes/masterdocs/docs/api.md index 1e2ced6964a..57087a30de3 100644 --- a/_includes/masterdocs/docs/api.md +++ b/_includes/masterdocs/docs/api.md @@ -73,13 +73,13 @@ Currently there are two API groups in use: In the future we expect that there will be more API groups, all at REST path `/apis/$API_GROUP` and using `apiVersion: $API_GROUP/$VERSION`. We expect that there will be a way for [third parties to -create their own API groups](design/extending-api.md), and to avoid naming collisions. +create their own API groups](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/extending-api.md), and to avoid naming collisions. ## Enabling resources in the extensions group DaemonSets, Deployments, HorizontalPodAutoscalers, Ingress, Jobs and ReplicaSets are enabled by default. -Other extensions resources can be enabled by setting runtime-config on -apiserver. runtime-config accepts comma separated values. For ex: to disable deployments and jobs, set +Other extensions resources can be enabled by setting `runtime-config` on +apiserver. `runtime-config` accepts comma separated values. For ex: to disable deployments and jobs, set `--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/jobs=false` ## v1beta1, v1beta2, and v1beta3 are deprecated; please move to v1 ASAP From 74e83717d5121362e2452040c08887ee9cd87a2d Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Thu, 25 Feb 2016 16:08:24 -0800 Subject: [PATCH 2/5] Admin docs import: a files --- .../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, 75 insertions(+), 38 deletions(-) diff --git a/_includes/masterdocs/docs/admin/accessing-the-api.md b/_includes/masterdocs/docs/admin/accessing-the-api.md index 9c00b5d51c9..6f93a782b52 100644 --- a/_includes/masterdocs/docs/admin/accessing-the-api.md +++ b/_includes/masterdocs/docs/admin/accessing-the-api.md @@ -54,9 +54,7 @@ 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. 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. + API operations, 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 @@ -66,8 +64,4 @@ variety of uses cases: ## Expected changes - - 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. - - + - Policy will limit the actions kubelets can do via the authed port. \ No newline at end of file diff --git a/_includes/masterdocs/docs/admin/admission-controllers.md b/_includes/masterdocs/docs/admin/admission-controllers.md index 460b1556978..c16d1a4773d 100644 --- a/_includes/masterdocs/docs/admin/admission-controllers.md +++ b/_includes/masterdocs/docs/admin/admission-controllers.md @@ -35,6 +35,16 @@ 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. @@ -115,7 +125,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-existant `Namespace` are rejected. +and ensures that requests in a non-existent `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 fee71dbb18a..dc0df25c65d 100644 --- a/_includes/masterdocs/docs/admin/authentication.md +++ b/_includes/masterdocs/docs/admin/authentication.md @@ -12,7 +12,12 @@ 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 3 columns: token, user name, user uid. +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" +``` When using token authentication from an http client the apiserver expects an `Authorization` header with a value of `Bearer SOMETOKEN`. @@ -20,13 +25,15 @@ 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/#IDToken) MUST have this +A valid [ID token](http://openid.net/specs/openid-connect-core-1_0.html#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 ef61e03caf8..db3f7c161d5 100644 --- a/_includes/masterdocs/docs/admin/authorization.md +++ b/_includes/masterdocs/docs/admin/authorization.md @@ -23,17 +23,18 @@ The following implementations are available, and are selected by flag: ### Request Attributes -A request has 5 attributes that can be considered for authorization: - +A request has the following 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 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. + - 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) We anticipate adding more attributes to allow finer grained access control and to assist in policy management. @@ -46,19 +47,29 @@ 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. - - `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. + - `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. 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 @@ -67,23 +78,37 @@ 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). -An unset property will match any value of the corresponding -attribute. An unset attribute will match any value of the corresponding property. +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 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. +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 ### Examples - 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"}` + 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": "*"}}` -[Complete file example](http://releases.k8s.io/{{page.githubbranch}}/pkg/auth/authorizer/abac/example_policy_file.jsonl) +[Complete file example](http://releases.k8s.io/HEAD/pkg/auth/authorizer/abac/example_policy_file.jsonl) ### A quick note on service accounts @@ -92,6 +117,7 @@ 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 @@ -101,7 +127,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 -{"user":"system:serviceaccount:kube-system:default"} +{"apiVersion":"abac.authorization.kubernetes.io/v1beta1","kind":"Policy","user":"system:serviceaccount:kube-system:default","namespace":"*","resource":"*","apiGroup":"*"} ``` The apiserver will need to be restarted to pickup the new policy lines. From ddb9561fb081ff8e28987154dad221b7c5f27aa4 Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Thu, 25 Feb 2016 16:14:51 -0800 Subject: [PATCH 3/5] 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. From 8ff26badb4af2b9bbca0b87ec6ccc38cf91bf724 Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Thu, 25 Feb 2016 16:15:46 -0800 Subject: [PATCH 4/5] Revert "doc fix" This reverts commit 5aef96a20f8ea38a6e0a92a7399f5a7f87dcd030. --- _includes/masterdocs/docs/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_includes/masterdocs/docs/api.md b/_includes/masterdocs/docs/api.md index 57087a30de3..1e2ced6964a 100644 --- a/_includes/masterdocs/docs/api.md +++ b/_includes/masterdocs/docs/api.md @@ -73,13 +73,13 @@ Currently there are two API groups in use: In the future we expect that there will be more API groups, all at REST path `/apis/$API_GROUP` and using `apiVersion: $API_GROUP/$VERSION`. We expect that there will be a way for [third parties to -create their own API groups](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/extending-api.md), and to avoid naming collisions. +create their own API groups](design/extending-api.md), and to avoid naming collisions. ## Enabling resources in the extensions group DaemonSets, Deployments, HorizontalPodAutoscalers, Ingress, Jobs and ReplicaSets are enabled by default. -Other extensions resources can be enabled by setting `runtime-config` on -apiserver. `runtime-config` accepts comma separated values. For ex: to disable deployments and jobs, set +Other extensions resources can be enabled by setting runtime-config on +apiserver. runtime-config accepts comma separated values. For ex: to disable deployments and jobs, set `--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/jobs=false` ## v1beta1, v1beta2, and v1beta3 are deprecated; please move to v1 ASAP From f8a5f14a74ebc97a2aedccbcecc403a498fdbfd0 Mon Sep 17 00:00:00 2001 From: John Mulhausen Date: Thu, 25 Feb 2016 16:16:09 -0800 Subject: [PATCH 5/5] Revert "Diffs for top-level docs, flown in from master" This reverts commit 5de1faad0246892cbe19fda920b9859361840057. --- _includes/masterdocs/docs/api.md | 16 ++-- .../docs/reporting-security-issues.md | 4 +- _includes/masterdocs/docs/roadmap.md | 49 ++++++++++- _includes/masterdocs/docs/whatisk8s.md | 86 +++++++------------ 4 files changed, 83 insertions(+), 72 deletions(-) diff --git a/_includes/masterdocs/docs/api.md b/_includes/masterdocs/docs/api.md index 1e2ced6964a..2fe4044bc6d 100644 --- a/_includes/masterdocs/docs/api.md +++ b/_includes/masterdocs/docs/api.md @@ -47,7 +47,7 @@ in more detail in the [API Changes documentation](/{{page.version}}/docs/devel/a - Support for the overall feature will not be dropped, though details may change. - The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens, we will provide instructions for migrating to the next version. This may require deleting, editing, and re-creating - API objects. The editing process may require some thought. This may require downtime for applications that rely on the feature. + API objects. The editing process may require some thought. This may require downtime for appplications that rely on the feature. - Recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases. If you have multiple clusters which can be upgraded independently, you may be able to relax this restriction. - **Please do try our beta features and give feedback on them! Once they exit beta, it may not be practical for us to make more changes.** @@ -68,19 +68,17 @@ Currently there are two API groups in use: `apiVersion: v1`. 1. the "extensions" group, which is at REST path `/apis/extensions/$VERSION`, and which uses `apiVersion: extensions/$VERSION` (e.g. currently `apiVersion: extensions/v1beta1`). - This holds types which will probably move to another API group eventually. -1. the "componentconfig" and "metrics" API groups. In the future we expect that there will be more API groups, all at REST path `/apis/$API_GROUP` and -using `apiVersion: $API_GROUP/$VERSION`. We expect that there will be a way for [third parties to -create their own API groups](design/extending-api.md), and to avoid naming collisions. +using `apiVersion: $API_GROUP/$VERSION`. We expect that there will be a way for (third parties to +create their own API groups](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/extending-api.md), and to avoid naming collisions. ## Enabling resources in the extensions group -DaemonSets, Deployments, HorizontalPodAutoscalers, Ingress, Jobs and ReplicaSets are enabled by default. +Jobs, Ingress and HorizontalPodAutoscalers are enabled by default. Other extensions resources can be enabled by setting runtime-config on -apiserver. runtime-config accepts comma separated values. For ex: to disable deployments and jobs, set -`--runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/jobs=false` +apiserver. runtime-config accepts comma separated values. For ex: to enable deployments and disable jobs, set +`--runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/jobs=false` ## v1beta1, v1beta2, and v1beta3 are deprecated; please move to v1 ASAP @@ -88,7 +86,7 @@ As of June 4, 2015, the Kubernetes v1 API has been enabled by default. The v1bet ### v1 conversion tips (from v1beta3) -We're working to convert all documentation and examples to v1. Use `kubectl create --validate` in order to validate your json or yaml against our Swagger spec. +We're working to convert all documentation and examples to v1. A simple [API conversion tool](/{{page.version}}/docs/admin/cluster-management/#switching-your-config-files-to-a-new-api-version) has been written to simplify the translation process. Use `kubectl create --validate` in order to validate your json or yaml against our Swagger spec. Changes to services are the most significant difference between v1beta3 and v1. diff --git a/_includes/masterdocs/docs/reporting-security-issues.md b/_includes/masterdocs/docs/reporting-security-issues.md index 1e8e3056d0c..651f61295c2 100644 --- a/_includes/masterdocs/docs/reporting-security-issues.md +++ b/_includes/masterdocs/docs/reporting-security-issues.md @@ -8,8 +8,8 @@ To watch for security and major API announcements, please join our [kubernetes-a To report an issue, please: - Submit a bug report [here](http://goo.gl/vulnz). - - Select “I want to report a technical security bug in a Google product (SQLi, XSS, etc.).” - - Select “Other” as the Application Type. + - Select 'I want to report a technical security bug in a Google product (SQLi, XSS, etc.).'? + - Select 'Other'? as the Application Type. - Under reproduction steps, please additionally include - the words "Kubernetes Security issue" - Description of the issue diff --git a/_includes/masterdocs/docs/roadmap.md b/_includes/masterdocs/docs/roadmap.md index b7f4937d216..8a82c7f85ce 100644 --- a/_includes/masterdocs/docs/roadmap.md +++ b/_includes/masterdocs/docs/roadmap.md @@ -1,5 +1,46 @@ -The latest release of this document can be found -[here](http://releases.k8s.io/{{page.githubbranch}}/docs/roadmap.md). -Documentation for other releases can be found at -[releases.k8s.io](http://releases.k8s.io). \ No newline at end of file +## Kubernetes 1.1 + +### Timeline + +We are targetting late October for our 1.1 release of Kubernetes. We plan on cutting a first release candidate +in early October. We will enter feature freeze for the 1.1 release on September 21st. Note this does not mean +that the master branch is fully frozen, but all 1.1 features *must* be in by September 21st and large-scale +refactors of the codebase will be blocked until the 1.1 release is finalized to ensure easy cherry-picks. + +### Scope + +The 1.1 release of Kubernetes will be a purely additive releases, the `v1` API will be maintained, with a set +of newly added features. + +#### Blocking Features + +The following features are considered blocking for the 1.1 release: + * Docker 1.8.x + * Graceful pod termination + * IPtables based kube-proxy (tbd if this is the default for all platforms) + * Improvements to kubectl usability and features + * Support for 250 node clusters + * Horizontal Pod autoscaling + * Support for experimental APIs and API groups. + * Job objects + +#### Nice to have features + +The following features will be part of 1.1 if complete, but will not block the release: + * Deployment API + * ScheduledJob API + * Daemon Controller + * ConfigData API + * HTTP(S) load balancer support + * Rolling update improvements + * Third party CRUD resources + +## Post 1.1 + +We're in the process of prioritizing changes to be made after 1.1. + +Please watch the [Github milestones] (https://github.com/kubernetes/kubernetes/milestones) for our future plans. + + + diff --git a/_includes/masterdocs/docs/whatisk8s.md b/_includes/masterdocs/docs/whatisk8s.md index 37491495998..72b56f8afda 100644 --- a/_includes/masterdocs/docs/whatisk8s.md +++ b/_includes/masterdocs/docs/whatisk8s.md @@ -1,8 +1,7 @@ -Kubernetes is an [open-source platform for automating deployment, scaling, and operations of application containers](http://www.slideshare.net/BrianGrant11/wso2con-us-2015-kubernetes-a-platform-for-automating-deployment-scaling-and-operations) across clusters of hosts, providing container-centric infrastructure. +Kubernetes is an open-source platform for automating deployment, scaling, and operations of application containers across clusters of hosts. With Kubernetes, you are able to quickly and efficiently respond to customer demand: - - Deploy your applications quickly and predictably. - Scale your applications on the fly. - Seamlessly roll out new features. - Optimize use of your hardware by using only the resources you need. @@ -12,9 +11,10 @@ Our goal is to foster an ecosystem of components and tools that relieve the burd ## Kubernetes is: +* **lean**: lightweight, simple, accessible * **portable**: public, private, hybrid, multi-cloud * **extensible**: modular, pluggable, hookable, composable -* **self-healing**: auto-placement, auto-restart, auto-replication, auto-scaling +* **self-healing**: auto-placement, auto-restart, auto-replication The Kubernetes project was started by Google in 2014. Kubernetes builds upon a [decade and a half of experience that Google has with running production workloads at scale](https://research.google.com/pubs/pub43438), combined with best-of-breed ideas and practices from the community. @@ -23,73 +23,50 @@ The Kubernetes project was started by Google in 2014. Kubernetes builds upon a [ Looking for reasons why you should be using [containers](http://aucouranton.com/2014/06/13/linux-containers-parallels-lxc-openvz-docker-and-more/)? -The *Old Way* to deploy applications was to install the applications on a host using the operating system package manager. This had the disadvantage of entangling the applications' executables, configuration, libraries, and lifecycles with each other and with the host OS. One could build immutable virtual-machine images in order to achieve predictable rollouts and rollbacks, but VMs are heavyweight and non-portable. - -The *New Way* is to deploy containers based on operating-system-level virtualization rather than hardware virtualization. These containers are isolated from each other and from the host: they have their own filesystems, they can't see each others' processes, and their computational resource usage can be bounded. They are easier to build than VMs, and because they are decoupled from the underlying infrastructure and from the host filesystem, they are portable across clouds and OS distributions. - -Because containers are small and fast, one application can be packed in each container image. It is this one-to-one application-to-image relationship that unlocks the full benefits of containers: - -1. Immutable container images can be created at build/release time rather than deployment time, since each application doesn't need to be composed with the rest of the application stack nor married to the production infrastructure environment. This enables a consistent environment to be carried from development into production. - -2. Containers are vastly more transparent than VMs, which facilitates monitoring and management. This is especially true when the containers' process lifecycles are managed by the infrastructure rather than hidden by a process supervisor inside the container. - -3. With a single application per container, managing the containers becomes tantamount to managing deployment of the application. - -Summary of container benefits: +Here are some key points: +* **Application-centric management**: + Raises the level of abstraction from running an OS on virtual hardware to running an application on an OS using logical resources. This provides the simplicity of PaaS with the flexibility of IaaS and enables you to run much more than just [12-factor apps](http://12factor.net/). +* **Dev and Ops separation of concerns**: + Provides separation of build and deployment; therefore, decoupling applications from infrastructure. * **Agile application creation and deployment**: Increased ease and efficiency of container image creation compared to VM image use. * **Continuous development, integration, and deployment**: Provides for reliable and frequent container image build and deployment with quick and easy rollbacks (due to image immutability). -* **Dev and Ops separation of concerns**: - Create application container images at build/release time rather than deployment time, thereby decoupling applications from infrastructure. +* **Loosely coupled, distributed, elastic, liberated [micro-services](http://martinfowler.com/articles/microservices)**: + Applications are broken into smaller, independent pieces and can be deployed and managed dynamically -- not a fat monolithic stack running on one big single-purpose machine. * **Environmental consistency across development, testing, and production**: Runs the same on a laptop as it does in the cloud. * **Cloud and OS distribution portability**: - Runs on Ubuntu, RHEL, CoreOS, on-prem, Google Container Engine, and anywhere else. -* **Application-centric management**: - Raises the level of abstraction from running an OS on virtual hardware to running an application on an OS using logical resources. -* **Loosely coupled, distributed, elastic, liberated [micro-services](http://martinfowler.com/articles/microservices.html)**: - Applications are broken into smaller, independent pieces and can be deployed and managed dynamically -- not a fat monolithic stack running on one big single-purpose machine. + Runs on Ubuntu, RHEL, on-prem, or Google Container Engine, which makes sense for all environments: build, test, and production. * **Resource isolation**: Predictable application performance. * **Resource utilization**: High efficiency and density. -## Why do I need Kubernetes and what can it do? +## What can Kubernetes do? Kubernetes can schedule and run application containers on clusters of physical or virtual machines. It can also do much more than that. -In order to take full advantage of the potential benefits of containers and leave the old deployment methods behind, one needs to cut the cord to physical and virtual machines. - -However, once specific containers are no longer bound to specific machines, **host-centric** infrastructure no longer works: managed groups, load balancing, auto-scaling, etc. One needs **container-centric** infrastructure. That's what Kubernetes provides. - Kubernetes satisfies a number of common needs of applications running in production, such as: -* [co-locating helper processes](/{{page.version}}/docs/user-guide/pods/), facilitating composite applications and preserving the one-application-per-container model, -* [mounting storage systems](/{{page.version}}/docs/user-guide/volumes/), -* [distributing secrets](/{{page.version}}/docs/user-guide/secrets/), +* [co-locating helper processes](/{{page.version}}/docs/user-guide/pods), +* [mounting storage systems](/{{page.version}}/docs/user-guide/volumes), +* [distributing secrets](/{{page.version}}/docs/user-guide/secrets), * [application health checking](/{{page.version}}/docs/user-guide/production-pods/#liveness-and-readiness-probes-aka-health-checks), -* [replicating application instances](/{{page.version}}/docs/user-guide/replication-controller/), -* [horizontal auto-scaling](/{{page.version}}/docs/user-guide/horizontal-pod-autoscaler/), -* [naming and discovery](/{{page.version}}/docs/user-guide/connecting-applications/), -* [load balancing](/{{page.version}}/docs/user-guide/services/), -* [rolling updates](/{{page.version}}/docs/user-guide/update-demo/), -* [resource monitoring](/{{page.version}}/docs/user-guide/monitoring/), -* [log access and ingestion](/{{page.version}}/docs/user-guide/logging/), -* [support for introspection and debugging](/{{page.version}}/docs/user-guide/introspection-and-debugging/), and -* [identity and authorization](/{{page.version}}/docs/admin/authorization/). +* [replicating application instances](/{{page.version}}/docs/user-guide/replication-controller), +* [horizontal auto-scaling](/{{page.version}}/docs/user-guide/horizontal-pod-autoscaler), +* [load balancing](/{{page.version}}/docs/user-guide/services), +* [rolling updates](/{{page.version}}/docs/user-guide/update-demo/), and +* [resource monitoring](/{{page.version}}/docs/user-guide/monitoring). -This provides the simplicity of Platform as a Service (PaaS) with the flexibility of Infrastructure as a Service (IaaS), and facilitates portability across infrastructure providers. - -For more details, see the [user guide](/{{page.version}}/docs/user-guide/). ## Why and how is Kubernetes a platform? -Even though Kubernetes provides a lot of functionality, there are always new scenarios that would benefit from new features. Application-specific workflows can be streamlined to accelerate developer velocity. Ad hoc orchestration that is acceptable initially often requires robust automation at scale. This is why Kubernetes was also designed to serve as a platform for building an ecosystem of components and tools to make it easier to deploy, scale, and manage applications. +Even though Kubernetes provides a lot of functionality, there are always new scenarios that would benefit from new features. Ad hoc orchestration that is acceptable initially often requires robust automation at scale. Application-specific workflows can be streamlined to accelerate developer velocity. This is why Kubernetes was also designed to serve as a platform for building an ecosystem of components and tools to make it easier to deploy, scale, and manage applications. [Labels](/{{page.version}}/docs/user-guide/labels) empower users to organize their resources however they please. [Annotations](/{{page.version}}/docs/user-guide/annotations) enable users to decorate resources with custom information to facilitate their workflows and provide an easy way for management tools to checkpoint state. @@ -99,22 +76,17 @@ This [design](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch} ## Kubernetes is not: -Kubernetes is not a traditional, all-inclusive PaaS (Platform as a Service) system. We preserve user choice where it is important. +Kubernetes is not a PaaS (Platform as a Service). -* Kubernetes does not limit the types of applications supported. It does not dictate application frameworks (e.g., [Wildfly](http://wildfly.org/)), restrict the set of supported language runtimes (e.g., Java, Python, Ruby), cater to only [12-factor applications](http://12factor.net/), nor distinguish "apps" from "services". Kubernetes aims to support an extremely diverse variety of workloads, including stateless, stateful, and data-processing workloads. If an application can run in a container, it should run great on Kubernetes. -* Kubernetes does not provide middleware (e.g., message buses), data-processing frameworks (e.g., Spark), databases (e.g., mysql), nor cluster storage systems (e.g., Ceph) as built-in services. Such applications run on Kubernetes. -* Kubernetes does not have a click-to-deploy service marketplace. -* Kubernetes is unopinionated in the source-to-image space. It does not deploy source code and does not build your application. Continuous Integration (CI) workflow is an area where different users and projects have their own requirements and preferences, so we support layering CI workflows on Kubernetes but don't dictate how it should work. -* Kubernetes allows users to choose the logging, monitoring, and alerting systems of their choice. (Though we do provide some integrations as proof of concept.) -* Kubernetes does not provide nor mandate a comprehensive application configuration language/system (e.g., [jsonnet](https://github.com/google/jsonnet)). -* Kubernetes does not provide nor adopt any comprehensive machine configuration, maintenance, management, or self-healing systems. +* Kubernetes does not limit the types of applications supported. It does not dictate application frameworks, restrict the set of supported language runtimes, nor cater to only [12-factor applications](http://12factor.net/). Kubernetes aims to support an extremely diverse variety of workloads: if an application can run in a container, it should run great on Kubernetes. +* Kubernetes is unopinionated in the source-to-image space. It does not build your application. Continuous Integration (CI) workflow is an area where different users and projects have their own requirements and preferences, so we support layering CI workflows on Kubernetes but don't dictate how it should work. +* On the other hand, a number of PaaS systems run *on* Kubernetes, such as [Openshift](https://github.com/openshift/origin) and [Deis](http://deis.io/). You could also roll your own custom PaaS, integrate with a CI system of your choice, or get along just fine with just Kubernetes: bring your container images and deploy them on Kubernetes. +* Since Kubernetes operates at the application level rather than at just the hardware level, it provides some generally applicable features common to PaaS offerings, such as deployment, scaling, load balancing, logging, monitoring, etc. However, Kubernetes is not monolithic, and these default solutions are optional and pluggable. -On the other hand, a number of PaaS systems run *on* Kubernetes, such as [Openshift](https://github.com/openshift/origin), [Deis](http://deis.io/), and [Gondor](https://gondor.io/). You could also roll your own custom PaaS, integrate with a CI system of your choice, or get along just fine with just Kubernetes: bring your container images and deploy them on Kubernetes. +Kubernetes is not a mere "orchestration system"; it eliminates the need for orchestration: -Since Kubernetes operates at the application level rather than at just the hardware level, it provides some generally applicable features common to PaaS offerings, such as deployment, scaling, load balancing, logging, monitoring, etc. However, Kubernetes is not monolithic, and these default solutions are optional and pluggable. +* The technical definition of "orchestration" is execution of a defined workflow: do A, then B, then C. In contrast, Kubernetes is comprised of a set of control processes that continuously drive current state towards the provided desired state. It shouldn't matter how you get from A to C: make it so. This results in a system that is easier to use and more powerful, robust, and resilient. -Additionally, Kubernetes is not a mere "orchestration system"; it eliminates the need for orchestration. The technical definition of "orchestration" is execution of a defined workflow: do A, then B, then C. In contrast, Kubernetes is comprised of a set of independent, composable control processes that continuously drive current state towards the provided desired state. It shouldn't matter how you get from A to C: make it so. Centralized control is also not required; the approach is more akin to "choreography". This results in a system that is easier to use and more powerful, robust, resilient, and extensible. - -#### What does *Kubernetes* mean? K8s? +## What does *Kubernetes* mean? K8s? The name **Kubernetes** originates from Greek, meaning "helmsman" or "pilot", and is the root of "governor" and ["cybernetic"](http://www.etymonline.com/index.php?term=cybernetics). **K8s** is an abbreviation derived by replacing the 8 letters "ubernete" with 8. \ No newline at end of file