本文發表於一年多前。舊文章可能包含過時內容。請檢查頁面中的資訊自發布以來是否已變得不正確。

為人類註解 Kubernetes 服務

作者：Richard Li (Ambassador Labs) |

您是否曾被要求排查出現故障的 Kubernetes 服務，卻難以找到有關該服務的基本資訊，例如源倉庫和所有者？

隨著 Kubernetes 應用程式的增長，其中一個問題是服務的泛濫。隨著服務數量的增加，開發人員開始專注於處理特定服務。然而，在故障排除時，開發人員需要能夠找到任何服務的來源、理解服務及其依賴項，並與擁有團隊進行溝通。

人工服務發現

故障排除總是從資訊收集開始。雖然人們對集中機器資料（例如日誌、指標）給予了大量關注，但對服務發現的人工方面卻關注甚少。誰擁有特定的服務？團隊在哪個 Slack 頻道上工作？服務的來源在哪裡？目前已知並正在跟蹤哪些問題？

Kubernetes 註解

Kubernetes 註解正是為解決這個問題而設計的。Kubernetes 註解經常被忽視，但它旨在為 Kubernetes 物件新增元資料。Kubernetes 文件指出，註解可以“將任意非標識性元資料附加到物件”。這意味著註解應該用於附加 Kubernetes 外部的元資料（即 Kubernetes 不會用於識別物件的元資料）。因此，註解可以包含任何型別的資料。這與標籤形成對比，標籤是為 Kubernetes 內部使用而設計的。因此，標籤的結構和值受到約束，以便 Kubernetes 可以高效地使用它們。

Kubernetes 註解的實際應用

這裡有一個例子。假設您有一個用於報價的 Kubernetes 服務，稱為報價服務。您可以執行以下操作：

kubectl annotate service quote a8r.io/owner=”@sally”

在這個例子中，我們添加了一個名為 `a8r.io/owner` 的註解，其值為 `@sally`。現在，我們可以使用 `kubectl describe` 來獲取資訊。

Name:              quote
Namespace:         default
Labels:            <none>
Annotations:       a8r.io/owner: @sally
Selector:          app=quote
Type:              ClusterIP
IP:                10.109.142.131
Port:              http  80/TCP
TargetPort:        8080/TCP
Endpoints:         <none>
Session Affinity:  None
Events:            <none>

如果您正在實踐 GitOps（您應該這樣做！），您會希望將這些值直接編碼到您的 Kubernetes 清單中，例如：

apiVersion: v1
kind: Service
metadata:
  name: quote
  annotations:
    a8r.io/owner: “@sally”
spec:
  ports:
  - name: http
    port: 80
    targetPort: 8080
  selector:
    app: quote

註解的約定

採用通用的註解約定可確保一致性和可理解性。通常，您會將註解附加到服務物件，因為服務是與團隊職責最清晰對應的高階資源。對註解進行名稱空間劃分也非常重要。以下是一組約定，記錄在a8r.io，並轉載如下

人類可讀服務的註解約定
註解描述
a8r.io/description服務的非結構化文字描述，供人類閱讀。
a8r.io/ownerSSO 使用者名稱（GitHub）、電子郵件地址（連結到 GitHub 帳戶）或非結構化所有者描述。
a8r.io/chatSlack 頻道或外部聊天系統連結。
a8r.io/bugs外部錯誤跟蹤器連結。
a8r.io/logs外部日誌檢視器連結。
a8r.io/documentation外部專案文件連結。
a8r.io/repository外部 VCS 倉庫連結。
a8r.io/support外部支援中心連結。
a8r.io/runbook外部專案執行手冊連結。
a8r.io/incidents外部事件儀表板連結。
a8r.io/uptime外部執行時間儀表板連結。
a8r.io/performance外部效能儀表板連結。
a8r.io/dependencies服務的非結構化文字描述，供人類閱讀。

註解視覺化：服務目錄

隨著微服務和註解數量的激增，執行 `kubectl describe` 可能會變得繁瑣。此外，使用 `kubectl describe` 要求每個開發人員都能夠直接訪問 Kubernetes 叢集。在過去幾年中，服務目錄在 Kubernetes 生態系統中獲得了更高的可見性。透過 Shopify 的 ServicesDB 和 Spotify 的 System Z 等工具的推廣，服務目錄成為了面向內部的開發者門戶，提供了有關微服務的關鍵資訊。

請注意，這些服務目錄不應與Kubernetes 服務目錄專案混淆。Kubernetes 服務目錄基於開放服務代理 API 構建，使 Kubernetes 運營商能夠將不同的服務（例如資料庫）連線到其叢集。

現在就為你的服務添加註解，以後你會感謝自己的

就像在微服務系統中實現可觀測性一樣，你常常直到為時已晚才意識到自己需要人工服務發現。不要等到生產環境中出現問題才開始希望自己能夠實現更好的度量，並記錄下如何聯絡負責該部分的組織。

構建一個有效的“版本 0”服務具有巨大的優勢：一個跳舞的骨架應用程式，具有一小部分完整的功能，可以透過最小但有效的持續交付管道部署到生產環境。

新增服務註解應該成為所有服務的“版本 0”的重要組成部分。現在就新增它們，以後你會感謝自己的。