whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Release 1.7 (#4094)

Browse Source 
* Minor fixes in the Deployment doc

Signed-off-by: Michail Kargakis <mkargaki@redhat.com>

* add NodeRestriction to admission-controllers (#3842)

* Admins Can Configure Zones in Storage Class

The PR #38505 (https://github.com/kubernetes/kubernetes/pull/38505) added zones optional parameter to Storage Class for AWS and GCE provisioners.

That's why documentation needs to be updated accordingly.

* document custom resource definitions

* add host paths to psp (#3971)

* add host paths to psp

* add italics

* Update ConfigMap doc to explain TTL-based cache updates (#3989)

* Update ConfigMap doc to explain TTL-based cache updates

* swap word order

Change "When a ConfigMap being already consumed..." to "When a ConfigMap already being consumed..."

* Update NetworkPolicy docs for v1

* StorageOS Volume plugin

* Update GPU docs

* docs: HPA autoscaling/v2alpha1 status conditions

This commit documents the new status conditions feature for HPA
autoscaling/v2alpha1.  It demonstrates how to get the status conditions
using `kubectl describe`, and how to interpret them.

* Update description about NodeRestriction

kubelet node can alse create mirror pods for their own static pods.

* adding storage as a supported resource to node allocatable

Signed-off-by: Vishnu kannan <vishnuk@google.com>

* Add documentation for podpreset opt-out annotation

This adds the annotation for having the podpreset admission controller
to skip (opt-out) manipulating the pod spec.

Also, the annotation format for what presets have acted on a pod has
been modified to add a prefix of "podpreset-". The new naming makes it such
that there is no chance of collision with the newly introduced opt-out
annotation (or future ones yet to be added).

Opt-out annotation PR:
kubernetes/kubernetes#44965

* Update PDB documentation to explain new field (#3885)

* update-docs-pdb

* Addressed erictune@'s comments

* Fix title and add a TOC to the logging concept page

* Patch #4118 for typos

* Describe setting coredns server in nameserver resolv chain

* Address comments in PR #3997.

Comment is in
https://github.com/kubernetes/kubernetes.github.io/pull/3997/files/f6eb59c67e28efc298c87b1ef49a96bc6adacd1e#diff-7a14981f3dd8eb203f897ce6c11d9828

* Update task for DaemonSet history and rollback (#4098)

* Update task for DaemonSet history and rollback

Also remove mentions of templateGeneration field because it's deprecated

* Address comments

* removed lt and gt as operators (#4152)

* removed lt and gt as operators

* replace lt and gt for node-affinfity

* updated based on bsalamat review

* Initial draft of upgrade guide for kubeadm clusters.

In-place upgrades are supported between 1.6 and 1.7 releases. Rollback
instructions to come in a separate commit.

Fixes https://github.com/kubernetes/kubeadm/issues/278

* Add local volume documentation (#4050)

* Add local volume documentation

* Add PV local volume example

* Patch PR #3999

* Add documentation for Stackdriver event exporter

* Add documentation about controller metrics

* Federation: Add task for setting up placement policies (#4075)

* Add task for setting up placement policies

* Update version of management sidecar in policy engine deployment

* Address @nikhiljindal's comments

- Lower case filenames
- Comments in policy
- Typo fixes
- Removed type LoadBalancer from OPA Service

* Add example that sets cluster selector

Per-@nikhiljindal's suggestion

* Fix wording and templating per @chenopis

* PodDisruptionBudget documentation Improvements (#4140)

* Changes from #3885

Title: Update PDB documentation to explain new field
Author: foxish

* Added Placeholder Disruptions Concept Guide

New file: docs/concepts/workloads/pods/disruptions.md
Intented contents: concept for Pod Disruption Budget,
 cross reference to Eviction and Preemption docs.
Linked from: concepts > workloads > pods

* Added placeholder Configuring PDB Task

New file: docs/tasks/run-application/configure-pdb.md
Intented contents: task for writing a Pod Disruption Budget.
Linked from: tasks > configuring-applications > configure pdb.

* Add refs to the "drain a node" task.

* Refactor PDB docs.

Move the "Requesting an eviction" section from:
docs/tasks/administer-cluster/configure-pod-disruption-budget.md
-- which is going away -- to:
docs/tasks/administer-cluster/safely-drain-node.md

The move is verbatim, except for an introductory sentence.

Also added assignees.

* Refactor of PDB docs

Moved the section:
Specifying a PodDisruptionBudget
from:
docs/tasks/administer-cluster/configure-pod-disruption-budget.md
to:
docs/tasks/run-application/configure-pdb.md
because that former file is going away.
Move is verbatim.

* Explain how Eviction tools should handle failures

* Refactor PDB docs

Move text from:
docs/tasks/administer-cluster/configure-pod-disruption-budget.md
to:
docs/concepts/workloads/pods/disruptions.md

Delete the now empty:
docs/tasks/administer-cluster/configure-pod-disruption-budget.md

Added a redirects_from section to the new doc, containing the path
of the now-deleted doc, plus all the redirects from the deleted
doc.

* Expand PDB Concept guide

Building on a little content from the old task,
greatly expanded the Disruptions concept
guide, including an abstract example.

* Update creating a pdb Task.

* Address review comments.

* Fixed for all cody-clark's review comments

* Address review comments from mml

* Address review comments from maisem

* Fix missing backtick

* Api and Kubectl reference docs updates for 1.7 (#4193)

* Fix includes groups

* Generated kubectl docs for 1.7

* Generated references docs for 1.7 api

* Document node authorization mode

* API Aggregator (#4173)

* API Aggregator

* Additional bullet points

* incorporated feedback for apiserver-aggregation.md

* split setup-api-aggregator.md into two docs and address feedback

* fix link

* addressed docs feedback

* incorporate feedback

* integrate feedback

* Add documentation for DNS stub domains (#4063)

* Add documentation for DNS stub domains

* add additional prereq

* fix image path

* review feedback

* minor grammar and style nits

* documentation for using hostAliases to manage hosts file (#4080)

* documentation for using hostAliases to manage hosts file

* add to table of contents

* review comments

* update the right command to see hosts file

* reformat doc based on suggestion and change some wording

* Fix typo for #4080

* Patch PR #4063

* Fix wording in placement policy task introduction

* Add update to statefulset concepts and basic tutorial (#4174)

* Add update to statefulset concpets and basic tutorial

* Address tech comments.

* Update ESIPP docs for new added API fields

* Custom resource docs

* update audit document with advanced audit features added in 1.7

* kubeadm v1.7 documentation updates (#4018)

* v1.7 updates for kubeadm

* Address review comments

* Address Luke's comments

* Encrypting secrets at rest and cluster security guide

* Edits for Custom DNS Documentation (#4207)

* reorganize custom dns doc

* format fixes

* Update version numbers to 1.7

* Patch PR #4140 (#4215)

* Patch PR #4140

* fix link and typos

* Update PR template

* Update TLS bootstrapping with 1.7 features

This includes documenting the new CSR approver built into the
controller manager and the kubelet alpha features for certificate
rotation.

Since the CSR approver changed over the 1.7 release cycle we need
to call out the migration steps for those using the alpha feature.
This document as a whole could probably use some updates, but the
main focus of this PR is just to get these features minimally
documented before the release.

* Federated ClusterSelector

formatting updates from review

* complete PR #4181 (#4223)

* complete PR #4181

* fix security link

* Extensible admission controller (#4092)

* extensible-admission-controllers

* Update extensible-admission-controllers.md

* more on initializers

* fixes

* Expand external admission webhooks documentation

* wrap at 80 chars

* more

* add reference

* Use correct apigroup for network policy

* Docs changes to PR #4092 (#4224)

* Docs changes to PR #4092

* address feedback

* add doc for --as-group in cli

Add doc for this pr:
https://github.com/kubernetes/kubernetes/pull/43696
This commit is contained in:
zhangchaolei
2017-06-30 13:39:40 +08:00
committed by Dawn Chen
parent cbdb17706f
commit aae3bfaf3e
1620 changed files with 297157 additions and 676 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/extensible-admission-controllers.md
+284
View File
@@ -0,0 +1,284 @@
---
assignees:
- smarterclayton
- lavalamp
- whitlockjc
- caesrxuchao
title: Dynamic Admission Control
---
* TOC
{:toc}
## Overview
The [admission controllers documentation](/docs/admin/admission-controllers/)
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:
* 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
Webhooks*, that address these limitations. These features allow admission
controllers to be developed out-of-tree and configured at runtime.
This page describes how to use Initializers and External Admission Webhooks.
## Initializers
### What are initializers?
*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 perform 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`. 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](/docs/admin/admission-controllers/#alwayspullimages)
admission controller), or to inject defaults (e.g., the
[DefaultStorageClass](/docs/admin/admission-controllers/#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[].name`s are appended to the new object's
`metadata.initializers` 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](https://github.com/kubernetes/kubernetes/blob/v1.7.0-rc.1/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/types.go#L315)
to true.
For the observed uninitialized objects, an initializer controller should first
check if its name matches `metadata.initializers[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:
* Include "Initializer" in the `--admission-control` 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
to `kube-apiserver`, e.g.
`--runtime-config=admissionregistration.k8s.io/v1alpha1`. Again, all replicas
should have the same flag setting.
### Deploy an initializer controller
You should deploy an initializer controller via the [deployment
API](/docs/api-reference/v1.6/#deployment-v1beta1-apps).
### Configure initializers on the fly
You can configure what initializers are enabled and what resources are subject
to the initializers by creating `initializerconfigurations`.
You should first deploy the initializer controller and make sure that it is
working properly before creating the `initializerconfigurations`. Otherwise, any
newly created resources will be stuck in an uninitialized state.
The following is an example `initiallizerConfiguration`.
```yaml
apiVersion: admissionregistration.k8s.io/v1alpha1
kind: InitializerConfiguration
metadata:
name: example-config
spec:
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
```
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`.
After you create the `initializerConfiguration`, the system will take a few
seconds to honor the new configuration.
## External Admission Webhooks
### What are external admission webhooks?
External admission webhooks are HTTP callbacks that are intended to receive
admission requests and do something with them. What an external admission
webhook does is up to you, but there is an
[interface](https://github.com/kubernetes/kubernetes/blob/v1.7.0-rc.1/pkg/apis/admission/v1alpha1/types.go)
that it must adhere to so that it responds with whether or not the
admission request should be allowed.
Unlike initializers or the plugin-style admission controllers, external
admission webhooks are not allowed to mutate the admission request in any way.
Because admission is a high security operation, the external admission webhooks
must support TLS.
### When to use admission webhooks?
A simple example use case for an external admission webhook is to do semantic validation
of Kubernetes resources. Suppose that your infrastructure requires that all `Pod`
resources have a common set of labels, and you do not want any `Pod` to be
persisted to Kubernetes if those needs are not met. You could write your
external admission webhook to do this validation and respond accordingly.
### How are external admission webhooks triggered?
Whenever a request comes in, the `GenericAdmissionWebhook` admission plugin will
get the list of interested external admission webhooks from
`externalAdmissionHookConfiguration` objects (explained below) and call them in
parallel. If **all** of the external admission webhooks approve the admission
request, the admission chain continues. If **any** of the external admission
webhooks deny the admission request, the admission request will be denied, and
the reason for doing so will be based on the _first_ external admission webhook
denial reason. _This means if there is more than one external admission webhook
that denied the admission request, only the first will be returned to the
user._ If there is an error encountered when calling an external admission
webhook, that request is ignored and will not be used to approve/deny the
admission request.
**Note:** The admission chain depends solely on the order of the
`--admission-control` option passed to `kube-apiserver`.
### Enable external admission webhooks
*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
starting the 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
to `kube-apiserver`, e.g.
`--runtime-config=admissionregistration.k8s.io/v1alpha1`. Again, all replicas
should have the same flag setting.
### Write a webhook admission controller
See [caesarxuchao/example-webhook-admission-controller](https://github.com/caesarxuchao/example-webhook-admission-controller)
for an example webhook admission controller.
The communication between the webhook admission controller and the apiserver, or
more precisely, the GenericAdmissionWebhook admission controller, needs to be
TLS secured. You need to generate a CA cert and use it to sign the server cert
used by your webhook admission controller. The pem formatted CA cert is supplied
to the apiserver via the dynamic registration API
`externaladmissionhookconfigurations.clientConfig.caBundle`.
For each request received by the apiserver, the GenericAdmissionWebhook
admission controller sends an
[admissionReview](https://github.com/kubernetes/kubernetes/blob/v1.7.0-rc.1/pkg/apis/admission/v1alpha1/types.go#L27)
to the relevant webhook admission controller. The webhook admission controller
gathers information like `object`, `oldobject`, and `userInfo`, from
`admissionReview.spec`, sends back a response with the body also being the
`admissionReview`, whose `status` field is filled with the admission decision.
### Deploy the webhook admission controller
See [caesarxuchao/example-webhook-admission-controller deployment](https://github.com/caesarxuchao/example-webhook-admission-controller/tree/master/deployment)
for an example deployment.
The webhook admission controller should be deployed via the
[deployment API](/docs/api-reference/v1.6/#deployment-v1beta1-apps).
You also need to create a
[service](/docs/api-reference/v1.6/#service-v1-core) as the
front-end of the deployment.
### Configure webhook admission controller on the fly
You can configure what webhook admission controllers are enabled and what
resources are subject to the admission controller via creating
externaladmissionhookconfigurations.
We suggest that you first deploy the webhook admission controller and make sure
it is working properly before creating the externaladmissionhookconfigurations.
Otherwise, depending whether the webhook is configured as fail open or fail
closed, operations will be unconditionally accepted or rejected.
The following is an example externaladmissionhookconfiguration.
```yaml
apiVersion: admissionregistration.k8s.io/v1alpha1
kind: ExternalAdmissionHookConfiguration
metadata:
name: example-config
externalAdmissionHooks:
- name: pod-image.k8s.io
rules:
- apiGroups:
- ""
apiVersions:
- v1
operations:
- CREATE
resources:
- pods
failurePolicy: Ignore
clientConfig:
caBundle: <pem encoded ca cert that signs the server cert used by the webhook>
service:
name: <name of the front-end service>
namespace: <namespace of the front-end service>
```
For a request received by the apiserver, if the request matches any of the
`rules` of an `externalAdmissionHook`, the `GenericAdmissionWebhook` admission
controller will send an `admissionReview` request to the `externalAdmissionHook`
to ask for admission decision.
The `rule` is similar to the `rule` in `initializerConfiguration`, with two
differences:
* The addition of the `operations` field, specifying what operations the webhook
is interested in;
* The `resources` field accepts subresources in the form or resource/subresource.
Make sure that all expansions of the `<apiGroup, apiVersions,resources>` 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`
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.
After you create the `initializerConfiguration`, the system will take a few
seconds to honor the new configuration.