From de895fbf5a9e92c574844980f5f078ae1ac68ac4 Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Fri, 31 Mar 2017 13:10:28 -0700 Subject: [PATCH] Move Guide topic Replica Sets. (#3180) --- _data/concepts.yml | 1 + .../workloads/controllers/frontend.yaml | 45 ++++++++ .../workloads/controllers/hpa-rs.yaml | 11 ++ .../workloads/controllers/replicaset.md | 102 ++++++++++++++++++ docs/user-guide/replicasets.md | 95 +--------------- 5 files changed, 161 insertions(+), 93 deletions(-) create mode 100644 docs/concepts/workloads/controllers/frontend.yaml create mode 100644 docs/concepts/workloads/controllers/hpa-rs.yaml create mode 100644 docs/concepts/workloads/controllers/replicaset.md diff --git a/_data/concepts.yml b/_data/concepts.yml index 73cc8b2c34..0211d531e1 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -28,6 +28,7 @@ toc: - docs/concepts/workloads/pods/init-containers.md - title: Controllers section: + - docs/concepts/workloads/controllers/replicaset.md - docs/concepts/workloads/controllers/deployment.md - docs/concepts/workloads/controllers/statefulset.md - docs/concepts/workloads/controllers/petset.md diff --git a/docs/concepts/workloads/controllers/frontend.yaml b/docs/concepts/workloads/controllers/frontend.yaml new file mode 100644 index 0000000000..2a2b4d13b9 --- /dev/null +++ b/docs/concepts/workloads/controllers/frontend.yaml @@ -0,0 +1,45 @@ +apiVersion: extensions/v1beta1 +kind: ReplicaSet +metadata: + name: frontend + # these labels can be applied automatically + # from the labels in the pod template if not set + # labels: + # app: guestbook + # tier: frontend +spec: + # this replicas value is default + # modify it according to your case + replicas: 3 + # selector can be applied automatically + # 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: + app: guestbook + tier: frontend + spec: + containers: + - name: php-redis + image: gcr.io/google_samples/gb-frontend:v3 + resources: + requests: + cpu: 100m + memory: 100Mi + env: + - name: GET_HOSTS_FROM + value: dns + # If your cluster config does not include a dns service, then to + # instead access environment variables to find service host + # info, comment out the 'value: dns' line above, and uncomment the + # line below. + # value: env + ports: + - containerPort: 80 diff --git a/docs/concepts/workloads/controllers/hpa-rs.yaml b/docs/concepts/workloads/controllers/hpa-rs.yaml new file mode 100644 index 0000000000..a8388530dc --- /dev/null +++ b/docs/concepts/workloads/controllers/hpa-rs.yaml @@ -0,0 +1,11 @@ +apiVersion: autoscaling/v1 +kind: HorizontalPodAutoscaler +metadata: + name: frontend-scaler +spec: + scaleTargetRef: + kind: ReplicaSet + name: frontend + minReplicas: 3 + maxReplicas: 10 + targetCPUUtilizationPercentage: 50 diff --git a/docs/concepts/workloads/controllers/replicaset.md b/docs/concepts/workloads/controllers/replicaset.md new file mode 100644 index 0000000000..1742e57479 --- /dev/null +++ b/docs/concepts/workloads/controllers/replicaset.md @@ -0,0 +1,102 @@ +--- +assignees: +- Kashomon +- bprashanth +- madhusudancs +title: Replica Sets +--- + +* TOC +{:toc} + +## What is a ReplicaSet? + +ReplicaSet is the next-generation Replication Controller. The only difference +between a _ReplicaSet_ and a +[_Replication Controller_](/docs/user-guide/replication-controller/) 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) +whereas a Replication Controller only supports equality-based selector requirements. + +Most [`kubectl`](/docs/user-guide/kubectl/) commands that support +Replication Controllers also support ReplicaSets. 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 ReplicaSets 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 ReplicaSets that they create. Deployments own and manage +their ReplicaSets. + +## When to use a ReplicaSet? + +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 ReplicaSets and +provides declarative updates to pods along with a lot of other useful features. +Therefore, we recommend using Deployments instead of directly using ReplicaSets, unless +you require custom update orchestration or don't require updates at all. + +This actually means that you may never need to manipulate ReplicaSet objects: +use directly a Deployment and define your application in the spec section. + +## Example + +{% include code.html language="yaml" file="frontend.yaml" ghlink="/docs/concepts/workloads/controllers/frontend.yaml" %} + +Saving this config into `frontend.yaml` and submitting it to a Kubernetes cluster should +create the defined ReplicaSet 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 +``` + +## ReplicaSet as an Horizontal Pod Autoscaler target + +A ReplicaSet can also be a target for +[Horizontal Pod Autoscalers (HPA)](/docs/user-guide/horizontal-pod-autoscaling/), +i.e. a ReplicaSet can be auto-scaled by an HPA. Here is an example HPA targeting +the ReplicaSet we created in the previous example. + +{% include code.html language="yaml" file="hpa-rs.yaml" ghlink="/docs/concepts/workloads/controllers/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 ReplicaSet 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 accomplish the same +(and it's easier!) + +```shell +kubectl autoscale rs frontend +``` diff --git a/docs/user-guide/replicasets.md b/docs/user-guide/replicasets.md index 3c40a47b3e..9a53a5ecff 100644 --- a/docs/user-guide/replicasets.md +++ b/docs/user-guide/replicasets.md @@ -6,97 +6,6 @@ assignees: title: Replica Sets --- -* TOC -{:toc} +{% include user-guide-content-moved.md %} -## What is a ReplicaSet? - -ReplicaSet is the next-generation Replication Controller. The only difference -between a _ReplicaSet_ and a -[_Replication Controller_](/docs/user-guide/replication-controller/) 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) -whereas a Replication Controller only supports equality-based selector requirements. - -Most [`kubectl`](/docs/user-guide/kubectl/) commands that support -Replication Controllers also support ReplicaSets. 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 ReplicaSets 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 ReplicaSets that they create. Deployments own and manage -their ReplicaSets. - -## When to use a ReplicaSet? - -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 ReplicaSets and -provides declarative updates to pods along with a lot of other useful features. -Therefore, we recommend using Deployments instead of directly using ReplicaSets, unless -you require custom update orchestration or don't require updates at all. - -This actually means that you may never need to manipulate ReplicaSet objects: -use directly a Deployment and define your application in the spec section. - -## 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 ReplicaSet 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 -``` - -## ReplicaSet as an Horizontal Pod Autoscaler target - -A ReplicaSet can also be a target for -[Horizontal Pod Autoscalers (HPA)](/docs/user-guide/horizontal-pod-autoscaling/), -i.e. a ReplicaSet can be auto-scaled by an HPA. Here is an example HPA targeting -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" %} - - -Saving this config into `hpa-rs.yaml` and submitting it to a Kubernetes cluster should -create the defined HPA that autoscales the target ReplicaSet 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 accomplish the same -(and it's easier!) - -```shell -kubectl autoscale rs frontend -``` +[ReplicaSets](/docs/concepts/workloads/controllers/replicaset/)