Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Trying to update ReplicaSet Docs as per issue 12081 #12409

Merged
merged 9 commits into from
Feb 6, 2019
Merged

Trying to update ReplicaSet Docs as per issue 12081 #12409

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7f4f2e1
First draft of the updates to the ReplicaSet Docs
juandiegopalomino Jan 28, 2019
56d9ff2
Clearing up RC refs & explaining acquisition behavior
juandiegopalomino Jan 29, 2019
7e7a840
Mismatched link seems to have disappeared from preview
juandiegopalomino Jan 30, 2019
2a9dee2
refactoring link to example yaml
juandiegopalomino Jan 30, 2019
32ceb9c
adding pod-rs test case
juandiegopalomino Jan 30, 2019
bb185a6
Addressing Steve Perry's comments
juandiegopalomino Jan 31, 2019
f5d6396
Previous commit broke Pod example links due to casing
juandiegopalomino Jan 31, 2019
a08dd12
Forgot 1 comment
juandiegopalomino Jan 31, 2019
12d901c
Addressing grammar/syntax errors
juandiegopalomino Feb 1, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 44 additions & 16 deletions content/en/docs/concepts/workloads/controllers/replicaset.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,27 @@ weight: 10

{{% capture overview %}}

ReplicaSet is the next-generation Replication Controller. The only difference
ReplicaSet is a type of Replication Controller. The only difference
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ReplicaSet is a replacement for the old ReplicationController. So it's not really a type of replication controller. We can probably remove all mention of ReplicationController from this topic, except for one statement that mentions ReplicationController as a thing of the past.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

between a _ReplicaSet_ and a
[_Replication Controller_](/docs/concepts/workloads/controllers/replicationcontroller/) right now is
[_ReplicationController_](/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/concepts/overview/working-with-objects/labels/#label-selectors)
whereas a Replication Controller only supports equality-based selector requirements.


{{% /capture %}}

{{% capture body %}}

## How a ReplicaSet Works
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our style for headings is sentence case. So this heading would be "How a ReplicaSet works".

Several headings in this topic need to be converted to sentence case.


Just like a ReplicationController, a ReplicaSet's purpose is to maintain a stable set of replica Pods available at any
given time. It does so by creating and deleting a pods as needed to reach the desired number. The link a ReplicaSet has
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our style is to capitalize the names of Kubernetes objects. So Pod should be capitalized throughout the topic.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed

to its Pods is via the [metadata.ownerReferences][/docs/concepts/workloads/controllers/garbage-collection/#owners-and-dependents]
field, which specifies one resource dependent on another. All these _Pods_ have their owning ReplicaSet's identifying
information within their ownerReferences field. It's through this link that the ReplicaSet knows of the state of the
Pods it is maintaining and plan accordingly.

## How to use a ReplicaSet

Most [`kubectl`](/docs/user-guide/kubectl/) commands that support
Expand All @@ -32,9 +42,9 @@ instead. Also, the
imperative whereas Deployments are declarative, so we recommend using Deployments
through the [`rollout`](/docs/reference/generated/kubectl/kubectl-commands#rollout) command.

While ReplicaSets can be used independently, today it's mainly used by
[Deployments](/docs/concepts/workloads/controllers/deployment/) as a mechanism to orchestrate pod
creation, deletion and updates. When you use Deployments you don't have to worry
While ReplicaSets can be used independently, it could also be used by other resources. For example,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think rather than saying ReplicaSets can be used by Deployments, we should say that creating a Deployment is the recommended way of using a ReplicaSet.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

[Deployments](/docs/concepts/workloads/controllers/deployment/) use them as a mechanism to orchestrate
pod creation, deletion and updates. When you use Deployments you don't have to worry
about managing the ReplicaSets that they create. Deployments own and manage
their ReplicaSets.

Expand All @@ -53,13 +63,25 @@ use a Deployment instead, and define your application in the spec section.

{{< codenew file="controllers/frontend.yaml" >}}

Saving this manifest into `frontend.yaml` and submitting it to a Kubernetes cluster should
Saving this manifest into `frontend.yaml` and submitting it to a Kubernetes cluster will
create the defined ReplicaSet and the pods that it manages.

```shell
$ kubectl create -f http://k8s.io/examples/controllers/frontend.yaml
kubectl create -f http://k8s.io/examples/controllers/frontend.yaml
```

With the output of
```shell
replicaset.apps/frontend created
$ kubectl describe rs/frontend
```

You can then check on the state of the replicaset:
```shell
kubectl describe rs/frontend
```

And you will see output similar to:
```shell
Name: frontend
Namespace: default
Selector: tier=frontend,tier in (frontend)
Expand Down Expand Up @@ -88,7 +110,15 @@ Events:
1m 1m 1 {replicaset-controller } Normal SuccessfulCreate Created pod: frontend-qhloh
1m 1m 1 {replicaset-controller } Normal SuccessfulCreate Created pod: frontend-dnjpy
1m 1m 1 {replicaset-controller } Normal SuccessfulCreate Created pod: frontend-9si5l
$ kubectl get pods
```

And lastly checking on the pods brought up:
```shell
kubectl get pods
```

Will yield pod information similar to
```shell
NAME READY STATUS RESTARTS AGE
frontend-9si5l 1/1 Running 0 1m
frontend-dnjpy 1/1 Running 0 1m
Expand All @@ -104,8 +134,8 @@ A ReplicaSet also needs a [`.spec` section](https://git.k8s.io/community/contrib

### Pod Template

The `.spec.template` is the only required field of the `.spec`. The `.spec.template` is a
[pod template](/docs/concepts/workloads/pods/pod-overview/#pod-templates). It has exactly the same schema as a
The `.spec.template` is the only required field of the `.spec`. The `.spec.template` is a
[pod template](/docs/concepts/workloads/pods/pod-overview/#pod-templates). It has exactly the same schema as a
[pod](/docs/concepts/workloads/pods/pod/), except that it is nested and does not have an `apiVersion` or `kind`.

In addition to required fields of a pod, a pod template in a ReplicaSet must specify appropriate
Expand All @@ -130,8 +160,8 @@ be rejected by the API.

In Kubernetes 1.9 the API version `apps/v1` on the ReplicaSet kind is the current version and is enabled by default. The API version `apps/v1beta2` is deprecated.

Also you should not normally create any pods whose labels match this selector, either directly, with
another ReplicaSet, or with another controller such as a Deployment. If you do so, the ReplicaSet thinks that it
Also you should not normally create any pods whose labels match this selector, either directly, with
another ReplicaSet, or with another controller such as a Deployment. If you do so, the ReplicaSet thinks that it
created the other pods. Kubernetes does not stop you from doing this.

If you do end up with multiple controllers that have overlapping selectors, you
Expand Down Expand Up @@ -183,7 +213,7 @@ To update pods to a new spec in a controlled way, use a [rolling update](#rollin

### Isolating pods from a ReplicaSet

Pods may be removed from a ReplicaSet's target set by changing their labels. This technique may be used to remove pods
Pods may be removed from a ReplicaSet'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).

Expand Down Expand Up @@ -242,5 +272,3 @@ to a machine lifetime: the pod needs to be running on the machine before other p
safe to terminate when the machine is otherwise ready to be rebooted/shutdown.

{{% /capture %}}


2 changes: 2 additions & 0 deletions content/en/examples/controllers/frontend.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ spec:
# modify replicas according to your case
replicas: 3
selector:
# The matchLabels and matchExpressions achieve the same effect, and the redundancy
# is to demonstrate the usage of both equality-based and set-based selectors
matchLabels:
tier: frontend
matchExpressions:
Expand Down