From 3fdd27ef4bbf11223f8c163aba051a29b33e027a Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Wed, 23 May 2018 14:24:23 -0400 Subject: [PATCH 1/3] Adding documentation on recommended labels and annotations This content was developed as part of the App Def WG --- .../common-labels-annotations.md | 183 ++++++++++++++++++ data/concepts.yml | 1 + 2 files changed, 184 insertions(+) create mode 100644 content/en/docs/concepts/overview/working-with-objects/common-labels-annotations.md diff --git a/content/en/docs/concepts/overview/working-with-objects/common-labels-annotations.md b/content/en/docs/concepts/overview/working-with-objects/common-labels-annotations.md new file mode 100644 index 0000000000000..ee2259de89a5b --- /dev/null +++ b/content/en/docs/concepts/overview/working-with-objects/common-labels-annotations.md @@ -0,0 +1,183 @@ +--- +title: Recommended Labels and Annotations +content_template: templates/concept +--- + +{{% capture overview %}} +Many tools can be used to visualize and manage Kubernetes objects. The tools used +to manage objects goes beyond kubectl and the dashboard. To enable interoperability +between tools, a common set of labels and annotation allows objects to be described +in a common manner that all tools can understand. + +In addition to supporting tooling, the recommended labels and annotations describe +applications, in a generic sense, in a way that can queried or are otherwise useful +when operating applications. +{{% /capture %}} + +{{% capture body %}} +The recommended object metadata is broken apart so that some of it is labels while +other parts are annotations. Labels are shorter and can be used when querying +the Kubernetes API. Annotations allow for longer data that's not meant to be +queried. + +The metadata is organized around the concept of an Application. Kubernetes is not +a Platform as a Service and doesn't have or enforce a formal notion of an application. +Instead, applications are informal, described with metadata, and the definition of what an +application contains is loose. + +Note, these are recommended labels and annotations. They aid the use of managing +applications but are not required for any core tooling to work. + +One common theme you'll notice about the labels and annotations is that they +contain a prefix of `app.kubernetes.io`. Labels and annotations without a prefix +are considered private to users. These are meant to be common labels that do not +interfere with existing or custom user labels. To accomplish this a prefix is +used. + +## Labels + +| Key | Description | Example | Type | +| ----------------------------------- | --------------------- | -------- | ---- | +| `app.kubernetes.io/name` | The name of the application | `mysql` | 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 illustrative these labels in action consider the following StatefulSet object +containing them: + +```yaml +apiVersion: apps/v1 +kind: StatefulSet +metadata: + labels: + app.kubernetes.io/name: mysql + app.kubernetes.io/version: "5.7.21" + app.kubernetes.io/component: database + app.kubernetes.io/part-of: wordpress + app.kubernetes.io/managed-by: helm +``` + +## Annotations + +| Key | Description | Example | Type | +| ----------------------- | --------------------- | -------- | ---- | +| `app.kubernetes.io/usage` | The location of an applications usage information (e.g., details for how it's being run by an organization). A preference is given to version specific information | `https://example.com/foo/1.2/` | URL | +| `app.kubernetes.io/website` | A website to find out more information about the application in general | `https://wordpress.org` | URL | + +To illustrative these annotations in action consider the following StatefulSet object +containing them: + +```yaml +apiVersion: apps/v1 +kind: StatefulSet +metadata: + annotations: + app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/mysql + app.kubernetes.io/website: https://www.mysql.com/ +``` + +## 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 +... +``` + +The `Service` is used to expose the application. +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app.kubernetes.io/name: myservice +... +``` + +### Web Application With A Database + +A slightly more complicated application may be a web application and a database. For this example we consider WordPress using a MySQL database. To add to the metadata complexity Helm is used to install the application. 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/version: "4.9.4" + app.kubernetes.io/managed-by: helm + annotations: + app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/wordpress + app.kubernetes.io/website: https://wordpress.org/ +... +``` + +The `Service` is used to expose WordPress: + +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app.kubernetes.io/name: wordpress + app.kubernetes.io/version: "4.9.4" + app.kubernetes.io/managed-by: helm + annotations: + app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/wordpress + app.kubernetes.io/website: https://wordpress.org/ +... +``` + +MySQL is exposed as a `StatefulSet` with metadata for both it and the larger application it is apart of: + +```yaml +apiVersion: apps/v1 +kind: StatefulSet +metadata: + labels: + app.kubernetes.io/name: mysql + app.kubernetes.io/managed-by: helm + app.kubernetes.io/component: database + app.kubernetes.io/part-of: wordpress + app.kubernetes.io/version: "5.7.21" + annotations: + app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/mysql + app.kubernetes.io/website: https://mysql.org/ +... +``` + +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/managed-by: helm + app.kubernetes.io/component: database + app.kubernetes.io/part-of: wordpress + app.kubernetes.io/version: "5.7.21" + annotations: + app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/mysql + app.kubernetes.io/website: https://mysql.org/ +... +``` + +With the MySQL `StatefulSet` and `Service` you'll notice information about both MySQL and Wordpress, the broader application, are included. + +{{% /capture %}} \ No newline at end of file diff --git a/data/concepts.yml b/data/concepts.yml index bf6f8b53e842e..2134c690a9249 100644 --- a/data/concepts.yml +++ b/data/concepts.yml @@ -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-annotations.md - title: Object Management Using kubectl section: - docs/concepts/overview/object-management-kubectl/overview.md From aec59a5dae81f9761525bf40eeafc3c1a1275664 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Tue, 5 Jun 2018 10:30:52 -0400 Subject: [PATCH 2/3] Updates per feedback from editing and to remove annotations per WG --- .../common-labels-annotations.md | 183 ------------------ .../working-with-objects/common-labels.md | 149 ++++++++++++++ data/concepts.yml | 2 +- 3 files changed, 150 insertions(+), 184 deletions(-) delete mode 100644 content/en/docs/concepts/overview/working-with-objects/common-labels-annotations.md create mode 100644 content/en/docs/concepts/overview/working-with-objects/common-labels.md diff --git a/content/en/docs/concepts/overview/working-with-objects/common-labels-annotations.md b/content/en/docs/concepts/overview/working-with-objects/common-labels-annotations.md deleted file mode 100644 index ee2259de89a5b..0000000000000 --- a/content/en/docs/concepts/overview/working-with-objects/common-labels-annotations.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Recommended Labels and Annotations -content_template: templates/concept ---- - -{{% capture overview %}} -Many tools can be used to visualize and manage Kubernetes objects. The tools used -to manage objects goes beyond kubectl and the dashboard. To enable interoperability -between tools, a common set of labels and annotation allows objects to be described -in a common manner that all tools can understand. - -In addition to supporting tooling, the recommended labels and annotations describe -applications, in a generic sense, in a way that can queried or are otherwise useful -when operating applications. -{{% /capture %}} - -{{% capture body %}} -The recommended object metadata is broken apart so that some of it is labels while -other parts are annotations. Labels are shorter and can be used when querying -the Kubernetes API. Annotations allow for longer data that's not meant to be -queried. - -The metadata is organized around the concept of an Application. Kubernetes is not -a Platform as a Service and doesn't have or enforce a formal notion of an application. -Instead, applications are informal, described with metadata, and the definition of what an -application contains is loose. - -Note, these are recommended labels and annotations. They aid the use of managing -applications but are not required for any core tooling to work. - -One common theme you'll notice about the labels and annotations is that they -contain a prefix of `app.kubernetes.io`. Labels and annotations without a prefix -are considered private to users. These are meant to be common labels that do not -interfere with existing or custom user labels. To accomplish this a prefix is -used. - -## Labels - -| Key | Description | Example | Type | -| ----------------------------------- | --------------------- | -------- | ---- | -| `app.kubernetes.io/name` | The name of the application | `mysql` | 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 illustrative these labels in action consider the following StatefulSet object -containing them: - -```yaml -apiVersion: apps/v1 -kind: StatefulSet -metadata: - labels: - app.kubernetes.io/name: mysql - app.kubernetes.io/version: "5.7.21" - app.kubernetes.io/component: database - app.kubernetes.io/part-of: wordpress - app.kubernetes.io/managed-by: helm -``` - -## Annotations - -| Key | Description | Example | Type | -| ----------------------- | --------------------- | -------- | ---- | -| `app.kubernetes.io/usage` | The location of an applications usage information (e.g., details for how it's being run by an organization). A preference is given to version specific information | `https://example.com/foo/1.2/` | URL | -| `app.kubernetes.io/website` | A website to find out more information about the application in general | `https://wordpress.org` | URL | - -To illustrative these annotations in action consider the following StatefulSet object -containing them: - -```yaml -apiVersion: apps/v1 -kind: StatefulSet -metadata: - annotations: - app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/mysql - app.kubernetes.io/website: https://www.mysql.com/ -``` - -## 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 -... -``` - -The `Service` is used to expose the application. -```yaml -apiVersion: v1 -kind: Service -metadata: - labels: - app.kubernetes.io/name: myservice -... -``` - -### Web Application With A Database - -A slightly more complicated application may be a web application and a database. For this example we consider WordPress using a MySQL database. To add to the metadata complexity Helm is used to install the application. 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/version: "4.9.4" - app.kubernetes.io/managed-by: helm - annotations: - app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/wordpress - app.kubernetes.io/website: https://wordpress.org/ -... -``` - -The `Service` is used to expose WordPress: - -```yaml -apiVersion: v1 -kind: Service -metadata: - labels: - app.kubernetes.io/name: wordpress - app.kubernetes.io/version: "4.9.4" - app.kubernetes.io/managed-by: helm - annotations: - app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/wordpress - app.kubernetes.io/website: https://wordpress.org/ -... -``` - -MySQL is exposed as a `StatefulSet` with metadata for both it and the larger application it is apart of: - -```yaml -apiVersion: apps/v1 -kind: StatefulSet -metadata: - labels: - app.kubernetes.io/name: mysql - app.kubernetes.io/managed-by: helm - app.kubernetes.io/component: database - app.kubernetes.io/part-of: wordpress - app.kubernetes.io/version: "5.7.21" - annotations: - app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/mysql - app.kubernetes.io/website: https://mysql.org/ -... -``` - -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/managed-by: helm - app.kubernetes.io/component: database - app.kubernetes.io/part-of: wordpress - app.kubernetes.io/version: "5.7.21" - annotations: - app.kubernetes.io/usage: https://github.com/kubernetes/charts/tree/master/stable/mysql - app.kubernetes.io/website: https://mysql.org/ -... -``` - -With the MySQL `StatefulSet` and `Service` you'll notice information about both MySQL and Wordpress, the broader application, are included. - -{{% /capture %}} \ No newline at end of file diff --git a/content/en/docs/concepts/overview/working-with-objects/common-labels.md b/content/en/docs/concepts/overview/working-with-objects/common-labels.md new file mode 100644 index 0000000000000..1cfc6ba80fb59 --- /dev/null +++ b/content/en/docs/concepts/overview/working-with-objects/common-labels.md @@ -0,0 +1,149 @@ +--- +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/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/version: "5.7.21" + app.kubernetes.io/component: database + app.kubernetes.io/part-of: wordpress + app.kubernetes.io/managed-by: helm +``` + +## 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 +... +``` + +The `Service` is used to expose the application. +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app.kubernetes.io/name: myservice +... +``` + +### 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/version: "4.9.4" + app.kubernetes.io/managed-by: helm +... +``` + +The `Service` is used to expose WordPress: + +```yaml +apiVersion: v1 +kind: Service +metadata: + labels: + app.kubernetes.io/name: wordpress + app.kubernetes.io/version: "4.9.4" + app.kubernetes.io/managed-by: helm +... +``` + +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/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/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 %}} \ No newline at end of file diff --git a/data/concepts.yml b/data/concepts.yml index 2134c690a9249..4519addde536b 100644 --- a/data/concepts.yml +++ b/data/concepts.yml @@ -17,7 +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-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 From 4294dda51929d4c3daa790d81f51b6cece823046 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Fri, 6 Jul 2018 15:27:57 -0400 Subject: [PATCH 3/3] Adding app instance to the recommended labels --- .../working-with-objects/common-labels.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/content/en/docs/concepts/overview/working-with-objects/common-labels.md b/content/en/docs/concepts/overview/working-with-objects/common-labels.md index 1cfc6ba80fb59..314bbc7bb0b88 100644 --- a/content/en/docs/concepts/overview/working-with-objects/common-labels.md +++ b/content/en/docs/concepts/overview/working-with-objects/common-labels.md @@ -35,6 +35,7 @@ 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 | @@ -48,12 +49,25 @@ 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. @@ -69,6 +83,7 @@ kind: Deployment metadata: labels: app.kubernetes.io/name: myservice + app.kubernetes.io/instance: myservice-abcxzy ... ``` @@ -79,6 +94,7 @@ kind: Service metadata: labels: app.kubernetes.io/name: myservice + app.kubernetes.io/instance: myservice-abcxzy ... ``` @@ -96,8 +112,11 @@ 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 ... ``` @@ -109,8 +128,11 @@ 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 ... ``` @@ -122,6 +144,7 @@ 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 @@ -137,6 +160,7 @@ 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