Skip to main content

Central Admission Control


Pro Feature

This feature is available in the vCluster Pro tier. Contact us for more details and to start a trial.

important

You must enable MutatingAdmissionWebhook and ValidatingAdmissionWebhook admission controllers to use the Central Admission Control feature. See the Kubernetes Admission Controllers Reference for details.

Centralized Admission Control is an advanced feature for cluster admins that have custom rules that they need to apply to the virtual cluster. Cluster admins can enforce Kubernetes admission webhooks that reference the host cluster or external policy services from within the virtual cluster. Examples of validating and mutating webhook based policy engines include OPA, Kyverno, and jsPolicy.

warning
  • Central Admission Control is read-only after virtual cluster creation. Admins cannot bypass or alter hooks after vCluster deployment.
  • If you need the ability to modify or delete webhook configurations, do not use Central Admission Control. Instead, manually map the host policy service into the virtual cluster.

Central admission webhooks are different from the other policies:

  • LimitRange and ResourceQuota resources are created and enforced on the host cluster. They do do not appear as resources in the virtual cluster.
  • A user could define LimitRange and ResourceQuota resources inside the virtual cluster, but they have full control over them and can delete them at will.
  • Webhooks are different because they need to be configured inside the virtual cluster in order for them to be called by the vCluster's API server.
  • vCluster rewrites these definitions to point to a proxy for a host cluster service that handles webhook requests. The host may also have webhook configurations that use this service.
  • A user can still install a webhook service or webhook configuration into the virtual cluster outside of this config, but it would run inside the virtual cluster like any other workload.

Example​

This example ensures that all new ConfigMap resources are sent to a mutating webhook on the host cluster.

centralAdmission:
  mutatingWebhooks:
    - apiVersion: admissionregistration.k8s.io/v1
      kind: MutatingWebhookConfiguration
      metadata:
        labels:
          webhook.kyverno.io/managed-by: kyverno
        name: kyverno-resource-mutating-webhook-cfg
      webhooks:
      - admissionReviewVersions:
        - v1
        clientConfig:
          service:
            name: kyverno-svc
            namespace: kyverno
            path: /mutate/fail
            port: 443
        failurePolicy: Fail
        matchPolicy: Equivalent
        name: mutate.kyverno.svc-fail
        namespaceSelector:
          matchExpressions:
          - key: kubernetes.io/metadata.name
            operator: NotIn
            values:
            - kyverno
        objectSelector: {}
        reinvocationPolicy: IfNeeded
        rules:
        - apiGroups:
          - ""
          apiVersions:
          - v1
          operations:
          - CREATE
          resources:
          - configmaps
          scope: '*'
        sideEffects: NoneOnDryRun
        timeoutSeconds: 10

Any time a ConfigMap is created, the vCluster API server forwards the admission request to a proxy, which in turn calls the actual admission hook running in the host cluster in the kyverno namespace.

Note that the service providing the webhooks should not rely on the real names of the objects if they are synced on the host cluster (for example, pods). The requests that will reach the host admission service holds the objects from the virtual cluster, so your policies need to be able to handle those objects.

The hook services do not require authentication as the proxy does not have access to the AdmissionConfiguration object or the files it references. Most policy engines (like jsPolicy, Kyverno, or Gatekeeper) do not set authentication by default, so it should work with most installations.

If a user inside the virtual cluster (admin or not) tries to delete one of your admission hooks, that uses is prompted with the following error message:

kubectl delete kyverno-resource-mutating-webhook-cfg
error: the resource kyverno-resource-mutating-webhook-cfg is protected

Config reference​

centralAdmission required object pro​

CentralAdmission defines what validating or mutating webhooks should be enforced within the virtual cluster.

validatingWebhooks required object[] pro​

ValidatingWebhooks are validating webhooks that should be enforced in the virtual cluster

kind required string pro​

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to.

apiVersion required string pro​

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values.

metadata required object pro​

Standard object metadata; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata.

name required string pro​

Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition.

labels required object pro​

Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services.

annotations required object pro​

Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.

webhooks required object[] pro​

Webhooks is a list of webhooks and the affected resources and operations.

name required string pro​

The name of the admission webhook. Name should be fully qualified, e.g., imagepolicy.kubernetes.io, where "imagepolicy" is the name of the webhook, and kubernetes.io is the name of the organization.

clientConfig required object pro​

ClientConfig defines how to communicate with the hook.

url required string pro​

