|
|
|
@@ -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
|
|
|
|
|
Andrew Chen