From 2e5e4d2489ec0fc201b920409b368d5877ace8a6 Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Sat, 18 Jun 2022 17:30:37 +0800 Subject: [PATCH] Reformat the extend-kubernetes page This page has too many long lines which make change tracking very difficult. --- .../docs/concepts/extend-kubernetes/_index.md | 152 ++++++++++++------ 1 file changed, 106 insertions(+), 46 deletions(-) diff --git a/content/en/docs/concepts/extend-kubernetes/_index.md b/content/en/docs/concepts/extend-kubernetes/_index.md index c50010a39f..5404f8c463 100644 --- a/content/en/docs/concepts/extend-kubernetes/_index.md +++ b/content/en/docs/concepts/extend-kubernetes/_index.md @@ -17,26 +17,29 @@ no_list: true -Kubernetes is highly configurable and extensible. As a result, -there is rarely a need to fork or submit patches to the Kubernetes -project code. +Kubernetes is highly configurable and extensible. As a result, there is rarely a need to fork or +submit patches to the Kubernetes project code. -This guide describes the options for customizing a Kubernetes -cluster. It is aimed at {{< glossary_tooltip text="cluster operators" term_id="cluster-operator" >}} who want to -understand how to adapt their Kubernetes cluster to the needs of -their work environment. Developers who are prospective {{< glossary_tooltip text="Platform Developers" term_id="platform-developer" >}} or Kubernetes Project {{< glossary_tooltip text="Contributors" term_id="contributor" >}} will also find it -useful as an introduction to what extension points and patterns -exist, and their trade-offs and limitations. +This guide describes the options for customizing a Kubernetes cluster. It is aimed at +{{< glossary_tooltip text="cluster operators" term_id="cluster-operator" >}} who want to understand +how to adapt their Kubernetes cluster to the needs of their work environment. Developers who are +prospective {{< glossary_tooltip text="Platform Developers" term_id="platform-developer" >}} or +Kubernetes Project {{< glossary_tooltip text="Contributors" term_id="contributor" >}} will also +find it useful as an introduction to what extension points and patterns exist, and their +trade-offs and limitations. ## Overview -Customization approaches can be broadly divided into *configuration*, which only involves changing flags, local configuration files, or API resources; and *extensions*, which involve running additional programs or services. This document is primarily about extensions. +Customization approaches can be broadly divided into *configuration*, which only involves changing +flags, local configuration files, or API resources; and *extensions*, which involve running +additional programs or services. This document is primarily about extensions. ## Configuration -*Configuration files* and *flags* are documented in the Reference section of the online documentation, under each binary: +*Configuration files* and *flags* are documented in the Reference section of the online +documentation, under each binary: * [kubelet](/docs/reference/command-line-tools-reference/kubelet/) * [kube-proxy](/docs/reference/command-line-tools-reference/kube-proxy/) @@ -44,9 +47,22 @@ Customization approaches can be broadly divided into *configuration*, which only * [kube-controller-manager](/docs/reference/command-line-tools-reference/kube-controller-manager/) * [kube-scheduler](/docs/reference/command-line-tools-reference/kube-scheduler/). -Flags and configuration files may not always be changeable in a hosted Kubernetes service or a distribution with managed installation. When they are changeable, they are usually only changeable by the cluster administrator. Also, they are subject to change in future Kubernetes versions, and setting them may require restarting processes. For those reasons, they should be used only when there are no other options. +Flags and configuration files may not always be changeable in a hosted Kubernetes service or a +distribution with managed installation. When they are changeable, they are usually only changeable +by the cluster administrator. Also, they are subject to change in future Kubernetes versions, and +setting them may require restarting processes. For those reasons, they should be used only when +there are no other options. -*Built-in Policy APIs*, such as [ResourceQuota](/docs/concepts/policy/resource-quotas/), [PodSecurityPolicies](/docs/concepts/security/pod-security-policy/), [NetworkPolicy](/docs/concepts/services-networking/network-policies/) and Role-based Access Control ([RBAC](/docs/reference/access-authn-authz/rbac/)), are built-in Kubernetes APIs. APIs are typically used with hosted Kubernetes services and with managed Kubernetes installations. They are declarative and use the same conventions as other Kubernetes resources like pods, so new cluster configuration can be repeatable and be managed the same way as applications. And, where they are stable, they enjoy a [defined support policy](/docs/reference/using-api/deprecation-policy/) like other Kubernetes APIs. For these reasons, they are preferred over *configuration files* and *flags* where suitable. +*Built-in Policy APIs*, such as [ResourceQuota](/docs/concepts/policy/resource-quotas/), +[PodSecurityPolicies](/docs/concepts/security/pod-security-policy/), +[NetworkPolicy](/docs/concepts/services-networking/network-policies/) and Role-based Access Control +([RBAC](/docs/reference/access-authn-authz/rbac/)), are built-in Kubernetes APIs. +APIs are typically used with hosted Kubernetes services and with managed Kubernetes installations. +They are declarative and use the same conventions as other Kubernetes resources like pods, +so new cluster configuration can be repeatable and be managed the same way as applications. +And, where they are stable, they enjoy a +[defined support policy](/docs/reference/using-api/deprecation-policy/) like other Kubernetes APIs. +For these reasons, they are preferred over *configuration files* and *flags* where suitable. ## Extensions @@ -70,10 +86,9 @@ There is a specific pattern for writing client programs that work well with Kubernetes called the *Controller* pattern. Controllers typically read an object's `.spec`, possibly do things, and then update the object's `.status`. -A controller is a client of Kubernetes. When Kubernetes is the client and -calls out to a remote service, it is called a *Webhook*. The remote service -is called a *Webhook Backend*. Like Controllers, Webhooks do add a point of -failure. +A controller is a client of Kubernetes. When Kubernetes is the client and calls out to a remote +service, it is called a *Webhook*. The remote service is called a *Webhook Backend*. Like +Controllers, Webhooks do add a point of failure. In the webhook model, Kubernetes makes a network request to a remote service. In the *Binary Plugin* model, Kubernetes executes a binary (program). @@ -95,15 +110,35 @@ This diagram shows the extension points in a Kubernetes system. ![Extension Points](/docs/concepts/extend-kubernetes/extension-points.png) -1. Users often interact with the Kubernetes API using `kubectl`. [Kubectl plugins](/docs/tasks/extend-kubectl/kubectl-plugins/) extend the kubectl binary. They only affect the individual user's local environment, and so cannot enforce site-wide policies. -2. The apiserver handles all requests. Several types of extension points in the apiserver allow authenticating requests, or blocking them based on their content, editing content, and handling deletion. These are described in the [API Access Extensions](#api-access-extensions) section. -3. The apiserver serves various kinds of *resources*. *Built-in resource kinds*, like `pods`, are defined by the Kubernetes project and can't be changed. You can also add resources that you define, or that other projects have defined, called *Custom Resources*, as explained in the [Custom Resources](#user-defined-types) section. Custom Resources are often used with API Access Extensions. -4. The Kubernetes scheduler decides which nodes to place pods on. There are several ways to extend scheduling. These are described in the [Scheduler Extensions](#scheduler-extensions) section. -5. Much of the behavior of Kubernetes is implemented by programs called Controllers which are clients of the API-Server. Controllers are often used in conjunction with Custom Resources. -6. The kubelet runs on servers, and helps pods appear like virtual servers with their own IPs on the cluster network. [Network Plugins](#network-plugins) allow for different implementations of pod networking. -7. The kubelet also mounts and unmounts volumes for containers. New types of storage can be supported via [Storage Plugins](#storage-plugins). +1. Users often interact with the Kubernetes API using `kubectl`. + [Kubectl plugins](/docs/tasks/extend-kubectl/kubectl-plugins/) extend the kubectl binary. + They only affect the individual user's local environment, and so cannot enforce site-wide policies. -If you are unsure where to start, this flowchart can help. Note that some solutions may involve several types of extensions. +1. The API server handles all requests. Several types of extension points in the API server allow + authenticating requests, or blocking them based on their content, editing content, and handling + deletion. These are described in the [API Access Extensions](#api-access-extensions) section. + +1. The API server serves various kinds of *resources*. *Built-in resource kinds*, like `pods`, are + defined by the Kubernetes project and can't be changed. You can also add resources that you + define, or that other projects have defined, called *Custom Resources*, as explained in the + [Custom Resources](#user-defined-types) section. Custom Resources are often used with API access + extensions. + +1. The Kubernetes scheduler decides which nodes to place pods on. There are several ways to extend + scheduling. These are described in the [Scheduler Extensions](#scheduler-extensions) section. + +1. Much of the behavior of Kubernetes is implemented by programs called Controllers which are + clients of the API server. Controllers are often used in conjunction with Custom Resources. + +1. The kubelet runs on servers, and helps pods appear like virtual servers with their own IPs on + the cluster network. [Network Plugins](#network-plugins) allow for different implementations of + pod networking. + +1. The kubelet also mounts and unmounts volumes for containers. New types of storage can be + supported via [Storage Plugins](#storage-plugins). + +If you are unsure where to start, this flowchart can help. Note that some solutions may involve +several types of extensions. ![Flowchart for Extension](/docs/concepts/extend-kubernetes/flowchart.png) @@ -112,60 +147,86 @@ If you are unsure where to start, this flowchart can help. Note that some soluti ### User-Defined Types -Consider adding a Custom Resource to Kubernetes if you want to define new controllers, application configuration objects or other declarative APIs, and to manage them using Kubernetes tools, such as `kubectl`. +Consider adding a Custom Resource to Kubernetes if you want to define new controllers, application +configuration objects or other declarative APIs, and to manage them using Kubernetes tools, such +as `kubectl`. Do not use a Custom Resource as data storage for application, user, or monitoring data. -For more about Custom Resources, see the [Custom Resources concept guide](/docs/concepts/extend-kubernetes/api-extension/custom-resources/). +For more about Custom Resources, see the +[Custom Resources concept guide](/docs/concepts/extend-kubernetes/api-extension/custom-resources/). ### Combining New APIs with Automation -The combination of a custom resource API and a control loop is called the [Operator pattern](/docs/concepts/extend-kubernetes/operator/). The Operator pattern is used to manage specific, usually stateful, applications. These custom APIs and control loops can also be used to control other resources, such as storage or policies. +The combination of a custom resource API and a control loop is called the +[Operator pattern](/docs/concepts/extend-kubernetes/operator/). The Operator pattern is used to manage +specific, usually stateful, applications. These custom APIs and control loops can also be used to +control other resources, such as storage or policies. ### Changing Built-in Resources -When you extend the Kubernetes API by adding custom resources, the added resources always fall into a new API Groups. You cannot replace or change existing API groups. -Adding an API does not directly let you affect the behavior of existing APIs (e.g. Pods), but API Access Extensions do. +When you extend the Kubernetes API by adding custom resources, the added resources always fall +into a new API Groups. You cannot replace or change existing API groups. +Adding an API does not directly let you affect the behavior of existing APIs (e.g. Pods), but API +Access Extensions do. ### API Access Extensions -When a request reaches the Kubernetes API Server, it is first Authenticated, then Authorized, then subject to various types of Admission Control. See [Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access/) for more on this flow. +When a request reaches the Kubernetes API Server, it is first Authenticated, then Authorized, then +subject to various types of Admission Control. See +[Controlling Access to the Kubernetes API](/docs/concepts/security/controlling-access/) +for more on this flow. Each of these steps offers extension points. -Kubernetes has several built-in authentication methods that it supports. It can also sit behind an authenticating proxy, and it can send a token from an Authorization header to a remote service for verification (a webhook). All of these methods are covered in the [Authentication documentation](/docs/reference/access-authn-authz/authentication/). +Kubernetes has several built-in authentication methods that it supports. It can also sit behind an +authenticating proxy, and it can send a token from an Authorization header to a remote service for +verification (a webhook). All of these methods are covered in the +[Authentication documentation](/docs/reference/access-authn-authz/authentication/). ### Authentication -[Authentication](/docs/reference/access-authn-authz/authentication/) maps headers or certificates in all requests to a username for the client making the request. - -Kubernetes provides several built-in authentication methods, and an [Authentication webhook](/docs/reference/access-authn-authz/authentication/#webhook-token-authentication) method if those don't meet your needs. +[Authentication](/docs/reference/access-authn-authz/authentication/) maps headers or certificates +in all requests to a username for the client making the request. +Kubernetes provides several built-in authentication methods, and an +[Authentication webhook](/docs/reference/access-authn-authz/authentication/#webhook-token-authentication) +method if those don't meet your needs. ### Authorization -[Authorization](/docs/reference/access-authn-authz/authorization/) determines whether specific users can read, write, and do other operations on API resources. It works at the level of whole resources -- it doesn't discriminate based on arbitrary object fields. If the built-in authorization options don't meet your needs, [Authorization webhook](/docs/reference/access-authn-authz/webhook/) allows calling out to user-provided code to make an authorization decision. - +[Authorization](/docs/reference/access-authn-authz/authorization/) determines whether specific +users can read, write, and do other operations on API resources. It works at the level of whole +resources -- it doesn't discriminate based on arbitrary object fields. If the built-in +authorization options don't meet your needs, [Authorization webhook](/docs/reference/access-authn-authz/webhook/) +allows calling out to user-provided code to make an authorization decision. ### Dynamic Admission Control -After a request is authorized, if it is a write operation, it also goes through [Admission Control](/docs/reference/access-authn-authz/admission-controllers/) steps. In addition to the built-in steps, there are several extensions: +After a request is authorized, if it is a write operation, it also goes through +[Admission Control](/docs/reference/access-authn-authz/admission-controllers/) steps. +In addition to the built-in steps, there are several extensions: -* The [Image Policy webhook](/docs/reference/access-authn-authz/admission-controllers/#imagepolicywebhook) restricts what images can be run in containers. -* To make arbitrary admission control decisions, a general [Admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) can be used. Admission Webhooks can reject creations or updates. +* The [Image Policy webhook](/docs/reference/access-authn-authz/admission-controllers/#imagepolicywebhook) + restricts what images can be run in containers. +* To make arbitrary admission control decisions, a general + [Admission webhook](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) + can be used. Admission Webhooks can reject creations or updates. ## Infrastructure Extensions ### Storage Plugins -[Flex Volumes](https://git.k8s.io/design-proposals-archive/storage/flexvolume-deployment.md -) allow users to mount volume types without built-in support by having the -Kubelet call a Binary Plugin to mount the volume. - -FlexVolume is deprecated since Kubernetes v1.23. The Out-of-tree CSI driver is the recommended way to write volume drivers in Kubernetes. See [Kubernetes Volume Plugin FAQ for Storage Vendors](https://github.com/kubernetes/community/blob/master/sig-storage/volume-plugin-faq.md#kubernetes-volume-plugin-faq-for-storage-vendors) for more information. +[Flex Volumes](https://git.k8s.io/design-proposals-archive/storage/flexvolume-deployment.md) +allow users to mount volume types without built-in support by having the kubelet call a binary +plugin to mount the volume. +FlexVolume is deprecated since Kubernetes v1.23. The out-of-tree CSI driver is the recommended way +to write volume drivers in Kubernetes. See +[Kubernetes Volume Plugin FAQ for Storage Vendors](https://github.com/kubernetes/community/blob/master/sig-storage/volume-plugin-faq.md#kubernetes-volume-plugin-faq-for-storage-vendors) +for more information. ### Device Plugins @@ -173,7 +234,6 @@ Device plugins allow a node to discover new Node resources (in addition to the builtin ones like cpu and memory) via a [Device Plugin](/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/). - ### Network Plugins Different networking fabrics can be supported via node-level