From bc023f265cfe4829e09e74859219dd7fbd65124f Mon Sep 17 00:00:00 2001 From: Richard Li Date: Sat, 27 Feb 2021 07:03:42 -0500 Subject: [PATCH 01/15] add blog post on using kubectl annotate for human service discovery --- .../2021-02-27-annotating-k8s-for-humans.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md new file mode 100644 index 0000000000..bfc49a431b --- /dev/null +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -0,0 +1,99 @@ +--- +layout: blog +title: 'Annotating Kubernetes Services for Humans' +date: 2021-02-27 +slug: annotating-k8s-for-humans +--- + +**Authors:** Richard Li (Ambassador Labs) + +Have you ever been asked to troubleshoot a failing Kubernetes service and struggled to find basic information about the service such as the source repository and owner? + +One of the problems as Kubernetes applications grow is the proliferation of services. As the number of services grows, developers start to specialize working with specific services. When it comes to troubleshooting, however, developers need to be able to find the source, understand the service and dependencies, and chat with the owning team for any service. + +## Human Service Discovery + +Troubleshooting always begins with information gathering. While much attention has been paid to centralizing machine data (e.g., logs, metrics), much less attention has been given to the human aspect of service discovery. Who owns a particular service? What Slack channel does the team work on? Where is the source for the service? What issues are currently known and being tracked? + +## Kubernetes Annotations + +Kubernetes annotations are designed to solve exactly this problem. Oft-overlooked, Kubernetes annotations are designed to add metadata to Kubernetes objects. The Kubernetes documentation says annotations can “attach arbitrary non-identifying metadata to objects.” This means that annotations should be used for attaching metadata that is external to Kubernetes (i.e., metadata that Kubernetes won’t use to identify objects. As such, annotations can contain any type of data. This is a contrast to labels, which are designed for uses internal to Kubernetes. As such, label structure and values are [constrained](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) so they can be efficiently used by Kubernetes. + + +## Kubernetes Annotations in Action + +Here is an example. Imagine you have a Kubernetes service for quoting, called the quote service. You can do the following: + +``` +$ kubectl annotate service quote a8r.io/owner=”@sally” +``` + +In this example, we’ve just added an annotation called `a8r.io/owner` with the value of @sally. Now, we can use `kubectl describe` to get the information. + +``` +$ kubectl describe svc quote +Name: quote +Namespace: default +Labels: +Annotations: a8r.io/owner: @sally +Selector: app=quote +Type: ClusterIP +IP: 10.109.142.131 +Port: http 80/TCP +TargetPort: 8080/TCP +Endpoints: +Session Affinity: None +Events: +``` + +If you’re practicing GitOps (and you should be!) you’ll want to code these values directly into your Kubernetes manifest, e.g., + +``` +apiVersion: v1 +kind: Service +metadata: + name: quote + annotations: + a8r.io/owner: “@sally” +spec: + ports: + - name: http + port: 80 + targetPort: 8080 + selector: + app: quote +``` + +## A Convention for Annotations + +Adopting a common convention for annotations ensures consistency and understandability. Typically, you’ll want to attach the annotation to the service object, as services are the high-level resource that maps most clearly to a team’s responsibility. Namespacing your annotations is also very important. Here is one set of conventions, documented at [a8r.io](https://a8r.io), and reproduced below: + +| Annotation | Description | +| ------------------------------------------ | ------------------------------------------- | +| `a8r.io/description` | Unstructured text description of the service for humans. | +| `a8r.io/owner` | SSO username (GitHub), email address (linked to GitHub account), or unstructured owner description. | +| `a8r.io/chat` | Slack channel, or link to external chat system | +| `a8r.io/bugs` | Link to external bug tracker | +| `a8r.io/logs` | Link to external log viewer | +| `a8r.io/documentation` | Link to external project documentation | +| `a8r.io/repository` | Link to external VCS repository | +| `a8r.io/support` | Link to external support center | +| `a8r.io/runbook` | Link to external project runbook | +| `a8r.io/incidents` | Link to external incident dashboard | +| `a8r.io/uptime` | Link to external uptime dashboard | +| `a8r.io/performance` | Link to external performance dashboard | +| `a8r.io/dependencies` | Unstructured text describing the service dependencies for humans. | + + +## Visualizing Annotations: Service Catalogs + +As the number of microservices and annotations proliferate, using `kubectl describe` can get tedious. Moreover, kubectl describe requires every developer to have some direct access to the Kubernetes cluster. A [service catalog](https://www.getambassador.io/learn/kubernetes-glossary/service-catalog) presents an internal, developer-oriented view of all services. + +Historically, service catalogs have not been a key piece of infrastructure, as applications consisted of a single monolith. Today, with distributed development and microservices the norm, service catalogs are increasingly being adopted as a best practice. Some popular options today include Backstage and Ambassador. [Backstage](https://backstage.io/) is a highly flexible project ideal for organizations that wish to customize every aspect of their service catalog, while [Ambassador](https://www.getambassador.io/products/service-catalog) provides a turnkey, cloud-hosted solution that can be set up quickly. + +## Annotate Your Services Now and Thank Yourself Later +Much like implementing observability within microservice systems, you often don’t realize that you need human service discovery until it’s too late. Typically, something is on fire in production and you wished you had implemented better metrics and also specified which Slack channel the owning team lived in within your organization. + +There's enormous benefits to building an effective “[version 0](https://www.getambassador.io/learn/kubernetes-glossary/version-0/)” of any service: a “[dancing skeleton](https://containerjournal.com/topics/container-management/dancing-skeleton-apis-and-microservices/)” application with a thin slice of complete functionality that can be deployed to production with a minimal yet effective continuous delivery pipeline. + +Adding service annotations should be an essential part of your “version 0” for all of your services. Add them now, and you’ll thank yourself later. From ecd25dfefb01c707393a579087b39026ab522775 Mon Sep 17 00:00:00 2001 From: Richard Li Date: Mon, 1 Mar 2021 08:09:13 -0500 Subject: [PATCH 02/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md Co-authored-by: Tim Bannister --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index bfc49a431b..a1969cd9cc 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -17,7 +17,7 @@ Troubleshooting always begins with information gathering. While much attention h ## Kubernetes Annotations -Kubernetes annotations are designed to solve exactly this problem. Oft-overlooked, Kubernetes annotations are designed to add metadata to Kubernetes objects. The Kubernetes documentation says annotations can “attach arbitrary non-identifying metadata to objects.” This means that annotations should be used for attaching metadata that is external to Kubernetes (i.e., metadata that Kubernetes won’t use to identify objects. As such, annotations can contain any type of data. This is a contrast to labels, which are designed for uses internal to Kubernetes. As such, label structure and values are [constrained](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) so they can be efficiently used by Kubernetes. +Kubernetes annotations are designed to solve exactly this problem. Oft-overlooked, Kubernetes annotations are designed to add metadata to Kubernetes objects. The Kubernetes documentation says annotations can “attach arbitrary non-identifying metadata to objects.” This means that annotations should be used for attaching metadata that is external to Kubernetes (i.e., metadata that Kubernetes won’t use to identify objects. As such, annotations can contain any type of data. This is a contrast to labels, which are designed for uses internal to Kubernetes. As such, label structure and values are [constrained](/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) so they can be efficiently used by Kubernetes. ## Kubernetes Annotations in Action From eeb8c0b45ec3972d942c32d791d8d68dbbe5c2fc Mon Sep 17 00:00:00 2001 From: Richard Li Date: Mon, 1 Mar 2021 08:09:20 -0500 Subject: [PATCH 03/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md Co-authored-by: Tim Bannister --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index a1969cd9cc..9a0c166421 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -87,7 +87,7 @@ Adopting a common convention for annotations ensures consistency and understanda ## Visualizing Annotations: Service Catalogs -As the number of microservices and annotations proliferate, using `kubectl describe` can get tedious. Moreover, kubectl describe requires every developer to have some direct access to the Kubernetes cluster. A [service catalog](https://www.getambassador.io/learn/kubernetes-glossary/service-catalog) presents an internal, developer-oriented view of all services. +As the number of microservices and annotations proliferate, running `kubectl describe` can get tedious. Moreover, using `kubectl describe` requires every developer to have some direct access to the Kubernetes cluster. An [service catalog](https://www.getambassador.io/learn/kubernetes-glossary/service-catalog), in the Ambassador meaning of that term, presents an internal, developer-oriented view of all services. Historically, service catalogs have not been a key piece of infrastructure, as applications consisted of a single monolith. Today, with distributed development and microservices the norm, service catalogs are increasingly being adopted as a best practice. Some popular options today include Backstage and Ambassador. [Backstage](https://backstage.io/) is a highly flexible project ideal for organizations that wish to customize every aspect of their service catalog, while [Ambassador](https://www.getambassador.io/products/service-catalog) provides a turnkey, cloud-hosted solution that can be set up quickly. From 69ee6318a5f6d293f2c9a2c3bfd2dfd371af228b Mon Sep 17 00:00:00 2001 From: Richard Li Date: Mon, 1 Mar 2021 08:10:02 -0500 Subject: [PATCH 04/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md Co-authored-by: Tim Bannister --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index 9a0c166421..ddf0bca364 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -92,7 +92,7 @@ As the number of microservices and annotations proliferate, running `kubectl des Historically, service catalogs have not been a key piece of infrastructure, as applications consisted of a single monolith. Today, with distributed development and microservices the norm, service catalogs are increasingly being adopted as a best practice. Some popular options today include Backstage and Ambassador. [Backstage](https://backstage.io/) is a highly flexible project ideal for organizations that wish to customize every aspect of their service catalog, while [Ambassador](https://www.getambassador.io/products/service-catalog) provides a turnkey, cloud-hosted solution that can be set up quickly. ## Annotate Your Services Now and Thank Yourself Later -Much like implementing observability within microservice systems, you often don’t realize that you need human service discovery until it’s too late. Typically, something is on fire in production and you wished you had implemented better metrics and also specified which Slack channel the owning team lived in within your organization. +Much like implementing observability within microservice systems, you often don’t realize that you need human service discovery until it’s too late. Don't wait until something is on fire in production to start wishing you had implemented better metrics and also documented how to get in touch with the part of your organization that looks after it. There's enormous benefits to building an effective “[version 0](https://www.getambassador.io/learn/kubernetes-glossary/version-0/)” of any service: a “[dancing skeleton](https://containerjournal.com/topics/container-management/dancing-skeleton-apis-and-microservices/)” application with a thin slice of complete functionality that can be deployed to production with a minimal yet effective continuous delivery pipeline. From dc86d666482105fc0edfe4b392c7ab0d5a54ad2a Mon Sep 17 00:00:00 2001 From: Richard Li Date: Mon, 1 Mar 2021 08:11:11 -0500 Subject: [PATCH 05/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md Co-authored-by: Tim Bannister --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index ddf0bca364..994601a9f3 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -85,7 +85,7 @@ Adopting a common convention for annotations ensures consistency and understanda | `a8r.io/dependencies` | Unstructured text describing the service dependencies for humans. | -## Visualizing Annotations: Service Catalogs +## Visualizing annotations: service catalogs As the number of microservices and annotations proliferate, running `kubectl describe` can get tedious. Moreover, using `kubectl describe` requires every developer to have some direct access to the Kubernetes cluster. An [service catalog](https://www.getambassador.io/learn/kubernetes-glossary/service-catalog), in the Ambassador meaning of that term, presents an internal, developer-oriented view of all services. From 3188c43241b6be5484b65dd351417ca36b66ef65 Mon Sep 17 00:00:00 2001 From: Richard Li Date: Mon, 1 Mar 2021 08:11:17 -0500 Subject: [PATCH 06/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md Co-authored-by: Tim Bannister --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index 994601a9f3..1c05fe2410 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -91,7 +91,7 @@ As the number of microservices and annotations proliferate, running `kubectl des Historically, service catalogs have not been a key piece of infrastructure, as applications consisted of a single monolith. Today, with distributed development and microservices the norm, service catalogs are increasingly being adopted as a best practice. Some popular options today include Backstage and Ambassador. [Backstage](https://backstage.io/) is a highly flexible project ideal for organizations that wish to customize every aspect of their service catalog, while [Ambassador](https://www.getambassador.io/products/service-catalog) provides a turnkey, cloud-hosted solution that can be set up quickly. -## Annotate Your Services Now and Thank Yourself Later +## Annotate your services now and thank yourself later Much like implementing observability within microservice systems, you often don’t realize that you need human service discovery until it’s too late. Don't wait until something is on fire in production to start wishing you had implemented better metrics and also documented how to get in touch with the part of your organization that looks after it. There's enormous benefits to building an effective “[version 0](https://www.getambassador.io/learn/kubernetes-glossary/version-0/)” of any service: a “[dancing skeleton](https://containerjournal.com/topics/container-management/dancing-skeleton-apis-and-microservices/)” application with a thin slice of complete functionality that can be deployed to production with a minimal yet effective continuous delivery pipeline. From a381d88fe26590491b5e81652afa18b7651caf9f Mon Sep 17 00:00:00 2001 From: Richard Li Date: Mon, 1 Mar 2021 08:11:26 -0500 Subject: [PATCH 07/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md Co-authored-by: Tim Bannister --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index 1c05fe2410..87af6e8863 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -11,7 +11,7 @@ Have you ever been asked to troubleshoot a failing Kubernetes service and strugg One of the problems as Kubernetes applications grow is the proliferation of services. As the number of services grows, developers start to specialize working with specific services. When it comes to troubleshooting, however, developers need to be able to find the source, understand the service and dependencies, and chat with the owning team for any service. -## Human Service Discovery +## Human service discovery Troubleshooting always begins with information gathering. While much attention has been paid to centralizing machine data (e.g., logs, metrics), much less attention has been given to the human aspect of service discovery. Who owns a particular service? What Slack channel does the team work on? Where is the source for the service? What issues are currently known and being tracked? From 5b3eedc8c2ccbcb149e535aff6a2ce6d1fb47d37 Mon Sep 17 00:00:00 2001 From: Richard Li Date: Mon, 1 Mar 2021 08:49:44 -0500 Subject: [PATCH 08/15] clarify difference with k8s service catalog Signed-off-by: Richard Li --- .../blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index 87af6e8863..d2c4223713 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -5,7 +5,7 @@ date: 2021-02-27 slug: annotating-k8s-for-humans --- -**Authors:** Richard Li (Ambassador Labs) +**Author:** Richard Li, Ambassador Labs Have you ever been asked to troubleshoot a failing Kubernetes service and struggled to find basic information about the service such as the source repository and owner? @@ -15,7 +15,7 @@ One of the problems as Kubernetes applications grow is the proliferation of serv Troubleshooting always begins with information gathering. While much attention has been paid to centralizing machine data (e.g., logs, metrics), much less attention has been given to the human aspect of service discovery. Who owns a particular service? What Slack channel does the team work on? Where is the source for the service? What issues are currently known and being tracked? -## Kubernetes Annotations +## Kubernetes annotations Kubernetes annotations are designed to solve exactly this problem. Oft-overlooked, Kubernetes annotations are designed to add metadata to Kubernetes objects. The Kubernetes documentation says annotations can “attach arbitrary non-identifying metadata to objects.” This means that annotations should be used for attaching metadata that is external to Kubernetes (i.e., metadata that Kubernetes won’t use to identify objects. As such, annotations can contain any type of data. This is a contrast to labels, which are designed for uses internal to Kubernetes. As such, label structure and values are [constrained](/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set) so they can be efficiently used by Kubernetes. @@ -87,9 +87,9 @@ Adopting a common convention for annotations ensures consistency and understanda ## Visualizing annotations: service catalogs -As the number of microservices and annotations proliferate, running `kubectl describe` can get tedious. Moreover, using `kubectl describe` requires every developer to have some direct access to the Kubernetes cluster. An [service catalog](https://www.getambassador.io/learn/kubernetes-glossary/service-catalog), in the Ambassador meaning of that term, presents an internal, developer-oriented view of all services. +As the number of microservices and annotations proliferate, running `kubectl describe` can get tedious. Moreover, using `kubectl describe` requires every developer to have some direct access to the Kubernetes cluster. Over the past few years, [service catalogs](https://www.getambassador.io/learn/kubernetes-glossary/service-catalog) have gained greater visibility in the Kubernetes ecosystem. Popularized by tools such as [Shopify's ServicesDB](https://shopify.engineering/scaling-mobile-development-by-treating-apps-as-services) and [Spotify's System Z](https://dzone.com/articles/modeling-microservices-at-spotify-with-petter-mari), service catalogs are internally-facing developer portals that present critical information about microservices. Note that these service catalogs should not be confused with the [Kubernetes Service Catalog project](https://svc-cat.io/). Built on the Open Service Broker API, the Kubernetes Service Catalog enables Kubernetes operators to plug in different services (e.g., databases) to their cluster. -Historically, service catalogs have not been a key piece of infrastructure, as applications consisted of a single monolith. Today, with distributed development and microservices the norm, service catalogs are increasingly being adopted as a best practice. Some popular options today include Backstage and Ambassador. [Backstage](https://backstage.io/) is a highly flexible project ideal for organizations that wish to customize every aspect of their service catalog, while [Ambassador](https://www.getambassador.io/products/service-catalog) provides a turnkey, cloud-hosted solution that can be set up quickly. +Historically, service catalogs have not been a key piece of infrastructure, as applications consisted of a single monolith. Today, with distributed development and microservices the norm, service catalogs are increasingly being adopted as a best practice. Some popular options today include [Backstage]((https://backstage.io/) and [Ambassador Service Catalog](https://www.getambassador.io/products/service-catalog). Backstage is a highly flexible project ideal for organizations that wish to customize every aspect of their service catalog, while Ambassador Service Catalog provides a turnkey, cloud-hosted solution that can be set up quickly. ## Annotate your services now and thank yourself later Much like implementing observability within microservice systems, you often don’t realize that you need human service discovery until it’s too late. Don't wait until something is on fire in production to start wishing you had implemented better metrics and also documented how to get in touch with the part of your organization that looks after it. From 2300a732101af99e171b669d5d8bde07b5c28465 Mon Sep 17 00:00:00 2001 From: Richard Li Date: Tue, 2 Mar 2021 09:01:39 -0500 Subject: [PATCH 09/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md Co-authored-by: Tim Bannister --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index d2c4223713..922debf381 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -25,7 +25,7 @@ Kubernetes annotations are designed to solve exactly this problem. Oft-overlooke Here is an example. Imagine you have a Kubernetes service for quoting, called the quote service. You can do the following: ``` -$ kubectl annotate service quote a8r.io/owner=”@sally” +kubectl annotate service quote a8r.io/owner=”@sally” ``` In this example, we’ve just added an annotation called `a8r.io/owner` with the value of @sally. Now, we can use `kubectl describe` to get the information. From 48bd9a6a441db79c63a2080f6af7c50a2f15026e Mon Sep 17 00:00:00 2001 From: Richard Li Date: Tue, 2 Mar 2021 09:10:11 -0500 Subject: [PATCH 10/15] a few more fixes --- .../2021-02-27-annotating-k8s-for-humans.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index d2c4223713..81b14038e5 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -31,7 +31,6 @@ $ kubectl annotate service quote a8r.io/owner=”@sally” In this example, we’ve just added an annotation called `a8r.io/owner` with the value of @sally. Now, we can use `kubectl describe` to get the information. ``` -$ kubectl describe svc quote Name: quote Namespace: default Labels: @@ -48,7 +47,7 @@ Events: If you’re practicing GitOps (and you should be!) you’ll want to code these values directly into your Kubernetes manifest, e.g., -``` +```yaml apiVersion: v1 kind: Service metadata: @@ -68,20 +67,21 @@ spec: Adopting a common convention for annotations ensures consistency and understandability. Typically, you’ll want to attach the annotation to the service object, as services are the high-level resource that maps most clearly to a team’s responsibility. Namespacing your annotations is also very important. Here is one set of conventions, documented at [a8r.io](https://a8r.io), and reproduced below: +{{< table caption="Annotation convention for human-readable services">}} | Annotation | Description | | ------------------------------------------ | ------------------------------------------- | | `a8r.io/description` | Unstructured text description of the service for humans. | | `a8r.io/owner` | SSO username (GitHub), email address (linked to GitHub account), or unstructured owner description. | -| `a8r.io/chat` | Slack channel, or link to external chat system | -| `a8r.io/bugs` | Link to external bug tracker | -| `a8r.io/logs` | Link to external log viewer | -| `a8r.io/documentation` | Link to external project documentation | -| `a8r.io/repository` | Link to external VCS repository | -| `a8r.io/support` | Link to external support center | -| `a8r.io/runbook` | Link to external project runbook | -| `a8r.io/incidents` | Link to external incident dashboard | -| `a8r.io/uptime` | Link to external uptime dashboard | -| `a8r.io/performance` | Link to external performance dashboard | +| `a8r.io/chat` | Slack channel, or link to external chat system. | +| `a8r.io/bugs` | Link to external bug tracker. | +| `a8r.io/logs` | Link to external log viewer. | +| `a8r.io/documentation` | Link to external project documentation. | +| `a8r.io/repository` | Link to external VCS repository. | +| `a8r.io/support` | Link to external support center. | +| `a8r.io/runbook` | Link to external project runbook. | +| `a8r.io/incidents` | Link to external incident dashboard. | +| `a8r.io/uptime` | Link to external uptime dashboard. | +| `a8r.io/performance` | Link to external performance dashboard. | | `a8r.io/dependencies` | Unstructured text describing the service dependencies for humans. | From 5829a5d9584640b727b9420967a0189c6862e5b3 Mon Sep 17 00:00:00 2001 From: Richard Li Date: Thu, 4 Mar 2021 14:48:45 -0500 Subject: [PATCH 11/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md Co-authored-by: Kaitlyn Barnard --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index a9a65c9dae..b81c13a7f0 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -89,7 +89,7 @@ Adopting a common convention for annotations ensures consistency and understanda As the number of microservices and annotations proliferate, running `kubectl describe` can get tedious. Moreover, using `kubectl describe` requires every developer to have some direct access to the Kubernetes cluster. Over the past few years, [service catalogs](https://www.getambassador.io/learn/kubernetes-glossary/service-catalog) have gained greater visibility in the Kubernetes ecosystem. Popularized by tools such as [Shopify's ServicesDB](https://shopify.engineering/scaling-mobile-development-by-treating-apps-as-services) and [Spotify's System Z](https://dzone.com/articles/modeling-microservices-at-spotify-with-petter-mari), service catalogs are internally-facing developer portals that present critical information about microservices. Note that these service catalogs should not be confused with the [Kubernetes Service Catalog project](https://svc-cat.io/). Built on the Open Service Broker API, the Kubernetes Service Catalog enables Kubernetes operators to plug in different services (e.g., databases) to their cluster. -Historically, service catalogs have not been a key piece of infrastructure, as applications consisted of a single monolith. Today, with distributed development and microservices the norm, service catalogs are increasingly being adopted as a best practice. Some popular options today include [Backstage]((https://backstage.io/) and [Ambassador Service Catalog](https://www.getambassador.io/products/service-catalog). Backstage is a highly flexible project ideal for organizations that wish to customize every aspect of their service catalog, while Ambassador Service Catalog provides a turnkey, cloud-hosted solution that can be set up quickly. +Historically, service catalogs have not been a key piece of infrastructure, as applications consisted of a single monolith. Today, with distributed development and microservices the norm, service catalogs are increasingly being adopted as a best practice. Some popular options today include [Backstage](https://backstage.io/) and [Ambassador Service Catalog](https://www.getambassador.io/products/service-catalog). Backstage is a highly flexible project ideal for organizations that wish to customize every aspect of their service catalog, while Ambassador Service Catalog provides a turnkey, cloud-hosted solution that can be set up quickly. ## Annotate your services now and thank yourself later Much like implementing observability within microservice systems, you often don’t realize that you need human service discovery until it’s too late. Don't wait until something is on fire in production to start wishing you had implemented better metrics and also documented how to get in touch with the part of your organization that looks after it. From c854d9e027708a087bf1b796033d70797c87e6c2 Mon Sep 17 00:00:00 2001 From: Zach Corleissen Date: Tue, 6 Apr 2021 11:32:36 -0700 Subject: [PATCH 12/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index b81c13a7f0..682489b227 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -1,7 +1,7 @@ --- layout: blog title: 'Annotating Kubernetes Services for Humans' -date: 2021-02-27 +date: 2021-04-06 slug: annotating-k8s-for-humans --- From 1ecc9948aa661c9f7140cfdacc75fbf410e36acc Mon Sep 17 00:00:00 2001 From: Zach Corleissen Date: Tue, 6 Apr 2021 11:32:45 -0700 Subject: [PATCH 13/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index 682489b227..2c28c00cb6 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -94,6 +94,6 @@ Historically, service catalogs have not been a key piece of infrastructure, as a ## Annotate your services now and thank yourself later Much like implementing observability within microservice systems, you often don’t realize that you need human service discovery until it’s too late. Don't wait until something is on fire in production to start wishing you had implemented better metrics and also documented how to get in touch with the part of your organization that looks after it. -There's enormous benefits to building an effective “[version 0](https://www.getambassador.io/learn/kubernetes-glossary/version-0/)” of any service: a “[dancing skeleton](https://containerjournal.com/topics/container-management/dancing-skeleton-apis-and-microservices/)” application with a thin slice of complete functionality that can be deployed to production with a minimal yet effective continuous delivery pipeline. +There's enormous benefits to building an effective [version 0](https://www.getambassador.io/learn/kubernetes-glossary/version-0/) of any service: a “[dancing skeleton](https://containerjournal.com/topics/container-management/dancing-skeleton-apis-and-microservices/)” application with a thin slice of complete functionality that can be deployed to production with a minimal yet effective continuous delivery pipeline. Adding service annotations should be an essential part of your “version 0” for all of your services. Add them now, and you’ll thank yourself later. From 4079e588223d457c5c555cc1693412066a2f6d14 Mon Sep 17 00:00:00 2001 From: Zach Corleissen Date: Tue, 6 Apr 2021 11:43:04 -0700 Subject: [PATCH 14/15] Update content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index 2c28c00cb6..9e86770abe 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -1,7 +1,7 @@ --- layout: blog title: 'Annotating Kubernetes Services for Humans' -date: 2021-04-06 +date: 2021-04-12 slug: annotating-k8s-for-humans --- From f94b9bf6b3f61e6f754494735c29ef749b23b3e5 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Tue, 13 Apr 2021 21:43:26 +0100 Subject: [PATCH 15/15] Update publication date --- content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md index 9e86770abe..5df7e4ca5e 100644 --- a/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md +++ b/content/en/blog/_posts/2021-02-27-annotating-k8s-for-humans.md @@ -1,7 +1,7 @@ --- layout: blog title: 'Annotating Kubernetes Services for Humans' -date: 2021-04-12 +date: 2021-04-20 slug: annotating-k8s-for-humans ---