Try Kubernetes

Reference

Design docs, concept definitions, and references for APIs and CLIs.

Documentation for Kubernetes v1.9 is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

Edit This Page

Dynamic Admission Control

Overview

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

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 and MutatingAdmissionWebhooks. 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(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

Write an admission webhook server

Please refer to the implementation of the admission webhook server 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, 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.

Deploy the admission webhook service

The webhook server in the e2e test is deployed in the Kubernetes cluster, via the deployment API. The test also creates a service as the front-end of the webhook server. See code.

You may also deploy your webhooks outside of the cluster. You will need to update your webhook client configurations accordingly.

Configure admission webhooks on the fly

You can dynamically configure what resources are subject to what admission webhooks via ValidatingWebhookConfiguration or MutatingWebhookConifuration.

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>

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.

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.

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

What are initializers?

Initializer has two meanings:

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, ?includeUninitialized=true.

When to use initializers?

Initializers are useful for admins to force policies (e.g., the AlwaysPullImages admission controller), or to inject defaults (e.g., the DefaultStorageClass admission controller), etc.

Note: If your use case does not involve mutating objects, consider using external admission webhooks, as they have better performance.

How are initializers triggered?

When an object is POSTed, it is checked against all existing initializerConfiguration objects (explained below). For all that it matches, all spec.initializers[].names are appended to the new object’s metadata.initializers.pending field.

An initializer controller should list and watch for uninitialized objects, by using the query parameter ?includeUninitialized=true. If using client-go, just set listOptions.includeUninitialized to true.

For the observed uninitialized objects, an initializer controller should first check if its name matches metadata.initializers.pending[0]. If so, it should then perform its assigned task and remove its name from the list.

Enable initializers alpha feature

Initializers is an alpha feature, so it is disabled by default. To turn it on, you need to:

Deploy an initializer controller

You should deploy an initializer controller via the deployment API.

Configure initializers on the fly

You can configure what initializers are enabled and what resources are subject to the initializers by creating initializerConfiguration resources.

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 initializerConfiguration:

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 whose metadata.initializers.pending[0].name="podimage.example.com". Otherwise 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.

Analytics

Create an Issue Edit this Page