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

為人類標註 Kubernetes 服務

作者：Richard Li (Ambassador Labs) |

您是否曾被要求排除故障 Kubernetes 服務，卻難以找到有關該服務的基本資訊，例如原始碼儲存庫和擁有者？

隨著 Kubernetes 應用程式的成長，問題之一是服務的激增。隨著服務數量的增長，開發人員開始專注於使用特定服務。然而，在進行故障排除時，開發人員需要能夠找到原始碼、了解服務和依賴關係，並與任何服務的擁有團隊聊天。

人工服務探索

故障排除始終從資訊收集開始。雖然人們已非常關注集中化機器數據（例如，日誌、指標），但對服務探索的人工方面卻關注較少。誰擁有特定的服務？團隊在哪個 Slack 頻道上工作？服務的原始碼在哪裡？目前已知和正在追蹤哪些問題？

Kubernetes 註釋

Kubernetes 註釋旨在精確地解決這個問題。Kubernetes 註釋經常被忽略，但它們旨在將元數據添加到 Kubernetes 物件。Kubernetes 文件指出，註釋可以「將任意非識別元數據附加到物件」。這表示註釋應該用於附加 Kubernetes 外部的元數據（即 Kubernetes 不會用來識別物件的元數據）。因此，註釋可以包含任何類型的資料。這與標籤形成對比，標籤旨在用於 Kubernetes 內部。因此，標籤結構和值受到約束，以便 Kubernetes 可以有效率地使用它們。

實際運作中的 Kubernetes 註釋

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

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 Manifest 中，例如：

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連結到外部專案 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 服務目錄建立在 Open Service Broker API 之上，使 Kubernetes 運營商能夠將不同的服務（例如，資料庫）插入到他們的叢集中。

立即註釋您的服務，以後會感謝自己

就像在微服務系統中實作可觀察性一樣，您通常不會意識到自己需要人工服務探索，直到為時已晚。不要等到生產環境中的某些東西著火了，才開始希望您已實作更好的指標，並記錄了如何與您組織中負責管理它的部門取得聯繫。

建構有效的「版本 0」服務有巨大的好處：一個 dancing skeleton 應用程式，具有一小部分完整的功能，可以使用最小但有效的持續交付管道部署到生產環境。

為所有服務新增服務註釋應該是您的「版本 0」的重要組成部分。立即新增它們，以後您會感謝自己。