diff --git a/_data/reference.yml b/_data/reference.yml index 3e808060f4..34b198e196 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -220,6 +220,8 @@ toc: path: /docs/user-guide/jobs/ - title: Resource Quotas path: /docs/admin/resource-quota/ + - title: Replica Sets + path: /docs/user-guide/replicasets/ - title: Kubernetes Design Docs section: diff --git a/docs/user-guide/replicasets.md b/docs/user-guide/replicasets.md new file mode 100644 index 0000000000..ae755b69fa --- /dev/null +++ b/docs/user-guide/replicasets.md @@ -0,0 +1,94 @@ +--- +--- + +* TOC +{:toc} + +## What is a _Replica Set_? + +Replica Set is the next-generation Replication Controller. The only difference +between a _Replica Set_ and a +[_Replication Controller_](/docs/user-guide/replication-controller/) right now is +the selector support. Replica Set supports the new set-based selector requirements +as described in the [labels user guide](/docs/user-guide/labels/#label-selectors) +whereas a Replication Controller only supports equality-based selector requirements. + +Most [`kubectl`](/docs/user-guide/kubectl/kubectl/) commands that support +Replication Controllers also support Replica Sets. One exception is the +[`rolling-update`](/docs/user-guide/kubectl/kubectl_rolling-update/) command. If +you want the rolling update functionality please consider using Deployments +instead. Also, the +[`rolling-update`](/docs/user-guide/kubectl/kubectl_rolling-update/) command is +imperative whereas Deployments are declarative, so we recommend using Deployments +through the [`rollout`](/docs/user-guide/kubectl/kubectl_rollout/) command. + +While replica sets can be used independently, today it's mainly used by +[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 +about managing the replica sets that they create. Deployments own and manage +their replica sets. + +## When to use a Replica Set? + +A Replica Set 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 +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 +you require custom update orchestration or don't require updates at all. + +### Example + +{% 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 +create the defined replica set and the pods that it manages. + +```shell +$ kubectl create -f frontend.yaml +replicaset "frontend" created +$ kubectl describe rs/frontend +Name: frontend +Namespace: default +Image(s): gcr.io/google_samples/gb-frontend:v3 +Selector: tier=frontend,tier in (frontend) +Labels: app=guestbook,tier=frontend +Replicas: 3 current / 3 desired +Pods Status: 3 Running / 0 Waiting / 0 Succeeded / 0 Failed +No volumes. +Events: + FirstSeen LastSeen Count From SubobjectPath Type Reason Message + --------- -------- ----- ---- ------------- -------- ------ ------- + 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 +NAME READY STATUS RESTARTS AGE +frontend-9si5l 1/1 Running 0 1m +frontend-dnjpy 1/1 Running 0 1m +frontend-qhloh 1/1 Running 0 1m +``` + +## Replica Set as an Horizontal Pod Autoscaler target + +A Replica Set can also be a target for +[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 +the Replica Set we created in the previous example. + +{% 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 +create the defined HPA that autoscales the target Replica Set depending on the CPU usage +of the replicated pods. + +```shell +kubectl create -f hpa-rs.yaml +``` + +Alternatively, you can just use the `kubectl autoscale` command to acommplish the same +(and it's easier!) + +```shell +kubectl autoscale rs frontend +``` diff --git a/docs/user-guide/replicaset/frontend.yaml b/docs/user-guide/replicasets/frontend.yaml similarity index 80% rename from docs/user-guide/replicaset/frontend.yaml rename to docs/user-guide/replicasets/frontend.yaml index 878e10181e..2a2b4d13b9 100644 --- a/docs/user-guide/replicaset/frontend.yaml +++ b/docs/user-guide/replicasets/frontend.yaml @@ -12,11 +12,14 @@ spec: # modify it according to your case replicas: 3 # selector can be applied automatically - # from the labels in the pod template if not set - # selector: - # matchLabels: - # app: guestbook - # tier: frontend + # from the labels in the pod template if not set, + # but we are specifying the selector here to + # demonstrate its usage. + selector: + matchLabels: + tier: frontend + matchExpressions: + - {key: tier, operator: In, values: [frontend]} template: metadata: labels: diff --git a/docs/user-guide/replicasets/hpa-rs.yaml b/docs/user-guide/replicasets/hpa-rs.yaml new file mode 100644 index 0000000000..5b0fd054f8 --- /dev/null +++ b/docs/user-guide/replicasets/hpa-rs.yaml @@ -0,0 +1,13 @@ +apiVersion: autoscaling/v1 +kind: HorizontalPodAutoscaler +metadata: + name: frontend-scaler +spec: + scaleRef: + kind: ReplicaSet + name: frontend + subresource: scale + minReplicas: 3 + maxReplicas: 10 + cpuUtilization: + targetPercentage: 50 \ No newline at end of file diff --git a/docs/user-guide/replicaset/redis-slave.yaml b/docs/user-guide/replicasets/redis-slave.yaml similarity index 100% rename from docs/user-guide/replicaset/redis-slave.yaml rename to docs/user-guide/replicasets/redis-slave.yaml