Merge branch 'master' of https://github.com/kubernetes/kubernetes.github.io into release-1.8
* 'master' of https://github.com/kubernetes/kubernetes.github.io: (87 commits) fix envFrom in configmap Add link to example for CRDs (#5641) Fixed links to architecture.md and principles.md Polish AppArmor tutorial Remove dangling files related to apparmor fix the typo of serviceaccount (#5533) Correct setup link (#5634) relink the persistent volume of petset (#5582) Updates to case study landing page (#5629) translate doc resource-quotas into chinese minor encoding fix for CN page fix typo concepts-overview-components+abac-fix concepts-overview-components-fix Update links to avoid redirects. (#5627) Update links to avoid redirects. (#5625) Fix 404s. (#5624) Fix 404s. (#5623) Edits cpu-constraint-namespace.md Fix index redirects (#5502) ... # Conflicts: # _redirects # docs/concepts/storage/volumes.md # docs/concepts/workloads/controllers/daemonset.md # docs/concepts/workloads/controllers/petset.md # docs/concepts/workloads/controllers/statefulset.md # docs/tasks/run-application/run-single-instance-stateful-application.md # docs/tutorials/stateful-application/zookeeper.md
This commit is contained in:
Andrew Chen
@@ -53,8 +53,12 @@ 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).
|
||||
|
||||
CRD is the successor to the deprecated *ThirdPartyResource* (TPR) API, and is available as of
|
||||
Kubernetes 1.7.
|
||||
Refer to the [Custom Resource Example](https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/apiextensions-apiserver/examples/client-go)
|
||||
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.
|
||||
|
||||
**Note:** CRD is the successor to the deprecated *ThirdPartyResource* (TPR) API, and is available as of Kubernetes 1.7.
|
||||
{: .note}
|
||||
|
||||
## API server aggregation
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ This section describes all the possible configurations which can
|
||||
be used when running Kubernetes on Amazon Web Services.
|
||||
|
||||
## Load Balancers
|
||||
You can setup [external load balancers](/docs/tasks/access-application-cluster/create-external-load-balancer)
|
||||
You can setup [external load balancers](/docs/tasks/access-application-cluster/create-external-load-balancer/)
|
||||
to use specific features in AWS by configuring the annotations as shown below.
|
||||
|
||||
```yaml
|
||||
|
||||
@@ -18,23 +18,23 @@ See the guides in [Picking the Right Solution](/docs/setup/pick-right-solution/)
|
||||
Before choosing a guide, here are some considerations:
|
||||
|
||||
- Do you just want to try out Kubernetes on your computer, or do you want to build a high-availability, multi-node cluster? Choose distros best suited for your needs.
|
||||
- **If you are designing for high-availability**, learn about configuring [clusters in multiple zones](/docs/admin/multi-cluster).
|
||||
- **If you are designing for high-availability**, learn about configuring [clusters in multiple zones](/docs/admin/multi-cluster/).
|
||||
- Will you be using **a hosted Kubernetes cluster**, such as [Google Container Engine (GKE)](https://cloud.google.com/container-engine/), or **hosting your own cluster**?
|
||||
- Will your cluster be **on-premises**, or **in the cloud (IaaS)**? Kubernetes does not directly support hybrid clusters. Instead, you can set up multiple clusters.
|
||||
- **If you are configuring Kubernetes on-premises**, consider which [networking model](/docs/admin/networking) fits best. One option for custom networking is [*OpenVSwitch GRE/VxLAN networking*](/docs/admin/ovs-networking/), which uses OpenVSwitch to set up networking between pods across Kubernetes nodes.
|
||||
- **If you are configuring Kubernetes on-premises**, consider which [networking model](/docs/admin/networking/) fits best. One option for custom networking is [*OpenVSwitch GRE/VxLAN networking*](/docs/admin/ovs-networking/), which uses OpenVSwitch to set up networking between pods across Kubernetes nodes.
|
||||
- Will you be running Kubernetes on **"bare metal" hardware** or on **virtual machines (VMs)**?
|
||||
- Do you **just want to run a cluster**, or do you expect to do **active development of Kubernetes project code**? If the
|
||||
latter, choose a actively-developed distro. Some distros only use binary releases, but
|
||||
offer a greater variety of choices.
|
||||
- Familiarize yourself with the [components](/docs/admin/cluster-components) needed to run a cluster.
|
||||
- Familiarize yourself with the [components](/docs/admin/cluster-components/) needed to run a cluster.
|
||||
|
||||
Note: Not all distros are actively maintained. Choose distros which have been tested with a recent version of Kubernetes.
|
||||
|
||||
If you are using a guide involving Salt, see [Configuring Kubernetes with Salt](/docs/admin/salt).
|
||||
If you are using a guide involving Salt, see [Configuring Kubernetes with Salt](/docs/admin/salt/).
|
||||
|
||||
## Managing a cluster
|
||||
|
||||
* [Managing a cluster](/docs/concepts/cluster-administration/cluster-management/) describes several topics related to the lifecycle of a cluster: creating a new cluster, upgrading your cluster’s master and worker nodes, performing node maintenance (e.g. kernel upgrades), and upgrading the Kubernetes API version of a running cluster..
|
||||
* [Managing a cluster](/docs/concepts/cluster-administration/cluster-management/) describes several topics related to the lifecycle of a cluster: creating a new cluster, upgrading your cluster’s master and worker nodes, performing node maintenance (e.g. kernel upgrades), and upgrading the Kubernetes API version of a running cluster.
|
||||
|
||||
* Learn how to [manage nodes](/docs/concepts/nodes/node/).
|
||||
|
||||
@@ -44,20 +44,20 @@ If you are using a guide involving Salt, see [Configuring Kubernetes with Salt](
|
||||
|
||||
* [Kubernetes Container Environment](/docs/concepts/containers/container-environment-variables/) describes the environment for Kubelet managed containers on a Kubernetes node.
|
||||
|
||||
* [Controlling Access to the Kubernetes API](/docs/admin/accessing-the-api) describes how to set up permissions for users and service accounts.
|
||||
* [Controlling Access to the Kubernetes API](/docs/admin/accessing-the-api/) describes how to set up permissions for users and service accounts.
|
||||
|
||||
* [Authenticating](/docs/admin/authentication) explains authentication in Kubernetes, including the various authentication options.
|
||||
* [Authenticating](/docs/admin/authentication/) explains authentication in Kubernetes, including the various authentication options.
|
||||
|
||||
* [Authorization](/docs/admin/authorization) is separate from authentication, and controls how HTTP calls are handled.
|
||||
* [Authorization](/docs/admin/authorization/) is separate from authentication, and controls how HTTP calls are handled.
|
||||
|
||||
* [Using Admission Controllers](/docs/admin/admission-controllers) explains plug-ins which intercepts requests to the Kubernetes API server after authentication and authorization.
|
||||
* [Using Admission Controllers](/docs/admin/admission-controllers/) explains plug-ins which intercepts requests to the Kubernetes API server after authentication and authorization.
|
||||
|
||||
* [Using Sysctls in a Kubernetes Cluster](/docs/concepts/cluster-administration/sysctl-cluster/) describes to an administrator how to use the `sysctl` command-line tool to set kernel parameters .
|
||||
|
||||
* [Auditing](/docs/tasks/debug-application-cluster/audit/) describes how to interact with Kubernetes' audit logs.
|
||||
|
||||
### Securing the kubelet
|
||||
* [Master-Node communication](/docs/concepts/cluster-administration/master-node-communication/)
|
||||
* [Master-Node communication](/docs/concepts/architecture/master-node-communication/)
|
||||
* [TLS bootstrapping](/docs/admin/kubelet-tls-bootstrapping/)
|
||||
* [Kubelet authentication/authorization](/docs/admin/kubelet-authentication-authorization/)
|
||||
|
||||
|
||||
@@ -72,4 +72,4 @@ Including:
|
||||
| `--low-diskspace-threshold-mb` | `--eviction-hard` or `eviction-soft` | eviction generalizes disk thresholds to other resources |
|
||||
| `--outofdisk-transition-frequency` | `--eviction-pressure-transition-period` | eviction generalizes disk pressure transition to other resources |
|
||||
|
||||
See [Configuring Out Of Resource Handling](/docs/concepts/cluster-administration/out-of-resource/) for more details.
|
||||
See [Configuring Out Of Resource Handling](/docs/tasks/administer-cluster/out-of-resource/) for more details.
|
||||
|
||||
@@ -256,7 +256,7 @@ my-nginx-2035384211-u3t6x 1/1 Running 0 23m fe
|
||||
|
||||
This outputs all "app=nginx" pods, with an additional label column of pods' tier (specified with `-L` or `--label-columns`).
|
||||
|
||||
For more information, please see [labels](/docs/user-guide/labels/) and [kubectl label](/docs/user-guide/kubectl/{{page.version}}/#label) document.
|
||||
For more information, please see [labels](/docs/concepts/overview/working-with-objects/labels/) and [kubectl label](/docs/user-guide/kubectl/{{page.version}}/#label) document.
|
||||
|
||||
## Updating annotations
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ There are several different proxies you may encounter when using Kubernetes:
|
||||
- proxy to target may use HTTP or HTTPS as chosen by proxy using available information
|
||||
- can be used to reach a Node, Pod, or Service
|
||||
- does load balancing when used to reach a Service
|
||||
1. The [kube proxy](/docs/user-guide/services/#ips-and-vips):
|
||||
1. The [kube proxy](/docs/concepts/services-networking/service/#ips-and-vips):
|
||||
- runs on each node
|
||||
- proxies UDP and TCP
|
||||
- does not understand HTTP
|
||||
|
||||
@@ -26,7 +26,7 @@ CPU and memory are collectively referred to as *compute resources*, or just
|
||||
*resources*. Compute
|
||||
resources are measurable quantities that can be requested, allocated, and
|
||||
consumed. They are distinct from
|
||||
[API resources](/docs/api/). API resources, such as Pods and
|
||||
[API resources](/docs/concepts/overview/kubernetes-api/). API resources, such as Pods and
|
||||
[Services](/docs/user-guide/services) are objects that can be read and modified
|
||||
through the Kubernetes API server.
|
||||
|
||||
|
||||
@@ -37,16 +37,20 @@ in a variety of ways. For example:
|
||||
- Administrators might have sets of certificates that they provide to individual users.
|
||||
|
||||
With kubeconfig files, you can organize your clusters, users, and namespaces.
|
||||
And you can define contexts that enable users to quickly and easily switch between
|
||||
You can also define contexts to quickly and easily switch between
|
||||
clusters and namespaces.
|
||||
|
||||
## Context
|
||||
|
||||
A kubeconfig file can have *context* elements. Each context is a triple
|
||||
(cluster, namespace, user). You can use `kubectl config use-context` to set
|
||||
the current context. The `kubectl` command-line tool communicates with the
|
||||
cluster and namespace listed in the current context. And it uses the
|
||||
credentials of the user listed in the current context.
|
||||
A *context* element in a kubeconfig file is used to group access parameters
|
||||
under a convenient name. Each context has three parameters: cluster, namespace, and user.
|
||||
By default, the `kubectl` command-line tool uses parameters from
|
||||
the *current context* to communicate with the cluster.
|
||||
|
||||
To choose the current context:
|
||||
```
|
||||
kubectl config use-context
|
||||
```
|
||||
|
||||
## The KUBECONFIG environment variable
|
||||
|
||||
|
||||
@@ -50,15 +50,15 @@ This is a living document. If you think of something that is not on this list bu
|
||||
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.
|
||||
|
||||
If you explicitly need to expose a pod's port on the host machine, consider using a [NodePort](/docs/user-guide/services/#type-nodeport) service before resorting to `hostPort`.
|
||||
If you explicitly need to expose a pod's port on the host machine, consider using a [NodePort](/docs/concepts/services-networking/service/#type-nodeport) service before resorting to `hostPort`.
|
||||
|
||||
- Avoid using `hostNetwork`, for the same reasons as `hostPort`.
|
||||
|
||||
- Use _headless services_ for easy service discovery when you don't need kube-proxy load balancing. See [headless services](/docs/user-guide/services/#headless-services).
|
||||
- Use _headless services_ for easy service discovery when you don't need kube-proxy load balancing. See [headless services](/docs/concepts/services-networking/service/#headless-services).
|
||||
|
||||
## Using Labels
|
||||
|
||||
- Define and use [labels](/docs/user-guide/labels/) that identify __semantic attributes__ of your application or deployment. For example, instead of attaching a label to a set of pods to explicitly represent some service (For example, `service: myservice`), or explicitly representing the replication controller managing the pods (for example, `controller: mycontroller`), attach labels that identify semantic attributes, such as `{ app: myapp, tier: frontend, phase: test, deployment: v3 }`. This will let you select the object groups appropriate to the context— for example, a service for all "tier: frontend" pods, or all "test" phase components of app "myapp". See the [guestbook](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/guestbook/) app for an example of this approach.
|
||||
- Define and use [labels](/docs/concepts/overview/working-with-objects/labels/) that identify __semantic attributes__ of your application or deployment. For example, instead of attaching a label to a set of pods to explicitly represent some service (For example, `service: myservice`), or explicitly representing the replication controller managing the pods (for example, `controller: mycontroller`), attach labels that identify semantic attributes, such as `{ app: myapp, tier: frontend, phase: test, deployment: v3 }`. This will let you select the object groups appropriate to the context— for example, a service for all "tier: frontend" pods, or all "test" phase components of app "myapp". See the [guestbook](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/guestbook/) app for an example of this approach.
|
||||
|
||||
A service can be made to span multiple deployments, such as is done across [rolling updates](/docs/tasks/run-application/rolling-update-replication-controller/), by simply omitting release-specific labels from its selector, rather than updating a service's selector to match the replication controller's selector fully.
|
||||
|
||||
@@ -84,7 +84,7 @@ This is a living document. If you think of something that is not on this list bu
|
||||
|
||||
- Use `kubectl delete` rather than `stop`. `Delete` has a superset of the functionality of `stop`, and `stop` is deprecated.
|
||||
|
||||
- Use kubectl bulk operations (via files and/or labels) for get and delete. See [label selectors](/docs/user-guide/labels/#label-selectors) and [using labels effectively](/docs/concepts/cluster-administration/manage-deployment/#using-labels-effectively).
|
||||
- Use kubectl bulk operations (via files and/or labels) for get and delete. See [label selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors) and [using labels effectively](/docs/concepts/cluster-administration/manage-deployment/#using-labels-effectively).
|
||||
|
||||
- Use `kubectl run` and `expose` to quickly create and expose single container Deployments. See the [quick start guide](/docs/user-guide/quick-start/) for an example.
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ This page describes the resources available to Containers in the Container envir
|
||||
|
||||
The Kubernetes Container environment provides several important resources to Containers:
|
||||
|
||||
* A filesystem, which is a combination of an [image](/docs/concepts/containers/images) and one or more [volumes](/docs/concepts/storage/volumes).
|
||||
* A filesystem, which is a combination of an [image](/docs/concepts/containers/images/) and one or more [volumes](/docs/concepts/storage/volumes/).
|
||||
* Information about the Container itself.
|
||||
* Information about other objects in the cluster.
|
||||
|
||||
@@ -31,7 +31,7 @@ It is available through the `hostname` command or the
|
||||
function call in libc.
|
||||
|
||||
The Pod name and namespace are available as environment variables through the
|
||||
[downward API](/docs/tasks/configure-pod-container/downward-api-volume-expose-pod-information).
|
||||
[downward API](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/).
|
||||
|
||||
User defined environment variables from the Pod definition are also available to the Container,
|
||||
as are any environment variables specified statically in the Docker image.
|
||||
|
||||
@@ -25,7 +25,7 @@ you can do one of the following:
|
||||
|
||||
- set the `imagePullPolicy` of the container to `Always`;
|
||||
- use `:latest` as the tag for the image to use;
|
||||
- enable the [AllwaysPullImages](/docs/admin/admission-controllers/#alwayspullimages) admission controller.
|
||||
- enable the [AlwaysPullImages](/docs/admin/admission-controllers/#alwayspullimages) admission controller.
|
||||
|
||||
If you did not specify tag of your image, it will be assumed as `:latest`, with
|
||||
pull image policy of `Always` correspondingly.
|
||||
|
||||
@@ -18,20 +18,20 @@ cluster (for example, scheduling), and detecting and responding to cluster event
|
||||
Master components can be run on any node in the cluster. However,
|
||||
for simplicity, set up scripts typically start all master components on
|
||||
the same VM, and do not run user containers on this VM. See
|
||||
[Building High-Availability Clusters](/docs/admin/high-availability) for an example multi-master-VM setup.
|
||||
[Building High-Availability Clusters](/docs/admin/high-availability/) for an example multi-master-VM setup.
|
||||
|
||||
### kube-apiserver
|
||||
|
||||
[kube-apiserver](/docs/admin/kube-apiserver) exposes the Kubernetes API. It is the front-end for the
|
||||
Kubernetes control plane. It is designed to scale horizontally -- that is, it scales by deploying more instances. See [Building High-Availability Clusters](/docs/admin/high-availability).
|
||||
[kube-apiserver](/docs/admin/kube-apiserver/) exposes the Kubernetes API. It is the front-end for the
|
||||
Kubernetes control plane. It is designed to scale horizontally -- that is, it scales by deploying more instances. See [Building High-Availability Clusters](/docs/admin/high-availability/).
|
||||
|
||||
### etcd
|
||||
|
||||
[etcd](/docs/tasks/administer-cluster/configure-upgrade-etcd) is used as Kubernetes' backing store. All cluster data is stored here. Always have a backup plan for etcd's data for your Kubernetes cluster.
|
||||
[etcd](/docs/tasks/administer-cluster/configure-upgrade-etcd/) is used as Kubernetes' backing store. All cluster data is stored here. Always have a backup plan for etcd's data for your Kubernetes cluster.
|
||||
|
||||
### kube-controller-manager
|
||||
|
||||
[kube-controller-manager](/docs/admin/kube-controller-manager) runs controllers, which are the background threads that handle routine tasks in the cluster. Logically, each controller is a separate process, but to reduce complexity, they are all compiled into a single binary and run in a single process.
|
||||
[kube-controller-manager](/docs/admin/kube-controller-manager/) runs controllers, which are the background threads that handle routine tasks in the cluster. Logically, each controller is a separate process, but to reduce complexity, they are all compiled into a single binary and run in a single process.
|
||||
|
||||
These controllers include:
|
||||
|
||||
@@ -58,7 +58,7 @@ The following controllers have cloud provider dependencies:
|
||||
|
||||
### kube-scheduler
|
||||
|
||||
[kube-scheduler](/docs/admin/kube-scheduler) watches newly created pods that have no node assigned, and
|
||||
[kube-scheduler](/docs/admin/kube-scheduler/) watches newly created pods that have no node assigned, and
|
||||
selects a node for them to run on.
|
||||
|
||||
### addons
|
||||
@@ -84,12 +84,12 @@ Containers started by Kubernetes automatically include this DNS server in their
|
||||
|
||||
#### Container Resource Monitoring
|
||||
|
||||
[Container Resource Monitoring](/docs/tasks/debug-application-cluster/resource-usage-monitoring) records generic time-series metrics
|
||||
[Container Resource Monitoring](/docs/tasks/debug-application-cluster/resource-usage-monitoring/) records generic time-series metrics
|
||||
about containers in a central database, and provides a UI for browsing that data.
|
||||
|
||||
#### Cluster-level Logging
|
||||
|
||||
A [Cluster-level logging](/docs/concepts/cluster-administration/logging) mechanism is responsible for
|
||||
A [Cluster-level logging](/docs/concepts/cluster-administration/logging/) mechanism is responsible for
|
||||
saving container logs to a central log store with search/browsing interface.
|
||||
|
||||
## Node components
|
||||
@@ -98,7 +98,7 @@ Node components run on every node, maintaining running pods and providing the Ku
|
||||
|
||||
### kubelet
|
||||
|
||||
[kubelet](/docs/admin/kubelet) is the primary node agent. It watches for pods that have been assigned to its node (either by apiserver or via local configuration file) and:
|
||||
[kubelet](/docs/admin/kubelet/) is the primary node agent. It watches for pods that have been assigned to its node (either by apiserver or via local configuration file) and:
|
||||
|
||||
* Mounts the pod's required volumes.
|
||||
* Downloads the pod's secrets.
|
||||
@@ -109,7 +109,7 @@ Node components run on every node, maintaining running pods and providing the Ku
|
||||
|
||||
### kube-proxy
|
||||
|
||||
[kube-proxy](/docs/admin/kube-proxy) enables the Kubernetes service abstraction by maintaining
|
||||
[kube-proxy](/docs/admin/kube-proxy/) enables the Kubernetes service abstraction by maintaining
|
||||
network rules on the host and performing connection forwarding.
|
||||
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ Kubernetes itself is decomposed into multiple components, which interact through
|
||||
|
||||
## API changes
|
||||
|
||||
In our experience, any system that is successful needs to grow and change as new use cases emerge or existing ones change. Therefore, we expect the Kubernetes API to continuously change and grow. However, we intend to not break compatibility with existing clients, for an extended period of time. In general, new API resources and new resource fields can be expected to be added frequently. Elimination of resources or fields will require following a deprecation process. The precise deprecation policy for eliminating features is TBD, but once we reach our 1.0 milestone, there will be a specific policy.
|
||||
In our experience, any system that is successful needs to grow and change as new use cases emerge or existing ones change. Therefore, we expect the Kubernetes API to continuously change and grow. However, we intend to not break compatibility with existing clients, for an extended period of time. In general, new API resources and new resource fields can be expected to be added frequently. Elimination of resources or fields will require following the [API deprecation policy](https://kubernetes.io/docs/reference/deprecation-policy/).
|
||||
|
||||
What constitutes a compatible change and how to change the API are detailed by the [API change document](https://git.k8s.io/community/contributors/devel/api_changes.md).
|
||||
|
||||
|
||||
@@ -93,7 +93,7 @@ Even though Kubernetes provides a lot of functionality, there are always new sce
|
||||
|
||||
Additionally, the [Kubernetes control plane](/docs/concepts/overview/components/) is built upon the same [APIs](/docs/reference/api-overview/) that are available to developers and users. Users can write their own controllers, such as [schedulers](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/devel/scheduler.md), with [their own APIs](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/api-machinery/extending-api.md) that can be targeted by a general-purpose [command-line tool](/docs/user-guide/kubectl-overview/).
|
||||
|
||||
This [design](https://github.com/kubernetes/community/blob/{{page.githubbranch}}/contributors/design-proposals/architecture/principles.md) has enabled a number of other systems to build atop Kubernetes.
|
||||
This [design](https://git.k8s.io/community/contributors/design-proposals/architecture/principles.md) has enabled a number of other systems to build atop Kubernetes.
|
||||
|
||||
#### What Kubernetes is not
|
||||
|
||||
|
||||
@@ -55,7 +55,7 @@ and the like.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
Learn more about [Labels and Selectors](/docs/user-guide/labels/).
|
||||
Learn more about [Labels and Selectors](/docs/concepts/overview/working-with-objects/labels/).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/concept.md %}
|
||||
|
||||
@@ -56,7 +56,7 @@ In the `.yaml` file for the Kubernetes object you want to create, you'll need to
|
||||
* `kind` - What kind of object you want to create
|
||||
* `metadata` - Data that helps uniquely identify the object, including a `name` string, UID, and optional `namespace`
|
||||
|
||||
You'll also need to provide the object `spec` field. The precise format of the object `spec` is different for every Kubernetes object, and contains nested fields specific to that object. The [Kubernetes API reference](/docs/api/) can help you find the spec format for all of the objects you can create using Kubernetes.
|
||||
You'll also need to provide the object `spec` field. The precise format of the object `spec` is different for every Kubernetes object, and contains nested fields specific to that object. The [Kubernetes API reference](/docs/concepts/overview/kubernetes-api/) can help you find the spec format for all of the objects you can create using Kubernetes.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Objects of type `PodSecurityPolicy` govern the ability
|
||||
to make requests on a pod that affect the `SecurityContext` that will be
|
||||
applied to a pod and container.
|
||||
|
||||
See [PodSecurityPolicy proposal](https://git.k8s.io/community/contributors/design-proposals/auth/security-context-constraints.md) for more information.
|
||||
See [PodSecurityPolicy proposal](https://git.k8s.io/community/contributors/design-proposals/auth/pod-security-policy.md) for more information.
|
||||
|
||||
* TOC
|
||||
{:toc}
|
||||
|
||||
@@ -67,16 +67,16 @@ The following resource types are supported:
|
||||
|
||||
## Storage Resource Quota
|
||||
|
||||
You can limit the total sum of [storage resources](/docs/user-guide/persistent-volumes) that can be requested in a given namespace.
|
||||
You can limit the total sum of [storage resources](/docs/concepts/storage/persistent-volumes/) that can be requested in a given namespace.
|
||||
|
||||
In addition, you can limit consumption of storage resources based on associated storage-class.
|
||||
|
||||
| Resource Name | Description |
|
||||
| --------------------- | ----------------------------------------------------------- |
|
||||
| `requests.storage` | Across all persistent volume claims, the sum of storage requests cannot exceed this value. |
|
||||
| `persistentvolumeclaims` | The total number of [persistent volume claims](/docs/user-guide/persistent-volumes/#persistentvolumeclaims) that can exist in the namespace. |
|
||||
| `persistentvolumeclaims` | The total number of [persistent volume claims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) that can exist in the namespace. |
|
||||
| `<storage-class-name>.storageclass.storage.k8s.io/requests.storage` | Across all persistent volume claims associated with the storage-class-name, the sum of storage requests cannot exceed this value. |
|
||||
| `<storage-class-name>.storageclass.storage.k8s.io/persistentvolumeclaims` | Across all persistent volume claims associated with the storage-class-name, the total number of [persistent volume claims](/docs/user-guide/persistent-volumes/#persistentvolumeclaims) that can exist in the namespace. |
|
||||
| `<storage-class-name>.storageclass.storage.k8s.io/persistentvolumeclaims` | Across all persistent volume claims associated with the storage-class-name, the total number of [persistent volume claims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) that can exist in the namespace. |
|
||||
|
||||
For example, if an operator wants to quota storage with `gold` storage class separate from `bronze` storage class, the operator can
|
||||
define a quota as follows:
|
||||
@@ -99,7 +99,7 @@ are supported:
|
||||
| Resource Name | Description |
|
||||
| ------------------------------- | ------------------------------------------------- |
|
||||
| `configmaps` | The total number of config maps that can exist in the namespace. |
|
||||
| `persistentvolumeclaims` | The total number of [persistent volume claims](/docs/user-guide/persistent-volumes/#persistentvolumeclaims) that can exist in the namespace. |
|
||||
| `persistentvolumeclaims` | The total number of [persistent volume claims](/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) that can exist in the namespace. |
|
||||
| `pods` | The total number of pods in a non-terminal state that can exist in the namespace. A pod is in a terminal state if `status.phase in (Failed, Succeeded)` is true. |
|
||||
| `replicationcontrollers` | The total number of replication controllers that can exist in the namespace. |
|
||||
| `resourcequotas` | The total number of [resource quotas](/docs/admin/admission-controllers/#resourcequota) that can exist in the namespace. |
|
||||
@@ -244,4 +244,4 @@ See a [detailed example for how to use resource quota](/docs/tasks/administer-cl
|
||||
|
||||
## Read More
|
||||
|
||||
See [ResourceQuota design doc](https://git.k8s.io/community/contributors/design-proposals/admission_control_resource_quota.md) for more information.
|
||||
See [ResourceQuota design doc](https://git.k8s.io/community/contributors/design-proposals/resource-management/admission_control_resource_quota.md) for more information.
|
||||
|
||||
@@ -94,7 +94,7 @@ NAME ENDPOINTS AGE
|
||||
my-nginx 10.244.2.5:80,10.244.3.4:80 1m
|
||||
```
|
||||
|
||||
You should now be able to curl the nginx Service on `<CLUSTER-IP>:<PORT>` from any node in your cluster. Note that the Service IP is completely virtual, it never hits the wire, if you're curious about how this works you can read more about the [service proxy](/docs/user-guide/services/#virtual-ips-and-service-proxies).
|
||||
You should now be able to curl the nginx Service on `<CLUSTER-IP>:<PORT>` from any node in your cluster. Note that the Service IP is completely virtual, it never hits the wire, if you're curious about how this works you can read more about the [service proxy](/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies).
|
||||
|
||||
## Accessing the Service
|
||||
|
||||
|
||||
@@ -292,7 +292,7 @@ Please track the [L7 and Ingress proposal](https://github.com/kubernetes/kuberne
|
||||
|
||||
You can expose a Service in multiple ways that don't directly involve the Ingress resource:
|
||||
|
||||
* Use [Service.Type=LoadBalancer](/docs/user-guide/services/#type-loadbalancer)
|
||||
* Use [Service.Type=NodePort](/docs/user-guide/services/#type-nodeport)
|
||||
* Use [Service.Type=LoadBalancer](/docs/concepts/services-networking/service/#type-loadbalancer)
|
||||
* Use [Service.Type=NodePort](/docs/concepts/services-networking/service/#type-nodeport)
|
||||
* Use a [Port Proxy](https://git.k8s.io/contrib/for-demos/proxy-to-service)
|
||||
* Deploy the [Service loadbalancer](https://git.k8s.io/contrib/service-loadbalancer). This allows you to share a single IP among multiple Services and achieve more advanced loadbalancing through Service Annotations.
|
||||
|
||||
@@ -44,6 +44,10 @@ spec:
|
||||
- Egress
|
||||
ingress:
|
||||
- from:
|
||||
- ipBlock:
|
||||
cidr: 172.17.0.0/16
|
||||
except:
|
||||
- 172.17.1.0/24
|
||||
- namespaceSelector:
|
||||
matchLabels:
|
||||
project: myproject
|
||||
@@ -76,6 +80,11 @@ __ingress__: Each `NetworkPolicy` may include a list of whitelist `ingress` rule
|
||||
|
||||
__egress__: Each `NetworkPolicy` may include a list of whitelist `egress` rules. Each rule allows traffic which matches both the `to` and `ports` sections. The example policy contains a single rule, which matches traffic on a single port to any destination in `10.0.0.0/24`.
|
||||
|
||||
__ipBlock__: `ipBlock` describes a particular CIDR that is allowed to
|
||||
the pods matched by a NetworkPolicySpec's podSelector. The `except` entry
|
||||
is a slice of CIDRs that should not be included within an IP Block. Except
|
||||
values will be rejected if they are outside the CIDR range.
|
||||
|
||||
So, the example NetworkPolicy:
|
||||
|
||||
1. isolates "role=db" pods in the "default" namespace for both ingress and egress traffic (if they weren't already isolated)
|
||||
|
||||
@@ -120,7 +120,7 @@ subsets:
|
||||
NOTE: Endpoint IPs may not be loopback (127.0.0.0/8), link-local
|
||||
(169.254.0.0/16), or link-local multicast (224.0.0.0/24).
|
||||
|
||||
Accessing a `Service` without a selector works the same as if it had selector.
|
||||
Accessing a `Service` without a selector works the same as if it had a selector.
|
||||
The traffic will be routed to endpoints defined by the user (`1.2.3.4:9376` in
|
||||
this example).
|
||||
|
||||
@@ -176,7 +176,9 @@ or `Services` or `Pods`.
|
||||
|
||||
By default, the choice of backend is round robin. Client-IP based session affinity
|
||||
can be selected by setting `service.spec.sessionAffinity` to `"ClientIP"` (the
|
||||
default is `"None"`).
|
||||
default is `"None"`), and you can set the max session sticky time by setting the field
|
||||
`service.spec.sessionAffinityConfig.clientIP.timeoutSeconds` if you have already set
|
||||
`service.spec.sessionAffinity` to `"ClientIP"` (the default is "10800").
|
||||
|
||||
|
||||
|
||||
@@ -191,7 +193,9 @@ select a backend `Pod`.
|
||||
|
||||
By default, the choice of backend is random. Client-IP based session affinity
|
||||
can be selected by setting `service.spec.sessionAffinity` to `"ClientIP"` (the
|
||||
default is `"None"`).
|
||||
default is `"None"`), and you can set the max session sticky time by setting the field
|
||||
`service.spec.sessionAffinityConfig.clientIP.timeoutSeconds` if you have already set
|
||||
`service.spec.sessionAffinity` to `"ClientIP"` (the default is "10800").
|
||||
|
||||
As with the userspace proxy, the net result is that any traffic bound for the
|
||||
`Service`'s IP:Port is proxied to an appropriate backend without the clients
|
||||
|
||||
@@ -35,7 +35,7 @@ administrators. Kubernetes itself is unopinionated about what classes
|
||||
represent. This concept is sometimes called "profiles" in other storage
|
||||
systems.
|
||||
|
||||
Please see the [detailed walkthrough with working examples](/docs/user-guide/persistent-volumes/walkthrough/).
|
||||
Please see the [detailed walkthrough with working examples](/docs/tasks/configure-pod-container/configure-persistent-volume-storage/).
|
||||
|
||||
|
||||
## Lifecycle of a volume and claim
|
||||
@@ -334,7 +334,7 @@ Claims, like pods, can request specific quantities of a resource. In this case,
|
||||
|
||||
### Selector
|
||||
|
||||
Claims can specify a [label selector](/docs/user-guide/labels/#label-selectors) to further filter the set of volumes. Only the volumes whose labels match the selector can be bound to the claim. The selector can consist of two fields:
|
||||
Claims can specify a [label selector](/docs/concepts/overview/working-with-objects/labels/#label-selectors) to further filter the set of volumes. Only the volumes whose labels match the selector can be bound to the claim. The selector can consist of two fields:
|
||||
|
||||
* matchLabels - the volume must have a label with this value
|
||||
* matchExpressions - a list of requirements made by specifying key, list of values, and operator that relates the key and values. Valid operators include In, NotIn, Exists, and DoesNotExist.
|
||||
|
||||
@@ -462,7 +462,7 @@ Secrets are described in more detail [here](/docs/user-guide/secrets).
|
||||
### persistentVolumeClaim
|
||||
|
||||
A `persistentVolumeClaim` volume is used to mount a
|
||||
[PersistentVolume](/docs/user-guide/persistent-volumes) into a pod. PersistentVolumes are a
|
||||
[PersistentVolume](/docs/concepts/storage/persistent-volumes/) into a pod. PersistentVolumes are a
|
||||
way for users to "claim" durable storage (such as a GCE PersistentDisk or an
|
||||
iSCSI volume) without knowing the details of the particular cloud environment.
|
||||
|
||||
@@ -474,7 +474,7 @@ details.
|
||||
A `downwardAPI` volume is used to make downward API data available to applications.
|
||||
It mounts a directory and writes the requested data in plain text files.
|
||||
|
||||
See the [`downwardAPI` volume example](/docs/tasks/configure-pod-container/downward-api-volume-expose-pod-information/) for more details.
|
||||
See the [`downwardAPI` volume example](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/) for more details.
|
||||
|
||||
### projected
|
||||
|
||||
@@ -686,8 +686,8 @@ More details and examples can be found [here](https://github.com/kubernetes/exam
|
||||
### ScaleIO
|
||||
ScaleIO is a software-based storage platform that can use existing hardware to create clusters of scalable
|
||||
shared block networked storage. The ScaleIO volume plugin allows deployed pods to access existing ScaleIO
|
||||
volumes or it can dynamically provision new volumes, see
|
||||
[ScaleIO Persistent Volumes](/docs/user-guide/persistent-volumes/#scaleio).
|
||||
volumes (or it can dynamically provision new volumes for persistent volume claims, see
|
||||
[ScaleIO Persistent Volumes](/docs/concepts/storage/persistent-volumes/#scaleio)).
|
||||
|
||||
**Important:** You must have an existing ScaleIO cluster already setup and running with the volumes created before you can use them.
|
||||
{: .caution}
|
||||
|
||||
@@ -138,8 +138,8 @@ Some possible patterns for communicating with Pods in a DaemonSet are:
|
||||
|
||||
- **Push**: Pods in the DaemonSet are configured to send updates to another service, such
|
||||
as a stats database. They do not have clients.
|
||||
- **NodeIP and Known Port**: Pods in the DaemonSet can use a `hostPort`, so that the Pods are reachable via the node IPs. Clients know the list of node IPs somehow, and know the port by convention.
|
||||
- **DNS**: Create a [headless service](/docs/user-guide/services/#headless-services) with the same Pod selector,
|
||||
- **NodeIP and Known Port**: Pods in the DaemonSet can use a `hostPort`, so that the pods are reachable via the node IPs. Clients know the list of node IPs somehow, and know the port by convention.
|
||||
- **DNS**: Create a [headless service](/docs/concepts/services-networking/service/#headless-services) with the same pod selector,
|
||||
and then discover DaemonSets using the `endpoints` resource or retrieve multiple A records from
|
||||
DNS.
|
||||
- **Service**: Create a service with the same Pod selector, and use the service to reach a
|
||||
|
||||
@@ -92,9 +92,7 @@ $ kubectl logs $pods
|
||||
|
||||
## Writing a Job Spec
|
||||
|
||||
As with all other Kubernetes config, a Job needs `apiVersion`, `kind`, and `metadata` fields. For
|
||||
general information about working with config files, see [here](/docs/user-guide/simple-yaml),
|
||||
[here](/docs/user-guide/configuring-containers), and [here](/docs/user-guide/working-with-resources).
|
||||
As with all other Kubernetes config, a Job needs `apiVersion`, `kind`, and `metadata` fields.
|
||||
|
||||
A Job also needs a [`.spec` section](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status).
|
||||
|
||||
|
||||
@@ -0,0 +1,441 @@
|
||||
---
|
||||
approvers:
|
||||
- bprashanth
|
||||
- enisoc
|
||||
- erictune
|
||||
- foxish
|
||||
- janetkuo
|
||||
- kow3ns
|
||||
- smarterclayton
|
||||
title: PetSets
|
||||
---
|
||||
|
||||
__Warning:__ Starting in Kubernetes version 1.5, PetSet has been renamed to [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets). To use (or continue to use) PetSet in Kubernetes 1.5, you _must_ [migrate](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/) your existing PetSets to StatefulSets. For information on working with StatefulSet, see the tutorial on [how to run replicated stateful applications](/docs/tasks/run-application/run-replicated-stateful-application/).
|
||||
|
||||
__This document has been deprecated__, but can still apply if you're using
|
||||
Kubernetes version 1.4 or earlier.
|
||||
|
||||
* TOC
|
||||
{:toc}
|
||||
|
||||
__Terminology__
|
||||
|
||||
Throughout this doc you will see a few terms that are sometimes used interchangeably elsewhere, that might cause confusion. This section attempts to clarify them.
|
||||
|
||||
* Node: A single virtual or physical machine in a Kubernetes cluster.
|
||||
* Cluster: A group of nodes in a single failure domain, unless mentioned otherwise.
|
||||
* Persistent Volume Claim (PVC): A request for storage, typically a [persistent volume](/docs/tasks/configure-pod-container/configure-persistent-volume-storage/).
|
||||
* Host name: The hostname attached to the UTS namespace of the pod, i.e. the output of `hostname` in the pod.
|
||||
* DNS/Domain name: A *cluster local* domain name resolvable using standard methods (e.g.: [gethostbyname](http://linux.die.net/man/3/gethostbyname)).
|
||||
* Ordinality: the property of being "ordinal", or occupying a position in a sequence.
|
||||
* Pet: a single member of a PetSet; more generally, a stateful application.
|
||||
* Peer: a process running a server, capable of communicating with other such processes.
|
||||
|
||||
__Prerequisites__
|
||||
|
||||
This doc assumes familiarity with the following Kubernetes concepts:
|
||||
|
||||
* [Pods](/docs/user-guide/pods/single-container/)
|
||||
* [Cluster DNS](/docs/concepts/services-networking/dns-pod-service/)
|
||||
* [Headless Services](/docs/concepts/services-networking/service/#headless-services)
|
||||
* [Persistent Volumes](/docs/concepts/storage/persistent-volumes/)
|
||||
* [Persistent Volume Provisioning](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/persistent-volume-provisioning/README.md)
|
||||
|
||||
You need a working Kubernetes cluster at version >= 1.3, with a healthy DNS [cluster addon](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/README.md) at version >= 15. You cannot use PetSet on a hosted Kubernetes provider that has disabled `alpha` resources.
|
||||
|
||||
## What is a PetSet?
|
||||
|
||||
In Kubernetes, most pod management abstractions group them into disposable units of work that compose a micro service. Replication controllers for example, are designed with a weak guarantee - that there should be N replicas of a particular pod template. The pods are treated as stateless units, if one of them is unhealthy or superseded by a newer version, the system just disposes it.
|
||||
|
||||
```
|
||||
foo.default.svc.cluster.local
|
||||
|service|
|
||||
/ \
|
||||
| pod-asdf | | pod-zxcv |
|
||||
```
|
||||
|
||||
A PetSet, in contrast, is a group of stateful pods that require a stronger notion of identity. The document refers to these as "clustered applications".
|
||||
|
||||
```
|
||||
*.foo.default.svc.cluster.local
|
||||
| mysql-0 | <-> | mysql-1 |
|
||||
[pv 0] [pv 1]
|
||||
```
|
||||
|
||||
The co-ordinated deployment of clustered applications is notoriously hard. They require stronger notions of identity and membership, which they use in opaque internal protocols, and are especially prone to race conditions and deadlock. Traditionally administrators have deployed these applications by leveraging nodes as stable, long-lived entities with persistent storage and static ips.
|
||||
|
||||
The goal of PetSet is to decouple this dependency by assigning identities to individual instances of an application that are not anchored to the underlying physical infrastructure. For the rest of this document we will refer to these entities as "Pets". Our use of this term is predated by the "Pets vs Cattle" analogy.
|
||||
|
||||
__Relationship between Pets and Pods__: PetSet requires there be {0..N-1} Pets. Each Pet has a deterministic name - PetSetName-Ordinal, and a unique identity. Each Pet has at most one pod, and each PetSet has at most one Pet with a given identity.
|
||||
|
||||
## When to use PetSet?
|
||||
|
||||
A PetSet ensures that a specified number of "pets" with unique identities are running at any given time. The identity of a Pet is comprised of:
|
||||
|
||||
* a stable hostname, available in DNS
|
||||
* an ordinal index
|
||||
* stable storage: linked to the ordinal & hostname
|
||||
|
||||
These properties are useful in deploying stateful applications. However most stateful applications are also clustered, meaning they form groups with strict membership requirements that rely on stored state. PetSet also helps with the 2 most common problems encountered managing such clustered applications:
|
||||
|
||||
* discovery of peers for quorum
|
||||
* startup/teardown ordering
|
||||
|
||||
Only use PetSet if your application requires some or all of these properties. Managing pods as stateless replicas is vastly easier.
|
||||
|
||||
Example workloads for PetSet:
|
||||
|
||||
* Databases like MySQL or PostgreSQL that require a single instance attached to an NFS persistent volume at any time
|
||||
* Clustered software like Zookeeper, Etcd, or Elasticsearch that require stable membership.
|
||||
|
||||
## Alpha limitations
|
||||
|
||||
Before you start deploying applications as PetSets, there are a few limitations you should understand.
|
||||
|
||||
* PetSet is an *alpha* resource, not available in any Kubernetes release prior to 1.3.
|
||||
* As with all alpha/beta resources, it can be disabled through the `--runtime-config` option passed to the apiserver, and in fact most likely will be disabled on hosted offerings of Kubernetes.
|
||||
* The only updatable field on a PetSet is `replicas`.
|
||||
* The storage for a given pet must either be provisioned by a [persistent volume provisioner](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/staging/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. Note that persistent volume provisioning is also currently in alpha.
|
||||
* Deleting and/or scaling a PetSet down will *not* delete the volumes associated with the PetSet. This is done to ensure safety first, your data is more valuable than an auto purge of all related PetSet resources. **Deleting the Persistent Volume Claims will result in a deletion of the associated volumes**.
|
||||
* All PetSets currently require a "governing service", or a Service responsible for the network identity of the pets. The user is responsible for this Service.
|
||||
* Updating an existing PetSet is currently a manual process, meaning you either need to deploy a new PetSet with the new image version, or orphan Pets one by one, update their image, and join them back to the cluster.
|
||||
|
||||
## Example PetSet
|
||||
|
||||
We'll create a basic PetSet to demonstrate how Pets are assigned unique and "sticky" identities.
|
||||
|
||||
{% include code.html language="yaml" file="petset.yaml" ghlink="/docs/concepts/workloads/controllers/petset.yaml" %}
|
||||
|
||||
Saving this config into `petset.yaml` and submitting it to a Kubernetes cluster should create the defined PetSet and Pets it manages:
|
||||
|
||||
```shell
|
||||
$ kubectl create -f petset.yaml
|
||||
service "nginx" created
|
||||
petset "web" created
|
||||
```
|
||||
|
||||
## Pet Identity
|
||||
|
||||
The identity of a Pet sticks to it, regardless of which node it's (re) scheduled on. We can examine the identity of the pets we just created.
|
||||
|
||||
### Ordinal index
|
||||
|
||||
you should see 2 pods with predictable names formatted thus: `$(petset name)-$(ordinal index assigned by petset controller)`
|
||||
|
||||
```shell
|
||||
$ kubectl get po
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
web-0 1/1 Running 0 10m
|
||||
web-1 1/1 Running 0 10m
|
||||
```
|
||||
|
||||
### Stable storage
|
||||
|
||||
2 persistent volumes, one per pod. This is auto created by the PetSet based on the `volumeClaimTemplate` field
|
||||
|
||||
```shell
|
||||
$ kubectl get pv
|
||||
NAME CAPACITY ACCESSMODES STATUS CLAIM REASON AGE
|
||||
pvc-90234946-3717-11e6-a46e-42010af00002 1Gi RWO Bound default/www-web-0 11m
|
||||
pvc-902733c2-3717-11e6-a46e-42010af00002 1Gi RWO Bound default/www-web-1 11m
|
||||
```
|
||||
|
||||
### Network identity
|
||||
|
||||
The network identity has 2 parts. First, we created a headless Service that controls the domain within which we create Pets. The domain managed by this Service takes the form: `$(service name).$(namespace).svc.cluster.local`, where "cluster.local" is the [cluster domain](/docs/concepts/services-networking/dns-pod-service/). As each pet is created, it gets a matching DNS subdomain, taking the form: `$(petname).$(governing service domain)`, where the governing service is defined by the `serviceName` field on the PetSet.
|
||||
|
||||
Here are some examples of choices for Cluster Domain, Service name, PetSet name, and how that affects the DNS names for the Pets and the hostnames in the Pet's pods:
|
||||
|
||||
Cluster Domain | Service (ns/name) | PetSet (ns/name) | PetSet Domain | Pet DNS | Pet Hostname |
|
||||
-------------- | ----------------- | ----------------- | -------------- | ------- | ------------ |
|
||||
cluster.local | default/nginx | default/web | nginx.default.svc.cluster.local | web-{0..N-1}.nginx.default.svc.cluster.local | web-{0..N-1} |
|
||||
cluster.local | foo/nginx | foo/web | nginx.foo.svc.cluster.local | web-{0..N-1}.nginx.foo.svc.cluster.local | web-{0..N-1} |
|
||||
kube.local | foo/nginx | foo/web | nginx.foo.svc.kube.local | web-{0..N-1}.nginx.foo.svc.kube.local | web-{0..N-1} |
|
||||
|
||||
Note that Cluster Domain will be set to `cluster.local` unless [otherwise configured](https://github.com/kubernetes/kubernetes/blob/master/examples/cluster-dns/README.md).
|
||||
|
||||
Let's verify our assertion with a simple test.
|
||||
|
||||
```shell
|
||||
$ kubectl get svc
|
||||
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
nginx None <none> 80/TCP 12m
|
||||
...
|
||||
```
|
||||
|
||||
First, the PetSet provides a stable hostname:
|
||||
|
||||
```shell
|
||||
$ for i in 0 1; do kubectl exec web-$i -- sh -c 'hostname'; done
|
||||
web-0
|
||||
web-1
|
||||
```
|
||||
|
||||
And the hostname is linked to the in-cluster DNS address:
|
||||
|
||||
```shell
|
||||
$ kubectl run -i --tty --image busybox dns-test --restart=Never /bin/sh
|
||||
dns-test # nslookup web-0.nginx
|
||||
Server: 10.0.0.10
|
||||
Address 1: 10.0.0.10 kube-dns.kube-system.svc.cluster.local
|
||||
|
||||
Name: web-0.nginx
|
||||
Address 1: 10.180.3.5
|
||||
|
||||
dns-test # nslookup web-1.nginx
|
||||
Server: 10.0.0.10
|
||||
Address 1: 10.0.0.10 kube-dns.kube-system.svc.cluster.local
|
||||
|
||||
Name: web-1.nginx
|
||||
Address 1: 10.180.0.9
|
||||
```
|
||||
|
||||
The containers are running nginx webservers, which by default will look for an index.html file in `/usr/share/nginx/html/index.html`. That directory is backed by a `PersistentVolume` created by the PetSet. So let's write our hostname there:
|
||||
|
||||
```shell
|
||||
$ for i in 0 1; do
|
||||
kubectl exec web-$i -- sh -c 'echo $(hostname) > /usr/share/nginx/html/index.html';
|
||||
done
|
||||
```
|
||||
|
||||
And verify each webserver serves its own hostname:
|
||||
|
||||
```shell
|
||||
$ for i in 0 1; do kubectl exec -it web-$i -- curl localhost; done
|
||||
web-0
|
||||
web-1
|
||||
```
|
||||
|
||||
Now delete all pods in the petset:
|
||||
|
||||
```shell
|
||||
$ kubectl delete po -l app=nginx
|
||||
pod "web-0" deleted
|
||||
pod "web-1" deleted
|
||||
```
|
||||
|
||||
Wait for them to come back up, and try to retrieve the previously written hostname through the DNS name of the peer. They match, because the storage, DNS name, and hostname stick to the Pet no matter where it gets scheduled:
|
||||
|
||||
```shell
|
||||
$ kubectl exec -it web-1 -- curl web-0.nginx
|
||||
web-0
|
||||
$ kubectl exec -it web-0 -- curl web-1.nginx
|
||||
web-1
|
||||
```
|
||||
|
||||
## Peer discovery
|
||||
|
||||
A pet can piece together its own identity:
|
||||
|
||||
1. Use the [downward api](/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/) to find its pod name
|
||||
2. Run `hostname` to find its DNS name
|
||||
3. Run `mount` or `df` to find its volumes (usually this is unnecessary)
|
||||
|
||||
It's not necessary to "discover" the governing Service of a PetSet, since it's known at creation time you can simply pass it down through an [environment variable](/docs/user-guide/environment-guide).
|
||||
|
||||
Usually pets also need to find their peers. In the previous nginx example, we just used `kubectl` to get the names of existing pods, and as humans, we could tell which ones belonged to a given PetSet. Another way to find peers is by contacting the API server, just like `kubectl`, but that has several disadvantages (you end up implementing a Kubernetes specific init system that runs as pid 1 in your application container).
|
||||
|
||||
PetSet gives you a way to discover your peers using DNS records. To illustrate this we can use the previous example (note: one usually doesn't `apt-get` in a container).
|
||||
|
||||
```shell
|
||||
$ kubectl exec -it web-0 /bin/sh
|
||||
web-0 # apt-get update && apt-get install -y dnsutils
|
||||
...
|
||||
|
||||
web-0 # nslookup -type=srv nginx.default
|
||||
Server: 10.0.0.10
|
||||
Address: 10.0.0.10#53
|
||||
|
||||
nginx.default.svc.cluster.local service = 10 50 0 web-1.ub.default.svc.cluster.local.
|
||||
nginx.default.svc.cluster.local service = 10 50 0 web-0.ub.default.svc.cluster.local.
|
||||
```
|
||||
|
||||
## Updating a PetSet
|
||||
|
||||
You cannot update any field of the PetSet except `spec.replicas` and the `containers` in the podTemplate. Updating `spec.replicas` will scale the PetSet, updating `containers` will not have any effect till a Pet is deleted, at which time it is recreated with the modified podTemplate.
|
||||
|
||||
## Scaling a PetSet
|
||||
|
||||
You can scale a PetSet by updating the "replicas" field. Note however that the controller will only:
|
||||
|
||||
1. Create one pet at a time, in order from {0..N-1}, and wait till each one is in [Running and Ready](/docs/user-guide/pod-states) before creating the next
|
||||
2. Delete one pet at a time, in reverse order from {N-1..0}, and wait till each one is completely shutdown (past its [terminationGracePeriodSeconds](/docs/concepts/workloads/pods/pod/#termination-of-pods) before deleting the next
|
||||
|
||||
```shell
|
||||
$ kubectl get po
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
web-0 1/1 Running 0 30s
|
||||
web-1 1/1 Running 0 36s
|
||||
|
||||
$ kubectl patch petset web -p '{"spec":{"replicas":3}}'
|
||||
petset "web" patched
|
||||
|
||||
$ kubectl get po
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
web-0 1/1 Running 0 40s
|
||||
web-1 1/1 Running 0 46s
|
||||
web-2 1/1 Running 0 8s
|
||||
```
|
||||
|
||||
You can also use the `kubectl scale` command:
|
||||
|
||||
```shell
|
||||
$ kubectl get petset
|
||||
NAME DESIRED CURRENT AGE
|
||||
web 3 3 24m
|
||||
|
||||
$ kubectl scale petset web --replicas=5
|
||||
petset "web" scaled
|
||||
|
||||
$ kubectl get po --watch-only
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
web-0 1/1 Running 0 10m
|
||||
web-1 1/1 Running 0 27m
|
||||
web-2 1/1 Running 0 10m
|
||||
web-3 1/1 Running 0 3m
|
||||
web-4 0/1 ContainerCreating 0 48s
|
||||
|
||||
$ kubectl get petset web
|
||||
NAME DESIRED CURRENT AGE
|
||||
web 5 5 30m
|
||||
```
|
||||
|
||||
Note however, that scaling up to N and back down to M *will not* delete the volumes of the M-N pets, as described in the section on [deletion](#deleting-a-petset), i.e. scaling back up to M creates new pets that use the same volumes. To see this in action, scale the PetSet back down to 3:
|
||||
|
||||
```shell
|
||||
$ kubectl get po --watch-only
|
||||
web-4 1/1 Terminating 0 4m
|
||||
web-4 1/1 Terminating 0 4m
|
||||
web-3 1/1 Terminating 0 6m
|
||||
web-3 1/1 Terminating 0 6m
|
||||
```
|
||||
|
||||
Note that we still have 5 pvcs:
|
||||
|
||||
```shell
|
||||
$ kubectl get pvc
|
||||
NAME STATUS VOLUME CAPACITY ACCESSMODES AGE
|
||||
www-web-0 Bound pvc-42ca5cef-8113-11e6-82f6-42010af00002 1Gi RWO 32m
|
||||
www-web-1 Bound pvc-42de30af-8113-11e6-82f6-42010af00002 1Gi RWO 32m
|
||||
www-web-2 Bound pvc-ba416413-8115-11e6-82f6-42010af00002 1Gi RWO 14m
|
||||
www-web-3 Bound pvc-ba45f19c-8115-11e6-82f6-42010af00002 1Gi RWO 14m
|
||||
www-web-4 Bound pvc-ba47674a-8115-11e6-82f6-42010af00002 1Gi RWO 14m
|
||||
```
|
||||
|
||||
This allows you to upgrade the image of a petset and have it come back up with the same data, as described in the next section.
|
||||
|
||||
## Image upgrades
|
||||
|
||||
PetSet currently *does not* support automated image upgrade as noted in the section on [limitations](#alpha-limitations), however you can update the `image` field of any container in the podTemplate and delete Pets one by one, the PetSet controller will recreate it with the new image.
|
||||
|
||||
Edit the image on the PetSet to `gcr.io/google_containers/nginx-slim:0.7` and delete 1 Pet:
|
||||
|
||||
```shell{% raw %}
|
||||
$ for p in 0 1 2; do kubectl get po web-$p --template '{{range $i, $c := .spec.containers}}{{$c.image}}{{end}}'; echo; done
|
||||
gcr.io/google_containers/nginx-slim:0.8
|
||||
gcr.io/google_containers/nginx-slim:0.8
|
||||
gcr.io/google_containers/nginx-slim:0.8
|
||||
|
||||
$ kubectl delete po web-0
|
||||
pod "web-0" deleted
|
||||
|
||||
$ for p in 0 1 2; do kubectl get po web-$p --template '{{range $i, $c := .spec.containers}}{{$c.image}}{{end}}'; echo; done
|
||||
gcr.io/google_containers/nginx-slim:0.7
|
||||
gcr.io/google_containers/nginx-slim:0.8
|
||||
gcr.io/google_containers/nginx-slim:0.8
|
||||
{% endraw %}```
|
||||
|
||||
Delete the remaining 2:
|
||||
|
||||
```shell
|
||||
$ kubectl delete po web-1 web-2
|
||||
pod "web-1" deleted
|
||||
pod "web-2" deleted
|
||||
```
|
||||
|
||||
Wait till the PetSet is stable and check the images:
|
||||
|
||||
```shell{% raw %}
|
||||
$ for p in 0 1 2; do kubectl get po web-$p --template '{{range $i, $c := .spec.containers}}{{$c.image}}{{end}}'; echo; done
|
||||
gcr.io/google_containers/nginx-slim:0.7
|
||||
gcr.io/google_containers/nginx-slim:0.7
|
||||
gcr.io/google_containers/nginx-slim:0.7
|
||||
{% endraw %}```
|
||||
|
||||
## Deleting a PetSet
|
||||
|
||||
Deleting a PetSet through kubectl will scale it down to 0, thereby deleting all the Pets. If you wish to delete just the PetSet and not the Pets, use `--cascade=false`:
|
||||
|
||||
```shell
|
||||
$ kubectl delete -f petset.yaml --cascade=false
|
||||
petset "web" deleted
|
||||
|
||||
$ kubectl get po -l app=nginx
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
web-0 1/1 Running 0 21h
|
||||
web-1 1/1 Running 0 21h
|
||||
|
||||
$ kubectl delete po -l app=nginx
|
||||
pod "web-0" deleted
|
||||
pod "web-1" deleted
|
||||
```
|
||||
|
||||
Deleting the pods will *not* delete the volumes. Until we finalize the recycle policy for these volumes they will have to get cleaned up by an admin. This is to ensure that you have the chance to copy data off the volume before deleting it. Simply deleting the PVC after the pods have left the [terminating state](/docs/concepts/workloads/pods/pod/#termination-of-pods) should trigger deletion of the backing Persistent Volumes.
|
||||
|
||||
**Note: you will lose all your data once the PVC is deleted, do this with caution.**
|
||||
|
||||
```shell
|
||||
$ kubectl get po -l app=nginx
|
||||
$ kubectl get pvc -l app=nginx
|
||||
NAME STATUS VOLUME CAPACITY ACCESSMODES AGE
|
||||
www-web-0 Bound pvc-62d271cd-3822-11e6-b1b7-42010af00002 0 21h
|
||||
www-web-1 Bound pvc-62d6750e-3822-11e6-b1b7-42010af00002 0 21h
|
||||
|
||||
$ kubectl delete pvc -l app=nginx
|
||||
$ kubectl get pv
|
||||
```
|
||||
|
||||
If you simply want to clean everything:
|
||||
|
||||
```shell{% raw %}
|
||||
$ grace=$(kubectl get po web-0 --template '{{.spec.terminationGracePeriodSeconds}}')
|
||||
$ kubectl delete petset,po -l app=nginx
|
||||
$ sleep $grace
|
||||
$ kubectl delete pvc -l app=nginx
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
You might have noticed an `annotations` field in all the PetSets shown above.
|
||||
|
||||
```yaml
|
||||
annotations:
|
||||
pod.alpha.kubernetes.io/initialized: "true"
|
||||
```
|
||||
|
||||
This field is a debugging hook. It pauses any scale up/down operations on the entire PetSet. If you'd like to pause a petset after each pet, set it to `false` in the template, wait for each pet to come up, verify it has initialized correctly, and then set it to `true` using `kubectl edit` on the pet (setting it to `false` on *any pet* is enough to pause the PetSet). If you don't need it, create the PetSet with it set to `true` as shown. This is surprisingly useful in debugging bootstrapping race conditions.
|
||||
|
||||
## Future Work
|
||||
|
||||
There are a LOT of planned improvements since PetSet is still in alpha.
|
||||
|
||||
* Data gravity and local storage
|
||||
* Richer notification events
|
||||
* Public network identities
|
||||
* WAN cluster deployments (multi-AZ/region/cloud provider)
|
||||
* Image and node upgrades
|
||||
|
||||
This list goes on, if you have examples, ideas or thoughts, please contribute.
|
||||
|
||||
## Alternatives
|
||||
|
||||
Deploying one RC of size 1/Service per pod is a popular alternative, as is simply deploying a DaemonSet that utilizes the identity of a Node.
|
||||
|
||||
## Next steps
|
||||
|
||||
* Learn about [StatefulSet](/docs/concepts/abstractions/controllers/statefulsets/),
|
||||
the replacement for PetSet introduced in Kubernetes version 1.5.
|
||||
* [Migrate your existing PetSets to StatefulSets](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/)
|
||||
when upgrading to Kubernetes version 1.5 or higher.
|
||||
|
||||
@@ -12,7 +12,7 @@ ReplicaSet is the next-generation Replication Controller. The only difference
|
||||
between a _ReplicaSet_ and a
|
||||
[_Replication Controller_](/docs/concepts/workloads/controllers/replicationcontroller/) right now is
|
||||
the selector support. ReplicaSet supports the new set-based selector requirements
|
||||
as described in the [labels user guide](/docs/user-guide/labels/#label-selectors)
|
||||
as described in the [labels user guide](/docs/concepts/overview/working-with-objects/labels/#label-selectors)
|
||||
whereas a Replication Controller only supports equality-based selector requirements.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
@@ -129,7 +129,7 @@ different, and the `.metadata.labels` do not affect the behavior of the Replicat
|
||||
|
||||
### Pod Selector
|
||||
|
||||
The `.spec.selector` field is a [label selector](/docs/user-guide/labels/#label-selectors). A ReplicationController
|
||||
The `.spec.selector` field is a [label selector](/docs/concepts/overview/working-with-objects/labels/#label-selectors). A ReplicationController
|
||||
manages all the pods with labels that match the selector. It does not distinguish
|
||||
between pods that it created or deleted and pods that another person or process created or
|
||||
deleted. This allows the ReplicationController to be replaced without affecting the running pods.
|
||||
@@ -243,7 +243,7 @@ object](/docs/api-reference/{{page.version}}/#replicationcontroller-v1-core).
|
||||
|
||||
### ReplicaSet
|
||||
|
||||
[`ReplicaSet`](/docs/concepts/workloads/controllers/replicaset/) is the next-generation ReplicationController that supports the new [set-based label selector](/docs/user-guide/labels/#set-based-requirement).
|
||||
[`ReplicaSet`](/docs/concepts/workloads/controllers/replicaset/) is the next-generation ReplicationController that supports the new [set-based label selector](/docs/concepts/overview/working-with-objects/labels/#set-based-requirement).
|
||||
It’s mainly used by [`Deployment`](/docs/concepts/workloads/controllers/deployment/) as a mechanism to orchestrate pod creation, deletion and updates.
|
||||
Note that we recommend using Deployments instead of directly using Replica Sets, unless you require custom update orchestration or don’t require updates at all.
|
||||
|
||||
|
||||
@@ -163,7 +163,7 @@ The StatefulSet should not specify a `pod.Spec.TerminationGracePeriodSeconds` of
|
||||
|
||||
When the nginx example above is created, three Pods will be deployed in the order
|
||||
web-0, web-1, web-2. web-1 will not be deployed before web-0 is
|
||||
[Running and Ready](/docs/user-guide/pod-states), and web-2 will not be deployed until
|
||||
[Running and Ready](/docs/user-guide/pod-states/), and web-2 will not be deployed until
|
||||
web-1 is Running and Ready. If web-0 should fail, after web-1 is Running and Ready, but before
|
||||
web-2 is launched, web-2 will not be launched until web-0 is successfully relaunched and
|
||||
becomes Running and Ready.
|
||||
@@ -228,7 +228,7 @@ update, roll out a canary, or perform a phased roll out.
|
||||
{% endcapture %}
|
||||
{% capture whatsnext %}
|
||||
|
||||
* Follow an example of [deploying a stateful application](/docs/tutorials/stateful-application/basic-stateful-set).
|
||||
* Follow an example of [deploying a stateful application](/docs/tutorials/stateful-application/basic-stateful-set/).
|
||||
* Follow an example of [deploying Cassandra with Stateful Sets](/docs/tutorials/stateful-application/cassandra/).
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
Reference in New Issue
Block a user