[go: nahoru, domu]
Skip to content

Commit

Permalink
Move labels discussion back to its concept page
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@tengqm
tengqm committed Sep 1, 2023
1 parent 37fe704 commit a84bdb6
Show file tree
Hide file tree
Showing 4 changed files with 105 additions and 105 deletions.
104 changes: 2 additions & 102 deletions content/en/docs/concepts/cluster-administration/manage-deployment.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,6 @@ weight: 40

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

<!-- body -->

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

## Using labels effectively

The examples we've used so far apply at most a single label to any resource. There are many
scenarios where multiple labels should be used to distinguish sets from one another.

For instance, different applications would use different values for the `app` label, but a
multi-tier application, such as the [guestbook example](https://github.com/kubernetes/examples/tree/master/guestbook/),
would additionally need to distinguish each tier. The frontend could carry the following labels:

```yaml
labels:
app: guestbook
tier: frontend
```

while the Redis master and slave would have different `tier` labels, and perhaps even an
additional `role` label:

```yaml
labels:
app: guestbook
tier: backend
role: master
```

and

```yaml
labels:
app: guestbook
tier: backend
role: slave
```

The labels allow us to slice and dice our resources along any dimension specified by a label:

```shell
kubectl apply -f examples/guestbook/all-in-one/guestbook-all-in-one.yaml
kubectl get pods -Lapp -Ltier -Lrole
```

```none
NAME READY STATUS RESTARTS AGE APP TIER ROLE
guestbook-fe-4nlpb 1/1 Running 0 1m guestbook frontend <none>
guestbook-fe-ght6d 1/1 Running 0 1m guestbook frontend <none>
guestbook-fe-jpy62 1/1 Running 0 1m guestbook frontend <none>
guestbook-redis-master-5pg3b 1/1 Running 0 1m guestbook backend master
guestbook-redis-slave-2q2yf 1/1 Running 0 1m guestbook backend slave
guestbook-redis-slave-qgazl 1/1 Running 0 1m guestbook backend slave
my-nginx-divi2 1/1 Running 0 29m nginx <none> <none>
my-nginx-o0ef1 1/1 Running 0 29m nginx <none> <none>
```

```shell
kubectl get pods -lapp=guestbook,role=slave
```

```none
NAME READY STATUS RESTARTS AGE
guestbook-redis-slave-2q2yf 1/1 Running 0 3m
guestbook-redis-slave-qgazl 1/1 Running 0 3m
```

## Canary deployments

<!--TODO: make a task out of this for canary deployment, ref #42786-->

Another scenario where multiple labels are needed is to distinguish deployments of different
releases or configurations of the same component. It is common practice to deploy a *canary* of a
new application release (specified via image tag in the pod template) side by side with the
Expand Down Expand Up @@ -296,42 +232,6 @@ the canary one.
For a more concrete example, check the
[tutorial of deploying Ghost](https://github.com/kelseyhightower/talks/tree/master/kubecon-eu-2016/demo#deploy-a-canary).

## Updating labels

Sometimes existing pods and other resources need to be relabeled before creating new resources.
This can be done with `kubectl label`.
For example, if you want to label all your nginx pods as frontend tier, run:

```shell
kubectl label pods -l app=nginx tier=fe
```

```none
pod/my-nginx-2035384211-j5fhi labeled
pod/my-nginx-2035384211-u2c7e labeled
pod/my-nginx-2035384211-u3t6x labeled
```

This first filters all pods with the label "app=nginx", and then labels them with the "tier=fe".
To see the pods you labeled, run:

```shell
kubectl get pods -l app=nginx -L tier
```

```none
NAME READY STATUS RESTARTS AGE TIER
my-nginx-2035384211-j5fhi 1/1 Running 0 23m fe
my-nginx-2035384211-u2c7e 1/1 Running 0 23m fe
my-nginx-2035384211-u3t6x 1/1 Running 0 23m fe
```

This outputs all "app=nginx" pods, with an additional label column of pods' tier (specified with
`-L` or `--label-columns`).

For more information, please see [labels](/docs/concepts/overview/working-with-objects/labels/)
and [kubectl label](/docs/reference/generated/kubectl/kubectl-commands/#label).

## Updating annotations

Sometimes you would want to attach annotations to resources. Annotations are arbitrary
Expand Down
2 changes: 1 addition & 1 deletion content/en/docs/concepts/configuration/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ for a comprehensive list.

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

- Use `kubectl create deployment` and `kubectl expose` to quickly create single-container
Deployments and Services.
Expand Down
101 changes: 100 additions & 1 deletion content/en/docs/concepts/overview/working-with-objects/labels.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -297,11 +297,110 @@ One use case for selecting over labels is to constrain the set of nodes onto whi
a pod can schedule. See the documentation on
[node selection](/docs/concepts/scheduling-eviction/assign-pod-node/) for more information.

## Using labels effectively

You can apply a single label to any resources, but this is not always the
best practice. There are many scenarios where multiple labels should be used to
distinguish resource sets from one another.

For instance, different applications would use different values for the `app` label, but a
multi-tier application, such as the [guestbook example](https://github.com/kubernetes/examples/tree/master/guestbook/),
would additionally need to distinguish each tier. The frontend could carry the following labels:

```yaml
labels:
app: guestbook
tier: frontend
```

while the Redis master and replica would have different `tier` labels, and perhaps even an
additional `role` label:

```yaml
labels:
app: guestbook
tier: backend
role: master
```

and

```yaml
labels:
app: guestbook
tier: backend
role: replica
```

The labels allow for slicing and dicing the resources along any dimension specified by a label:

```shell
kubectl apply -f examples/guestbook/all-in-one/guestbook-all-in-one.yaml
kubectl get pods -Lapp -Ltier -Lrole
```

```none
NAME READY STATUS RESTARTS AGE APP TIER ROLE
guestbook-fe-4nlpb 1/1 Running 0 1m guestbook frontend <none>
guestbook-fe-ght6d 1/1 Running 0 1m guestbook frontend <none>
guestbook-fe-jpy62 1/1 Running 0 1m guestbook frontend <none>
guestbook-redis-master-5pg3b 1/1 Running 0 1m guestbook backend master
guestbook-redis-replica-2q2yf 1/1 Running 0 1m guestbook backend replica
guestbook-redis-replica-qgazl 1/1 Running 0 1m guestbook backend replica
my-nginx-divi2 1/1 Running 0 29m nginx <none> <none>
my-nginx-o0ef1 1/1 Running 0 29m nginx <none> <none>
```

```shell
kubectl get pods -lapp=guestbook,role=replica
```

```none
NAME READY STATUS RESTARTS AGE
guestbook-redis-replica-2q2yf 1/1 Running 0 3m
guestbook-redis-replica-qgazl 1/1 Running 0 3m
```

## Updating labels

Sometimes you may want to relabel existing pods and other resources before creating
new resources. This can be done with `kubectl label`.
For example, if you want to label all your NGINX Pods as frontend tier, run:

```shell
kubectl label pods -l app=nginx tier=fe
```

```none
pod/my-nginx-2035384211-j5fhi labeled
pod/my-nginx-2035384211-u2c7e labeled
pod/my-nginx-2035384211-u3t6x labeled
```

This first filters all pods with the label "app=nginx", and then labels them with the "tier=fe".
To see the pods you labeled, run:

```shell
kubectl get pods -l app=nginx -L tier
```

```none
NAME READY STATUS RESTARTS AGE TIER
my-nginx-2035384211-j5fhi 1/1 Running 0 23m fe
my-nginx-2035384211-u2c7e 1/1 Running 0 23m fe
my-nginx-2035384211-u3t6x 1/1 Running 0 23m fe
```

This outputs all "app=nginx" pods, with an additional label column of pods' tier
(specified with `-L` or `--label-columns`).

For more information, please see [kubectl label](/docs/reference/generated/kubectl/kubectl-commands/#label).

## {{% heading "whatsnext" %}}

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

3 changes: 2 additions & 1 deletion content/en/docs/tutorials/stateless-application/guestbook.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -419,4 +419,5 @@ labels to delete multiple resources with one command.
* Complete the [Kubernetes Basics](/docs/tutorials/kubernetes-basics/) Interactive Tutorials
* 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)
* Read more about [connecting applications with services](/docs/tutorials/services/connect-applications-service/)
* Read more about [Managing Resources](/docs/concepts/cluster-administration/manage-deployment/#using-labels-effectively)
* Read more about [using labels effectively](/docs/concepts/overview/working-with-objects/labels/#using-labels-effectively)

0 comments on commit a84bdb6

Please sign in to comment.