Merge master into release-1.10
This commit is contained in:
Andrew Chen
@@ -4,6 +4,7 @@ reviewers:
|
||||
- lavalamp
|
||||
- whitlockjc
|
||||
- caesarxuchao
|
||||
- deads2k
|
||||
title: Dynamic Admission Control
|
||||
---
|
||||
|
||||
@@ -20,11 +21,175 @@ 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 Initializers and External Admission Webhooks.
|
||||
This page describes how to use Admission Webhooks and Initializers.
|
||||
|
||||
## Admission Webhooks
|
||||
|
||||
### What are admission webhooks?
|
||||
|
||||
Admission webhooks are HTTP callbacks that receive admission requests and do
|
||||
something with them. You can define two types of admission webhooks,
|
||||
[ValidatingAdmissionWebhooks](/docs/admin/admission-controllers.md#validatingadmissionwebhook-alpha-in-18-beta-in-19)
|
||||
and
|
||||
[MutatingAdmissionWebhooks](/docs/admin/admission-controllers.md#mutatingadmissionwebhook-beta-in-19).
|
||||
With `ValidatingAdmissionWebhooks`, you may reject requests to enforce custom
|
||||
admission policies. With `MutatingAdmissionWebhooks`, you may change requests to
|
||||
enforce custom defaults.
|
||||
|
||||
### Experimenting with admission webhooks
|
||||
|
||||
Admission webhooks are essentially part of the cluster control-plane. You should
|
||||
write and deploy them with great caution. Please read the [user
|
||||
guides](https://github.com/kubernetes/website/pull/6836/files)(WIP) for
|
||||
instructions if you intend to write/deploy production-grade admission webhooks.
|
||||
In the following, we describe how to quickly experiment with admission webhooks.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
* Ensure that the Kubernetes cluster is at least as new as v1.9.
|
||||
|
||||
* Ensure that MutatingAdmissionWebhook and ValidatingAdmissionWebhook
|
||||
admission controllers are enabled.
|
||||
[Here](/docs/admin/admission-controllers.md#is-there-a-recommended-set-of-admission-controllers-to-use)
|
||||
is a recommended set of admission controllers to enable in general.
|
||||
|
||||
* Ensure that the admissionregistration.k8s.io/v1beta1 API is enabled.
|
||||
|
||||
### Write an admission webhook server
|
||||
|
||||
Please refer to the implementation of the [admission webhook
|
||||
server](https://github.com/kubernetes/kubernetes/blob/v1.10.0-beta.1/test/images/webhook/main.go)
|
||||
that is validated in a Kubernetes e2e test. The webhook handles the
|
||||
`admissionReview` requests sent by the apiservers, and sends back its decision
|
||||
wrapped in `admissionResponse`.
|
||||
|
||||
The example admission webhook server leaves the `ClientAuth` field
|
||||
[empty](https://github.com/kubernetes/kubernetes/blob/v1.10.0-beta.1/test/images/webhook/config.go#L48-L49),
|
||||
which defaults to `NoClientCert`. This means that the webhook server does not
|
||||
authenticate the identity of the clients, supposedly apiservers. If you need
|
||||
mutual TLS or other ways to authenticate the clients, see
|
||||
how to [authenticate apiservers](#authenticate-apiservers).
|
||||
|
||||
### Deploy the admission webhook service
|
||||
|
||||
The webhook server in the e2e test is deployed in the Kubernetes cluster, via
|
||||
the [deployment API](/docs/api-reference/{{page.version}}/#deployment-v1beta1-apps).
|
||||
The test also creates a [service](/docs/api-reference/{{page.version}}/#service-v1-core)
|
||||
as the front-end of the webhook server. See
|
||||
[code](https://github.com/kubernetes/kubernetes/blob/v1.10.0-beta.1/test/e2e/apimachinery/webhook.go#L196).
|
||||
|
||||
You may also deploy your webhooks outside of the cluster. You will need to update
|
||||
your [webhook client configurations](https://github.com/kubernetes/kubernetes/blob/v1.10.0-beta.1/staging/src/k8s.io/api/admissionregistration/v1beta1/types.go#L218) accordingly.
|
||||
|
||||
### Configure admission webhooks on the fly
|
||||
|
||||
You can dynamically configure what resources are subject to what admission
|
||||
webhooks via
|
||||
[ValidatingWebhookConfiguration](https://github.com/kubernetes/kubernetes/blob/v1.10.0-beta.1/staging/src/k8s.io/api/admissionregistration/v1beta1/types.go#L68)
|
||||
or
|
||||
[MutatingWebhookConifuration](https://github.com/kubernetes/kubernetes/blob/v1.10.0-beta.1/staging/src/k8s.io/api/admissionregistration/v1beta1/types.go#L98).
|
||||
|
||||
The following is an example `validatingWebhookConfiguration`, a mutating webhook
|
||||
configuration is similar.
|
||||
|
||||
```yaml
|
||||
apiVersion: admissionregistration.k8s.io/v1beta1
|
||||
kind: ValidatingWebhookConfiguration
|
||||
metadata:
|
||||
name: <name of this configuration object>
|
||||
webhooks:
|
||||
- name: <webhook name, e.g., pod-policy.example.io>
|
||||
rules:
|
||||
- apiGroups:
|
||||
- ""
|
||||
apiVersions:
|
||||
- v1
|
||||
operations:
|
||||
- CREATE
|
||||
resources:
|
||||
- pods
|
||||
clientConfig:
|
||||
service:
|
||||
namespace: <namespace of the front-end service>
|
||||
name: <name of the front-end service>
|
||||
caBundle: <pem encoded ca cert that signs the server cert used by the webhook>
|
||||
```
|
||||
|
||||
When an apiserver receives a request that matches one of the `rules`, the
|
||||
apiserver sends an `admissionReview` request to webhook as specified in the
|
||||
`clientConfig`.
|
||||
|
||||
After you create the webhook configuration, the system will take a few seconds
|
||||
to honor the new configuration.
|
||||
|
||||
### Authenticate apiservers
|
||||
|
||||
If your admission webhooks require authentication, you can configure the
|
||||
apiservers to use basic auth, bearer token, or a cert to authenticate itself to
|
||||
the webhooks. There are three steps to complete the configuration.
|
||||
|
||||
* When starting the apiserver, specify the location of the admission control
|
||||
configuration file via the `--admission-control-config-file` flag.
|
||||
|
||||
* In the admission control configuration file, specify where the
|
||||
MutatingAdmissionWebhook controller and ValidatingAdmissionWebhook controller
|
||||
should read the credentials. The credentials are stored in kubeConfig files
|
||||
(yes, the same schema that's used by kubectl), so the field name is
|
||||
`kubeConfigFile`. Here is an example admission control configuration file:
|
||||
|
||||
```yaml
|
||||
apiVersion: apiserver.k8s.io/v1alpha1
|
||||
kind: AdmissionConfiguration
|
||||
plugins:
|
||||
- name: ValidatingAdmissionWebhook
|
||||
configuration:
|
||||
apiVersion: apiserver.config.k8s.io/v1alpha1
|
||||
kind: WebhookAdmission
|
||||
kubeConfigFile: <path-to-kubeconfig-file>
|
||||
- name: MutatingAdmissionWebhook
|
||||
configuration:
|
||||
apiVersion: apiserver.config.k8s.io/v1alpha1
|
||||
kind: WebhookAdmission
|
||||
kubeConfigFile: <path-to-kubeconfig-file>
|
||||
```
|
||||
|
||||
The schema of `admissionConfiguration` is defined
|
||||
[here](https://github.com/kubernetes/kubernetes/blob/v1.10.0-beta.0/staging/src/k8s.io/apiserver/pkg/apis/apiserver/v1alpha1/types.go#L27).
|
||||
|
||||
* In the kubeConfig file, provide the credentials:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Config
|
||||
users:
|
||||
# DNS name of webhook service, i.e., <service name>.<namespace>.svc, or the URL
|
||||
# of the webhook server.
|
||||
- name: 'webhook1.ns1.svc'
|
||||
user:
|
||||
client-certificate-data: <pem encoded certificate>
|
||||
client-key-data: <pem encoded key>
|
||||
# The `name` supports using * to wildmatch prefixing segments.
|
||||
- name: '*.webhook-company.org'
|
||||
user:
|
||||
password: <password>
|
||||
username: <name>
|
||||
# '*' is the default match.
|
||||
- name: '*'
|
||||
user:
|
||||
token: <token>
|
||||
```
|
||||
|
||||
Of course you need to set up the webhook server to handle these authentications.
|
||||
|
||||
## Initializers
|
||||
|
||||
@@ -135,6 +300,7 @@ the pods will be stuck in an uninitialized state.
|
||||
|
||||
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`.
|
||||
<<<<<<< HEAD
|
||||
|
||||
## External Admission Webhooks
|
||||
|
||||
@@ -285,3 +451,5 @@ operation based on the configured policy.
|
||||
|
||||
After you create the `externalAdmissionHookConfiguration`, the system will take a few
|
||||
seconds to honor the new configuration.
|
||||
=======
|
||||
>>>>>>> 4ac258363735f8d35150e4dcd0213516fcdc83b9
|
||||
|
||||
Reference in New Issue
Block a user