Skip to content

Commit c9fe098

Browse files
mattfarinak8s-ci-robot
mattfarina
authored and
k8s-ci-robot
committed
Adding documentation on recommended labels and annotations (#8703)
* Adding documentation on recommended labels and annotations This content was developed as part of the App Def WG * Updates per feedback from editing and to remove annotations per WG * Adding app instance to the recommended labels
1 parent 22f5f71 commit c9fe098

File tree

2 files changed

+174
-0
lines changed

2 files changed

+174
-0
lines changed

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

+173
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: Recommended Labels
3+
content_template: templates/concept
4+
---
5+
6+
{{% capture overview %}}
7+
You can visualize and manage Kubernetes objects with more tools than kubectl and
8+
the dashboard. A common set of labels allows tools to work interoperably, describing
9+
objects in a common manner that all tools can understand.
10+
11+
In addition to supporting tooling, the recommended labels describe applications
12+
in a way that can be queried.
13+
{{% /capture %}}
14+
15+
{{% capture body %}}
16+
The metadata is organized around the concept of an _application_. Kubernetes is not
17+
a platform as a service (PaaS) and doesn't have or enforce a formal notion of an application.
18+
Instead, applications are informal and described with metadata. The definition of
19+
what an application contains is loose.
20+
21+
{{< note >}}
22+
**Note:** These are recommended labels. They make it easier to manage applications
23+
but aren't required for any core tooling.
24+
{{< /note >}}
25+
26+
Shared labels and annotations share a common prefix: `app.kubernetes.io`. Labels
27+
without a prefix are private to users. The shared prefix ensures that shared labels
28+
do not interfere with custom user labels.
29+
30+
## Labels
31+
32+
In order to take full advantage of using these labels, they should be applied
33+
on every resource object.
34+
35+
| Key | Description | Example | Type |
36+
| ----------------------------------- | --------------------- | -------- | ---- |
37+
| `app.kubernetes.io/name` | The name of the application | `mysql` | string |
38+
| `app.kubernetes.io/instance` | A unique name identifying the instance of an application | `wordpress-abcxzy` | string |
39+
| `app.kubernetes.io/version` | The current version of the application (e.g., a semantic version, revision hash, etc.) | `5.7.21` | string |
40+
| `app.kubernetes.io/component` | The component within the architecture | `database` | string |
41+
| `app.kubernetes.io/part-of` | The name of a higher level application this one is part of | `wordpress` | string |
42+
| `app.kubernetes.io/managed-by` | The tool being used to manage the operation of an application | `helm` | string |
43+
44+
To illustrate these labels in action, consider the following StatefulSet object:
45+
46+
```yaml
47+
apiVersion: apps/v1
48+
kind: StatefulSet
49+
metadata:
50+
labels:
51+
app.kubernetes.io/name: mysql
52+
app.kubernetes.io/instance: wordpress-abcxzy
53+
app.kubernetes.io/version: "5.7.21"
54+
app.kubernetes.io/component: database
55+
app.kubernetes.io/part-of: wordpress
56+
app.kubernetes.io/managed-by: helm
57+
```
58+
59+
## Applications And Instances Of Applications
60+
61+
An application can be installed one or more times into a Kubernetes cluster and,
62+
in some cases, the same namespace. For example, wordpress can be installed more
63+
than once where different websites are different installations of wordpress.
64+
65+
The name of an application and the instance name are recorded separately. For
66+
example, WordPress has a `app.kubernetes.io/name` of `wordpress` while it has
67+
an instance name, represented as `app.kubernetes.io/instance` with a value of
68+
`wordpress-abcxzy`. This enables the application and instance of the application
69+
to be identifiable. Every instance of an application must have a unique name.
70+
71+
## Examples
72+
73+
To illustrate different ways to use these labels the following examples have varying complexity.
74+
75+
### A Simple Stateless Service
76+
77+
Consider the case for a simple stateless service deployed using `Deployment` and `Service` objects. The following two snippets represent how the labels could be used in their simplest form.
78+
79+
The `Deployment` is used to oversee the pods running the application itself.
80+
```yaml
81+
apiVersion: apps/v1
82+
kind: Deployment
83+
metadata:
84+
labels:
85+
app.kubernetes.io/name: myservice
86+
app.kubernetes.io/instance: myservice-abcxzy
87+
...
88+
```
89+
90+
The `Service` is used to expose the application.
91+
```yaml
92+
apiVersion: v1
93+
kind: Service
94+
metadata:
95+
labels:
96+
app.kubernetes.io/name: myservice
97+
app.kubernetes.io/instance: myservice-abcxzy
98+
...
99+
```
100+
101+
### Web Application With A Database
102+
103+
Consider a slightly more complicated application: a web application (WordPress)
104+
using a database (MySQL), installed using Helm. The following snippets illustrate
105+
the start of objects used to deploy this application.
106+
107+
The start to the following `Deployment` is used for WordPress:
108+
109+
```yaml
110+
apiVersion: apps/v1
111+
kind: Deployment
112+
metadata:
113+
labels:
114+
app.kubernetes.io/name: wordpress
115+
app.kubernetes.io/instance: wordpress-abcxzy
116+
app.kubernetes.io/version: "4.9.4"
117+
app.kubernetes.io/managed-by: helm
118+
app.kubernetes.io/component: server
119+
app.kubernetes.io/part-of: wordpress
120+
...
121+
```
122+
123+
The `Service` is used to expose WordPress:
124+
125+
```yaml
126+
apiVersion: v1
127+
kind: Service
128+
metadata:
129+
labels:
130+
app.kubernetes.io/name: wordpress
131+
app.kubernetes.io/instance: wordpress-abcxzy
132+
app.kubernetes.io/version: "4.9.4"
133+
app.kubernetes.io/managed-by: helm
134+
app.kubernetes.io/component: server
135+
app.kubernetes.io/part-of: wordpress
136+
...
137+
```
138+
139+
MySQL is exposed as a `StatefulSet` with metadata for both it and the larger application it belongs to:
140+
141+
```yaml
142+
apiVersion: apps/v1
143+
kind: StatefulSet
144+
metadata:
145+
labels:
146+
app.kubernetes.io/name: mysql
147+
app.kubernetes.io/instance: wordpress-abcxzy
148+
app.kubernetes.io/managed-by: helm
149+
app.kubernetes.io/component: database
150+
app.kubernetes.io/part-of: wordpress
151+
app.kubernetes.io/version: "5.7.21"
152+
...
153+
```
154+
155+
The `Service` is used to expose MySQL as part of WordPress:
156+
157+
```yaml
158+
apiVersion: v1
159+
kind: Service
160+
metadata:
161+
labels:
162+
app.kubernetes.io/name: mysql
163+
app.kubernetes.io/instance: wordpress-abcxzy
164+
app.kubernetes.io/managed-by: helm
165+
app.kubernetes.io/component: database
166+
app.kubernetes.io/part-of: wordpress
167+
app.kubernetes.io/version: "5.7.21"
168+
...
169+
```
170+
171+
With the MySQL `StatefulSet` and `Service` you'll notice information about both MySQL and Wordpress, the broader application, are included.
172+
173+
{{% /capture %}}

‎data/concepts.yml

+1
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ toc:
1717
- docs/concepts/overview/working-with-objects/namespaces.md
1818
- docs/concepts/overview/working-with-objects/labels.md
1919
- docs/concepts/overview/working-with-objects/annotations.md
20+
- docs/concepts/overview/working-with-objects/common-labels.md
2021
- title: Object Management Using kubectl
2122
section:
2223
- docs/concepts/overview/object-management-kubectl/overview.md

0 commit comments

Comments
 (0)