URL gives the location of the webhook, in standard URL form (scheme://host:port/path). Exactly one of url or service must be specified.

service required object pro​

Service is a reference to the service for this webhook. Either service or url must be specified.

If the webhook is running within the cluster, then you should use service.

namespace required string pro​

Namespace is the namespace of the service.

name required string pro​

Name is the name of the service.

path required string pro​

Path is an optional URL path which will be sent in any request to this service.

port required integer pro​

If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. port should be a valid port number (1-65535, inclusive).

caBundle required string pro​

CABundle is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used.

rules required object[] pro​

Rules describes what operations on what resources/subresources the webhook cares about. The webhook cares about an operation if it matches any Rule.

failurePolicy required string pro​

FailurePolicy defines how unrecognized errors from the admission endpoint are handled - allowed values are Ignore or Fail. Defaults to Fail.

matchPolicy required string pro​

matchPolicy defines how the "rules" list is used to match incoming requests. Allowed values are "Exact" or "Equivalent".

namespaceSelector required object pro​

NamespaceSelector decides whether to run the webhook on an object based on whether the namespace for that object matches the selector. If the object itself is a namespace, the matching is performed on object.metadata.labels. If the object is another cluster scoped resource, it never skips the webhook.

objectSelector required object pro​

ObjectSelector decides whether to run the webhook based on if the object has matching labels. objectSelector is evaluated against both the oldObject and newObject that would be sent to the webhook, and is considered to match if either object matches the selector.

sideEffects required string pro​

SideEffects states whether this webhook has side effects.

timeoutSeconds required integer pro​

TimeoutSeconds specifies the timeout for this webhook.

admissionReviewVersions required string[] pro​

AdmissionReviewVersions is an ordered list of preferred AdmissionReview versions the Webhook expects.

matchConditions required object[] pro​

MatchConditions is a list of conditions that must be met for a request to be sent to this webhook. Match conditions filter requests that have already been matched by the rules, namespaceSelector, and objectSelector. An empty list of matchConditions matches all requests. There are a maximum of 64 match conditions allowed.

mutatingWebhooks required object[] pro​

MutatingWebhooks are mutating webhooks that should be enforced in the virtual cluster

kind required string pro​

Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to.

apiVersion required string pro​

APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values.

metadata required object pro​

Standard object metadata; More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata.

name required string pro​

Name must be unique within a namespace. Is required when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is primarily intended for creation idempotence and configuration definition.

labels required object pro​

Map of string keys and values that can be used to organize and categorize (scope and select) objects. May match selectors of replication controllers and services.

annotations required object pro​

Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.

webhooks required object[] pro​

Webhooks is a list of webhooks and the affected resources and operations.

reinvocationPolicy required string pro​

reinvocationPolicy indicates whether this webhook should be called multiple times as part of a single admission evaluation. Allowed values are "Never" and "IfNeeded".

name required string pro​

The name of the admission webhook. Name should be fully qualified, e.g., imagepolicy.kubernetes.io, where "imagepolicy" is the name of the webhook, and kubernetes.io is the name of the organization.

clientConfig required object pro​

ClientConfig defines how to communicate with the hook.

url required string pro​

URL gives the location of the webhook, in standard URL form (scheme://host:port/path). Exactly one of url or service must be specified.

service required object pro​

Service is a reference to the service for this webhook. Either service or url must be specified.

If the webhook is running within the cluster, then you should use service.

namespace required string pro​

Namespace is the namespace of the service.

name required string pro​

Name is the name of the service.

path required string pro​

Path is an optional URL path which will be sent in any request to this service.

port required integer pro​

If specified, the port on the service that hosting webhook. Default to 443 for backward compatibility. port should be a valid port number (1-65535, inclusive).

caBundle required string pro​

CABundle is a PEM encoded CA bundle which will be used to validate the webhook's server certificate. If unspecified, system trust roots on the apiserver are used.

rules required object[] pro​

Rules describes what operations on what resources/subresources the webhook cares about. The webhook cares about an operation if it matches any Rule.

failurePolicy required string pro​

FailurePolicy defines how unrecognized errors from the admission endpoint are handled - allowed values are Ignore or Fail. Defaults to Fail.

matchPolicy required string pro​

matchPolicy defines how the "rules" list is used to match incoming requests. Allowed values are "Exact" or "Equivalent".

namespaceSelector required object pro​

NamespaceSelector decides whether to run the webhook on an object based on whether the namespace for that object matches the selector. If the object itself is a namespace, the matching is performed on object.metadata.labels. If the object is another cluster scoped resource, it never skips the webhook.

objectSelector required object pro​

ObjectSelector decides whether to run the webhook based on if the object has matching labels. objectSelector is evaluated against both the oldObject and newObject that would be sent to the webhook, and is considered to match if either object matches the selector.

sideEffects required string pro​

SideEffects states whether this webhook has side effects.

timeoutSeconds required integer pro​

TimeoutSeconds specifies the timeout for this webhook.

admissionReviewVersions required string[] pro​

AdmissionReviewVersions is an ordered list of preferred AdmissionReview versions the Webhook expects.

matchConditions required object[] pro​

MatchConditions is a list of conditions that must be met for a request to be sent to this webhook. Match conditions filter requests that have already been matched by the rules, namespaceSelector, and objectSelector. An empty list of matchConditions matches all requests. There are a maximum of 64 match conditions allowed.