From d634fb7f042cd9dcefcd46e5b07bf0dabb677b04 Mon Sep 17 00:00:00 2001 From: aburdenthehand Date: Fri, 9 Mar 2018 06:00:57 +1000 Subject: [PATCH] Flag names changed (s/admission-control/enable-admission-plugins); disable-admissions-plugin entry added; removed reference to admission controller/plugins requiring set order (for v1.10), redundant example enabling specific plugin, and redundant version-specific info (#7449) --- docs/admin/admission-controllers.md | 35 +++++++++---------- docs/admin/authorization/node.md | 2 +- .../admin/extensible-admission-controllers.md | 8 ++--- .../high-availability/kube-apiserver.yaml | 2 +- .../configuration/pod-priority-preemption.md | 2 +- docs/concepts/policy/resource-quotas.md | 4 +-- docs/concepts/storage/persistent-volumes.md | 2 +- docs/concepts/workloads/pods/podpreset.md | 2 +- .../coreos/cloud-configs/master.yaml | 2 +- docs/getting-started-guides/scratch.md | 2 +- .../kubeadm/implementation-details.md | 2 +- .../running-cloud-controller.md | 2 +- .../set-up-placement-policies-federation.md | 4 +-- docs/tutorials/clusters/apparmor.md | 2 +- 14 files changed, 35 insertions(+), 36 deletions(-) diff --git a/docs/admin/admission-controllers.md b/docs/admin/admission-controllers.md index 7ef88633f07f2..13eee5b052c17 100644 --- a/docs/admin/admission-controllers.md +++ b/docs/admin/admission-controllers.md @@ -31,8 +31,7 @@ controllers may modify the objects they admit; validating controllers may not. The admission control process proceeds in two phases. In the first phase, mutating admission controllers are run. In the second phase, validating admission controllers are run. Note again that some of the controllers are -both. In both phases, the controllers are run in the order specified by the -`--admission-control` flag of `kube-apiserver`. +both. If any of the controllers in either phase reject the request, the entire request is rejected immediately and an error is returned to the end-user. @@ -54,13 +53,12 @@ support all the features you expect. ## How do I turn on an admission controller? -The Kubernetes API server supports a flag, `admission-control` that takes a comma-delimited, -ordered list of admission control choices to invoke prior to modifying objects in the cluster. -For example, the following command line turns on the `NamespaceLifecycle` and the `LimitRanger` -admission controller: +The Kubernetes API server flag `enable-admission-plugins` takes a comma-delimited list of admission control plugins to invoke prior to modifying objects in the cluster. +For example, the following command line enables the `NamespaceLifecycle` and the `LimitRanger` +admission control plugins: ```shell -kube-apiserver --admission-control=NamespaceLifecyle,LimitRanger ... +kube-apiserver --enable-admission-plugins=NamespaceLifecyle,LimitRanger ... ``` **Note**: Depending on the way your Kubernetes cluster is deployed and how the @@ -70,6 +68,14 @@ deployed as a systemd service, you may modify the manifest file for the API server if Kubernetes is deployed in a self-hosted way. {: .note} +## How do I turn off an admission controller? + +The Kubernetes API server flag `disable-admission-plugins` takes a comma-delimited list of admission control plugins to be disabled, even if they are in the list of plugins enabled by default. + +```shell +kube-apiserver --disable-admission-plugins=PodNodeSelector,AlwaysDeny ... +``` + ## What does each admission controller do? ### AlwaysAdmit (DEPRECATED) @@ -134,7 +140,7 @@ enabling this admission controller. ### EventRateLimit (alpha) -This admission controller is introduced in v1.9 to mitigate the problem where the API server gets flooded by +This admission controller mitigates the problem where the API server gets flooded by event requests. The cluster admin can specify event rate limits by: * Ensuring that `eventratelimit.admission.k8s.io/v1alpha1=true` is included in the @@ -180,7 +186,7 @@ for more details. ### ExtendedResourceToleration -This plug-in is introduced in v1.9 to facilitate creation of dedicated nodes with extended resources. +This plug-in facilitates creation of dedicated nodes with extended resources. If operators want to create dedicated nodes with extended resources (like GPUs, FPGAs etc.), they are expected to taint the node with the extended resource name as the key. This admission controller, if enabled, automatically adds tolerations for such taints to pods requesting extended resources, so users don't have to manually @@ -188,11 +194,7 @@ add these tolerations. ### ImagePolicyWebhook -The ImagePolicyWebhook admission controller allows a backend webhook to make admission decisions. You enable this admission controller by setting the admission-control option as follows: - -```shell ---admission-control=ImagePolicyWebhook -``` +The ImagePolicyWebhook admission controller allows a backend webhook to make admission decisions. #### Configuration File Format @@ -314,7 +316,6 @@ In any case, the annotations are provided by the user and are not validated by K ### Initializers (alpha) -This admission controller is introduced in v1.7. The admission controller determines the initializers of a resource based on the existing `InitializerConfiguration`s. It sets the pending initializers by modifying the metadata of the resource to be created. @@ -554,8 +555,6 @@ objects in your Kubernetes deployment, you MUST use this admission controller to See the [resourceQuota design doc](https://git.k8s.io/community/contributors/design-proposals/resource-management/admission_control_resource_quota.md) and the [example of Resource Quota](/docs/concepts/policy/resource-quotas/) for more details. -It is strongly encouraged that this admission controller is configured last in the sequence of admission controllers. This is -so that quota is not prematurely incremented only for the request to be rejected later in admission control. ### SecurityContextDeny @@ -590,7 +589,7 @@ versions >= 1.9). ## Is there a recommended set of admission controllers to use? Yes. -For Kubernetes >= 1.9.0, we strongly recommend running the following set of admission controllers (order matters): +For Kubernetes >= 1.9.0, we strongly recommend running the following set of admission controllers (order matters for 1.9 but not >1.10): ```shell --admission-control=NamespaceLifecycle,LimitRanger,ServiceAccount,PersistentVolumeLabel,DefaultStorageClass,DefaultTolerationSeconds,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota diff --git a/docs/admin/authorization/node.md b/docs/admin/authorization/node.md index 1bc07d600e0a3..00c848928abba 100644 --- a/docs/admin/authorization/node.md +++ b/docs/admin/authorization/node.md @@ -45,7 +45,7 @@ This group and user name format match the identity created for each kubelet as p To enable the Node authorizer, start the apiserver with `--authorization-mode=Node`. -To limit the API objects kubelets are able to write, enable the [NodeRestriction](/docs/admin/admission-controllers#NodeRestriction) admission plugin by starting the apiserver with `--admission-control=...,NodeRestriction,...` +To limit the API objects kubelets are able to write, enable the [NodeRestriction](/docs/admin/admission-controllers#NodeRestriction) admission plugin by starting the apiserver with `--enable-admission-plugins=...,NodeRestriction,...` ## Migration considerations diff --git a/docs/admin/extensible-admission-controllers.md b/docs/admin/extensible-admission-controllers.md index 7e67c2d252c71..d1d8595d2c392 100644 --- a/docs/admin/extensible-admission-controllers.md +++ b/docs/admin/extensible-admission-controllers.md @@ -20,7 +20,7 @@ the following: * They need to be compiled into kube-apiserver. * They are only configurable when the apiserver starts up. -1.7 introduces two alpha features, *Initializers* and *External Admission +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. @@ -81,7 +81,7 @@ 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 `--admission-control` flag when starting +* 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. @@ -184,7 +184,7 @@ admission request. *External Admission Webhooks* is an alpha feature, so it is disabled by default. To turn it on, you need to -* Include "GenericAdmissionWebhook" in the `--admission-control` flag when +* Include "GenericAdmissionWebhook" in the `--enable-admission-plugins` flag when starting the apiserver. If you have multiple `kube-apiserver` replicas, all should have the same flag setting. @@ -278,7 +278,7 @@ differences: Make sure that all expansions of the `` tuple in a `rule` are valid. If they are not, separate them to different `rules`. -You can also specify the `failurePolicy`. In 1.7, the system supports `Ignore` +You can also specify the `failurePolicy`. As of 1.7, the system supports `Ignore` and `Fail` policies, meaning that upon a communication error with the webhook admission controller, the `GenericAdmissionWebhook` can admit or reject the operation based on the configured policy. diff --git a/docs/admin/high-availability/kube-apiserver.yaml b/docs/admin/high-availability/kube-apiserver.yaml index 057764fc529af..af5b1812e8b45 100644 --- a/docs/admin/high-availability/kube-apiserver.yaml +++ b/docs/admin/high-availability/kube-apiserver.yaml @@ -11,7 +11,7 @@ spec: - /bin/sh - -c - /usr/local/bin/kube-apiserver --address=127.0.0.1 --etcd-servers=http://127.0.0.1:4001 - --cloud-provider=gce --admission-control=NamespaceLifecycle,LimitRanger,SecurityContextDeny,ServiceAccount,ResourceQuota + --cloud-provider=gce --enable-admission-plugins=NamespaceLifecycle,LimitRanger,SecurityContextDeny,ServiceAccount,ResourceQuota --service-cluster-ip-range=10.0.0.0/16 --client-ca-file=/srv/kubernetes/ca.crt --basic-auth-file=/srv/kubernetes/basic_auth.csv --cluster-name=e2e-test-bburns --tls-cert-file=/srv/kubernetes/server.cert --tls-private-key-file=/srv/kubernetes/server.key diff --git a/docs/concepts/configuration/pod-priority-preemption.md b/docs/concepts/configuration/pod-priority-preemption.md index f4292eee1940f..72d67ac2a5268 100644 --- a/docs/concepts/configuration/pod-priority-preemption.md +++ b/docs/concepts/configuration/pod-priority-preemption.md @@ -45,7 +45,7 @@ Also enable scheduling.k8s.io/v1alpha1 API and Priority [admission controller](/ ``` ---runtime-config=scheduling.k8s.io/v1alpha1=true --admission-control=Controller-Foo,Controller-Bar,...,Priority +--runtime-config=scheduling.k8s.io/v1alpha1=true --enable-admission-plugins=Controller-Foo,Controller-Bar,...,Priority ``` After the feature is enabled, you can create [PriorityClasses](#priorityclass) diff --git a/docs/concepts/policy/resource-quotas.md b/docs/concepts/policy/resource-quotas.md index e44091700c7c6..67e8ea0521e04 100644 --- a/docs/concepts/policy/resource-quotas.md +++ b/docs/concepts/policy/resource-quotas.md @@ -42,8 +42,8 @@ Neither contention nor changes to quota will affect already created resources. ## Enabling Resource Quota -Resource quota support is enabled by default for many Kubernetes distributions. It is -enabled when the apiserver `--admission-control=` flag has `ResourceQuota` as +Resource Quota support is enabled by default for many Kubernetes distributions. It is +enabled when the apiserver `--enable-admission-plugins=` flag has `ResourceQuota` as one of its arguments. A resource quota is enforced in a particular namespace when there is a diff --git a/docs/concepts/storage/persistent-volumes.md b/docs/concepts/storage/persistent-volumes.md index 4afdeedd72637..7a0e88796473e 100644 --- a/docs/concepts/storage/persistent-volumes.md +++ b/docs/concepts/storage/persistent-volumes.md @@ -54,7 +54,7 @@ dynamic provisioning for themselves. To enable dynamic storage provisioning based on storage class, the cluster administrator needs to enable the `DefaultStorageClass` [admission controller](/docs/admin/admission-controllers/#defaultstorageclass) on the API server. This can be done, for example, by ensuring that `DefaultStorageClass` is -among the comma-delimited, ordered list of values for the `--admission-control` flag of +among the comma-delimited, ordered list of values for the `--enable-admission-plugins` flag of the API server component. For more information on API server command line flags, please check [kube-apiserver](/docs/admin/kube-apiserver/) documentation. diff --git a/docs/concepts/workloads/pods/podpreset.md b/docs/concepts/workloads/pods/podpreset.md index 0152e8a566810..7863d61be5ff5 100644 --- a/docs/concepts/workloads/pods/podpreset.md +++ b/docs/concepts/workloads/pods/podpreset.md @@ -68,7 +68,7 @@ In order to use Pod Presets in your cluster you must ensure the following: example, this can be done by including `settings.k8s.io/v1alpha1=true` in the `--runtime-config` option for the API server. 1. You have enabled the admission controller `PodPreset`. One way to doing this - is to include `PodPreset` in the `--admission-control` option value specified + is to include `PodPreset` in the `--enable-admission-plugins` option value specified for the API server. 1. You have defined your Pod Presets by creating `PodPreset` objects in the namespace you will use. diff --git a/docs/getting-started-guides/coreos/cloud-configs/master.yaml b/docs/getting-started-guides/coreos/cloud-configs/master.yaml index 768e91ab40cc8..5b7df1bd77d70 100644 --- a/docs/getting-started-guides/coreos/cloud-configs/master.yaml +++ b/docs/getting-started-guides/coreos/cloud-configs/master.yaml @@ -91,7 +91,7 @@ coreos: ExecStart=/opt/bin/kube-apiserver \ --service-account-key-file=/opt/bin/kube-serviceaccount.key \ --service-account-lookup=false \ - --admission-control=NamespaceLifecycle,LimitRanger,SecurityContextDeny,ServiceAccount,ResourceQuota \ + --enable-admission-plugins=NamespaceLifecycle,LimitRanger,SecurityContextDeny,ServiceAccount,ResourceQuota \ --runtime-config=api/v1 \ --allow-privileged=true \ --insecure-bind-address=0.0.0.0 \ diff --git a/docs/getting-started-guides/scratch.md b/docs/getting-started-guides/scratch.md index b9b733c4b8f71..b0d6bfaef53d6 100644 --- a/docs/getting-started-guides/scratch.md +++ b/docs/getting-started-guides/scratch.md @@ -607,7 +607,7 @@ Here are some apiserver flags you may need to set: - `--etcd-servers=http://127.0.0.1:4001` - `--tls-cert-file=/srv/kubernetes/server.cert` - `--tls-private-key-file=/srv/kubernetes/server.key` -- `--admission-control=$RECOMMENDED_LIST` +- `--enable-admission-plugins=$RECOMMENDED_LIST` - See [admission controllers](/docs/admin/admission-controllers/) for recommended arguments. - `--allow-privileged=true`, only if you trust your cluster user to run pods as root. diff --git a/docs/reference/setup-tools/kubeadm/implementation-details.md b/docs/reference/setup-tools/kubeadm/implementation-details.md index 834a5e7266462..b7219b98e22b9 100644 --- a/docs/reference/setup-tools/kubeadm/implementation-details.md +++ b/docs/reference/setup-tools/kubeadm/implementation-details.md @@ -233,7 +233,7 @@ Other API server flags that are set unconditionally are: - `--enable-bootstrap-token-auth=true` to enable the `BootstrapTokenAuthenticator` authentication module. see [TLS Bootstrapping](/docs/admin/kubelet-tls-bootstrapping.md) for more details - `--allow-privileged` to `true` (required e.g. by kube proxy) - `--requestheader-client-ca-file` to `front-proxy-ca.crt` - - `--admission-control` to: + - `--enable-admission-plugins` to: - [`Initializers`](/docs/admin/admission-controllers/#initializers-alpha) to enable [Dynamic Admission Control](/docs/admin/extensible-admission-controllers/). - [`NamespaceLifecycle`](/docs/admin/admission-controllers/#namespacelifecycle) e.g. to avoid deletion of system reserved namespaces diff --git a/docs/tasks/administer-cluster/running-cloud-controller.md b/docs/tasks/administer-cluster/running-cloud-controller.md index 7fdb2a9433384..fe5ba70ac9cf2 100644 --- a/docs/tasks/administer-cluster/running-cloud-controller.md +++ b/docs/tasks/administer-cluster/running-cloud-controller.md @@ -33,7 +33,7 @@ Successfully running cloud-controller-manager requires some changes to your clus * `kube-apiserver` and `kube-controller-manager` MUST NOT specify the `--cloud-provider` flag. This ensures that it does not run any cloud specific loops that would be run by cloud controller manager. In the future, this flag will be deprecated and removed. * `kubelet` must run with `--cloud-provider=external`. This is to ensure that the kubelet is aware that it must be initialized by the cloud controller manager before it is scheduled any work. -* `kube-apiserver` SHOULD NOT run the `PersistentVolumeLabel` admission controller since the cloud controller manager takes over labeling persistent volumes. To prevent the PersistentVolumeLabel admission plugin from running, make sure the `kube-apiserver` has a `--admission-control` flag with a value that does not include `PersistentVolumeLabel`. +* `kube-apiserver` SHOULD NOT run the `PersistentVolumeLabel` admission controller since the cloud controller manager takes over labeling persistent volumes. To prevent the PersistentVolumeLabel admission plugin from running in `kube-apiserver`, include the `PersistentVolumeLabel` as a listed value in the `--disable-admission-plugins` flag. * For the `cloud-controller-manager` to label persistent volumes, initializers will need to be enabled and an InitializerConifguration needs to be added to the system. Follow [these instructions](/docs/admin/extensible-admission-controllers.md#enable-initializers-alpha-feature) to enable initializers. Use the following YAML to create the InitializerConfiguration: {% include code.html language="yaml" file="persistent-volume-label-initializer-config.yaml" ghlink="/docs/tasks/administer-cluster/persistent-volume-label-initializer-config.yaml" %} diff --git a/docs/tasks/federation/set-up-placement-policies-federation.md b/docs/tasks/federation/set-up-placement-policies-federation.md index 99a18b67573b1..a86f6bffaa7f5 100644 --- a/docs/tasks/federation/set-up-placement-policies-federation.md +++ b/docs/tasks/federation/set-up-placement-policies-federation.md @@ -51,10 +51,10 @@ Admission Controller. Update the Federation API server command line arguments to enable the Admission Controller and mount the ConfigMap into the container. If there's an existing -`--admission-control` flag, append `,SchedulingPolicy` instead of adding +`--enable-admission-plugins` flag, append `,SchedulingPolicy` instead of adding another line. - --admission-control=SchedulingPolicy + --enable-admission-plugins=SchedulingPolicy --admission-control-config-file=/etc/kubernetes/admission/config.yml Add the following volume to the Federation API server pod: diff --git a/docs/tutorials/clusters/apparmor.md b/docs/tutorials/clusters/apparmor.md index a4ac24d532639..4f8ecca51989d 100644 --- a/docs/tutorials/clusters/apparmor.md +++ b/docs/tutorials/clusters/apparmor.md @@ -320,7 +320,7 @@ If the PodSecurityPolicy extension is enabled, cluster-wide AppArmor restriction enable the PodSecurityPolicy, the following flag must be set on the `apiserver`: ``` ---admission-control=PodSecurityPolicy[,others...] +--enable-admission-plugins=PodSecurityPolicy[,others...] ``` The AppArmor options can be specified as annotations on the PodSecurityPolicy: