ReplicationController [page]deterministic

> Note: A [`Deployment`](/docs/concepts/workloads/controllers/deployment/) that configures a [`ReplicaSet`](/docs/concepts/workloads/controllers/replicaset/) is now the recommended way to set up replication.

A _ReplicationController_ ensures that a specified number of pod replicas are running at any one time. In other words, a ReplicationController makes sure that a pod or a homogeneous set of pods is always up and available.

## How a ReplicationController works

If there are too many pods, the ReplicationController terminates the extra pods. If there are too few, the ReplicationController starts more pods. Unlike manually created pods, the pods maintained by a ReplicationController are automatically replaced if they fail, are deleted, or are terminated. For example, your pods are re-created on a node after disruptive maintenance such as a kernel upgrade. For this reason, you should use a ReplicationController even if your application requires only a single pod. A ReplicationController is similar to a process supervisor, but instead of supervising individual processes on a single node, the ReplicationController supervises multiple pods across multiple nodes.

ReplicationController is often abbreviated to "rc" in discussion, and as a shortcut in kubectl commands.

A simple case is to create one ReplicationController object to reliably run one instance of a Pod indefinitely. A more complex use case is to run several identical replicas of a replicated service, such as web servers.

## Running an example ReplicationController

This example ReplicationController config runs three copies of the nginx web server.

Run the example job by downloading the example file and then running this command:

```shell kubectl apply -f https://k8s.io/examples/controllers/replication.yaml ```

The output is similar to this:

``` replicationcontroller/nginx created ```

Check on the status of the ReplicationController using this command:

```shell kubectl describe replicationcontrollers/nginx ```

The output is similar to this:

``` Name: nginx Namespace: default Selector: app=nginx Labels: app=nginx Annotations: <none> Replicas: 3 current / 3 desired Pods Status: 0 Running / 3 Waiting / 0 Succeeded / 0 Failed Pod Template: Labels: app=nginx Containers: nginx: Image: nginx Port: 80/TCP Environment: <none> Mounts: <none> Volumes: <none> Events: FirstSeen LastSeen Count From SubobjectPath Type Reason Message --------- -------- ----- ---- ------------- ---- ------ ------- 20s 20s 1 {replication-controller } Normal SuccessfulCreate Created pod: nginx-qrm3m 20s 20s 1 {replication-controller } Normal SuccessfulCreate Created pod: nginx-3ntk0 20s 20s 1 {replication-controller } Normal SuccessfulCreate Created pod: nginx-4ok8v ```

Here, three pods are created, but none is running yet, perhaps because the image is being pulled. A little later, the same command may show:

```shell Pods Status: 3 Running / 0 Waiting / 0 Succeeded / 0 Failed ```

To list all the pods that belong to the ReplicationController in a machine readable form, you can use a command like this:

```shell pods=$(kubectl get pods --selector=app=nginx --output=jsonpath={.items..metadata.name}) echo $pods ```

The output is similar to this:

``` nginx-3ntk0 nginx-4ok8v nginx-qrm3m ```

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 specifies an expression with the name from each pod in the returned list.

## Writing a ReplicationControlle …(trimmed)