Skip to content

Commit 827c80f

Browse files
bergerhofferbergerhoffer
authored
Merge pull request #22019 from pneedle-rh/bz1701038-admission-controllers
BZ1701038 - Adding OpenShift 4 admission controller document.
2 parents ff9dba6 + 0a0027c commit 827c80f

8 files changed

+593
-0
lines changed

‎_topic_map.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,9 @@ Topics:
105105
- Name: The CI/CD methodology and practice
106106
File: cicd_gitops
107107
Distros: openshift-enterprise,openshift-webscale
108+
- Name: Admission plug-ins
109+
File: admission-plug-ins
110+
Distros: openshift-enterprise,openshift-webscale,openshift-aro
108111
---
109112
Name: Administering a cluster
110113
Dir: administering_a_cluster

‎architecture/admission-plug-ins.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
[id="admission-plug-ins"]
2+
= Admission plug-ins
3+
include::modules/common-attributes.adoc[]
4+
:context: admission-plug-ins
5+
toc::[]
6+
7+
// Concept modules
8+
include::modules/admission-plug-ins-about.adoc[leveloffset=+1]
9+
10+
include::modules/admission-plug-ins-default.adoc[leveloffset=+1]
11+
12+
include::modules/admission-webhooks-about.adoc[leveloffset=+1]
13+
14+
include::modules/admission-webhook-types.adoc[leveloffset=+1]
15+
16+
// Procedure module
17+
include::modules/configuring-dynamic-admission.adoc[leveloffset=+1]
18+
19+
[id="admission-plug-ins-additional-resources"]
20+
== Additional resources
21+
22+
* xref:../networking/hardware_networks/configuring-sriov-operator.adoc#configuring-sriov-operator[Limiting custom network resources managed by the SR-IOV network device plug-in]
23+
24+
* xref:../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations_dedicating_nodes-scheduler-taints-tolerations[Defining tolerations that enable taints to qualify which pods should be scheduled on a node]
25+
26+
* xref:../nodes/pods/nodes-pods-priority.adoc#admin-guide-priority-preemption-names_nodes-pods-priority[Pod priority class validation]

‎images/api-admission-chain.png‎

43.4 KB
Loading

‎modules/admission-plug-ins-about.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * architecture/admission-plug-ins.adoc
4+
5+
[id="admission-plug-ins-about_{context}"]
6+
= About admission plug-ins
7+
8+
Admission plug-ins are used to help regulate how {product-title} {product-version} functions. Admission plug-ins intercept requests to the master API to validate resource requests and ensure policies are adhered to, after the request is authenticated and authorized. For example, they are commonly used to enforce security policy, resource limitations or configuration requirements.
9+
10+
Admission plug-ins run in sequence as an admission chain. If any admission plug-in in the sequence rejects a request, the whole chain is aborted and an error is returned.
11+
12+
{product-title} has a default set of admission plug-ins enabled for each resource type. These are required for proper functioning of the cluster. Admission plug-ins ignore resources that they are not responsible for.
13+
14+
In addition to the defaults, the admission chain can be extended dynamically through webhook admission plug-ins that call out to custom webhook servers. There are two types of webhook admission plug-ins: a mutating admission plug-in and a validating admission plug-in. The mutating admission plug-in runs first and can both modify resources and validate requests. The validating admission plug-in validates requests and runs after the mutating admission plug-in so that modifications triggered by the mutating admission plug-in can also be validated.
15+
16+
Calling webhook servers through a mutating admission plug-in can produce side effects on resources related to the target object. In such situations, you must take steps to validate that the end result is as expected.
17+
18+
[WARNING]
19+
====
20+
Dynamic admission should be used cautiously because it impacts cluster control plane operations. When calling webhook servers through webhook admission plug-ins in {product-title} {product-version}, ensure that you have read the documentation fully and tested for side effects of mutations. Include steps to restore resources back to their original state prior to mutation, in the event that a request does not pass through the entire admission chain.
21+
====

‎modules/admission-plug-ins-default.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * architecture/admission-plug-ins.adoc
4+
5+
[id="admission-plug-ins-default_{context}"]
6+
= Default admission plug-ins
7+
8+
//Future xref - A set of default admission plug-ins is enabled in {product-title} {product-version}. These default plug-ins contribute to fundamental control plane functionality, such as ingress policy, xref:../nodes/clusters/nodes-cluster-overcommit.adoc#nodes-cluster-resource-override_nodes-cluster-overcommit[cluster resource limit override] and quota policy.
9+
A set of default admission plug-ins is enabled in {product-title} {product-version}. These default plug-ins contribute to fundamental control plane functionality, such as ingress policy, cluster resource limit override and quota policy.

