whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs changes to PR #4092 (#4224)

Browse Source 
* Docs changes to PR #4092

* address feedback
This commit is contained in:
Andrew Chen
2017-06-28 22:03:44 -07:00
committed by GitHub
parent b9593e8e1d
commit 61892b82ec
1 changed files with 45 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/extensible-admission-controllers.md
+45 -47
View File
@@ -12,13 +12,12 @@ title: Dynamic Admission Control
## Overview ## Overview
The [admission controllers documentation](/doc/admin/admission-controllers.md) The [admission controllers documentation](/docs/admin/admission-controllers/)
introduces how to use standard, plugin-style admission controllers. However, introduces how to use standard, plugin-style admission controllers. However,
plugin admission controllers are not flexible enough for all use cases, due to plugin admission controllers are not flexible enough for all use cases, due to
the following: the following:
* They need to be compiled into kube-apiserver. * They need to be compiled into kube-apiserver.
* They are only configurable when the apiserver starts up. * They are only configurable when the apiserver starts up.
1.7 introduces two alpha features, *Initializers* and *External Admission 1.7 introduces two alpha features, *Initializers* and *External Admission
@@ -31,34 +30,34 @@ This page describes how to use Initializers and External Admission Webhooks.
### What are initializers? ### What are initializers?
Two meanings: *Initializer* has two meanings:
* A list of pending pre-initialization tasks, stored in every object's metadata * A list of pending pre-initialization tasks, stored in every object's metadata
(e.g., "AddMyCorporatePolicySidecar"). (e.g., "AddMyCorporatePolicySidecar").
* The controllers which actually perform those tasks. The name of the task * A user customized controller, which actually perform those tasks. The name of the task
corresponds to the controller which performs the task. For clarity, we call corresponds to the controller which performs the task. For clarity, we call
them "initializer controllers" in this page. them *initializer controllers* in this page.
Once the controller has performed its assigned task, it removes its name from Once the controller has performed its assigned task, it removes its name from
the list. For example, it may send a PATCH that inserts a container in a pod and the list. For example, it may send a PATCH that inserts a container in a pod and
also removes its name from `metadata.initalizers`. Initializers may make also removes its name from `metadata.initializers`. Initializers may make
mutations to objects. mutations to objects.
Objects which have a non-empty initializer list are considered uninitialized, Objects which have a non-empty initializer list are considered uninitialized,
and are not visible in the API unless specifically requested and are not visible in the API unless specifically requested by using the query parameter,
(`?includeUninitialized=true`). `?includeUninitialized=true`.
### When to use initializers? ### When to use initializers?
Initializers are useful for admins to force policies (e.g., the Initializers are useful for admins to force policies (e.g., the
[AlwaysPullImages](https://kubernetes.io/docs/admin/admission-controllers/#alwayspullimages) [AlwaysPullImages](/docs/admin/admission-controllers/#alwayspullimages)
admission controller), or to inject defaults (e.g., the admission controller), or to inject defaults (e.g., the
[DefaultStorageClass](https://kubernetes.io/docs/admin/admission-controllers/#defaultstorageclass) [DefaultStorageClass](/docs/admin/admission-controllers/#defaultstorageclass)
admission controller), etc. admission controller), etc.
Note that if your use case does not involve mutating objects, consider using **Note:** If your use case does not involve mutating objects, consider using
external admission webhooks as they have better performance. external admission webhooks, as they have better performance.
### How are initializers triggered? ### How are initializers triggered?
@@ -69,17 +68,17 @@ all `spec.initializers[].name`s are appended to the new object's
An initializer controller should list and watch for uninitialized objects, by An initializer controller should list and watch for uninitialized objects, by
using the query parameter `?includeUninitialized=true`. If using client-go, just using the query parameter `?includeUninitialized=true`. If using client-go, just
set the set
[listOptions.includeUninitialized](https://github.com/kubernetes/kubernetes/blob/v1.7.0-rc.1/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/types.go#L315) [listOptions.includeUninitialized](https://github.com/kubernetes/kubernetes/blob/v1.7.0-rc.1/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/types.go#L315)
to true. to true.
For the observed uninitialized objects, an initializer controller should first For the observed uninitialized objects, an initializer controller should first
check if its name matches `metadata.initializers[0]`, if so, it should then check if its name matches `metadata.initializers[0]`. If so, it should then
perform its assigned task and remove its name from the list. perform its assigned task and remove its name from the list.
### Enable initializers alpha feature ### Enable initializers alpha feature
Initializers are an alpha feature, which is disabled by default. To turn it on, *Initializers* is an alpha feature, so it is disabled by default. To turn it on,
you need to: you need to:
* Include "Initializer" in the `--admission-control` flag when starting * Include "Initializer" in the `--admission-control` flag when starting
@@ -94,16 +93,16 @@ you need to:
### Deploy an initializer controller ### Deploy an initializer controller
We suggest that deploying an initializer controller via the [deployment You should deploy an initializer controller via the [deployment
API](https://kubernetes.io/docs/api-reference/v1.6/#deployment-v1beta1-apps). API](/docs/api-reference/v1.6/#deployment-v1beta1-apps).
### Configure initializers on the fly ### Configure initializers on the fly
You can configure what initializers are enabled and what resources are subject You can configure what initializers are enabled and what resources are subject
to the initializers by creating `initializerconfigurations`. to the initializers by creating `initializerconfigurations`.
We suggest that you first deploy the initializer controller and make sure it is You should first deploy the initializer controller and make sure that it is
working properly before creating the `initializerconfigurations`, otherwise any working properly before creating the `initializerconfigurations`. Otherwise, any
newly created resources will be stuck in an uninitialized state. newly created resources will be stuck in an uninitialized state.
The following is an example `initiallizerConfiguration`. The following is an example `initiallizerConfiguration`.
@@ -129,9 +128,9 @@ spec:
``` ```
Make sure that all expansions of the `<apiGroup, apiVersions, resources>` tuple Make sure that all expansions of the `<apiGroup, apiVersions, resources>` tuple
in a `rule` are valid; if they are not, separate them in different `rules`. in a `rule` are valid. If they are not, separate them in different `rules`.
After you create the `initializerConfiguration`, the system will take a few After you create the `initializerConfiguration`, the system will take a few
seconds to honor the new configuration. seconds to honor the new configuration.
## External Admission Webhooks ## External Admission Webhooks
@@ -139,11 +138,11 @@ seconds to honor the new configuration.
### What are external admission webhooks? ### What are external admission webhooks?
External admission webhooks are HTTP callbacks that are intended to receive External admission webhooks are HTTP callbacks that are intended to receive
admission requests and do something with them. What the external admission admission requests and do something with them. What an external admission
webhook does is up to you but there is an webhook does is up to you, but there is an
[interface](https://github.com/kubernetes/kubernetes/blob/v1.7.0-rc.1/pkg/apis/admission/v1alpha1/types.go) [interface](https://github.com/kubernetes/kubernetes/blob/v1.7.0-rc.1/pkg/apis/admission/v1alpha1/types.go)
the external admission webhook must follow and that is to respond back with that it must adhere to so that it responds with whether or not the
whether or not the admission request should be allowed. admission request should be allowed.
Unlike initializers or the plugin-style admission controllers, external Unlike initializers or the plugin-style admission controllers, external
admission webhooks are not allowed to mutate the admission request in any way. admission webhooks are not allowed to mutate the admission request in any way.
@@ -153,12 +152,11 @@ must support TLS.
### When to use admission webhooks? ### When to use admission webhooks?
A good example use of an external admission webhook is to do semantic validation A simple example use case for an external admission webhook is to do semantic validation
of Kubernetes resources. Imagine your infrastructure requires that all `Pod` of Kubernetes resources. Suppose that your infrastructure requires that all `Pod`
resources have a common set of labels and you do not want any `Pod` to be resources have a common set of labels, and you do not want any `Pod` to be
persisted to Kubernetes if those needs are not met. You could write your persisted to Kubernetes if those needs are not met. You could write your
external admission webhook to do this validation and respond accordingly. Of external admission webhook to do this validation and respond accordingly.
course this is a very simple case but you get the idea.
### How are external admission webhooks triggered? ### How are external admission webhooks triggered?
@@ -167,11 +165,11 @@ get the list of interested external admission webhooks from
`externalAdmissionHookConfiguration` objects (explained below) and call them in `externalAdmissionHookConfiguration` objects (explained below) and call them in
parallel. If **all** of the external admission webhooks approve the admission parallel. If **all** of the external admission webhooks approve the admission
request, the admission chain continues. If **any** of the external admission request, the admission chain continues. If **any** of the external admission
webhooks deny the admission request, the admission request will be denied and webhooks deny the admission request, the admission request will be denied, and
the reason for doing so will be based on the _first_ external admission webhook the reason for doing so will be based on the _first_ external admission webhook
denial reason. _(This means if there is more than one external admission webhook denial reason. _This means if there is more than one external admission webhook
that denied the admission request, only the first will be returned to the that denied the admission request, only the first will be returned to the
user.)_ If there is an error encountered when calling an external admission user._ If there is an error encountered when calling an external admission
webhook, that request is ignored and will not be used to approve/deny the webhook, that request is ignored and will not be used to approve/deny the
admission request. admission request.
@@ -180,7 +178,7 @@ admission request.
### Enable external admission webhooks ### Enable external admission webhooks
External Admission Webhooks is an alpha feature, which is disabled by default. *External Admission Webhooks* is an alpha feature, so it is disabled by default.
To turn it on, you need to To turn it on, you need to
* Include "GenericAdmissionWebhook" in the `--admission-control` flag when * Include "GenericAdmissionWebhook" in the `--admission-control` flag when
@@ -195,7 +193,7 @@ To turn it on, you need to
### Write a webhook admission controller ### Write a webhook admission controller
See [here](https://github.com/caesarxuchao/example-webhook-admission-controller) See [caesarxuchao/example-webhook-admission-controller](https://github.com/caesarxuchao/example-webhook-admission-controller)
for an example webhook admission controller. for an example webhook admission controller.
The communication between the webhook admission controller and the apiserver, or The communication between the webhook admission controller and the apiserver, or
@@ -215,24 +213,24 @@ gathers information like `object`, `oldobject`, and `userInfo`, from
### Deploy the webhook admission controller ### Deploy the webhook admission controller
See [here](https://github.com/caesarxuchao/example-webhook-admission-controller/tree/master/deployment) See [caesarxuchao/example-webhook-admission-controller deployment](https://github.com/caesarxuchao/example-webhook-admission-controller/tree/master/deployment)
for an example deployment. for an example deployment.
We suggest that deploying the webhook admission controller via the [deployment The webhook admission controller should be deployed via the
API](https://kubernetes.io/docs/api-reference/v1.6/#deployment-v1beta1-apps). [deployment API](/docs/api-reference/v1.6/#deployment-v1beta1-apps).
You also need to create a You also need to create a
[service](https://kubernetes.io/docs/api-reference/v1.6/#service-v1-core) as the [service](/docs/api-reference/v1.6/#service-v1-core) as the
front-end of the deployment. front-end of the deployment.
### Configure webhook admission controller on the fly ### Configure webhook admission controller on the fly
You can configure what webhook admission controller are enabled and what You can configure what webhook admission controllers are enabled and what
resources are subject to the admission controller via creating resources are subject to the admission controller via creating
externaladmissionhookconfigurations. externaladmissionhookconfigurations.
We suggest that you first deploy the webhook admission controller and make sure We suggest that you first deploy the webhook admission controller and make sure
it is working properly before creating the externaladmissionhookconfigurations, it is working properly before creating the externaladmissionhookconfigurations.
otherwise depending whether the webhook is configured as fail open or fail Otherwise, depending whether the webhook is configured as fail open or fail
closed, operations will be unconditionally accepted or rejected. closed, operations will be unconditionally accepted or rejected.
The following is an example externaladmissionhookconfiguration. The following is an example externaladmissionhookconfiguration.
@@ -275,12 +273,12 @@ differences:
* The `resources` field accepts subresources in the form or resource/subresource. * The `resources` field accepts subresources in the form or resource/subresource.
Make sure that all expansions of the `<apiGroup, apiVersions,resources>` tuple Make sure that all expansions of the `<apiGroup, apiVersions,resources>` tuple
in a `rule` are valid; if they are not, separate them to different `rules`. in a `rule` are valid. If they are not, separate them to different `rules`.
You can also specify the `failurePolicy`. In 1.7, the system supports `Ignore` You can also specify the `failurePolicy`. In 1.7, the system supports `Ignore`
and `Fail` policies, meaning upon an communication error with the webhook and `Fail` policies, meaning that upon a communication error with the webhook
admission controller, if the `GenericAdmissionWebhook` will admit or reject the admission controller, the `GenericAdmissionWebhook` can admit or reject the
operation. operation based on the configured policy.
After you create the `initializerConfiguration`, the system will take a few After you create the `initializerConfiguration`, the system will take a few
seconds to honor the new configuration. seconds to honor the new configuration.