From 30aab8074f9f23c89cab2d7d8ebe0e7902b2c99d Mon Sep 17 00:00:00 2001 From: Zach Corleissen Date: Tue, 3 Apr 2018 17:13:08 -0700 Subject: [PATCH] Resolved merge conflict, removed merge artifacts (#7947) --- .../admin/extensible-admission-controllers.md | 165 +----------------- 1 file changed, 1 insertion(+), 164 deletions(-) diff --git a/docs/admin/extensible-admission-controllers.md b/docs/admin/extensible-admission-controllers.md index 629d21c108..96ca73a6b9 100644 --- a/docs/admin/extensible-admission-controllers.md +++ b/docs/admin/extensible-admission-controllers.md @@ -21,15 +21,9 @@ the following: * They need to be compiled into kube-apiserver. * They are only configurable when the apiserver starts up. -<<<<<<< HEAD -1.7 introduced two alpha features, *Initializers* and *External Admission -Webhooks*, that address these limitations. These features allow admission -controllers to be developed out-of-tree and configured at runtime. -======= Two features, *Admission Webhooks* (beta in 1.9) and *Initializers* (alpha), address these limitations. They allow admission controllers to be developed out-of-tree and configured at runtime. ->>>>>>> 4ac258363735f8d35150e4dcd0213516fcdc83b9 This page describes how to use Admission Webhooks and Initializers. @@ -233,7 +227,7 @@ all `spec.initializers[].name`s are appended to the new object's An initializer controller should list and watch for uninitialized objects, by using the query parameter `?includeUninitialized=true`. If using client-go, just -set +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) to true. @@ -300,160 +294,3 @@ the pods will be stuck in an uninitialized state. Make sure that all expansions of the `` tuple in a `rule` are valid. If they are not, separate them in different `rules`. -<<<<<<< HEAD - -## External Admission Webhooks - -### What are external admission webhooks? - -External admission webhooks are HTTP callbacks that are intended to receive -admission requests and do something with them. What an external admission -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) -that it must adhere to so that it responds with whether or not the -admission request should be allowed. - -Unlike initializers or the plugin-style admission controllers, external -admission webhooks are not allowed to mutate the admission request in any way. - -Because admission is a high security operation, the external admission webhooks -must support TLS. - -### When to use admission webhooks? - -A simple example use case for an external admission webhook is to do semantic validation -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 -persisted to Kubernetes if those needs are not met. You could write your -external admission webhook to do this validation and respond accordingly. - -### How are external admission webhooks triggered? - -Whenever a request comes in, the `GenericAdmissionWebhook` admission plugin will -get the list of interested external admission webhooks from -`externalAdmissionHookConfiguration` objects (explained below) and call them in -parallel. If **all** of the external admission webhooks approve the admission -request, the admission chain continues. If **any** of the external admission -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 -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 -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 -admission request. - -**Note** In kubernetes versions earlier than v1.10, the admission chain depends -only on the order of the `--admission-control` option passed to `kube-apiserver`. -In versions v1.10 and later, the `--admission-control` option is replaced by the -`--enable-admission-plugins` and the `--disable-admission-plugins` options. -The order of plugins for these two options no longer matters. -{: .note} - -### Enable external admission webhooks - -*External Admission Webhooks* is an alpha feature, so it is disabled by default. -To turn it on, you need to - -* Include "GenericAdmissionWebhook" in the `--enable-admission-plugins` flag when - starting the apiserver. If you have multiple `kube-apiserver` replicas, all - should have the same flag setting. - -* Enable the dynamic admission controller registration API by adding - `admissionregistration.k8s.io/v1alpha1` to the `--runtime-config` flag passed - to `kube-apiserver`, e.g. - `--runtime-config=admissionregistration.k8s.io/v1alpha1`. Again, all replicas - should have the same flag setting. - -### Write a webhook admission controller - -See [caesarxuchao/example-webhook-admission-controller](https://github.com/caesarxuchao/example-webhook-admission-controller) -for an example webhook admission controller. - -The communication between the webhook admission controller and the apiserver, or -more precisely, the GenericAdmissionWebhook admission controller, needs to be -TLS secured. You need to generate a CA cert and use it to sign the server cert -used by your webhook admission controller. The pem formatted CA cert is supplied -to the apiserver via the dynamic registration API -`externaladmissionhookconfigurations.clientConfig.caBundle`. - -For each request received by the apiserver, the GenericAdmissionWebhook -admission controller sends an -[admissionReview](https://github.com/kubernetes/kubernetes/blob/v1.7.0-rc.1/pkg/apis/admission/v1alpha1/types.go#L27) -to the relevant webhook admission controller. The webhook admission controller -gathers information like `object`, `oldobject`, and `userInfo`, from -`admissionReview.spec`, sends back a response with the body also being the -`admissionReview`, whose `status` field is filled with the admission decision. - -### Deploy the webhook admission controller - -See [caesarxuchao/example-webhook-admission-controller deployment](https://github.com/caesarxuchao/example-webhook-admission-controller/tree/master/deployment) -for an example deployment. - -The webhook admission controller should be deployed via the -[deployment API](/docs/reference/generated/kubernetes-api/{{page.version}}/#deployment-v1beta1-apps). -You also need to create a -[service](/docs/reference/generated/kubernetes-api/{{page.version}}/#service-v1-core) as the -front-end of the deployment. - -### Configure webhook admission controller on the fly - -You can configure what webhook admission controllers are enabled and what -resources are subject to the admission controller via creating -externaladmissionhookconfigurations. - -We suggest that you first deploy the webhook admission controller and make sure -it is working properly before creating the externaladmissionhookconfigurations. -Otherwise, depending whether the webhook is configured as fail open or fail -closed, operations will be unconditionally accepted or rejected. - -The following is an example `externaladmissionhookconfiguration`: - -```yaml -apiVersion: admissionregistration.k8s.io/v1alpha1 -kind: ExternalAdmissionHookConfiguration -metadata: - name: example-config -externalAdmissionHooks: -- name: pod-image.k8s.io - rules: - - apiGroups: - - "" - apiVersions: - - v1 - operations: - - CREATE - resources: - - pods - failurePolicy: Ignore - clientConfig: - caBundle: - service: - name: - namespace: -``` - -For a request received by the apiserver, if the request matches any of the -`rules` of an `externalAdmissionHook`, the `GenericAdmissionWebhook` admission -controller will send an `admissionReview` request to the `externalAdmissionHook` -to ask for admission decision. - -The `rule` is similar to the `rule` in `initializerConfiguration`, with two -differences: - -* The addition of the `operations` field, specifying what operations the webhook - is interested in; - -* The `resources` field accepts subresources in the form or resource/subresource. - -Make sure that all expansions of the `` tuple -in a `rule` are valid. If they are not, separate them to different `rules`. - -You can also specify the `failurePolicy`. As of 1.7, the system supports `Ignore` -and `Fail` policies, meaning that upon a communication error with the webhook -admission controller, the `GenericAdmissionWebhook` can admit or reject the -operation based on the configured policy. - -After you create the `externalAdmissionHookConfiguration`, the system will take a few -seconds to honor the new configuration. -======= ->>>>>>> 4ac258363735f8d35150e4dcd0213516fcdc83b9