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

Remove italics, correct CamelCase typos in titles

Browse Source
This commit is contained in:
Elijah C. Voigt
2016-12-16 15:51:48 -08:00
parent e43373ea65
commit f9d1cbc8fa
8 changed files with 92 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/daemons.md
+14 -15
View File
@@ -7,20 +7,20 @@ title: Daemon Sets
* TOC * TOC
{:toc} {:toc}
## What is a Daemon Set? ## What is a DaemonSet?
A _Daemon Set_ ensures that all (or some) nodes run a copy of a pod. As nodes are added to the A _DaemonSet_ ensures that all (or some) nodes run a copy of a pod. As nodes are added to the
cluster, pods are added to them. As nodes are removed from the cluster, those pods are garbage cluster, pods are added to them. As nodes are removed from the cluster, those pods are garbage
collected. Deleting a Daemon Set will clean up the pods it created. collected. Deleting a DaemonSet will clean up the pods it created.
Some typical uses of a Daemon Set are: Some typical uses of a DaemonSet are:
- running a cluster storage daemon, such as `glusterd`, `ceph`, on each node. - running a cluster storage daemon, such as `glusterd`, `ceph`, on each node.
- running a logs collection daemon on every node, such as `fluentd` or `logstash`. - running a logs collection daemon on every node, such as `fluentd` or `logstash`.
- running a node monitoring daemon on every node, such as [Prometheus Node Exporter]( - running a node monitoring daemon on every node, such as [Prometheus Node Exporter](
https://github.com/prometheus/node_exporter), `collectd`, New Relic agent, or Ganglia `gmond`. https://github.com/prometheus/node_exporter), `collectd`, New Relic agent, or Ganglia `gmond`.
In a simple case, one Daemon Set, covering all nodes, would be used for each type of daemon. In a simple case, one DaemonSet, covering all nodes, would be used for each type of daemon.
A more complex setup might use multiple DaemonSets would be used for a single type of daemon, A more complex setup might use multiple DaemonSets would be used for a single type of daemon,
but with different flags and/or different memory and cpu requests for different hardware types. but with different flags and/or different memory and cpu requests for different hardware types.
@@ -74,7 +74,7 @@ a node for testing.
If you specify a `.spec.template.spec.nodeSelector`, then the DaemonSet controller will If you specify a `.spec.template.spec.nodeSelector`, then the DaemonSet controller will
create pods on nodes which match that [node create pods on nodes which match that [node
selector](/docs/user-guide/node-selection/). selector](/docs/user-guide/node-selection/).
If you specify a `scheduler.alpha.kubernetes.io/affinity` annotation in `.spec.template.metadata.annotations`, If you specify a `scheduler.alpha.kubernetes.io/affinity` annotation in `.spec.template.metadata.annotations`,
then DaemonSet controller will create pods on nodes which match that [node affinity](../../user-guide/node-selection/#alpha-feature-in-kubernetes-v12-node-affinity). then DaemonSet controller will create pods on nodes which match that [node affinity](../../user-guide/node-selection/#alpha-feature-in-kubernetes-v12-node-affinity).
@@ -88,18 +88,17 @@ created by the Daemon controller have the machine already selected (`.spec.nodeN
when the pod is created, so it is ignored by the scheduler). Therefore: when the pod is created, so it is ignored by the scheduler). Therefore:
- the [`unschedulable`](/docs/admin/node/#manual-node-administration) field of a node is not respected - the [`unschedulable`](/docs/admin/node/#manual-node-administration) field of a node is not respected
by the daemon set controller. by the DaemonSet controller.
- daemon set controller can make pods even when the scheduler has not been started, which can help cluster - DaemonSet controller can make pods even when the scheduler has not been started, which can help cluster
bootstrap. bootstrap.
## Communicating with DaemonSet Pods ## Communicating with DaemonSet Pods
Some possible patterns for communicating with pods in a DaemonSet are: Some possible patterns for communicating with pods in a DaemonSet are:
- **Push**: Pods in the Daemon Set are configured to send updates to another service, such - **Push**: Pods in the DaemonSet are configured to send updates to another service, such
as a stats database. They do not have clients. as a stats database. They do not have clients.
- **NodeIP and Known Port**: Pods in the Daemon Set use a `hostPort`, so that the pods are reachable - **NodeIP and Known Port**: Pods in the DaemonSet use a `hostPort`, so that the pods are reachable via the node IPs. Clients know the list of nodes ips somehow, and know the port by convention.
via the node IPs. Clients knows the list of nodes ips somehow, and know the port by convention.
- **DNS**: Create a [headless service](/docs/user-guide/services/#headless-services) with the same pod selector, - **DNS**: Create a [headless service](/docs/user-guide/services/#headless-services) with the same pod selector,
and then discover DaemonSets using the `endpoints` resource or retrieve multiple A records from and then discover DaemonSets using the `endpoints` resource or retrieve multiple A records from
DNS. DNS.
@@ -126,7 +125,7 @@ You cannot update a DaemonSet.
Support for updating DaemonSets and controlled updating of nodes is planned. Support for updating DaemonSets and controlled updating of nodes is planned.
## Alternatives to Daemon Set ## Alternatives to DaemonSet
### Init Scripts ### Init Scripts
@@ -145,9 +144,9 @@ running such processes via a DaemonSet:
### Bare Pods ### Bare Pods
It is possible to create pods directly which specify a particular node to run on. However, It is possible to create pods directly which specify a particular node to run on. However,
a Daemon Set replaces pods that are deleted or terminated for any reason, such as in the case of a DaemonSet replaces pods that are deleted or terminated for any reason, such as in the case of
node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, you should node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, you should
use a Daemon Set rather than creating individual pods. use a DaemonSet rather than creating individual pods.
### Static Pods ### Static Pods
@@ -159,7 +158,7 @@ in cluster bootstrapping cases. Also, static pods may be deprecated in the futu
### Replication Controller ### Replication Controller
Daemon Set are similar to [Replication Controllers](/docs/user-guide/replication-controller) in that DaemonSet are similar to [Replication Controllers](/docs/user-guide/replication-controller) in that
they both create pods, and those pods have processes which are not expected to terminate (e.g. web servers, they both create pods, and those pods have processes which are not expected to terminate (e.g. web servers,
storage servers). storage servers).
docs/admin/sysctls.md
+1 -1
View File
@@ -9,7 +9,7 @@ assignees:
This document describes how sysctls are used within a Kubernetes cluster. This document describes how sysctls are used within a Kubernetes cluster.
## What is a _Sysctl_? ## What is a Sysctl?
In Linux, the sysctl interface allows an administrator to modify kernel In Linux, the sysctl interface allows an administrator to modify kernel
parameters at runtime. Parameters are available via the `/proc/sys/` virtual parameters at runtime. Parameters are available via the `/proc/sys/` virtual
docs/user-guide/cron-jobs.md
+1 -1
View File
@@ -9,7 +9,7 @@ title: Cron Jobs
* TOC * TOC
{:toc} {:toc}
## What is a Cron Job? ## What is a cron job?
A _Cron Job_ manages time based [Jobs](/docs/user-guide/jobs/), namely: A _Cron Job_ manages time based [Jobs](/docs/user-guide/jobs/), namely:
docs/user-guide/jobs.md
+1 -1
View File
@@ -8,7 +8,7 @@ title: Jobs
* TOC * TOC
{:toc} {:toc}
## What is a job? ## What is a Job?
A _job_ creates one or more pods and ensures that a specified number of them successfully terminate. A _job_ creates one or more pods and ensures that a specified number of them successfully terminate.
As pods successfully complete, the _job_ tracks the successful completions. When a specified number As pods successfully complete, the _job_ tracks the successful completions. When a specified number
docs/user-guide/pod-security-policy/index.md
+1 -1
View File
@@ -6,7 +6,7 @@ title: Pod Security Policies
Objects of type `podsecuritypolicy` govern the ability Objects of type `podsecuritypolicy` govern the ability
to make requests on a pod that affect the `SecurityContext` that will be to make requests on a pod that affect the `SecurityContext` that will be
applied to a pod and container. applied to a pod and container.
See [PodSecurityPolicy proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/security-context-constraints.md) for more information. See [PodSecurityPolicy proposal](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/proposals/security-context-constraints.md) for more information.
docs/user-guide/pods/index.md
+1 -1
View File
@@ -10,7 +10,7 @@ title: Pods
_pods_ are the smallest deployable units of computing that can be created and _pods_ are the smallest deployable units of computing that can be created and
managed in Kubernetes. managed in Kubernetes.
## What is a pod? ## What is a Pod?
A _pod_ (as in a pod of whales or pea pod) is a group of one or more containers A _pod_ (as in a pod of whales or pea pod) is a group of one or more containers
(such as Docker containers), the shared storage for those containers, and (such as Docker containers), the shared storage for those containers, and
docs/user-guide/replicasets.md
+19 -19
View File
@@ -9,17 +9,17 @@ title: Replica Sets
* TOC * TOC
{:toc} {:toc}
## What is a Replica Set? ## What is a ReplicaSet?
Replica Set is the next-generation Replication Controller. The only difference ReplicaSet is the next-generation Replication Controller. The only difference
between a _Replica Set_ and a between a _ReplicaSet_ and a
[_Replication Controller_](/docs/user-guide/replication-controller/) right now is [_Replication Controller_](/docs/user-guide/replication-controller/) right now is
the selector support. Replica Set supports the new set-based selector requirements 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/user-guide/labels/#label-selectors)
whereas a Replication Controller only supports equality-based selector requirements. whereas a Replication Controller only supports equality-based selector requirements.
Most [`kubectl`](/docs/user-guide/kubectl/) commands that support Most [`kubectl`](/docs/user-guide/kubectl/) commands that support
Replication Controllers also support Replica Sets. One exception is the Replication Controllers also support ReplicaSets. One exception is the
[`rolling-update`](/docs/user-guide/kubectl/kubectl_rolling-update/) command. If [`rolling-update`](/docs/user-guide/kubectl/kubectl_rolling-update/) command. If
you want the rolling update functionality please consider using Deployments you want the rolling update functionality please consider using Deployments
instead. Also, the instead. Also, the
@@ -27,21 +27,21 @@ instead. Also, the
imperative whereas Deployments are declarative, so we recommend using Deployments imperative whereas Deployments are declarative, so we recommend using Deployments
through the [`rollout`](/docs/user-guide/kubectl/kubectl_rollout/) command. through the [`rollout`](/docs/user-guide/kubectl/kubectl_rollout/) command.
While Replica Sets can be used independently, today it's mainly used by While ReplicaSets can be used independently, today it's mainly used by
[Deployments](/docs/user-guide/deployments/) as a mechanism to orchestrate pod [Deployments](/docs/user-guide/deployments/) as a mechanism to orchestrate pod
creation, deletion and updates. When you use Deployments you don't have to worry creation, deletion and updates. When you use Deployments you don't have to worry
about managing the Replica Sets that they create. Deployments own and manage about managing the ReplicaSets that they create. Deployments own and manage
their Replica Sets. their ReplicaSets.
## When to use a Replica Set? ## When to use a ReplicaSet?
A Replica Set ensures that a specified number of pod “replicas” are running at any given A ReplicaSet ensures that a specified number of pod “replicas” are running at any given
time. However, a Deployment is a higher-level concept that manages Replica Sets and time. However, a Deployment is a higher-level concept that manages ReplicaSets and
provides declarative updates to pods along with a lot of other useful features. provides declarative updates to pods along with a lot of other useful features.
Therefore, we recommend using Deployments instead of directly using Replica Sets, unless Therefore, we recommend using Deployments instead of directly using ReplicaSets, unless
you require custom update orchestration or don't require updates at all. you require custom update orchestration or don't require updates at all.
This actually means that you may never need to manipulate Replica Set objects: This actually means that you may never need to manipulate ReplicaSet objects:
use directly a Deployment and define your application in the spec section. use directly a Deployment and define your application in the spec section.
## Example ## Example
@@ -49,7 +49,7 @@ use directly a Deployment and define your application in the spec section.
{% include code.html language="yaml" file="replicasets/frontend.yaml" ghlink="/docs/user-guide/replicasets/frontend.yaml" %} {% include code.html language="yaml" file="replicasets/frontend.yaml" ghlink="/docs/user-guide/replicasets/frontend.yaml" %}
Saving this config into `frontend.yaml` and submitting it to a Kubernetes cluster should Saving this config into `frontend.yaml` and submitting it to a Kubernetes cluster should
create the defined Replica Set and the pods that it manages. create the defined ReplicaSet and the pods that it manages.
```shell ```shell
$ kubectl create -f frontend.yaml $ kubectl create -f frontend.yaml
@@ -76,18 +76,18 @@ frontend-dnjpy 1/1 Running 0 1m
frontend-qhloh 1/1 Running 0 1m frontend-qhloh 1/1 Running 0 1m
``` ```
## Replica Set as an Horizontal Pod Autoscaler target ## ReplicaSet as an Horizontal Pod Autoscaler target
A Replica Set can also be a target for A ReplicaSet can also be a target for
[Horizontal Pod Autoscalers (HPA)](/docs/user-guide/horizontal-pod-autoscaling/), [Horizontal Pod Autoscalers (HPA)](/docs/user-guide/horizontal-pod-autoscaling/),
i.e. a Replica Set can be auto-scaled by an HPA. Here is an example HPA targeting i.e. a ReplicaSet can be auto-scaled by an HPA. Here is an example HPA targeting
the Replica Set we created in the previous example. the ReplicaSet we created in the previous example.
{% include code.html language="yaml" file="replicasets/hpa-rs.yaml" ghlink="/docs/user-guide/replicasets/hpa-rs.yaml" %} {% include code.html language="yaml" file="replicasets/hpa-rs.yaml" ghlink="/docs/user-guide/replicasets/hpa-rs.yaml" %}
Saving this config into `hpa-rs.yaml` and submitting it to a Kubernetes cluster should Saving this config into `hpa-rs.yaml` and submitting it to a Kubernetes cluster should
create the defined HPA that autoscales the target Replica Set depending on the CPU usage create the defined HPA that autoscales the target ReplicaSet depending on the CPU usage
of the replicated pods. of the replicated pods.
```shell ```shell
docs/user-guide/replication-controller/index.md
+54 -54
View File
@@ -8,30 +8,30 @@ title: Replication Controller
* TOC * TOC
{:toc} {:toc}
## What is a replication controller? ## What is a ReplicationController?
A _replication controller_ ensures that a specified number of pod "replicas" are running at any one A _ReplicationController_ ensures that a specified number of pod "replicas" are running at any one
time. In other words, a replication controller makes sure that a pod or homogeneous set of pods are time. In other words, a ReplicationController makes sure that a pod or homogeneous set of pods are
always up and available. always up and available.
If there are too many pods, it will kill some. If there are too few, the If there are too many pods, it will kill some. If there are too few, the
replication controller will start more. Unlike manually created pods, the pods maintained by a ReplicationController will start more. Unlike manually created pods, the pods maintained by a
replication controller are automatically replaced if they fail, get deleted, or are terminated. ReplicationController are automatically replaced if they fail, get deleted, or are terminated.
For example, your pods get re-created on a node after disruptive maintenance such as a kernel upgrade. For example, your pods get re-created on a node after disruptive maintenance such as a kernel upgrade.
For this reason, we recommend that you use a replication controller even if your application requires For this reason, we recommend that you use a ReplicationController even if your application requires
only a single pod. You can think of a replication controller as something similar to a process supervisor, only a single pod. You can think of a ReplicationController as something similar to a process supervisor,
but rather than individual processes on a single node, the replication controller supervises multiple pods but rather than individual processes on a single node, the ReplicationController supervises multiple pods
across multiple nodes. across multiple nodes.
Replication Controller is often abbreviated to "rc" or "rcs" in discussion, and as a shortcut in ReplicationController is often abbreviated to "rc" or "rcs" in discussion, and as a shortcut in
kubectl commands. kubectl commands.
A simple case is to create 1 Replication Controller object in order to reliably run one instance of A simple case is to create 1 ReplicationController object in order to reliably run one instance of
a Pod indefinitely. A more complex use case is to run several identical replicas of a replicated a Pod indefinitely. A more complex use case is to run several identical replicas of a replicated
service, such as web servers. service, such as web servers.
## Running an example Replication Controller ## Running an example ReplicationController
Here is an example Replication Controller config. It runs 3 copies of the nginx web server. Here is an example ReplicationController config. It runs 3 copies of the nginx web server.
{% include code.html language="yaml" file="replication.yaml" ghlink="/docs/user-guide/replication.yaml" %} {% include code.html language="yaml" file="replication.yaml" ghlink="/docs/user-guide/replication.yaml" %}
@@ -42,7 +42,7 @@ $ kubectl create -f ./replication.yaml
replicationcontrollers/nginx replicationcontrollers/nginx
``` ```
Check on the status of the replication controller using this command: Check on the status of the ReplicationController using this command:
```shell ```shell
$ kubectl describe replicationcontrollers/nginx $ kubectl describe replicationcontrollers/nginx
@@ -79,18 +79,18 @@ echo $pods
nginx-3ntk0 nginx-4ok8v nginx-qrm3m nginx-3ntk0 nginx-4ok8v nginx-qrm3m
``` ```
Here, the selector is the same as the selector for the replication controller (seen in the Here, the selector is the same as the selector for the ReplicationController (seen in the
`kubectl describe` output, and in a different form in `replication.yaml`. The `--output=jsonpath` option `kubectl describe` output, and in a different form in `replication.yaml`. The `--output=jsonpath` option
specifies an expression that just gets the name from each pod in the returned list. specifies an expression that just gets the name from each pod in the returned list.
## Writing a Replication Controller Spec ## Writing a ReplicationController Spec
As with all other Kubernetes config, a Job needs `apiVersion`, `kind`, and `metadata` fields. For 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/), 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/). [here](/docs/user-guide/configuring-containers/), and [here](/docs/user-guide/working-with-resources/).
A Replication Controller also needs a [`.spec` section](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status). A ReplicationController also needs a [`.spec` section](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#spec-and-status).
### Pod Template ### Pod Template
@@ -100,28 +100,28 @@ The `.spec.template` is a [pod template](#pod-template). It has exactly
the same schema as a [pod](/docs/user-guide/pods/), except it is nested and does not have an `apiVersion` or the same schema as a [pod](/docs/user-guide/pods/), except it is nested and does not have an `apiVersion` or
`kind`. `kind`.
In addition to required fields for a Pod, a pod template in a Replication Controller must specify appropriate In addition to required fields for a Pod, a pod template in a ReplicationController must specify appropriate
labels (i.e. don't overlap with other controllers, see [pod selector](#pod-selector)) and an appropriate restart policy. labels (i.e. don't overlap with other controllers, see [pod selector](#pod-selector)) and an appropriate restart policy.
Only a [`.spec.template.spec.restartPolicy`](/docs/user-guide/pod-states/) equal to `Always` is allowed, which is the default Only a [`.spec.template.spec.restartPolicy`](/docs/user-guide/pod-states/) equal to `Always` is allowed, which is the default
if not specified. if not specified.
For local container restarts, replication controllers delegate to an agent on the node, For local container restarts, ReplicationControllers delegate to an agent on the node,
for example the [Kubelet](/docs/admin/kubelet/) or Docker. for example the [Kubelet](/docs/admin/kubelet/) or Docker.
### Labels on the Replication Controller ### Labels on the ReplicationController
The replication controller can itself have labels (`.metadata.labels`). Typically, you The ReplicationController can itself have labels (`.metadata.labels`). Typically, you
would set these the same as the `.spec.template.metadata.labels`; if `.metadata.labels` is not specified would set these the same as the `.spec.template.metadata.labels`; if `.metadata.labels` is not specified
then it is defaulted to `.spec.template.metadata.labels`. However, they are allowed to be then it is defaulted to `.spec.template.metadata.labels`. However, they are allowed to be
different, and the `.metadata.labels` do not affect the behavior of the replication controller. different, and the `.metadata.labels` do not affect the behavior of the ReplicationController.
### Pod Selector ### Pod Selector
The `.spec.selector` field is a [label selector](/docs/user-guide/labels/#label-selectors). A replication The `.spec.selector` field is a [label selector](/docs/user-guide/labels/#label-selectors). A replication
controller manages all the pods with labels which match the selector. It does not distinguish controller manages all the pods with labels which match the selector. It does not distinguish
between pods which it created or deleted versus pods which some other person or process created or between pods which it created or deleted versus pods which some other person or process created or
deleted. This allows the replication controller to be replaced without affecting the running pods. deleted. This allows the ReplicationController to be replaced without affecting the running pods.
If specified, the `.spec.template.metadata.labels` must be equal to the `.spec.selector`, or it will If specified, the `.spec.template.metadata.labels` must be equal to the `.spec.selector`, or it will
be rejected by the API. If `.spec.selector` is unspecified, it will be defaulted to be rejected by the API. If `.spec.selector` is unspecified, it will be defaulted to
@@ -144,54 +144,54 @@ shutdown, and a replacement starts early.
If you do not specify `.spec.replicas`, then it defaults to 1. If you do not specify `.spec.replicas`, then it defaults to 1.
## Working with Replication Controllers ## Working with ReplicationControllers
### Deleting a Replication Controller and its Pods ### Deleting a ReplicationController and its Pods
To delete a replication controller and all its pods, use [`kubectl To delete a ReplicationController and all its pods, use [`kubectl
delete`](/docs/user-guide/kubectl/kubectl_delete/). Kubectl will scale the replication controller to zero and wait delete`](/docs/user-guide/kubectl/kubectl_delete/). Kubectl will scale the ReplicationController to zero and wait
for it to delete each pod before deleting the replication controller itself. If this kubectl for it to delete each pod before deleting the ReplicationController itself. If this kubectl
command is interrupted, it can be restarted. command is interrupted, it can be restarted.
When using the REST API or go client library, you need to do the steps explicitly (scale replicas to When using the REST API or go client library, you need to do the steps explicitly (scale replicas to
0, wait for pod deletions, then delete the replication controller). 0, wait for pod deletions, then delete the ReplicationController).
### Deleting just a Replication Controller ### Deleting just a ReplicationController
You can delete a replication controller without affecting any of its pods. You can delete a ReplicationController without affecting any of its pods.
Using kubectl, specify the `--cascade=false` option to [`kubectl delete`](/docs/user-guide/kubectl/kubectl_delete/). Using kubectl, specify the `--cascade=false` option to [`kubectl delete`](/docs/user-guide/kubectl/kubectl_delete/).
When using the REST API or go client library, simply delete the replication controller object. When using the REST API or go client library, simply delete the ReplicationController object.
Once the original is deleted, you can create a new replication controller to replace it. As long Once the original is deleted, you can create a new ReplicationController to replace it. As long
as the old and new `.spec.selector` are the same, then the new one will adopt the old pods. as the old and new `.spec.selector` are the same, then the new one will adopt the old pods.
However, it will not make any effort to make existing pods match a new, different pod template. However, it will not make any effort to make existing pods match a new, different pod template.
To update pods to a new spec in a controlled way, use a [rolling update](#rolling-updates). To update pods to a new spec in a controlled way, use a [rolling update](#rolling-updates).
### Isolating pods from a Replication Controller ### Isolating pods from a ReplicationController
Pods may be removed from a replication controller's target set by changing their labels. This technique may be used to remove pods from service for debugging, data recovery, etc. Pods that are removed in this way will be replaced automatically (assuming that the number of replicas is not also changed). Pods may be removed from a ReplicationController's target set by changing their labels. This technique may be used to remove pods from service for debugging, data recovery, etc. Pods that are removed in this way will be replaced automatically (assuming that the number of replicas is not also changed).
## Common usage patterns ## Common usage patterns
### Rescheduling ### Rescheduling
As mentioned above, whether you have 1 pod you want to keep running, or 1000, a replication controller will ensure that the specified number of pods exists, even in the event of node failure or pod termination (e.g., due to an action by another control agent). As mentioned above, whether you have 1 pod you want to keep running, or 1000, a ReplicationController will ensure that the specified number of pods exists, even in the event of node failure or pod termination (e.g., due to an action by another control agent).
### Scaling ### Scaling
The replication controller makes it easy to scale the number of replicas up or down, either manually or by an auto-scaling control agent, by simply updating the `replicas` field. The ReplicationController makes it easy to scale the number of replicas up or down, either manually or by an auto-scaling control agent, by simply updating the `replicas` field.
### Rolling updates ### Rolling updates
The replication controller is designed to facilitate rolling updates to a service by replacing pods one-by-one. The ReplicationController is designed to facilitate rolling updates to a service by replacing pods one-by-one.
As explained in [#1353](http://issue.k8s.io/1353), the recommended approach is to create a new replication controller with 1 replica, scale the new (+1) and old (-1) controllers one by one, and then delete the old controller after it reaches 0 replicas. This predictably updates the set of pods regardless of unexpected failures. As explained in [#1353](http://issue.k8s.io/1353), the recommended approach is to create a new ReplicationController with 1 replica, scale the new (+1) and old (-1) controllers one by one, and then delete the old controller after it reaches 0 replicas. This predictably updates the set of pods regardless of unexpected failures.
Ideally, the rolling update controller would take application readiness into account, and would ensure that a sufficient number of pods were productively serving at any given time. Ideally, the rolling update controller would take application readiness into account, and would ensure that a sufficient number of pods were productively serving at any given time.
The two replication controllers would need to create pods with at least one differentiating label, such as the image tag of the primary container of the pod, since it is typically image updates that motivate rolling updates. The two ReplicationControllers would need to create pods with at least one differentiating label, such as the image tag of the primary container of the pod, since it is typically image updates that motivate rolling updates.
Rolling update is implemented in the client tool Rolling update is implemented in the client tool
[`kubectl rolling-update`](/docs/user-guide/kubectl/kubectl_rolling-update). Visit [`kubectl rolling-update` tutorial](/docs/user-guide/rolling-updates/) for more concrete examples. [`kubectl rolling-update`](/docs/user-guide/kubectl/kubectl_rolling-update). Visit [`kubectl rolling-update` tutorial](/docs/user-guide/rolling-updates/) for more concrete examples.
@@ -200,26 +200,26 @@ Rolling update is implemented in the client tool
In addition to running multiple releases of an application while a rolling update is in progress, it's common to run multiple releases for an extended period of time, or even continuously, using multiple release tracks. The tracks would be differentiated by labels. In addition to running multiple releases of an application while a rolling update is in progress, it's common to run multiple releases for an extended period of time, or even continuously, using multiple release tracks. The tracks would be differentiated by labels.
For instance, a service might target all pods with `tier in (frontend), environment in (prod)`. Now say you have 10 replicated pods that make up this tier. But you want to be able to 'canary' a new version of this component. You could set up a replication controller with `replicas` set to 9 for the bulk of the replicas, with labels `tier=frontend, environment=prod, track=stable`, and another replication controller with `replicas` set to 1 for the canary, with labels `tier=frontend, environment=prod, track=canary`. Now the service is covering both the canary and non-canary pods. But you can mess with the replication controllers separately to test things out, monitor the results, etc. For instance, a service might target all pods with `tier in (frontend), environment in (prod)`. Now say you have 10 replicated pods that make up this tier. But you want to be able to 'canary' a new version of this component. You could set up a ReplicationController with `replicas` set to 9 for the bulk of the replicas, with labels `tier=frontend, environment=prod, track=stable`, and another ReplicationController with `replicas` set to 1 for the canary, with labels `tier=frontend, environment=prod, track=canary`. Now the service is covering both the canary and non-canary pods. But you can mess with the ReplicationControllers separately to test things out, monitor the results, etc.
### Using Replication Controllers with Services ### Using ReplicationControllers with Services
Multiple replication controllers can sit behind a single service, so that, for example, some traffic Multiple ReplicationControllers can sit behind a single service, so that, for example, some traffic
goes to the old version, and some goes to the new version. goes to the old version, and some goes to the new version.
A replication controller will never terminate on its own, but it isn't expected to be as long-lived as services. Services may be composed of pods controlled by multiple replication controllers, and it is expected that many replication controllers may be created and destroyed over the lifetime of a service (for instance, to perform an update of pods that run the service). Both services themselves and their clients should remain oblivious to the replication controllers that maintain the pods of the services. A ReplicationController will never terminate on its own, but it isn't expected to be as long-lived as services. Services may be composed of pods controlled by multiple ReplicationControllers, and it is expected that many ReplicationControllers may be created and destroyed over the lifetime of a service (for instance, to perform an update of pods that run the service). Both services themselves and their clients should remain oblivious to the ReplicationControllers that maintain the pods of the services.
## Writing programs for Replication ## Writing programs for Replication
Pods created by a replication controller are intended to be fungible and semantically identical, though their configurations may become heterogeneous over time. This is an obvious fit for replicated stateless servers, but replication controllers can also be used to maintain availability of master-elected, sharded, and worker-pool applications. Such applications should use dynamic work assignment mechanisms, such as the [etcd lock module](https://coreos.com/docs/distributed-configuration/etcd-modules/) or [RabbitMQ work queues](https://www.rabbitmq.com/tutorials/tutorial-two-python.html), as opposed to static/one-time customization of the configuration of each pod, which is considered an anti-pattern. Any pod customization performed, such as vertical auto-sizing of resources (e.g., cpu or memory), should be performed by another online controller process, not unlike the replication controller itself. Pods created by a ReplicationController are intended to be fungible and semantically identical, though their configurations may become heterogeneous over time. This is an obvious fit for replicated stateless servers, but ReplicationControllers can also be used to maintain availability of master-elected, sharded, and worker-pool applications. Such applications should use dynamic work assignment mechanisms, such as the [etcd lock module](https://coreos.com/docs/distributed-configuration/etcd-modules/) or [RabbitMQ work queues](https://www.rabbitmq.com/tutorials/tutorial-two-python.html), as opposed to static/one-time customization of the configuration of each pod, which is considered an anti-pattern. Any pod customization performed, such as vertical auto-sizing of resources (e.g., cpu or memory), should be performed by another online controller process, not unlike the ReplicationController itself.
## Responsibilities of the replication controller ## Responsibilities of the ReplicationController
The replication controller simply ensures that the desired number of pods matches its label selector and are operational. Currently, only terminated pods are excluded from its count. In the future, [readiness](http://issue.k8s.io/620) and other information available from the system may be taken into account, we may add more controls over the replacement policy, and we plan to emit events that could be used by external clients to implement arbitrarily sophisticated replacement and/or scale-down policies. The ReplicationController simply ensures that the desired number of pods matches its label selector and are operational. Currently, only terminated pods are excluded from its count. In the future, [readiness](http://issue.k8s.io/620) and other information available from the system may be taken into account, we may add more controls over the replacement policy, and we plan to emit events that could be used by external clients to implement arbitrarily sophisticated replacement and/or scale-down policies.
The replication controller is forever constrained to this narrow responsibility. It itself will not perform readiness nor liveness probes. Rather than performing auto-scaling, it is intended to be controlled by an external auto-scaler (as discussed in [#492](http://issue.k8s.io/492)), which would change its `replicas` field. We will not add scheduling policies (e.g., [spreading](http://issue.k8s.io/367#issuecomment-48428019)) to the replication controller. Nor should it verify that the pods controlled match the currently specified template, as that would obstruct auto-sizing and other automated processes. Similarly, completion deadlines, ordering dependencies, configuration expansion, and other features belong elsewhere. We even plan to factor out the mechanism for bulk pod creation ([#170](http://issue.k8s.io/170)). The ReplicationController is forever constrained to this narrow responsibility. It itself will not perform readiness nor liveness probes. Rather than performing auto-scaling, it is intended to be controlled by an external auto-scaler (as discussed in [#492](http://issue.k8s.io/492)), which would change its `replicas` field. We will not add scheduling policies (e.g., [spreading](http://issue.k8s.io/367#issuecomment-48428019)) to the ReplicationController. Nor should it verify that the pods controlled match the currently specified template, as that would obstruct auto-sizing and other automated processes. Similarly, completion deadlines, ordering dependencies, configuration expansion, and other features belong elsewhere. We even plan to factor out the mechanism for bulk pod creation ([#170](http://issue.k8s.io/170)).
The replication controller is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, stop, scale, rolling-update) are proof-of-concept examples of this. For instance, we could imagine something like [Asgard](http://techblog.netflix.com/2012/06/asgard-web-based-cloud-management-and.html) managing replication controllers, auto-scalers, services, scheduling policies, canaries, etc. The ReplicationController is intended to be a composable building-block primitive. We expect higher-level APIs and/or tools to be built on top of it and other complementary primitives for user convenience in the future. The "macro" operations currently supported by kubectl (run, stop, scale, rolling-update) are proof-of-concept examples of this. For instance, we could imagine something like [Asgard](http://techblog.netflix.com/2012/06/asgard-web-based-cloud-management-and.html) managing ReplicationControllers, auto-scalers, services, scheduling policies, canaries, etc.
## API Object ## API Object
@@ -228,11 +228,11 @@ Replication controller is a top-level resource in the kubernetes REST API. More
API object can be found at: [ReplicationController API API object can be found at: [ReplicationController API
object](/docs/api-reference/v1/definitions/#_v1_replicationcontroller). object](/docs/api-reference/v1/definitions/#_v1_replicationcontroller).
## Alternatives to Replication Controller ## Alternatives to ReplicationController
### ReplicaSet ### ReplicaSet
[`ReplicaSet`](/docs/user-guide/replicasets/) is the next-generation Replication Controller that supports the new [set-based label selector](/docs/user-guide/labels/#set-based-requirement). [`ReplicaSet`](/docs/user-guide/replicasets/) is the next-generation ReplicationController that supports the new [set-based label selector](/docs/user-guide/labels/#set-based-requirement).
It’s mainly used by [`Deployment`](/docs/user-guide/deployments/) as a mechanism to orchestrate pod creation, deletion and updates. It’s mainly used by [`Deployment`](/docs/user-guide/deployments/) 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. 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.
@@ -244,20 +244,20 @@ because unlike `kubectl rolling-update`, they are declarative, server-side, and
### Bare Pods ### Bare Pods
Unlike in the case where a user directly created pods, a replication controller replaces pods that are deleted or terminated for any reason, such as in the case of node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, we recommend that you use a replication controller even if your application requires only a single pod. Think of it similarly to a process supervisor, only it supervises multiple pods across multiple nodes instead of individual processes on a single node. A replication controller delegates local container restarts to some agent on the node (e.g., Kubelet or Docker). Unlike in the case where a user directly created pods, a ReplicationController replaces pods that are deleted or terminated for any reason, such as in the case of node failure or disruptive node maintenance, such as a kernel upgrade. For this reason, we recommend that you use a ReplicationController even if your application requires only a single pod. Think of it similarly to a process supervisor, only it supervises multiple pods across multiple nodes instead of individual processes on a single node. A ReplicationController delegates local container restarts to some agent on the node (e.g., Kubelet or Docker).
### Job ### Job
Use a [`Job`](/docs/user-guide/jobs/) instead of a replication controller for pods that are expected to terminate on their own Use a [`Job`](/docs/user-guide/jobs/) instead of a ReplicationController for pods that are expected to terminate on their own
(i.e. batch jobs). (i.e. batch jobs).
### DaemonSet ### DaemonSet
Use a [`DaemonSet`](/docs/admin/daemons/) instead of a replication controller for pods that provide a Use a [`DaemonSet`](/docs/admin/daemons/) instead of a ReplicationController for pods that provide a
machine-level function, such as machine monitoring or machine logging. These pods have a lifetime that is tied machine-level function, such as machine monitoring or machine logging. These pods have a lifetime that is tied
to a machine lifetime: the pod needs to be running on the machine before other pods start, and are to a machine lifetime: the pod needs to be running on the machine before other pods start, and are
safe to terminate when the machine is otherwise ready to be rebooted/shutdown. safe to terminate when the machine is otherwise ready to be rebooted/shutdown.
## For more information ## For more information
Read [Replication Controller Operations](/docs/user-guide/replication-controller/operations/). Read [ReplicationController Operations](/docs/user-guide/replication-controller/operations/).