‎modules/admission-webhook-types.adoc‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * architecture/admission-plug-ins.adoc
4+
5+
[id="admission-webhook-types_{context}"]
6+
= Types of webhook admission plug-ins
7+
8+
Cluster administrators can call out to webhook servers through the mutating admission plug-in or the validating admission plug-in in the API server admission chain.
9+
10+
[id="mutating-admission-plug-in_{context}"]
11+
== Mutating admission plug-in
12+
13+
The mutating admission plug-in is invoked during the mutation phase of the admission process, which allows modification of resource content before it is persisted. One example webhook that can be called through the mutating admission plug-in is the Pod Node Selector feature, which uses an annotation on a namespace to find a label selector and add it to the pod specification.
14+
15+
[id="mutating-admission-plug-in-config_{context}"]
16+
.Sample mutating admission plug-in configuration
17+
18+
[source,yaml]
19+
----
20+
apiVersion: admissionregistration.k8s.io/v1beta1
21+
kind: MutatingWebhookConfiguration <1>
22+
metadata:
23+
name: <webhook_name> <2>
24+
webhooks:
25+
- name: <webhook_name> <3>
26+
clientConfig: <4>
27+
service:
28+
namespace: default <5>
29+
name: kubernetes <6>
30+
path: <webhook_url> <7>
31+
caBundle: <ca_signing_certificate> <8>
32+
rules: <9>
33+
- operations: <10>
34+
- <operation>
35+
apiGroups:
36+
- ""
37+
apiVersions:
38+
- "*"
39+
resources:
40+
- <resource>
41+
failurePolicy: <policy> <11>
42+
sideEffects: None
43+
----
44+
45+
<1> Specifies a mutating admission plug-in configuration.
46+
<2> The name for the webhook object. Replace `<webhook_name>` with the appropriate value.
47+
<3> The name of the webhook to call. Replace `<webhook_name>` with the appropriate value.
48+
<4> Information about how to connect to, trust, and send data to the webhook server.
49+
<5> The namespace where the front-end service is created.
50+
<6> The name of the front-end service.
51+
<7> The webhook URL used for admission requests. Replace `<webhook_url>` with the appropriate value.
52+
<8> A PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace `<ca_signing_certificate>` with the appropriate certificate in base64 format.
53+
<9> Rules that define when the API server should use this webhook admission plug-in.
54+
<10> One or more operations that trigger the API server to call this webhook admission plug-in. Possible values are `create`, `update`, `delete` or `connect`. Replace `<operation>` and `<resource>` with the appropriate values.
55+
<11> Specifies how the policy should proceed if the webhook server is unavailable.
56+
Replace `<policy>` with either `Ignore` (to unconditionally accept the request in the event of a failure) or `Fail` (to deny the failed request). Using `Ignore` can result in unpredictable behavior for all clients.
57+
58+
[IMPORTANT]
59+
====
60+
In {product-title} {product-version}, objects created by users or control loops through a mutating admission plug-in might return unexpected results, especially if values set in an initial request are overwritten, which is not recommended.
61+
====
62+
63+
[id="validating-admission-plug-in_{context}"]
64+
== Validating admission plug-in
65+
66+
A validating admission plug-in is invoked during the validation phase of the admission process. This phase allows the enforcement of invariants on particular API resources to ensure that the resource does not change again. The Pod Node Selector is also an example of a webhook which is called by the validating admission plug-in, to ensure that all `nodeSelector` fields are constrained by the node selector restrictions on the namespace.
67+
68+
[id="validating-admission-plug-in-config_{context}"]
69+
//http://blog.kubernetes.io/2018/01/extensible-admission-is-beta.html
70+
.Sample validating admission plug-in configuration
71+
72+
[source,yaml]
73+
----
74+
apiVersion: admissionregistration.k8s.io/v1beta1
75+
kind: ValidatingWebhookConfiguration <1>
76+
metadata:
77+
name: <webhook_name> <2>
78+
webhooks:
79+
- name: <webhook_name> <3>
80+
clientConfig: <4>
81+
service:
82+
namespace: default <5>
83+
name: kubernetes <6>
84+
path: <webhook_url> <7>
85+
caBundle: <ca_signing_certificate> <8>
86+
rules: <9>
87+
- operations: <10>
88+
- <operation>
89+
apiGroups:
90+
- ""
91+
apiVersions:
92+
- "*"
93+
resources:
94+
- <resource>
95+
failurePolicy: <policy> <11>
96+
sideEffects: Unknown
97+
----
98+
99+
<1> Specifies a validating admission plug-in configuration.
100+
<2> The name for the webhook object. Replace `<webhook_name>` with the appropriate value.
101+
<3> The name of the webhook to call. Replace `<webhook_name>` with the appropriate value.
102+
<4> Information about how to connect to, trust, and send data to the webhook server.
103+
<5> The namespace where the front-end service is created.
104+
<6> The name of the front-end service.
105+
<7> The webhook URL used for admission requests. Replace `<webhook_url>` with the appropriate value.
106+
<8> A PEM-encoded CA certificate that signs the server certificate that is used by the webhook server. Replace `<ca_signing_certificate>` with the appropriate certificate in base64 format.
107+
<9> Rules that define when the API server should use this webhook admission plug-in.
108+
<10> One or more operations that trigger the API server to call this webhook admission plug-in. Possible values are `create`, `update`, `delete` or `connect`. Replace `<operation>` and `<resource>` with the appropriate values.
109+
<11> Specifies how the policy should proceed if the webhook server is unavailable.
110+
Replace `<policy>` with either `Ignore` (to unconditionally accept the request in the event of a failure) or `Fail` (to deny the failed request). Using `Ignore` can result in unpredictable behavior for all clients.

