kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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
pull/9269/merge
Matt Farina 2018-07-09 14:51:16 -04:00 committed by k8s-ci-robot
parent 22f5f71f40
commit c9fe098230
2 changed files with 174 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
content/en/docs/concepts/overview/working-with-objects/common-labels.md Normal file
View File

@ -0,0 +1,173 @@
---
title: Recommended Labels
content_template: templates/concept
---
{{% capture overview %}}
You can visualize and manage Kubernetes objects with more tools than kubectl and
the dashboard. A common set of labels allows tools to work interoperably, describing
objects in a common manner that all tools can understand.
In addition to supporting tooling, the recommended labels describe applications
in a way that can be queried.
{{% /capture %}}
{{% capture body %}}
The metadata is organized around the concept of an _application_. Kubernetes is not
a platform as a service (PaaS) and doesn't have or enforce a formal notion of an application.
Instead, applications are informal and described with metadata. The definition of
what an application contains is loose.
{{< note >}}
**Note:** These are recommended labels. They make it easier to manage applications
but aren't required for any core tooling.
{{< /note >}}
Shared labels and annotations share a common prefix: `app.kubernetes.io`. Labels
without a prefix are private to users. The shared prefix ensures that shared labels
do not interfere with custom user labels.
## Labels
In order to take full advantage of using these labels, they should be applied
on every resource object.
| Key | Description | Example | Type |
| ----------------------------------- | --------------------- | -------- | ---- |
| `app.kubernetes.io/name` | The name of the application | `mysql` | string |
| `app.kubernetes.io/instance` | A unique name identifying the instance of an application | `wordpress-abcxzy` | string |
| `app.kubernetes.io/version` | The current version of the application (e.g., a semantic version, revision hash, etc.) | `5.7.21` | string |
| `app.kubernetes.io/component` | The component within the architecture | `database` | string |
| `app.kubernetes.io/part-of` | The name of a higher level application this one is part of | `wordpress` | string |
| `app.kubernetes.io/managed-by` | The tool being used to manage the operation of an application | `helm` | string |
To illustrate these labels in action, consider the following StatefulSet object:
```yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
labels:
app.kubernetes.io/name: mysql
app.kubernetes.io/instance: wordpress-abcxzy
app.kubernetes.io/version: "5.7.21"
app.kubernetes.io/component: database
app.kubernetes.io/part-of: wordpress
app.kubernetes.io/managed-by: helm
```
## Applications And Instances Of Applications
An application can be installed one or more times into a Kubernetes cluster and,
in some cases, the same namespace. For example, wordpress can be installed more
than once where different websites are different installations of wordpress.
The name of an application and the instance name are recorded separately. For
example, WordPress has a `app.kubernetes.io/name` of `wordpress` while it has
an instance name, represented as `app.kubernetes.io/instance` with a value of
`wordpress-abcxzy`. This enables the application and instance of the application
to be identifiable. Every instance of an application must have a unique name.
## Examples
To illustrate different ways to use these labels the following examples have varying complexity.
### A Simple Stateless Service
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.
The `Deployment` is used to oversee the pods running the application itself.
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/name: myservice
app.kubernetes.io/instance: myservice-abcxzy
...
```
The `Service` is used to expose the application.
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/name: myservice
app.kubernetes.io/instance: myservice-abcxzy
...
```
### Web Application With A Database
Consider a slightly more complicated application: a web application (WordPress)
using a database (MySQL), installed using Helm. The following snippets illustrate
the start of objects used to deploy this application.
The start to the following `Deployment` is used for WordPress:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/name: wordpress
app.kubernetes.io/instance: wordpress-abcxzy
app.kubernetes.io/version: "4.9.4"
app.kubernetes.io/managed-by: helm
app.kubernetes.io/component: server
app.kubernetes.io/part-of: wordpress
...
```
The `Service` is used to expose WordPress:
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/name: wordpress
app.kubernetes.io/instance: wordpress-abcxzy
app.kubernetes.io/version: "4.9.4"
app.kubernetes.io/managed-by: helm
app.kubernetes.io/component: server
app.kubernetes.io/part-of: wordpress
...
```
MySQL is exposed as a `StatefulSet` with metadata for both it and the larger application it belongs to:
```yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
labels:
app.kubernetes.io/name: mysql
app.kubernetes.io/instance: wordpress-abcxzy
app.kubernetes.io/managed-by: helm
app.kubernetes.io/component: database
app.kubernetes.io/part-of: wordpress
app.kubernetes.io/version: "5.7.21"
...
```
The `Service` is used to expose MySQL as part of WordPress:
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/name: mysql
app.kubernetes.io/instance: wordpress-abcxzy
app.kubernetes.io/managed-by: helm
app.kubernetes.io/component: database
app.kubernetes.io/part-of: wordpress
app.kubernetes.io/version: "5.7.21"
...
```
With the MySQL `StatefulSet` and `Service` you'll notice information about both MySQL and Wordpress, the broader application, are included.
{{% /capture %}}

1
data/concepts.yml
View File

@ -17,6 +17,7 @@ toc:
- docs/concepts/overview/working-with-objects/namespaces.md
- docs/concepts/overview/working-with-objects/labels.md
- docs/concepts/overview/working-with-objects/annotations.md
- docs/concepts/overview/working-with-objects/common-labels.md
- title: Object Management Using kubectl
section:
- docs/concepts/overview/object-management-kubectl/overview.md