From d6dbba92afb80171796b94b039472adfeeb439d1 Mon Sep 17 00:00:00 2001 From: aburdenthehand Date: Fri, 9 Mar 2018 06:00:57 +1000 Subject: [PATCH] Flag names changed (s/admission-control/enable-admission-plugins); disable-admissions-plugin entry added; removed reference to admission controller/plugins requiring set order (for v1.10), redundant example enabling specific plugin, and redundant version-specific info (#7449) --- .../admin/extensible-admission-controllers.md | 314 ++++++++++++++++++ docs/concepts/policy/resource-quotas.md | 8 + docs/tutorials/clusters/apparmor.md | 6 + 3 files changed, 328 insertions(+) diff --git a/docs/admin/extensible-admission-controllers.md b/docs/admin/extensible-admission-controllers.md index 51bcac6787..95b92ad0c7 100644 --- a/docs/admin/extensible-admission-controllers.md +++ b/docs/admin/extensible-admission-controllers.md @@ -21,9 +21,19 @@ the following: * They need to be compiled into kube-apiserver. * They are only configurable when the apiserver starts up. +<<<<<<< HEAD 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. +||||||| merged common ancestors +1.7 introduces 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. +======= +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. +>>>>>>> Flag names changed (s/admission-control/enable-admission-plugins); disable-admissions-plugin entry added; removed reference to admission controller/plugins requiring set order (for v1.10), redundant example enabling specific plugin, and redundant version-specific info (#7449) This page describes how to use Admission Webhooks and Initializers. @@ -297,3 +307,307 @@ 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 +||||||| merged common ancestors + +## 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:** The admission chain depends solely on the order of the +`--admission-control` option passed to `kube-apiserver`. + +### 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 `--admission-control` 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/api-reference/{{page.version}}/#deployment-v1beta1-apps). +You also need to create a +[service](/docs/api-reference/{{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`. In 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. +======= + +## 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:** The admission chain depends solely on the order of the +`--admission-control` option passed to `kube-apiserver`. + +### 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/api-reference/{{page.version}}/#deployment-v1beta1-apps). +You also need to create a +[service](/docs/api-reference/{{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. +>>>>>>> Flag names changed (s/admission-control/enable-admission-plugins); disable-admissions-plugin entry added; removed reference to admission controller/plugins requiring set order (for v1.10), redundant example enabling specific plugin, and redundant version-specific info (#7449) diff --git a/docs/concepts/policy/resource-quotas.md b/docs/concepts/policy/resource-quotas.md index 79b0eaef57..7b3b8693eb 100644 --- a/docs/concepts/policy/resource-quotas.md +++ b/docs/concepts/policy/resource-quotas.md @@ -50,6 +50,7 @@ Neither contention nor changes to quota will affect already created resources. ## Enabling Resource Quota +<<<<<<< HEAD <<<<<<< HEAD Resource Quota support is enabled by default for many Kubernetes distributions. It is enabled when the apiserver `--enable-admission-plugins=` flag has `ResourceQuota` as @@ -60,6 +61,13 @@ enabled when the apiserver `--admission-control=` flag has `ResourceQuota` as Resource quota support is enabled by default for many Kubernetes distributions. It is enabled when the apiserver `--admission-control=` flag has `ResourceQuota` as >>>>>>> merge master to 1.10, with fixes (#7682) +||||||| merged common ancestors +Resource quota support is enabled by default for many Kubernetes distributions. It is +enabled when the apiserver `--admission-control=` flag has `ResourceQuota` as +======= +Resource Quota support is enabled by default for many Kubernetes distributions. It is +enabled when the apiserver `--enable-admission-plugins=` flag has `ResourceQuota` as +>>>>>>> Flag names changed (s/admission-control/enable-admission-plugins); disable-admissions-plugin entry added; removed reference to admission controller/plugins requiring set order (for v1.10), redundant example enabling specific plugin, and redundant version-specific info (#7449) one of its arguments. A resource quota is enforced in a particular namespace when there is a diff --git a/docs/tutorials/clusters/apparmor.md b/docs/tutorials/clusters/apparmor.md index d54442d0de..6578a8e3ff 100644 --- a/docs/tutorials/clusters/apparmor.md +++ b/docs/tutorials/clusters/apparmor.md @@ -321,6 +321,7 @@ enable the PodSecurityPolicy, the following flag must be set on the `apiserver`: ``` <<<<<<< HEAD +<<<<<<< HEAD --enable-admission-plugins=PodSecurityPolicy[,others...] ||||||| merged common ancestors --admission-control=PodSecurityPolicy[,others...] @@ -328,6 +329,11 @@ enable the PodSecurityPolicy, the following flag must be set on the `apiserver`: ======= --admission-control=PodSecurityPolicy[,others...] >>>>>>> Use PSP from policy API group. (#7562) +||||||| merged common ancestors +--admission-control=PodSecurityPolicy[,others...] +======= +--enable-admission-plugins=PodSecurityPolicy[,others...] +>>>>>>> Flag names changed (s/admission-control/enable-admission-plugins); disable-admissions-plugin entry added; removed reference to admission controller/plugins requiring set order (for v1.10), redundant example enabling specific plugin, and redundant version-specific info (#7449) ``` The AppArmor options can be specified as annotations on the PodSecurityPolicy: