From 7b44b7a3df523284c9f3c4cb76021088111831d7 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Tue, 11 Jun 2019 03:48:18 +0100 Subject: [PATCH] =?UTF-8?q?Downloadable=20examples=20for=20=E2=80=9CRun=20?= =?UTF-8?q?applications=E2=80=9D=20section=20(#14147)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Move examples ahead of commands that use them In support of https://github.com/kubernetes/website/issues/12740 The aim is to adopt a consistent style around providing downloadable examples for use with kubectl, etc. * Tweak wording for stateful app pod example * Adopt formatting conventions for code blocks * Move ReplicationController sample YAML to examples In aid of https://github.com/kubernetes/website/issues/12740 * Move PodDisruptionBudget sample YAML to examples In aid of https://github.com/kubernetes/website/issues/12740 * Update test schema for new examples * Use Unicode ellipsis in example Aim here is to make the elision more obvious --- .../tasks/run-application/configure-pdb.md | 26 +----- .../rolling-update-replication-controller.md | 88 +++++++------------ .../run-replicated-stateful-application.md | 16 ++-- .../controllers/replication-nginx-1.7.9.yaml | 16 ++++ .../controllers/replication-nginx-1.9.2.yaml | 21 +++++ content/en/examples/examples_test.go | 24 ++--- ...-pod-disruption-budget-maxunavailable.yaml | 9 ++ ...er-pod-disruption-budget-minavailable.yaml | 9 ++ 8 files changed, 111 insertions(+), 98 deletions(-) create mode 100644 content/en/examples/controllers/replication-nginx-1.7.9.yaml create mode 100644 content/en/examples/controllers/replication-nginx-1.9.2.yaml create mode 100644 content/en/examples/policy/zookeeper-pod-disruption-budget-maxunavailable.yaml create mode 100644 content/en/examples/policy/zookeeper-pod-disruption-budget-minavailable.yaml diff --git a/content/en/docs/tasks/run-application/configure-pdb.md b/content/en/docs/tasks/run-application/configure-pdb.md index 1ad39467f8..f5d735492d 100644 --- a/content/en/docs/tasks/run-application/configure-pdb.md +++ b/content/en/docs/tasks/run-application/configure-pdb.md @@ -151,31 +151,11 @@ You can find examples of pod disruption budgets defined below. They match pods w Example PDB Using minAvailable: -```yaml -apiVersion: policy/v1beta1 -kind: PodDisruptionBudget -metadata: - name: zk-pdb -spec: - minAvailable: 2 - selector: - matchLabels: - app: zookeeper -``` +{{< codenew file="policy/zookeeper-pod-disruption-budget-minavailable.yaml" >}} Example PDB Using maxUnavailable (Kubernetes 1.7 or higher): -```yaml -apiVersion: policy/v1beta1 -kind: PodDisruptionBudget -metadata: - name: zk-pdb -spec: - maxUnavailable: 1 - selector: - matchLabels: - app: zookeeper -``` +{{< codenew file="policy/zookeeper-pod-disruption-budget-maxunavailable.yaml" >}} For example, if the above `zk-pdb` object selects the pods of a StatefulSet of size 3, both specifications have the exact same meaning. The use of `maxUnavailable` is recommended as it @@ -227,7 +207,7 @@ metadata: creationTimestamp: 2017-08-28T02:38:26Z generation: 1 name: zk-pdb -... +… status: currentHealthy: 3 desiredHealthy: 3 diff --git a/content/en/docs/tasks/run-application/rolling-update-replication-controller.md b/content/en/docs/tasks/run-application/rolling-update-replication-controller.md index 1802465d11..823c70c7eb 100644 --- a/content/en/docs/tasks/run-application/rolling-update-replication-controller.md +++ b/content/en/docs/tasks/run-application/rolling-update-replication-controller.md @@ -37,8 +37,12 @@ A rolling update works by: Rolling updates are initiated with the `kubectl rolling-update` command: - kubectl rolling-update NAME \ - ([NEW_NAME] --image=IMAGE | -f FILE) +```shell +kubectl rolling-update NAME NEW_NAME --image=IMAGE:TAG + +# or read the configuration from a file +kubectl rolling-update NAME -f FILE +``` {{% /capture %}} @@ -50,7 +54,9 @@ Rolling updates are initiated with the `kubectl rolling-update` command: To initiate a rolling update using a configuration file, pass the new file to `kubectl rolling-update`: - kubectl rolling-update NAME -f FILE +```shell +kubectl rolling-update NAME -f FILE +``` The configuration file must: @@ -65,25 +71,29 @@ Replication controller configuration files are described in ### Examples - // Update pods of frontend-v1 using new replication controller data in frontend-v2.json. - kubectl rolling-update frontend-v1 -f frontend-v2.json +```shell +# Update pods of frontend-v1 using new replication controller data in frontend-v2.json. +kubectl rolling-update frontend-v1 -f frontend-v2.json - // Update pods of frontend-v1 using JSON data passed into stdin. - cat frontend-v2.json | kubectl rolling-update frontend-v1 -f - +# Update pods of frontend-v1 using JSON data passed into stdin. +cat frontend-v2.json | kubectl rolling-update frontend-v1 -f - +``` ## Updating the container image To update only the container image, pass a new image name and tag with the `--image` flag and (optionally) a new controller name: - kubectl rolling-update NAME [NEW_NAME] --image=IMAGE:TAG +```shell +kubectl rolling-update NAME NEW_NAME --image=IMAGE:TAG +``` The `--image` flag is only supported for single-container pods. Specifying `--image` with multi-container pods returns an error. -If no `NEW_NAME` is specified, a new replication controller is created with -a temporary name. Once the rollout is complete, the old controller is deleted, -and the new controller is updated to use the original name. +If you didn't specify a new name, this creates a new replication controller +with a temporary name. Once the rollout is complete, the old controller is +deleted, and the new controller is updated to use the original name. The update will fail if `IMAGE:TAG` is identical to the current value. For this reason, we recommend the use of versioned tags as @@ -94,11 +104,13 @@ Moreover, the use of `:latest` is not recommended, see ### Examples - // Update the pods of frontend-v1 to frontend-v2 - kubectl rolling-update frontend-v1 frontend-v2 --image=image:v2 +```shell +# Update the pods of frontend-v1 to frontend-v2 +kubectl rolling-update frontend-v1 frontend-v2 --image=image:v2 - // Update the pods of frontend, keeping the replication controller name - kubectl rolling-update frontend --image=image:v2 +# Update the pods of frontend, keeping the replication controller name +kubectl rolling-update frontend --image=image:v2 +``` ## Required and optional fields @@ -143,24 +155,7 @@ from the [`kubectl` reference](/docs/reference/generated/kubectl/kubectl-command Let's say you were running version 1.7.9 of nginx: -```yaml -apiVersion: v1 -kind: ReplicationController -metadata: - name: my-nginx -spec: - replicas: 5 - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.7.9 - ports: - - containerPort: 80 -``` +{{< codenew file="controllers/replication-nginx-1.7.9.yaml" >}} To update to version 1.9.1, you can use [`kubectl rolling-update --image`](https://git.k8s.io/community/contributors/design-proposals/cli/simple-rolling-update.md) to specify the new image: @@ -218,34 +213,13 @@ This is one example where the immutability of containers is a huge asset. If you need to update more than just the image (e.g., command arguments, environment variables), you can create a new replication controller, with a new name and distinguishing label value, such as: -```yaml -apiVersion: v1 -kind: ReplicationController -metadata: - name: my-nginx-v4 -spec: - replicas: 5 - selector: - app: nginx - deployment: v4 - template: - metadata: - labels: - app: nginx - deployment: v4 - spec: - containers: - - name: nginx - image: nginx:1.9.2 - args: ["nginx", "-T"] - ports: - - containerPort: 80 -``` +{{< codenew file="controllers/replication-nginx-1.9.2.yaml" >}} and roll it out: ```shell -kubectl rolling-update my-nginx -f ./nginx-rc.yaml +# Assuming you named the file "my-nginx.yaml" +kubectl rolling-update my-nginx -f ./my-nginx.yaml ``` ``` Created my-nginx-v4 diff --git a/content/en/docs/tasks/run-application/run-replicated-stateful-application.md b/content/en/docs/tasks/run-application/run-replicated-stateful-application.md index 1c74858f24..58c7ded5a8 100644 --- a/content/en/docs/tasks/run-application/run-replicated-stateful-application.md +++ b/content/en/docs/tasks/run-application/run-replicated-stateful-application.md @@ -59,12 +59,12 @@ and a StatefulSet. Create the ConfigMap from the following YAML configuration file: +{{< codenew file="application/mysql/mysql-configmap.yaml" >}} + ```shell kubectl apply -f https://k8s.io/examples/application/mysql/mysql-configmap.yaml ``` -{{< codenew file="application/mysql/mysql-configmap.yaml" >}} - This ConfigMap provides `my.cnf` overrides that let you independently control configuration on the MySQL master and slaves. In this case, you want the master to be able to serve replication logs to slaves @@ -79,12 +79,12 @@ based on information provided by the StatefulSet controller. Create the Services from the following YAML configuration file: +{{< codenew file="application/mysql/mysql-services.yaml" >}} + ```shell kubectl apply -f https://k8s.io/examples/application/mysql/mysql-services.yaml ``` -{{< codenew file="application/mysql/mysql-services.yaml" >}} - The Headless Service provides a home for the DNS entries that the StatefulSet controller creates for each Pod that's part of the set. Because the Headless Service is named `mysql`, the Pods are accessible by @@ -105,12 +105,12 @@ writes. Finally, create the StatefulSet from the following YAML configuration file: +{{< codenew file="application/mysql/mysql-statefulset.yaml" >}} + ```shell kubectl apply -f https://k8s.io/examples/application/mysql/mysql-statefulset.yaml ``` -{{< codenew file="application/mysql/mysql-statefulset.yaml" >}} - You can watch the startup progress by running: ```shell @@ -141,8 +141,8 @@ ordinal index. It waits until each Pod reports being Ready before starting the next one. In addition, the controller assigns each Pod a unique, stable name of the form -`-`. -In this case, that results in Pods named `mysql-0`, `mysql-1`, and `mysql-2`. +`-`, which results in Pods named `mysql-0`, +`mysql-1`, and `mysql-2`. The Pod template in the above StatefulSet manifest takes advantage of these properties to perform orderly startup of MySQL replication. diff --git a/content/en/examples/controllers/replication-nginx-1.7.9.yaml b/content/en/examples/controllers/replication-nginx-1.7.9.yaml new file mode 100644 index 0000000000..768ab92ca7 --- /dev/null +++ b/content/en/examples/controllers/replication-nginx-1.7.9.yaml @@ -0,0 +1,16 @@ +apiVersion: v1 +kind: ReplicationController +metadata: + name: my-nginx +spec: + replicas: 5 + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.7.9 + ports: + - containerPort: 80 diff --git a/content/en/examples/controllers/replication-nginx-1.9.2.yaml b/content/en/examples/controllers/replication-nginx-1.9.2.yaml new file mode 100644 index 0000000000..f92f2657ed --- /dev/null +++ b/content/en/examples/controllers/replication-nginx-1.9.2.yaml @@ -0,0 +1,21 @@ +apiVersion: v1 +kind: ReplicationController +metadata: + name: my-nginx-v4 +spec: + replicas: 5 + selector: + app: nginx + deployment: v4 + template: + metadata: + labels: + app: nginx + deployment: v4 + spec: + containers: + - name: nginx + image: nginx:1.9.2 + args: ["nginx", "-T"] + ports: + - containerPort: 80 diff --git a/content/en/examples/examples_test.go b/content/en/examples/examples_test.go index 1aabb6775c..279ade8f29 100644 --- a/content/en/examples/examples_test.go +++ b/content/en/examples/examples_test.go @@ -415,13 +415,15 @@ func TestExampleObjectSchemas(t *testing.T) { "configmap-multikeys": {&api.ConfigMap{}}, }, "controllers": { - "daemonset": {&apps.DaemonSet{}}, - "frontend": {&apps.ReplicaSet{}}, - "hpa-rs": {&autoscaling.HorizontalPodAutoscaler{}}, - "job": {&batch.Job{}}, - "replicaset": {&apps.ReplicaSet{}}, - "replication": {&api.ReplicationController{}}, - "nginx-deployment": {&apps.Deployment{}}, + "daemonset": {&apps.DaemonSet{}}, + "frontend": {&apps.ReplicaSet{}}, + "hpa-rs": {&autoscaling.HorizontalPodAutoscaler{}}, + "job": {&batch.Job{}}, + "replicaset": {&apps.ReplicaSet{}}, + "replication": {&api.ReplicationController{}}, + "replication-nginx-1.7.9": {&api.ReplicationController{}}, + "replication-nginx-1.9.2": {&api.ReplicationController{}}, + "nginx-deployment": {&apps.Deployment{}}, }, "debug": { "counter-pod": {&api.Pod{}}, @@ -523,9 +525,11 @@ func TestExampleObjectSchemas(t *testing.T) { "redis": {&api.Pod{}}, }, "policy": { - "privileged-psp": {&policy.PodSecurityPolicy{}}, - "restricted-psp": {&policy.PodSecurityPolicy{}}, - "example-psp": {&policy.PodSecurityPolicy{}}, + "privileged-psp": {&policy.PodSecurityPolicy{}}, + "restricted-psp": {&policy.PodSecurityPolicy{}}, + "example-psp": {&policy.PodSecurityPolicy{}}, + "zookeeper-pod-disruption-budget-maxunavailable": {&policy.PodDisruptionBudget{}}, + "zookeeper-pod-disruption-budget-minunavailable": {&policy.PodDisruptionBudget{}}, }, "service": { "nginx-service": {&api.Service{}}, diff --git a/content/en/examples/policy/zookeeper-pod-disruption-budget-maxunavailable.yaml b/content/en/examples/policy/zookeeper-pod-disruption-budget-maxunavailable.yaml new file mode 100644 index 0000000000..a62bef140f --- /dev/null +++ b/content/en/examples/policy/zookeeper-pod-disruption-budget-maxunavailable.yaml @@ -0,0 +1,9 @@ +apiVersion: policy/v1beta1 +kind: PodDisruptionBudget +metadata: + name: zk-pdb +spec: + maxUnavailable: 1 + selector: + matchLabels: + app: zookeeper diff --git a/content/en/examples/policy/zookeeper-pod-disruption-budget-minavailable.yaml b/content/en/examples/policy/zookeeper-pod-disruption-budget-minavailable.yaml new file mode 100644 index 0000000000..c4776ad4c0 --- /dev/null +++ b/content/en/examples/policy/zookeeper-pod-disruption-budget-minavailable.yaml @@ -0,0 +1,9 @@ +apiVersion: policy/v1beta1 +kind: PodDisruptionBudget +metadata: + name: zk-pdb +spec: + minAvailable: 2 + selector: + matchLabels: + app: zookeeper