Skip to content

Commit a84bdb6

Browse files
tengqmtengqm
committed
Move labels discussion back to its concept page
The discussion about "managing labels effectively" and "updating labels" are currently difficult to find. They are supposed to be part of the labels concept page. This PR moves this two sections there and adjusts the links where they were pointed at.
1 parent 37fe704 commit a84bdb6

File tree

4 files changed

+105
-105
lines changed

4 files changed

+105
-105
lines changed

‎content/en/docs/concepts/cluster-administration/manage-deployment.md

+2-102
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,6 @@ weight: 40
1010

1111
You've deployed your application and exposed it via a service. Now what? Kubernetes provides a
1212
number of tools to help you manage your application deployment, including scaling and updating.
13-
Among the features that we will discuss in more depth are
14-
[configuration files](/docs/concepts/configuration/overview/) and
15-
[labels](/docs/concepts/overview/working-with-objects/labels/).
1613

1714
<!-- body -->
1815

@@ -176,71 +173,10 @@ persistentvolumeclaim/my-pvc created
176173
If you're interested in learning more about `kubectl`, go ahead and read
177174
[Command line tool (kubectl)](/docs/reference/kubectl/).
178175

179-
## Using labels effectively
180-
181-
The examples we've used so far apply at most a single label to any resource. There are many
182-
scenarios where multiple labels should be used to distinguish sets from one another.
183-
184-
For instance, different applications would use different values for the `app` label, but a
185-
multi-tier application, such as the [guestbook example](https://github.com/kubernetes/examples/tree/master/guestbook/),
186-
would additionally need to distinguish each tier. The frontend could carry the following labels:
187-
188-
```yaml
189-
labels:
190-
app: guestbook
191-
tier: frontend
192-
```
193-
194-
while the Redis master and slave would have different `tier` labels, and perhaps even an
195-
additional `role` label:
196-
197-
```yaml
198-
labels:
199-
app: guestbook
200-
tier: backend
201-
role: master
202-
```
203-
204-
and
205-
206-
```yaml
207-
labels:
208-
app: guestbook
209-
tier: backend
210-
role: slave
211-
```
212-
213-
The labels allow us to slice and dice our resources along any dimension specified by a label:
214-
215-
```shell
216-
kubectl apply -f examples/guestbook/all-in-one/guestbook-all-in-one.yaml
217-
kubectl get pods -Lapp -Ltier -Lrole
218-
```
219-
220-
```none
221-
NAME READY STATUS RESTARTS AGE APP TIER ROLE
222-
guestbook-fe-4nlpb 1/1 Running 0 1m guestbook frontend <none>
223-
guestbook-fe-ght6d 1/1 Running 0 1m guestbook frontend <none>
224-
guestbook-fe-jpy62 1/1 Running 0 1m guestbook frontend <none>
225-
guestbook-redis-master-5pg3b 1/1 Running 0 1m guestbook backend master
226-
guestbook-redis-slave-2q2yf 1/1 Running 0 1m guestbook backend slave
227-
guestbook-redis-slave-qgazl 1/1 Running 0 1m guestbook backend slave
228-
my-nginx-divi2 1/1 Running 0 29m nginx <none> <none>
229-
my-nginx-o0ef1 1/1 Running 0 29m nginx <none> <none>
230-
```
231-
232-
```shell
233-
kubectl get pods -lapp=guestbook,role=slave
234-
```
235-
236-
```none
237-
NAME READY STATUS RESTARTS AGE
238-
guestbook-redis-slave-2q2yf 1/1 Running 0 3m
239-
guestbook-redis-slave-qgazl 1/1 Running 0 3m
240-
```
241-
242176
## Canary deployments
243177

178+
<!--TODO: make a task out of this for canary deployment, ref #42786-->
179+
244180
Another scenario where multiple labels are needed is to distinguish deployments of different
245181
releases or configurations of the same component. It is common practice to deploy a *canary* of a
246182
new application release (specified via image tag in the pod template) side by side with the
@@ -296,42 +232,6 @@ the canary one.
296232
For a more concrete example, check the
297233
[tutorial of deploying Ghost](https://github.com/kelseyhightower/talks/tree/master/kubecon-eu-2016/demo#deploy-a-canary).
298234
299-
## Updating labels
300-
301-
Sometimes existing pods and other resources need to be relabeled before creating new resources.
302-
This can be done with `kubectl label`.
303-
For example, if you want to label all your nginx pods as frontend tier, run:
304-
305-
```shell
306-
kubectl label pods -l app=nginx tier=fe
307-
```
308-
309-
```none
310-
pod/my-nginx-2035384211-j5fhi labeled
311-
pod/my-nginx-2035384211-u2c7e labeled
312-
pod/my-nginx-2035384211-u3t6x labeled
313-
```
314-
315-
This first filters all pods with the label "app=nginx", and then labels them with the "tier=fe".
316-
To see the pods you labeled, run:
317-
318-
```shell
319-
kubectl get pods -l app=nginx -L tier
320-
```
321-
322-
```none
323-
NAME READY STATUS RESTARTS AGE TIER
324-
my-nginx-2035384211-j5fhi 1/1 Running 0 23m fe
325-
my-nginx-2035384211-u2c7e 1/1 Running 0 23m fe
326-
my-nginx-2035384211-u3t6x 1/1 Running 0 23m fe
327-
```
328-
329-
This outputs all "app=nginx" pods, with an additional label column of pods' tier (specified with
330-
`-L` or `--label-columns`).
331-
332-
For more information, please see [labels](/docs/concepts/overview/working-with-objects/labels/)
333-
and [kubectl label](/docs/reference/generated/kubectl/kubectl-commands/#label).
334-
335235
## Updating annotations
336236
337237
Sometimes you would want to attach annotations to resources. Annotations are arbitrary

‎content/en/docs/concepts/configuration/overview.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ for a comprehensive list.
146146

147147
- Use label selectors for `get` and `delete` operations instead of specific object names. See the
148148
sections on [label selectors](/docs/concepts/overview/working-with-objects/labels/#label-selectors)
149-
and [using labels effectively](/docs/concepts/cluster-administration/manage-deployment/#using-labels-effectively).
149+
and [using labels effectively](/docs/concepts/overview/working-with-objects/labels/#using-labels-effectively).
150150

151151
- Use `kubectl create deployment` and `kubectl expose` to quickly create single-container
152152
Deployments and Services.

‎content/en/docs/concepts/overview/working-with-objects/labels.md

+100-1
Original file line numberDiff line numberDiff line change
@@ -297,11 +297,110 @@ One use case for selecting over labels is to constrain the set of nodes onto whi
297297
a pod can schedule. See the documentation on
298298
[node selection](/docs/concepts/scheduling-eviction/assign-pod-node/) for more information.
299299

300+
## Using labels effectively
301+
302+
You can apply a single label to any resources, but this is not always the
303+
best practice. There are many scenarios where multiple labels should be used to
304+
distinguish resource sets from one another.
305+
306+
For instance, different applications would use different values for the `app` label, but a
307+
multi-tier application, such as the [guestbook example](https://github.com/kubernetes/examples/tree/master/guestbook/),
308+
would additionally need to distinguish each tier. The frontend could carry the following labels:
309+
310+
```yaml
311+
labels:
312+
app: guestbook
313+
tier: frontend
314+
```
315+
316+
while the Redis master and replica would have different `tier` labels, and perhaps even an
317+
additional `role` label:
318+
319+
```yaml
320+
labels:
321+
app: guestbook
322+
tier: backend
323+
role: master
324+
```
325+
326+
and
327+
328+
```yaml
329+
labels:
330+
app: guestbook
331+
tier: backend
332+
role: replica
333+
```
334+
335+
The labels allow for slicing and dicing the resources along any dimension specified by a label:
336+
337+
```shell
338+
kubectl apply -f examples/guestbook/all-in-one/guestbook-all-in-one.yaml
339+
kubectl get pods -Lapp -Ltier -Lrole
340+
```
341+
342+
```none
343+
NAME READY STATUS RESTARTS AGE APP TIER ROLE
344+
guestbook-fe-4nlpb 1/1 Running 0 1m guestbook frontend <none>
345+
guestbook-fe-ght6d 1/1 Running 0 1m guestbook frontend <none>
346+
guestbook-fe-jpy62 1/1 Running 0 1m guestbook frontend <none>
347+
guestbook-redis-master-5pg3b 1/1 Running 0 1m guestbook backend master
348+
guestbook-redis-replica-2q2yf 1/1 Running 0 1m guestbook backend replica
349+
guestbook-redis-replica-qgazl 1/1 Running 0 1m guestbook backend replica
350+
my-nginx-divi2 1/1 Running 0 29m nginx <none> <none>
351+
my-nginx-o0ef1 1/1 Running 0 29m nginx <none> <none>
352+
```
353+
354+
```shell
355+
kubectl get pods -lapp=guestbook,role=replica
356+
```
357+
358+
```none
359+
NAME READY STATUS RESTARTS AGE
360+
guestbook-redis-replica-2q2yf 1/1 Running 0 3m
361+
guestbook-redis-replica-qgazl 1/1 Running 0 3m
362+
```
363+
364+
## Updating labels
365+
366+
Sometimes you may want to relabel existing pods and other resources before creating
367+
new resources. This can be done with `kubectl label`.
368+
For example, if you want to label all your NGINX Pods as frontend tier, run:
369+
370+
```shell
371+
kubectl label pods -l app=nginx tier=fe
372+
```
373+
374+
```none
375+
pod/my-nginx-2035384211-j5fhi labeled
376+
pod/my-nginx-2035384211-u2c7e labeled
377+
pod/my-nginx-2035384211-u3t6x labeled
378+
```
379+
380+
This first filters all pods with the label "app=nginx", and then labels them with the "tier=fe".
381+
To see the pods you labeled, run:
382+
383+
```shell
384+
kubectl get pods -l app=nginx -L tier
385+
```
386+
387+
```none
388+
NAME READY STATUS RESTARTS AGE TIER
389+
my-nginx-2035384211-j5fhi 1/1 Running 0 23m fe
390+
my-nginx-2035384211-u2c7e 1/1 Running 0 23m fe
391+
my-nginx-2035384211-u3t6x 1/1 Running 0 23m fe
392+
```
393+
394+
This outputs all "app=nginx" pods, with an additional label column of pods' tier
395+
(specified with `-L` or `--label-columns`).
396+
397+
For more information, please see [kubectl label](/docs/reference/generated/kubectl/kubectl-commands/#label).
398+
300399
## {{% heading "whatsnext" %}}
301400

302401
- Learn how to [add a label to a node](/docs/tasks/configure-pod-container/assign-pods-nodes/#add-a-label-to-a-node)
303402
- Find [Well-known labels, Annotations and Taints](/docs/reference/labels-annotations-taints/)
304403
- See [Recommended labels](/docs/concepts/overview/working-with-objects/common-labels/)
305404
- [Enforce Pod Security Standards with Namespace Labels](/docs/tasks/configure-pod-container/enforce-standards-namespace-labels/)
306-
- [Use Labels effectively](/docs/concepts/cluster-administration/manage-deployment/#using-labels-effectively) to manage deployments.
307405
- Read a blog on [Writing a Controller for Pod Labels](/blog/2021/06/21/writing-a-controller-for-pod-labels/)
406+

‎content/en/docs/tutorials/stateless-application/guestbook.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -419,4 +419,5 @@ labels to delete multiple resources with one command.
419419
* Complete the [Kubernetes Basics](/docs/tutorials/kubernetes-basics/) Interactive Tutorials
420420
* Use Kubernetes to create a blog using [Persistent Volumes for MySQL and Wordpress](/docs/tutorials/stateful-application/mysql-wordpress-persistent-volume/#visit-your-new-wordpress-blog)
421421
* Read more about [connecting applications with services](/docs/tutorials/services/connect-applications-service/)
422-
* Read more about [Managing Resources](/docs/concepts/cluster-administration/manage-deployment/#using-labels-effectively)
422+
* Read more about [using labels effectively](/docs/concepts/overview/working-with-objects/labels/#using-labels-effectively)
423+

0 commit comments

Comments
 (0)