‎modules/admission-webhooks-about.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * architecture/admission-plug-ins.adoc
4+
5+
[id="admission-webhooks-about_{context}"]
6+
= Webhook admission plug-ins
7+
8+
In addition to {product-title} default admission plug-ins, dynamic admission can be implemented through webhook admission plug-ins that call webhook servers, in order to extend the functionality of the admission chain. Webhook servers are called over HTTP at defined endpoints.
9+
10+
There are two types of webhook admission plug-ins in {product-title}:
11+
12+
//Future xref - * During the admission process, xref:../architecture/admission-plug-ins.adoc#mutating-admission-plug-in[the mutating admission plug-in] can perform tasks, such as injecting affinity labels.
13+
* During the admission process, the _mutating admission plug-in_ can perform tasks, such as injecting affinity labels.
14+
15+
//Future xref - * At the end of the admission process, xref:../architecture/admission-plug-ins.adoc#validating-admission-plug-in[the validating admission plug-in] makes sure an object is configured properly, for example ensuring affinity labels are as expected. If the validation passes, {product-title} schedules the object as configured.
16+
* At the end of the admission process, the _validating admission plug-in_ can be used to make sure an object is configured properly, for example ensuring affinity labels are as expected. If the validation passes, {product-title} schedules the object as configured.
17+
18+
When an API request comes in, mutating or validating admission plug-ins use the list of external webhooks in the configuration and call them in parallel:
19+
20+
* If all of the webhooks approve the request, the admission chain continues.
21+
22+
* If any of the webhooks deny the request, the admission request is denied and the reason for doing so is based on the first denial.
23+
24+
* If more than one webhook denies the admission request, only the first denial reason is returned to the user.
25+
26+
* If an error is encountered when calling a webhook, the request is either denied or the webhook is ignored depending on the error policy set. If the error policy is set to `Ignore`, the request is unconditionally accepted in the event of a failure. If the policy is set to `Fail`, failed requests are denied. Using `Ignore` can result in unpredictable behavior for all clients.
27+
28+
//Future xrefs - Communication between the webhook admission plug-in and the webhook server must use TLS. Generate a certificate authority (CA) certificate and use the certificate to sign the server certificate that is used by your webhook server. The PEM-encoded CA certificate is supplied to the webhook admission plug-in using a mechanism, such as xref:../authentication/certificates/service-serving-certificate.adoc#service-serving-certificate[service serving certificate secrets].
29+
Communication between the webhook admission plug-in and the webhook server must use TLS. Generate a CA certificate and use the certificate to sign the server certificate that is used by your webhook admission server. The PEM-encoded CA certificate is supplied to the webhook admission plug-in using a mechanism, such as service serving certificate secrets.
30+
31+
The following diagram illustrates the sequential admission chain process within which multiple webhook servers are called.
32+
33+
.API admission chain with mutating and validating admission plug-ins
34+
image::api-admission-chain.png["API admission stage", align="center"]
35+
36+
An example webhook admission plug-in use case is where all pods must have a common set of labels. In this example, the mutating admission plug-in can inject labels and the validating admission plug-in can check that labels are as expected. {product-title} would subsequently schedule pods that include required labels and reject those that do not.
37+
38+
Some common webhook admission plug-in use cases include:
39+
40+
//Future xref - * Namespace reservation.
41+
* Namespace reservation.
42+
//Future xrefs - * xref:../networking/hardware_networks/configuring-sriov-operator.adoc#configuring-sriov-operator[Limiting custom network resources managed by the SR-IOV network device plug-in].
43+
* Limiting custom network resources managed by the SR-IOV network device plug-in.
44+
//Future xref - * xref:../nodes/scheduling/nodes-scheduler-taints-tolerations.adoc#nodes-scheduler-taints-tolerations_dedicating_nodes-scheduler-taints-tolerations[Defining tolerations that enable taints to qualify which pods should be scheduled on a node].
45+
* Defining tolerations that enable taints to qualify which pods should be scheduled on a node.
46+
//Future xref - * xref:../nodes/pods/nodes-pods-priority.adoc#admin-guide-priority-preemption-names_nodes-pods-priority[Pod priority class validation].
47+
* Pod priority class validation.

0 commit comments

Comments
 (0)