The admission controllers documentation introduces how to use standard, plugin-style admission controllers. However, plugin admission controllers are not flexible enough for all use cases, due to the following:
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.
This page describes how to use Admission Webhooks and Initializers.
Admission webhooks are HTTP callbacks that receive admission requests and do something with them. You can define two types of admission webhooks, validating admission Webhook and mutating admission webhook. With validating admission Webhooks, you may reject requests to enforce custom admission policies. With mutating admission Webhooks, you may change requests to enforce custom defaults.
Admission webhooks are essentially part of the cluster control-plane. You should write and deploy them with great caution. Please read the user guides for instructions if you intend to write/deploy production-grade admission webhooks. In the following, we describe how to quickly experiment with admission webhooks.
Ensure that the Kubernetes cluster is at least as new as v1.9.
Ensure that MutatingAdmissionWebhook and ValidatingAdmissionWebhook admission controllers are enabled. Here is a recommended set of admission controllers to enable in general.
Ensure that the admissionregistration.k8s.io/v1beta1 API is enabled.
Please refer to the implementation of the admission webhook
that is validated in a Kubernetes e2e test. The webhook handles the
admissionReview requests sent by the apiservers, and sends back its decision
The example admission webhook server leaves the
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.
You may also deploy your webhooks outside of the cluster. You will need to update your webhook client configurations accordingly.
The following is an example
validatingWebhookConfiguration, a mutating webhook
configuration is similar.
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>
Note: When using
clientConfig.service, the server cert must be valid for
When an apiserver receives a request that matches one of the
apiserver sends an
admissionReview request to webhook as specified in the
After you create the webhook configuration, the system will take a few seconds to honor the new configuration.
Note: When the webhook plugin is deployed into the Kubernetes cluster as a service, it has to expose its service on the 443 port. The communication between the API server and the webhook service may fail if a different port is used.
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
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:
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
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.
Initializer has two meanings:
A list of pending pre-initialization tasks, stored in every object’s metadata (e.g., “AddMyCorporatePolicySidecar”).
A user customized controller, which actually performs those tasks. The name of the task corresponds to the controller which performs the task. For clarity, we call them initializer controllers in this page.
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
also removes its name from
metadata.initializers.pending. Initializers may make
mutations to objects.
Objects which have a non-empty initializer list are considered uninitialized,
and are not visible in the API unless specifically requested by using the query parameter,
Note: If your use case does not involve mutating objects, consider using external admission webhooks, as they have better performance.
When an object is POSTed, it is checked against all existing
initializerConfiguration objects (explained below). For all that it matches,
spec.initializers.names 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
For the observed uninitialized objects, an initializer controller should first
check if its name matches
metadata.initializers.pending. If so, it should then
perform its assigned task and remove its name from the list.
Initializers is an alpha feature, so it is disabled by default. To turn it on, you need to:
Include “Initializers” in the
--enable-admission-plugins flag when starting
kube-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
--runtime-config=admissionregistration.k8s.io/v1alpha1. Again, all replicas
should have the same flag setting.
You should deploy an initializer controller via the deployment API.
You can configure what initializers are enabled and what resources are subject
to the initializers by creating
You should first deploy the initializer controller and make sure that it is
working properly before creating the
initializerConfiguration. Otherwise, any
newly created resources will be stuck in an uninitialized state.
The following is an example
apiVersion: admissionregistration.k8s.io/v1alpha1 kind: InitializerConfiguration metadata: name: example-config initializers: # the name needs to be fully qualified, i.e., containing at least two "." - name: podimage.example.com rules: # apiGroups, apiVersion, resources all support wildcard "*". # "*" cannot be mixed with non-wildcard. - apiGroups: - "" apiVersions: - v1 resources: - pods
After you create the
initializerConfiguration, the system will take a few
seconds to honor the new configuration. Then,
"podimage.example.com" will be
appended to the
metadata.initializers.pending field of newly created pods. You
should already have a ready “podimage” initializer controller that handles pods
the pods will be stuck in an uninitialized state.
Make sure that all expansions of the
<apiGroup, apiVersions, resources> tuple
rule are valid. If they are not, separate them in different