From 3ced6dbc2eaf8305e4ce39ebb0ca5d3d1cfcca30 Mon Sep 17 00:00:00 2001 From: Andrew Chen Date: Wed, 15 Mar 2017 15:54:00 -0700 Subject: [PATCH] Move Guide topic: Replication Controller Operations --- _data/tutorials.yml | 1 + ...run-stateless-ap-replication-controller.md | 230 ++++++++++++++++++ .../replication-controller/index.md | 2 +- .../replication-controller/operations.md | 228 +---------------- docs/user-guide/rolling-updates.md | 2 +- 5 files changed, 235 insertions(+), 228 deletions(-) create mode 100644 docs/tutorials/stateless-application/run-stateless-ap-replication-controller.md diff --git a/_data/tutorials.yml b/_data/tutorials.yml index 8ae5f09a3b..b0b173a82b 100644 --- a/_data/tutorials.yml +++ b/_data/tutorials.yml @@ -43,6 +43,7 @@ toc: - docs/tutorials/stateless-application/run-stateless-application-deployment.md - docs/tutorials/stateless-application/expose-external-ip-address-service.md - docs/tutorials/stateless-application/expose-external-ip-address.md + - docs/tutorials/stateless-application/run-stateless-ap-replication-controller.md - title: Stateful Applications section: - docs/tutorials/stateful-application/basic-stateful-set.md diff --git a/docs/tutorials/stateless-application/run-stateless-ap-replication-controller.md b/docs/tutorials/stateless-application/run-stateless-ap-replication-controller.md new file mode 100644 index 0000000000..53b0bce3fc --- /dev/null +++ b/docs/tutorials/stateless-application/run-stateless-ap-replication-controller.md @@ -0,0 +1,230 @@ +--- +assignees: +- bprashanth +title: Run Stateless AP Replication Controller +--- + +* TOC +{:toc} + +A replication controller ensures that a specified number of pod "replicas" are +running at any one time. If there are too many, it will kill some. If there are +too few, it will start more. + +## Creating a replication controller + +Replication controllers are created with `kubectl create`: + +```shell +$ kubectl create -f FILE +``` + +Where: + +* `-f FILE` or `--filename FILE` is a relative path to a + [configuration file](#replication_controller_configuration_file) in + either JSON or YAML format. + +You can use the [sample file](#sample_file) below to try a create request. + +A successful create request returns the name of the replication controller. To +view more details about the controller, see +[Viewing replication controllers](#viewing_replication_controllers) below. + +### Replication controller configuration file + +When creating a replication controller, you must point to a configuration file +as the value of the `-f` flag. The configuration +file can be formatted as YAML or as JSON, and supports the following fields: + +```json +{ + "apiVersion": "v1", + "kind": "ReplicationController", + "metadata": { + "name": "", + "labels": "", + "namespace": "" + }, + "spec": { + "replicas": int, + "selector": { + "":"" + }, + "template": { + "metadata": { + "labels": { + "":"" + } + }, + "spec": { + // See 'The spec schema' below + } + } + } +} +``` + +Required fields are: + +* `kind`: Always `ReplicationController`. +* `apiVersion`: Currently `v1`. +* `metadata`: An object containing: + * `name`: Required if `generateName` is not specified. The name of this + replication controller. It must be an + [RFC1035](https://www.ietf.org/rfc/rfc1035.txt) compatible value and be + unique within the namespace. + * `labels`: Optional. Labels are arbitrary key:value pairs that can be used + for grouping and targeting by other resources and services. + * `generateName`: Required if `name` is not set. A prefix to use to generate + a unique name. Has the same validation rules as `name`. + * `namespace`: Optional. The namespace of the replication controller. + * `annotations`: Optional. A map of string keys and values that can be used + by external tooling to store and retrieve arbitrary metadata about + objects. +* `spec`: The configuration for this replication controller. It must + contain: + * `replicas`: The number of pods to create and maintain. + * `selector`: A map of key:value pairs assigned to the set of pods that + this replication controller is responsible for managing. **This must** + **match the key:value pairs in the `template`'s `labels` field**. + * `template` contains: + * A `metadata` object with `labels` for the pod. + * The [`spec` schema](#the_spec_schema) that defines the pod + configuration. + +### The `spec` schema + +The `spec` schema (that is a child of `template`) is described in the locations +below: + +* The [`spec` schema](/docs/user-guide/pods/multi-container/#the_spec_schema) + section of the Creating Multi-Container Pods page covers required and + frequently-used fields. +* The entire `spec` schema is documented in the + [Kubernetes API reference](/docs/api-reference/v1/definitions/#_v1_podspec). + +### Sample file + +The following sample file creates 2 pods, each containing a single container +using the `redis` image. Port 80 on each container is opened. The replication +controller is tagged with the `serving` label. The pods are given the label +`frontend` and the `selector` is set to `frontend`, to indicate that the +controller should manage pods with the `frontend` label. + +```json +{ + "kind": "ReplicationController", + "apiVersion": "v1", + "metadata": { + "name": "frontend-controller", + "labels": { + "state": "serving" + } + }, + "spec": { + "replicas": 2, + "selector": { + "app": "frontend" + }, + "template": { + "metadata": { + "labels": { + "app": "frontend" + } + }, + "spec": { + "volumes": null, + "containers": [ + { + "name": "php-redis", + "image": "redis", + "ports": [ + { + "containerPort": 80, + "protocol": "TCP" + } + ], + "imagePullPolicy": "IfNotPresent" + } + ], + "restartPolicy": "Always", + "dnsPolicy": "ClusterFirst" + } + } + } +} +``` + +## Updating replication controller pods + +See [Rolling Updates](/docs/user-guide/rolling-updates/). + +## Resizing a replication controller + +See +[Resizing a replication controller](/docs/user-guide/resizing-a-replication-controller/). + +## Viewing replication controllers + +To list replication controllers on a cluster, use the `kubectl get` command: + +```shell +$ kubectl get rc +``` + +A successful get command returns all replication controllers on the cluster in +the specified or default namespace. For example: + +```shell +CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS +frontend php-redis redis name=frontend 2 +``` + +You can also use `get rc NAME` to return information about a specific +replication controller. + +To view detailed information about a specific replication controller, use the +`kubectl describe` command: + +```shell +$ kubectl describe rc NAME +``` + +A successful describe request returns details about the replication controller +including number and status of pods managed, and recent events: + +```conf +Name: frontend +Namespace: default +Image(s): gcr.io/google_samples/gb-frontend:v3 +Selector: name=frontend +Labels: name=frontend +Replicas: 2 current / 2 desired +Pods Status: 2 Running / 0 Waiting / 0 Succeeded / 0 Failed +Events: + FirstSeen LastSeen Count From SubobjectPath Reason Message + Fri, 06 Nov 2015 16:52:50 -0800 Fri, 06 Nov 2015 16:52:50 -0800 1 {replication-controller } SuccessfulCreate Created pod: frontend-gyx2h + Fri, 06 Nov 2015 16:52:50 -0800 Fri, 06 Nov 2015 16:52:50 -0800 1 {replication-controller } SuccessfulCreate Created pod: frontend-vc9w4 +``` + +## Deleting replication controllers + +To delete a replication controller as well as the pods that it controls, use +`kubectl delete`: + +```shell +$ kubectl delete rc NAME +``` + +By default, `kubectl delete rc` will resize the controller to zero (effectively +deleting all pods) before deleting it. + +To delete a replication controller without deleting its pods, use +`kubectl delete` and specify `--cascade=false`: + +```shell +$ kubectl delete rc NAME --cascade=false +``` + +A successful delete request returns the name of the deleted resource. diff --git a/docs/user-guide/replication-controller/index.md b/docs/user-guide/replication-controller/index.md index 0fee281cdb..813f4a96b7 100644 --- a/docs/user-guide/replication-controller/index.md +++ b/docs/user-guide/replication-controller/index.md @@ -261,4 +261,4 @@ safe to terminate when the machine is otherwise ready to be rebooted/shutdown. ## For more information -Read [ReplicationController Operations](/docs/user-guide/replication-controller/operations/). +Read [Run Stateless AP Replication Controller](/docs/tutorials/stateless-application/run-stateless-ap-replication-controller/). diff --git a/docs/user-guide/replication-controller/operations.md b/docs/user-guide/replication-controller/operations.md index b3bd6115cc..d3d4697400 100644 --- a/docs/user-guide/replication-controller/operations.md +++ b/docs/user-guide/replication-controller/operations.md @@ -1,230 +1,6 @@ --- -assignees: -- bprashanth title: Replication Controller Operations --- -* TOC -{:toc} - -A replication controller ensures that a specified number of pod "replicas" are -running at any one time. If there are too many, it will kill some. If there are -too few, it will start more. - -## Creating a replication controller - -Replication controllers are created with `kubectl create`: - -```shell -$ kubectl create -f FILE -``` - -Where: - -* `-f FILE` or `--filename FILE` is a relative path to a - [configuration file](#replication_controller_configuration_file) in - either JSON or YAML format. - -You can use the [sample file](#sample_file) below to try a create request. - -A successful create request returns the name of the replication controller. To -view more details about the controller, see -[Viewing replication controllers](#viewing_replication_controllers) below. - -### Replication controller configuration file - -When creating a replication controller, you must point to a configuration file -as the value of the `-f` flag. The configuration -file can be formatted as YAML or as JSON, and supports the following fields: - -```json -{ - "apiVersion": "v1", - "kind": "ReplicationController", - "metadata": { - "name": "", - "labels": "", - "namespace": "" - }, - "spec": { - "replicas": int, - "selector": { - "":"" - }, - "template": { - "metadata": { - "labels": { - "":"" - } - }, - "spec": { - // See 'The spec schema' below - } - } - } -} -``` - -Required fields are: - -* `kind`: Always `ReplicationController`. -* `apiVersion`: Currently `v1`. -* `metadata`: An object containing: - * `name`: Required if `generateName` is not specified. The name of this - replication controller. It must be an - [RFC1035](https://www.ietf.org/rfc/rfc1035.txt) compatible value and be - unique within the namespace. - * `labels`: Optional. Labels are arbitrary key:value pairs that can be used - for grouping and targeting by other resources and services. - * `generateName`: Required if `name` is not set. A prefix to use to generate - a unique name. Has the same validation rules as `name`. - * `namespace`: Optional. The namespace of the replication controller. - * `annotations`: Optional. A map of string keys and values that can be used - by external tooling to store and retrieve arbitrary metadata about - objects. -* `spec`: The configuration for this replication controller. It must - contain: - * `replicas`: The number of pods to create and maintain. - * `selector`: A map of key:value pairs assigned to the set of pods that - this replication controller is responsible for managing. **This must** - **match the key:value pairs in the `template`'s `labels` field**. - * `template` contains: - * A `metadata` object with `labels` for the pod. - * The [`spec` schema](#the_spec_schema) that defines the pod - configuration. - -### The `spec` schema - -The `spec` schema (that is a child of `template`) is described in the locations -below: - -* The [`spec` schema](/docs/user-guide/pods/multi-container/#the_spec_schema) - section of the Creating Multi-Container Pods page covers required and - frequently-used fields. -* The entire `spec` schema is documented in the - [Kubernetes API reference](/docs/api-reference/v1/definitions/#_v1_podspec). - -### Sample file - -The following sample file creates 2 pods, each containing a single container -using the `redis` image. Port 80 on each container is opened. The replication -controller is tagged with the `serving` label. The pods are given the label -`frontend` and the `selector` is set to `frontend`, to indicate that the -controller should manage pods with the `frontend` label. - -```json -{ - "kind": "ReplicationController", - "apiVersion": "v1", - "metadata": { - "name": "frontend-controller", - "labels": { - "state": "serving" - } - }, - "spec": { - "replicas": 2, - "selector": { - "app": "frontend" - }, - "template": { - "metadata": { - "labels": { - "app": "frontend" - } - }, - "spec": { - "volumes": null, - "containers": [ - { - "name": "php-redis", - "image": "redis", - "ports": [ - { - "containerPort": 80, - "protocol": "TCP" - } - ], - "imagePullPolicy": "IfNotPresent" - } - ], - "restartPolicy": "Always", - "dnsPolicy": "ClusterFirst" - } - } - } -} -``` - -## Updating replication controller pods - -See [Rolling Updates](/docs/user-guide/rolling-updates/). - -## Resizing a replication controller - -See -[Resizing a replication controller](/docs/user-guide/resizing-a-replication-controller/). - -## Viewing replication controllers - -To list replication controllers on a cluster, use the `kubectl get` command: - -```shell -$ kubectl get rc -``` - -A successful get command returns all replication controllers on the cluster in -the specified or default namespace. For example: - -```shell -CONTROLLER CONTAINER(S) IMAGE(S) SELECTOR REPLICAS -frontend php-redis redis name=frontend 2 -``` - -You can also use `get rc NAME` to return information about a specific -replication controller. - -To view detailed information about a specific replication controller, use the -`kubectl describe` command: - -```shell -$ kubectl describe rc NAME -``` - -A successful describe request returns details about the replication controller -including number and status of pods managed, and recent events: - -```conf -Name: frontend -Namespace: default -Image(s): gcr.io/google_samples/gb-frontend:v3 -Selector: name=frontend -Labels: name=frontend -Replicas: 2 current / 2 desired -Pods Status: 2 Running / 0 Waiting / 0 Succeeded / 0 Failed -Events: - FirstSeen LastSeen Count From SubobjectPath Reason Message - Fri, 06 Nov 2015 16:52:50 -0800 Fri, 06 Nov 2015 16:52:50 -0800 1 {replication-controller } SuccessfulCreate Created pod: frontend-gyx2h - Fri, 06 Nov 2015 16:52:50 -0800 Fri, 06 Nov 2015 16:52:50 -0800 1 {replication-controller } SuccessfulCreate Created pod: frontend-vc9w4 -``` - -## Deleting replication controllers - -To delete a replication controller as well as the pods that it controls, use -`kubectl delete`: - -```shell -$ kubectl delete rc NAME -``` - -By default, `kubectl delete rc` will resize the controller to zero (effectively -deleting all pods) before deleting it. - -To delete a replication controller without deleting its pods, use -`kubectl delete` and specify `--cascade=false`: - -```shell -$ kubectl delete rc NAME --cascade=false -``` - -A successful delete request returns the name of the deleted resource. +{% include user-guide-content-moved.md %} +[Run Stateless AP Replication Controller](/docs/tutorials/stateless-application/run-stateless-ap-replication-controller/) diff --git a/docs/user-guide/rolling-updates.md b/docs/user-guide/rolling-updates.md index 6bd3c469c8..d350f41719 100644 --- a/docs/user-guide/rolling-updates.md +++ b/docs/user-guide/rolling-updates.md @@ -99,7 +99,7 @@ as well as either: YAML format. The configuration file must specify a new top-level `id` value and include at least one of the existing `spec.selector` key:value pairs. See the - [Replication Controller Operations](/docs/user-guide/replication-controller/operations#replication-controller-configuration-file) + [Run Stateless AP Replication Controller](/docs/tutorials/stateless-application/run-stateless-ap-replication-controller/#replication-controller-configuration-file) page for details.