Merge branch 'master' into release-1.9
This commit is contained in:
zacharysarah
@@ -6,16 +6,14 @@ approvers:
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page explains the concept of *custom resources*, which are extensions of the Kubernetes API.
|
||||
This page explains [*custom resources*](/docs/concepts/api-extension/custom-resources/), which are extensions of the Kubernetes API. This page explains when to add a custom resource to your Kubernetes cluster and when to use a standalone service. It describes the two methods for adding custom resources and how to choose between them.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture body %}
|
||||
## Custom resources
|
||||
|
||||
A *resource* is an endpoint in the [Kubernetes API](/docs/reference/api-overview/) that stores a
|
||||
collection of [API objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) of a
|
||||
certain kind.
|
||||
For example, the built-in *pods* resource contains a collection of Pod objects.
|
||||
A *resource* is an endpoint in the [Kubernetes API](/docs/reference/api-overview/) that stores a collection of [API objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) of a certain kind. For example, the built-in *pods* resource contains a collection of Pod objects.
|
||||
|
||||
A *custom resource* is an extension of the Kubernetes API that is not necessarily available on every
|
||||
Kubernetes cluster.
|
||||
@@ -26,34 +24,95 @@ and cluster admins can update custom resources independently of the cluster itse
|
||||
Once a custom resource is installed, users can create and access its objects with
|
||||
[kubectl](/docs/user-guide/kubectl-overview/), just as they do for built-in resources like *pods*.
|
||||
|
||||
## Custom controllers
|
||||
### Custom controllers
|
||||
|
||||
On their own, custom resources simply let you store and retrieve structured data.
|
||||
It is only when combined with a *controller* that they become a true
|
||||
[declarative API](/docs/concepts/overview/working-with-objects/kubernetes-objects/#understanding-kubernetes-objects).
|
||||
The controller interprets the structured data as a record of the user's desired state,
|
||||
and continually takes action to achieve and maintain that state.
|
||||
It is only when combined with a *controller* that they become a true [declarative API](/docs/concepts/overview/working-with-objects/kubernetes-objects/#understanding-kubernetes-objects). The controller interprets the structured data as a record of the user's desired state, and continually takes action to achieve and maintain that state.
|
||||
|
||||
A *custom controller* is a controller that users can deploy and update on a running cluster,
|
||||
independently of the cluster's own lifecycle.
|
||||
Custom controllers can work with any kind of resource, but they are especially effective when
|
||||
combined with custom resources.
|
||||
The [Operator](https://coreos.com/blog/introducing-operators.html) pattern is one example of such a
|
||||
combination. It allows developers to encode domain knowledge for specific applications into an
|
||||
extension of the Kubernetes API.
|
||||
A *custom controller* is a controller that users can deploy and update on a running cluster, independently of the cluster's own lifecycle. Custom controllers can work with any kind of resource, but they are especially effective when combined with custom resources. The [Operator](https://coreos.com/blog/introducing-operators.html) pattern is one example of such a combination. It allows developers to encode domain knowledge for specific applications into an extension of the Kubernetes API.
|
||||
|
||||
### Should I add a custom resource to my Kubernetes Cluster?
|
||||
|
||||
When creating a new API, consider whether to [aggregate your API with the Kubernetes cluster APIs](/docs/concepts/api-extension/apiserver-aggregation/) or let your API stand alone.
|
||||
|
||||
| Consider API aggregation if: | Prefer a stand-alone API if: |
|
||||
|-|-|
|
||||
| Your API is [Declarative](#declarative-apis). | Your API does not fit the [Declarative](#declarative-apis) model. |
|
||||
| You want your new types to be readable and writable using `kubectl`.| `kubectl` support is not required |
|
||||
| You want to view your new types in a Kubernetes UI, such as dashboard, alongside built-in types. | Kuberetes UI support is not required. |
|
||||
| You are developing a new API. | You already have program that serves your API and works well. |
|
||||
| You are willing to accept the format restriction that Kubernetes puts on REST resource paths, such as API Groups and Namespaces. (See the [API Overview](/docs/concepts/overview/kubernetes-api/).) | You need to have specific REST paths to be compatible with an already defined REST API. |
|
||||
| Your resources are naturally scoped to a cluster or to namespaces of a cluster. | Cluster or namespace scoped resources are a poor fit; you need control over the specifics of resource paths. |
|
||||
| You want to reuse [Kubernetes API support features](#common-features). | You don't need those features. |
|
||||
|
||||
#### Declarative APIs
|
||||
|
||||
In a Declarative API, typically:
|
||||
- your API consists of a relatively small number of relatively small objects (resources).
|
||||
- the objects define configuration of applications or infrastructure
|
||||
- the objects are updated relatively infrequently
|
||||
- humans often need to read and write the objects
|
||||
- the main operations on the objects are CRUD-y (creating, reading, updating and deleting)
|
||||
- transactions across objects are not required: the API represents a desired state, not an exact state.
|
||||
|
||||
Imperative APIs are not declarative.
|
||||
Signs that your API might not be declarative include:
|
||||
- the client says "do this", and then gets a synchornous response back when it is done.
|
||||
- the client says "do this", and then gets an operation ID back, and has to check a separate Operation objects to determine completion of the request.
|
||||
- you talk about Remote Procedure Calls (RPCs)
|
||||
- directly stoing large amounts of data (e.g. > a few kB per object, or >1000s of objects)
|
||||
- high bandwidth access (10s of requests per second sustained) needed
|
||||
- store end-user data (such as images, PII, etc) or other large-scale data processed by applications
|
||||
- the natural operations on the objects are not CRUD-y.
|
||||
- the API is not easily modeled as objects.
|
||||
- you chose to represent pending operations with an operation ID or operation object.
|
||||
|
||||
### Should I use a configMap or a custom resource?
|
||||
|
||||
Use a ConfigMap if any of the following apply:
|
||||
|
||||
* There is an existing, well-documented config file format, such as a `mysql.cnf` or `pom.xml`.
|
||||
* You want to put the entire config file into one key of a configMap.
|
||||
* The main use of the config file is for a program running in a Pod on your cluster to consume the file to configure itself.
|
||||
* Consumers of the file prefer to consume via file in a Pod or environment variable in a pod, rather than the Kubernetes API.
|
||||
* You want to perform rolling updates via Deployment, etc, when the file is updated.
|
||||
|
||||
**Note:** Use a [secret](/docs/concepts/configuration/secret/) for sensitive data, which is similar to a configMap but more secure.
|
||||
{: .note}
|
||||
|
||||
Use a custom resource (CRD or Aggregated API) if most of the following apply:
|
||||
|
||||
* You want to use Kubernetes client libraries and CLIs to create and update the new resource.
|
||||
* You want top-level support from kubectl (for example: `kubectl get my-object object-name`).
|
||||
* You want to build new automation that watches for updates on the new object, and then CRUD other objects, or vice versa.
|
||||
* You want to write automation that handles updates to the object.
|
||||
* You want to use Kubernetes API conventions like `.spec`, `.status`, and `.metadata`.
|
||||
* You want the object to be an abstraction over a collection of controlled resources, or a summarization of other resources.
|
||||
|
||||
## Adding custom resources
|
||||
|
||||
Kubernetes provides two ways to add custom resources to your cluster:
|
||||
|
||||
- [Custom Resource Definitions](/docs/concepts/api-extension/custom-resources/) (CRDs) are easier to use: they do not require any programming in some cases.
|
||||
- [API Aggregation](/docs/concepts/api-extension/apiserver-aggregation/) requires programming, but allows more control over API behaviors like how data is stored and conversion between API versions.
|
||||
|
||||
Kubernetes provides these two options to meet the needs of different users, so that neither ease of use nor flexibility are compromised.
|
||||
|
||||
Aggregated APIs are subordinate APIServers that sit behind the primary API server, which acts as a proxy. This arrangement is called [API Aggregation](docs/concepts/api-extension/apiserver-aggregation.md) (AA). To users, it simply appears that the Kubernetes API is extended.
|
||||
|
||||
Custom Resource Definitions (CRDS) allow users to create new types of resources without adding another APIserver. You do not need to understand API Aggregation to use CRDs.
|
||||
|
||||
Regardless of whether they are installed via CRDs or AA, the new resources are called Custom Resources to distinguish them from built-in Kubernetes resources (like pods)
|
||||
|
||||
## CustomResourceDefinitions
|
||||
|
||||
[CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/)
|
||||
(CRD) is a built-in API that offers a simple way to create custom resources.
|
||||
Deploying a CRD into the cluster causes the Kubernetes API server to begin serving the specified
|
||||
custom resource on your behalf.
|
||||
The [CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/) (CRD) API resource allows you to define custom resources. Defining a CRD object creates an new custom resource with a name and schema that you specify. The Kubernetes API serves and handles the storage of your custom resource.
|
||||
|
||||
This frees you from writing your own API server to handle the custom resource,
|
||||
but the generic nature of the implementation means you have less flexibility than with
|
||||
[API server aggregation](#api-server-aggregation).
|
||||
|
||||
Refer to the [Custom Resource Example](https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/apiextensions-apiserver/examples/client-go)
|
||||
Refer to the [Custom Controler example, which uses Custom Resources](https://github.com/kubernetes/sample-controller)
|
||||
for a demonstration of how to register a new custom resource, work with instances of your new resource type,
|
||||
and setup a controller to handle events.
|
||||
|
||||
@@ -62,16 +121,104 @@ and setup a controller to handle events.
|
||||
|
||||
## API server aggregation
|
||||
|
||||
Usually, each resource in the Kubernetes API requires code that handles REST requests and manages
|
||||
persistent storage of objects.
|
||||
The main Kubernetes API server handles built-in resources like *pods* and *services*,
|
||||
and can also handle custom resources in a generic way through [CustomResourceDefinitions](#customresourcedefinitions).
|
||||
Usually, each resource in the Kubernetes API requires code that handles REST requests and manages persistent storage of objects. The main Kubernetes API server handles built-in resources like *pods* and *services*, and can also handle custom resources in a generic way through [CustomResourceDefinitions](#customresourcedefinitions).
|
||||
|
||||
The [aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) allows you to provide specialized
|
||||
implementations for your custom resources by writing and deploying your own standalone API server.
|
||||
The main API server delegates requests to you for the custom resources that you handle,
|
||||
making them available to all of its clients.
|
||||
|
||||
### Choosing a method for adding custom resources
|
||||
|
||||
CRDs are easier to use. Aggregated APIs are more flexible. Choose the method that best meets your needs.
|
||||
|
||||
Typically, CRDs are a good fit if:
|
||||
|
||||
* You are have a handful of fields
|
||||
* You are using the resource within your company, or as part of a small open-source project (as opposed to a commercial product)
|
||||
|
||||
#### Comparing ease of use
|
||||
|
||||
CRDs are easier to create than Aggregated APIs.
|
||||
|
||||
| Custom Resource Definitions | Aggregated API |
|
||||
|-|-|
|
||||
| Do not require programming. Users can choose any language for a CRD controller. | Requires programming in Go and building binary and image. Users can choose any language for a CRD controller. |
|
||||
| No additional service to run; CRs are handled by API Server. | An additional service to create and that could fail. |
|
||||
| No ongoing support once the CRD is created. Any bug fixes are picked up as part of normal Kubernetes Master upgrades. | May need to periodically pickup bug fixes from upstream and rebuild and update the Aggregated APIserver. |
|
||||
| No need to handle multiple versions of your API. For example: when you control the client for this resource, you can upgrade it in sync with the API. | You need to handle multiple versions of your API, for example: when developing an extension to share with the world. |
|
||||
|
||||
### Advanced features and flexibility
|
||||
|
||||
Aggregated APIs offer more advanced API features and customization of other features, for example: the storage layer.
|
||||
|
||||
| Feature | Description | CRDs | Aggregated API |
|
||||
|-|-|-|-|
|
||||
| Validation | Help users prevent errors and allow you to evolve your API independently of your clients. These features are most useful when there are many clients who can't all update at the same time. | Alpha feature of CRDs in v1.8. Checks limited to what is supported by OpenAPI v3.0. | Yes, arbitrary validation checks |
|
||||
| Defaulting | See above | No, but can achieve the same effect with an Initializer (requires programming) | Yes |
|
||||
| Multi-versioning | Allows serving the same object through two API versions. Can help ease API changes like renaming fields. Less important if you control your client versions. | No | Yes |
|
||||
| Custom Storage | If you need storage with a different performance mode (for example, time-series database instead of key-value store) or isolation for security (for example, encryption secrets or different | No | Yes |
|
||||
| Custom Business Logic | Perform arbitrary checks or actions when creating, reading, updating or deleting an object | No, but can get some of the same effects with Initializers or Finalizers (requires programming) | Yes |
|
||||
| Subresources | <ul><li>Add extra operations other than CRUD, such as "scale" or "exec"</li><li>Allows systems like like HorizontalPodAutoscaler and PodDisruptionBudget interact with your new resource</li><li>Finer-grained access control: user writes spec section, controller writes status section.</li><li>Allows incrementing object Generation on custom resource data mutation (requires separate spec and status sections in the resource)</li></ul> | No but planned | Yes, any Subresource |
|
||||
| strategic-merge-patch | The new endpoints support PATCH with `Content-Type: application/strategic-merge-patch+json`. Useful for updating objects that may be modified both locally, and by the server. For more information, see ["Update API Objects in Place Using kubectl patch"](/docs/tasks/run-application/update-api-object-kubectl-patch/) | No | Yes |
|
||||
| Protocol Buffers | The new resource supports clients that want to use Protocol Buffers | No | Yes |
|
||||
| OpenAPI Schema | Is there an OpenAPI (swagger) schema for the types that can be dynamically fetched from the server? Is the user protected from misspelling field names by ensuring only allowed fields are set? Are types enforced (in other words, don't put an `int` in a `string` field?) | No but planned | Yes |
|
||||
|
||||
#### Common Features
|
||||
|
||||
When you create a custom resource, either via a CRDs or an AA, you get many features for your API, compared to implementing it outside the Kubernetes platform:
|
||||
|
||||
| Feature | What it does |
|
||||
|-|-|
|
||||
| CRUD | The new endpoints support CRUD basic operations via HTTP and `kubectl` |
|
||||
| Watch | The new endpoints support Kubernetes Watch operations via HTTP |
|
||||
| Discovery | Clients like kubectl and dashboard automatically offer list, display, and field edit operations on your resources |
|
||||
| json-patch | The new endpoints support PATCH with `Content-Type: application/json-patch+json` |
|
||||
| merge-patch | The new endpoints support PATCH with `Content-Type: application/merge-patch+json` |
|
||||
| HTTPS | The new endpoints uses HTTPS |
|
||||
| Built-in Authentication | Access to the extension uses the core apiserver (aggregation layer) for authentication |
|
||||
| Built-in Authorization | Access the the extension can reuse the authorization used by the core apiserver (e.g. RBAC) |
|
||||
| Finalizers | Block deletion of extension resources until external cleanup happens. |
|
||||
| Admission Webhooks | Set default values and validate extension resources during any create/update/delete operation. |
|
||||
| UI/CLI Display | Kubectl, dashboard can display extension resources. |
|
||||
| Unset vs Empty | Clients can distinguish unset fields from zero-valued fields. |
|
||||
| Client Libraries Generation | Kubernetes provides generic clent libraries, as well as tools to generate type-specific client libraries. |
|
||||
| Labels and annotations | Common metadata across objects that tools know how to edit for core and custom resources. |
|
||||
|
||||
## Preparing to install a custom resource
|
||||
|
||||
There are several points to be aware of before adding a custom resource to your cluster.
|
||||
|
||||
### Third party code and new points of failure
|
||||
|
||||
While creating a CRD does not automatically add any new points of failure (for example, by causing third party code to run on your API server), packages (for example, Charts) or other installation bundles often include CRDs as well as a Deployment of third-party code that implements the business logic for a new custom resource.
|
||||
|
||||
Installing an Aggregated APIserver always involves running a new Deployment.
|
||||
|
||||
### Storage
|
||||
|
||||
Custom resources consume storage space in the same way that ConfigMaps do. Creating too many custom resources may overload your API server's storage space.
|
||||
|
||||
Aggregated API servers may use the same storage as the main API server, in which case the same warning applies.
|
||||
|
||||
### Authentication, authorization, and auditing
|
||||
|
||||
CRDs always use the same authentication, authorization, and audit logging as the built-in resources of your API Server.
|
||||
|
||||
If you use RBAC for authorization, most RBAC roles will not grant access to the new resources (except the cluster-admin role or any role created with wildcard rules). You'll need to explicitly grant access to the new resources. CRDs and Aggregated APIs often come bundled with new role definitions for the types they add.
|
||||
|
||||
Aggregated API servers may or may not use the same authentication, authorization, and auditing as the primary API server.
|
||||
|
||||
## Accessing a custom resource
|
||||
|
||||
Kubernetes [client libraries](/docs/reference/client-libraries/) can be used to access custom resources. Not all client libraries support custom resources. The go and python client libraries do.
|
||||
|
||||
When you add a custom resource, you can access it using:
|
||||
- kubectl
|
||||
- the kubernetes dynamic client
|
||||
- a REST client that you write
|
||||
- a client generated using Kubernetes client generation tools (generating one is an advanced undertaking, but some projects may provide a client along with the CRD or AA).
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
|
||||
@@ -247,7 +247,7 @@ On each client, perform the following operations:
|
||||
```bash
|
||||
$ sudo cp ca.crt /usr/local/share/ca-certificates/kubernetes.crt
|
||||
$ sudo update-ca-certificates
|
||||
pdating certificates in /etc/ssl/certs...
|
||||
Updating certificates in /etc/ssl/certs...
|
||||
1 added, 0 removed; done.
|
||||
Running hooks in /etc/ca-certificates/update.d....
|
||||
done.
|
||||
|
||||
@@ -69,11 +69,11 @@ the underlying cloud, where available:
|
||||
| Identity (Keystone) | V2‡, V3 | Yes |
|
||||
| Load Balancing (Neutron) | V1§, V2 | No |
|
||||
|
||||
† Block Storage V1 API support is deprecated, support for Block Storage V3 will
|
||||
be added in the future.
|
||||
† Block Storage V1 API support is deprecated, support for Block Storage V3 will
|
||||
be added in the future.
|
||||
|
||||
‡ Identity V2 API support is deprecated and will be removed from the provider in
|
||||
a future release. As of the "Queens" release OpenStack will no longer expose the
|
||||
a future release. As of the "Queens" release, OpenStack will no longer expose the
|
||||
Identity V2 API.
|
||||
|
||||
§ Load Balancing V1 API support is deprecated and will be removed from the
|
||||
@@ -87,7 +87,8 @@ support for impacted features. Certain features are also enabled or disabled
|
||||
based on the list of extensions published by Neutron in the underlying cloud.
|
||||
|
||||
## cloud.conf
|
||||
Kubernetes knows how to interact with OpenStack via the file cloud.conf. It is the file that will provide Kubernetes with credentials and location for the OpenStack auth endpoint.
|
||||
Kubernetes knows how to interact with OpenStack via the file cloud.conf. It is
|
||||
the file that will provide Kubernetes with credentials and location for the OpenStack auth endpoint.
|
||||
You can create a cloud.conf file by specifying the following details in it
|
||||
|
||||
### Typical configuration
|
||||
@@ -139,7 +140,7 @@ file:
|
||||
endpoint of the Keystone API.
|
||||
* `ca-file` (Optional): TODO
|
||||
|
||||
When using Keystone V3 - which changes tenant to project the `tenant-id` value
|
||||
When using Keystone V3 - which changes tenant to project - the `tenant-id` value
|
||||
is automatically mapped to the project construct in the API.
|
||||
|
||||
#### Load Balancer
|
||||
@@ -190,10 +191,10 @@ and should appear in the `[BlockStorage]` section of the `cloud.conf` file:
|
||||
detection will select the highest supported version exposed by the underlying
|
||||
OpenStack cloud. The default value if none is provided is `auto`.
|
||||
* `trust-device-path` (Optional): In most scenarios the block device names
|
||||
provided by Cinder (e.g. /dev/vda) can not be trusted. This boolean toggles
|
||||
provided by Cinder (e.g. `/dev/vda`) can not be trusted. This boolean toggles
|
||||
this behavior. Setting it to `true` results in trusting the block device names
|
||||
provided by Cinder. The default value of `false` results in the discovery of
|
||||
the device path based on it's serial number and /dev/disk/by-id mapping and is
|
||||
the device path based on its serial number and `/dev/disk/by-id` mapping and is
|
||||
the recommended approach.
|
||||
|
||||
If deploying Kubernetes versions <= 1.8 on an OpenStack deployment that uses
|
||||
@@ -236,12 +237,19 @@ should appear in the `[Metadata]` section of the `cloud.conf` file:
|
||||
may be available which is why the default is to check both.
|
||||
|
||||
#### Router
|
||||
These configuration options for the OpenStack provider pertain to routing and
|
||||
should appear in the `[Route]` section of the `cloud.conf` file:
|
||||
|
||||
These configuration options for the OpenStack provider pertain to the [kubenet]
|
||||
Kubernetes network plugin and should appear in the `[Router]` section of the
|
||||
`cloud.conf` file:
|
||||
|
||||
* `router-id` (Optional): If the underlying cloud's Neutron deployment supports
|
||||
the `extraroutes` extension then use `router-id` to specify a router to add
|
||||
routes to.
|
||||
routes to. The router chosen must span the private networks containing your
|
||||
cluster nodes (typically there is only one node network, and this value should be
|
||||
the default router for the node network). This value is required to use [kubenet]
|
||||
on OpenStack.
|
||||
|
||||
[kubenet]: https://kubernetes.io/docs/concepts/cluster-administration/network-plugins/#kubenet
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
@@ -39,7 +39,17 @@ This is a living document. If you think of something that is not on this list bu
|
||||
|
||||
- It's typically best to create a [service](/docs/concepts/services-networking/service/) before the corresponding [replication controllers](/docs/concepts/workloads/controllers/replicationcontroller/). This lets the scheduler spread the pods that comprise the service.
|
||||
|
||||
- Don't use `hostPort` unless it is absolutely necessary (for example: for a node daemon). It specifies the port number to expose on the host. When you bind a Pod to a `hostPort`, there are a limited number of places to schedule a pod due to port conflicts— you can only schedule as many such Pods as there are nodes in your Kubernetes cluster.
|
||||
- Don't use `hostPort` unless it is absolutely necessary (for example: for a node daemon).
|
||||
It specifies the port number to expose on the host.
|
||||
When you bind a Pod to a `hostPort`, there are a limited number of places to schedule a pod due to port conflicts.
|
||||
The conflict comes from the requirement of an unique <hostIP,hostPort,protocol> combination.
|
||||
Different <hostIP,hostPort,protocol> combinations mean different requirements.
|
||||
For example, a pod that binds to host port 80 on 127.0.0.1 with TCP protocol has no conflict with another Pod that binds to host port 80 on 127.0.0.2 with TCP protocol.
|
||||
|
||||
*Special notes on hostIP and protocol*: If you don't specify the hostIP and protocol explicitly,
|
||||
kubernetes will use 0.0.0.0 and TCP as the default hostIP and protocol,
|
||||
where "0.0.0.0" is a wildcard IP that will match all <*,hostPort,protocol> on the node the pod is scheduled on.
|
||||
Specifically, it will match all <IP,hostPort,protocol> tuples for all IPs on the host.
|
||||
|
||||
If you only need access to the port for debugging purposes, you can use the [kubectl proxy and apiserver proxy](/docs/tasks/access-kubernetes-api/http-proxy-access-api/) or [kubectl port-forward](/docs/tasks/access-application-cluster/port-forward-access-application-cluster/).
|
||||
You can use a [Service](/docs/concepts/services-networking/service/) object for external service access.
|
||||
|
||||
@@ -0,0 +1,215 @@
|
||||
---
|
||||
title: Extending your Kubernetes Cluster
|
||||
approvers:
|
||||
- erictune
|
||||
- lavalamp
|
||||
- cheftako
|
||||
- chenopis
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
|
||||
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.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
{% capture body %}
|
||||
|
||||
## 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.
|
||||
|
||||
## Configuration
|
||||
|
||||
*Configuration files* and *flags* are documented in the Reference section of the online documentation, under each binary:
|
||||
|
||||
* [kubelet](/docs/admin/kubelet/)
|
||||
* [kube-apiserver](/docs/admin/kube-apiserver/)
|
||||
* [kube-controller-manager](/docs/admin/kube-controller-manager/)
|
||||
* [kube-scheduler](/docs/admin/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.
|
||||
|
||||
*Built-in Policy APIs*, such as [ResourceQuota](/docs/concepts/policy/resource-quotas/), [PodSecurityPolicies](/docs/concepts/policy/pod-security-policy/), [NetworkPolicy](/docs/concepts/services-networking/network-policies/) and Role-based Access Control ([RBAC](/docs/admin/authorization/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/deprecation-policy/) like other Kubernetes APIs. For these reasons, they are preferred over *configuration files* and *flags* where suitable.
|
||||
|
||||
## Extensions
|
||||
|
||||
Extensions are software components that extend and deeply integrate with Kubernetes.
|
||||
They adapt it to support new types and new kinds of hardware.
|
||||
|
||||
Most cluster administrators will use a hosted or distribution
|
||||
instance of Kubernetes. As a result, most Kubernetes users will need to
|
||||
install extensions and fewer will need to author new ones.
|
||||
|
||||
## Extension Patterns
|
||||
|
||||
Kubernetes is designed to be automated by writing client programs. Any
|
||||
program that reads and/or writes to the Kubernetes API can provide useful
|
||||
automation. *Automation* can run on the cluster or off it. By following
|
||||
the guidance in this doc you can write highly available and robust automation.
|
||||
Automation generally works with any Kubernetes cluster, including hosted
|
||||
clusters and managed installations.
|
||||
|
||||
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.
|
||||
|
||||
In the webhook model, Kubernetes makes a network request to a remote service.
|
||||
In the *Binary Plugin* model, Kubernetes executes a binary (program).
|
||||
Binary plugins are used by the kubelet (e.g. [Flex Volume
|
||||
Plugins](https://github.com/kubernetes/community/blob/master/contributors/devel/flexvolume.md)
|
||||
and [Network
|
||||
Plugins](/docs/concepts/cluster-administration/network-plugins/))
|
||||
and by kubectl.
|
||||
|
||||
Below is a diagram showing how the extensions points interact with the
|
||||
Kubernetes control plane.
|
||||
|
||||
<img src="https://docs.google.com/drawings/d/e/2PACX-1vQBRWyXLVUlQPlp7BvxvV9S1mxyXSM6rAc_cbLANvKlu6kCCf-kGTporTMIeG5GZtUdxXz1xowN7RmL/pub?w=960&h=720">
|
||||
|
||||
<!-- image source drawing https://docs.google.com/drawings/d/1muJ7Oxuj_7Gtv7HV9-2zJbOnkQJnjxq-v1ym_kZfB-4/edit?ts=5a01e054 -->
|
||||
|
||||
|
||||
## Extension Points
|
||||
|
||||
This diagram shows the extension points in a Kubernetes system.
|
||||
|
||||
<img src="https://docs.google.com/drawings/d/e/2PACX-1vSH5ZWUO2jH9f34YHenhnCd14baEb4vT-pzfxeFC7NzdNqRDgdz4DDAVqArtH4onOGqh0bhwMX0zGBb/pub?w=425&h=809">
|
||||
|
||||
<!-- image source diagrams: https://docs.google.com/drawings/d/1k2YdJgNTtNfW7_A8moIIkij-DmVgEhNrn3y2OODwqQQ/view -->
|
||||
|
||||
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](docs/concepts/overview/extending#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](docs/concepts/overview/extending#custom-resources) 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](docs/concepts/overview/extending#shceduler-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](docs/concepts/overview/extending#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](docs/concepts/overview/extending#storage-plugins).
|
||||
|
||||
If you are unsure where to start, this flowchart can help. Note that some solutions may involve several types of extensions.
|
||||
|
||||
|
||||
<img src="https://docs.google.com/drawings/d/e/2PACX-1vRWXNNIVWFDqzDY0CsKZJY3AR8sDeFDXItdc5awYxVH8s0OLherMlEPVUpxPIB1CSUu7GPk7B2fEnzM/pub?w=1440&h=1080">
|
||||
|
||||
<!-- image source drawing: https://docs.google.com/drawings/d/1sdviU6lDz4BpnzJNHfNpQrqI9F19QZ07KnhnxVrp2yg/edit -->
|
||||
|
||||
## API Extensions
|
||||
### 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`.
|
||||
|
||||
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/api-extension/custom-resources.md).
|
||||
|
||||
|
||||
### Combining New APIs with Automation
|
||||
|
||||
Often, when you add a new API, you also add a control loop that reads and/or writes the new APIs. When the combination of a Custom API and a control loop is used to manage a specific, usually stateful, application, this is called the *Operator* pattern. Custom APIs and control loops can also be used to control other resources, such as storage, policies, and so on.
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
### 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 [[Accessing the API](/docs/admin/accessing-the-api/)] 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/admin/authentication/).
|
||||
|
||||
### Authentication
|
||||
|
||||
[Authentication](/docs/admin/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/admin/authentication/#webhook-token-authentication) method if those don't meet your needs.
|
||||
|
||||
|
||||
### Authorization
|
||||
|
||||
[Authorization](/docs/admin/authorization/webhook/) determines whether specific users can read, write, and do other operations on API resources. It just 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, and [Authorization webhook](/docs/admin/authorization/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 t goes through [Admission Control](/docs/admin/admission-controllers/) steps. In addition to the built-in steps, there are several extensions:
|
||||
|
||||
* The [Image Policy webhook](/docs/admin/admission-controllers/#imagepolicywebhook) restricts what images can be run in containers.
|
||||
* To make arbitrary admission control decisions, a general [Admission webhook](/docs/admin/extensible-admission-controllers/#external-admission-webhooks) can be used. Admission Webhooks can reject creations or updates.
|
||||
* [Initializers](/docs/admin/extensible-admission-controllers/#initializers) are controllers that can modify objects before they are created. Initializers can modify initial object creations but cannot affect updates to objects. Initializers can also reject objects.
|
||||
|
||||
## Infrastructure Extensions
|
||||
|
||||
|
||||
### Storage Plugins
|
||||
|
||||
[Flex Volumes](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/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.
|
||||
|
||||
|
||||
### Device Plugins
|
||||
|
||||
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/cluster-administration/device-plugins/).
|
||||
|
||||
|
||||
### Network Plugins
|
||||
|
||||
Different networking fabrics can be supported via node-level [Network Plugins](/docs/admin/network-plugins/).
|
||||
|
||||
### Scheduler Extensions
|
||||
|
||||
The scheduler is a special type of controller that watches pods, and assigns
|
||||
pods to nodes. The default scheduler can be be replaced entirely, while
|
||||
continuing to use other Kubernetes components, or [multiple
|
||||
schedulers](/docs/tasks/administer-cluster/configure-multiple-schedulers/)
|
||||
can run at the same time.
|
||||
|
||||
This is a significant undertaking, and almost all Kubernetes users find they
|
||||
do not need to modify the scheduler.
|
||||
|
||||
The scheduler also supports a
|
||||
[webhook](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/scheduling/scheduler_extender.md)
|
||||
that permits a webhook backend (scheduler extension) to filter and prioritize
|
||||
the nodes chosen for a pod.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
{% capture whatsnext %}
|
||||
|
||||
* Learn more about [Custom Resources](/docs/concepts/api-extension/custom-resources/)
|
||||
* Learn about [Dynamic admission control](/docs/admin/extensible-admission-controller)
|
||||
* Learn more about Infrastructure extensions
|
||||
* [Network Plugins](/docs/concepts/cluster-administration/network-plugin)
|
||||
* [Device Plugins](/docs/concepts/cluster-administration/device-plugins.md)
|
||||
* Learn about [kubectl plugins](/docs/tasks/extend-kubectl/kubectl-plugin)
|
||||
* See examples of Automation
|
||||
* [List of Operators](https://github.com/coreos/awesome-kubernetes-extensions)
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/concept.md %}
|
||||
|
||||
|
||||
@@ -428,28 +428,18 @@ and need persistent storage, we recommend that you use the following pattern:
|
||||
the config may not have permission to create PersistentVolumes.
|
||||
- Give the user the option of providing a storage class name when instantiating
|
||||
the template.
|
||||
- If the user provides a storage class name, and the cluster is version 1.4
|
||||
or newer, put that value into the `volume.beta.kubernetes.io/storage-class`
|
||||
annotation of the PVC. This will cause the PVC to match the right storage
|
||||
- If the user provides a storage class name, put that value into the
|
||||
`persistentVolumeClaim.storageClassName` field.
|
||||
This will cause the PVC to match the right storage
|
||||
class if the cluster has StorageClasses enabled by the admin.
|
||||
- If the user does not provide a storage class name or the cluster is version
|
||||
1.3, then instead put a `volume.alpha.kubernetes.io/storage-class: default`
|
||||
annotation on the PVC.
|
||||
- If the user does not provide a storage class name, leave the
|
||||
`persistentVolumeClaim.storageClassName` field as nil.
|
||||
- This will cause a PV to be automatically provisioned for the user with
|
||||
sane default characteristics on some clusters.
|
||||
- Despite the word `alpha` in the name, the code behind this annotation has
|
||||
`beta` level support.
|
||||
- Do not use `volume.beta.kubernetes.io/storage-class:` with any value
|
||||
including the empty string since it will prevent `DefaultStorageClass`
|
||||
admission controller from running if enabled.
|
||||
the default StorageClass in the cluster. Many cluster environments have
|
||||
a default StorageClass installed, or administrators can create their own
|
||||
default StorageClass.
|
||||
- In your tooling, do watch for PVCs that are not getting bound after some time
|
||||
and surface this to the user, as this may indicate that the cluster has no
|
||||
dynamic storage support (in which case the user should create a matching PV)
|
||||
or the cluster has no storage system (in which case the user cannot deploy
|
||||
config requiring PVCs).
|
||||
- In the future, we expect most clusters to have `DefaultStorageClass` enabled,
|
||||
and to have some form of storage available. However, there may not be any
|
||||
storage class names which work on all clusters, so continue to not set one by
|
||||
default.
|
||||
At some point, the alpha annotation will cease to have meaning, but the unset
|
||||
`storageClass` field on the PVC will have the desired effect.
|
||||
|
||||
@@ -66,10 +66,10 @@ A Pod Template in a DaemonSet must have a [`RestartPolicy`](/docs/user-guide/pod
|
||||
The `.spec.selector` field is a pod selector. It works the same as the `.spec.selector` of
|
||||
a [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/).
|
||||
|
||||
As of Kubernetes 1.8, you must specify a pod selector that matches the labels of the
|
||||
`.spec.template`. The pod selector will no longer be defaulted when left empty. Selector
|
||||
defaulting was not compatible with `kubectl apply`. Also, once a DaemonSet is created,
|
||||
its `spec.selector` can not be mutated. Mutating the pod selector can lead to the
|
||||
As of Kubernetes 1.8, you must specify a pod selector that matches the labels of the
|
||||
`.spec.template`. The pod selector will no longer be defaulted when left empty. Selector
|
||||
defaulting was not compatible with `kubectl apply`. Also, once a DaemonSet is created,
|
||||
its `spec.selector` can not be mutated. Mutating the pod selector can lead to the
|
||||
unintentional orphaning of Pods, and it was found to be confusing to users.
|
||||
|
||||
The `spec.selector` is an object consisting of two fields:
|
||||
@@ -119,7 +119,7 @@ they will not be evicted when there are node problems such as a network partitio
|
||||
due to hard-coded behavior of the NodeController rather than due to tolerations).
|
||||
|
||||
They also tolerate following `NoSchedule` taints:
|
||||
|
||||
|
||||
- `node.kubernetes.io/memory-pressure`
|
||||
- `node.kubernetes.io/disk-pressure`
|
||||
|
||||
@@ -129,6 +129,8 @@ labelled as critical, the Daemon pods are created with an additional
|
||||
|
||||
Note that all above `NoSchedule` taints above are created only in version 1.8 or later if the alpha feature `TaintNodesByCondition` is enabled.
|
||||
|
||||
Also note that the `node-role.kubernetes.io/master` `NoSchedule` toleration specified in the above example is needed on 1.6 or later to schedule on *master* nodes as this is not a default toleration.
|
||||
|
||||
## Communicating with Daemon Pods
|
||||
|
||||
Some possible patterns for communicating with Pods in a DaemonSet are:
|
||||
@@ -160,8 +162,6 @@ You will need to force new Pod creation by deleting the Pod or deleting the node
|
||||
|
||||
In Kubernetes version 1.6 and later, you can [perform a rolling update](/docs/tasks/manage-daemon/update-daemon-set/) on a DaemonSet.
|
||||
|
||||
Future releases of Kubernetes will support controlled updating of nodes.
|
||||
|
||||
## Alternatives to DaemonSet
|
||||
|
||||
### Init Scripts
|
||||
@@ -172,8 +172,6 @@ running such processes via a DaemonSet:
|
||||
|
||||
- Ability to monitor and manage logs for daemons in the same way as applications.
|
||||
- Same config language and tools (e.g. Pod templates, `kubectl`) for daemons and applications.
|
||||
- Future versions of Kubernetes will likely support integration between DaemonSet-created
|
||||
Pods and node upgrade workflows.
|
||||
- Running daemons in containers with resource limits increases isolation between daemons from app
|
||||
containers. However, this can also be accomplished by running the daemons in a container but not in a Pod
|
||||
(e.g. start directly via Docker).
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
apiVersion: apps/v1beta2 # for versions before 1.8.0 use apps/v1beta1
|
||||
apiVersion: apps/v1beta2 # for versions before 1.8.0 use extensions/v1beta1
|
||||
kind: DaemonSet
|
||||
metadata:
|
||||
name: fluentd-elasticsearch
|
||||
@@ -14,6 +14,9 @@ spec:
|
||||
labels:
|
||||
name: fluentd-elasticsearch
|
||||
spec:
|
||||
tolerations:
|
||||
- key: node-role.kubernetes.io/master
|
||||
effect: NoSchedule
|
||||
containers:
|
||||
- name: fluentd-elasticsearch
|
||||
image: gcr.io/google-containers/fluentd-elasticsearch:1.20
|
||||
|
||||
@@ -89,7 +89,7 @@ Here are some ideas for how to use Init Containers:
|
||||
configuration file using Jinja.
|
||||
|
||||
More detailed usage examples can be found in the [StatefulSets documentation](/docs/concepts/workloads/controllers/statefulset/)
|
||||
and the [Production Pods guide](/docs/tasks/#handling-initialization).
|
||||
and the [Production Pods guide](/docs/tasks/configure-pod-container/configure-pod-initialization/).
|
||||
|
||||
### Init Containers in use
|
||||
|
||||
|
||||
Reference in New Issue
Block a user