如何在 Azure Kubernetes Service 中使用服務連接器 (AKS)

Azure Kubernetes Service (AKS) 是服務連接器支援的其中一個計算服務。 本文旨在協助您了解：

• 建立服務連線時，叢集上會進行哪些作業。
• 如何使用 Kubernetes 資源服務連接器建立。
• 如何針對 AKS 叢集中的服務連接器進行疑難排解和檢視記錄。

必要條件

• 本指南假設您已了解服務連接器的基本概念 (部分機器翻譯)。

服務連接器在叢集上執行的作業

根據建立服務連線時選取的不同目標服務和驗證類型而定，服務連接器會在 AKS 叢集上進行不同的作業。 下方列出服務連接器可能進行的作業。

新增服務連接器 kubernetes 延伸模組

第一次建立服務連線時，將會為叢集新增名為 sc-extension 的 kubernetes 延伸模組。 之後，每當服務連接器收到服務連線要求時，延伸模組可協助在使用者的叢集中建立 kubernetes 資源。 您可以在 Azure 入口網站的 AKS 叢集中，從 [延伸模組 + 應用程式] 選單中找到延伸模組。

延伸模組也是叢集連線中繼資料的儲存位置。 解除安裝延伸模組會導致叢集中的所有連線無法使用。 延伸模組運算子裝載於叢集命名空間 sc-system 中。

建立 kubernetes 資源

服務連接器 會將一些 kubernetes 資源建立在服務連線建立時使用者所指定的命名空間。 kubernetes 資源會儲存連線資訊，以供使用者工作負載定義或應用程式程式碼用於與目標服務通訊。 根據不同的驗證類型，系統會建立不同的 kubernetes 資源。 針對 Connection String 和 Service Principal 驗證類型，將會建立 kubernetes 秘密。 針對 Workload Identity 驗證類型，除了 kubernetes 秘密之外，還會建立 kubernetes 服務帳戶。

您可以在 Azure 入口網站的 [服務連接器] 功能表中，找到服務連接器為 Azure 入口網站中每個服務連線所建立的 kubernetes 資源。

刪除服務連線並不會刪除相關聯的 Kubernetes 資源。 如有必要，請使用 kubectl delete 命令來手動刪除您的資源。

啟用 azureKeyvaultSecretsProvider 附加元件

如果目標服務是 Azure Key Vault，且建立服務連線時已啟用秘密存放區 CSI 驅動程式，則服務連接器會為叢集啟用 azureKeyvaultSecretsProvider 附加元件。

遵循使用 CSI 驅動程式連線到 Azure Key Vault 教學課程 (部分機器翻譯)，以使用秘密存放區 CSI 驅動程式設定 Azure Key Vault 的連線。

啟用工作負載身分識別和 OpenID Connect (OIDC) 簽發者

如果建立服務連線時的驗證類型為 Workload Identity，服務連接器會為叢集啟用工作負載身分識別和 OIDC 簽發者。

當驗證類型為 Workload Identity 時，需要使用者指派的受控識別才能建立同盟身分識別認證。 深入了解什麼是工作負載身分識別 (部分機器翻譯)，或遵循教學課程 (部分機器翻譯)，以使用工作負載身分識別設定 Azure 儲存體的連線。

如何使用服務連接器建立的 kubernetes 資源

當目標服務類型和驗證類型不同時，將會建立不同的 kubernetes 資源。 下列各節說明如何，在叢集工作負載定義和應用程式程式碼中，使用服務連接器建立的 kubernetes 資源。

Kubernetes 祕密

當驗證類型為 Connection String 或 Service Principal時，就會建立 kubernetes 秘密。 您的叢集工作負載定義可以直接參考秘密。 下列代碼段是範例。

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
spec:
  template:
    spec:
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

然後，您的應用程式程式碼可以從環境變數取用秘密中的連接字串。 您可以檢視範例程式碼 (部分機器翻譯)，以深入了解環境變數名稱，以及如何在應用程式程式碼中使用這些變數以向不同的目標服務進行驗證。

Kubernetes 服務帳戶

當驗證類型為 Workload Identity 時，將會建立 kubernetes 服務帳戶和秘密。 您的叢集工作負載定義可以參考服務帳戶和秘密，以透過工作負載身分識別進行驗證。 下列程式碼片段提供範例。

apiVersion: batch/v1
kind: Job
metadata:
  namespace: default
  name: sc-sample-job
  labels:
    azure.workload.identity/use: "true"
spec:
  template:
    spec:
      serviceAccountName: <ServiceAccountCreatedByServiceConnector>
      containers:
      - name: raw-linux
        image: alpine
        command: ['printenv']
        envFrom:
          - secretRef:
              name: <SecretCreatedByServiceConnector>
      restartPolicy: OnFailure

您可以檢查此教學課程以了解如何使用工作負載身分識別連線到 Azure 儲存體 (部分機器翻譯)。

如何進行疑難排解並檢視記錄

如果在建立服務連線時發生錯誤，且無法透過重試減緩，可採用下列方法收集詳細資訊以協助進行疑難排解。

檢查服務連接器 kubernetes 延伸模組

服務連接器 kubernetes 延伸模組是以已啟用 Azure Arc 的 Kubernetes 叢集延伸模組為基礎。 使用下列命令來調查延伸模組安裝或更新期間是否有任何錯誤。

1. 安裝 k8s-extension Azure CLI 延伸模組。

az extension add --name k8s-extension

1. 取得服務連接器延伸模組狀態。 檢查命令輸出中的 statuses 屬性，以查看是否有任何錯誤。

az k8s-extension show \
    --resource-group MyClusterResourceGroup \
    --cluster-name MyCluster \
    --cluster-type managedClusters \
    --name sc-extension

檢查 kubernetes 叢集記錄

如果在延伸模組安裝期間發生錯誤，而且 statuses 屬性中的錯誤訊息未提供所發生狀況的資訊，您可以透過下列步驟進一步檢查 kubernetes 記錄。

1. 連線至您的 AKS 叢集。

   az aks get-credentials \
       --resource-group MyClusterResourceGroup \
       --name MyCluster
   

2. 服務連接器延伸模組是透過 helm chart 安裝在命名空間 sc-system 中，並遵循下列命令來檢查命名空間和 helm 版本。

   • 檢查命名空間是否存在。

   kubectl get ns
   

   • 檢查 helm 版本狀態。

   helm list -n sc-system
   

3. 在延伸模組安裝或更新期間，名為 sc-job 的 kubernetes 作業會建立服務連線的 kubernetes 資源。 作業執行失敗通常會導致延伸模組失敗。 執行下列命令來檢查作業狀態。 如果 sc-system 命名空間中不存在 sc-job，則應該已順利執行。 此作業按照設計會在執行成功之後自動刪除。

   • 檢查作業是否存在。

   kubectl get job -n sc-system
   

   • 取得作業狀態。

   kubectl describe job/sc-job -n sc-system
   

   • 檢視作業記錄。

   kubectl logs job/sc-job -n sc-system
   

常見的錯誤和風險降低措施

衝突

錯誤訊息：Operation returned an invalid status code: Conflict。

原因：發生此錯誤通常是在 AKS (Azure Kubernetes Service) 叢集處於更新狀態時，嘗試建立服務連線所導致。 服務連線更新與進行中的更新衝突。 當您的訂用帳戶未向 Microsoft.KubernetesConfiguration 資源提供者註冊時，也可能會發生此情況。

避免方法：

• 執行下列命令，以確定您的訂用帳戶已註冊 Microsoft.KubernetesConfiguration 資源提供者。

  az provider register -n Microsoft.KubernetesConfiguration
  

• 請確定您的叢集處於「成功」狀態並重試建立。

Timeout

錯誤訊息：

• Long running operation failed with status 'Failed'. Unable to get a response from the Agent in time.
• Timed out waiting for the resource to come to a ready/completed state

原因：發生此錯誤通常是在用來建立或更新服務連接器叢集延伸模組的 Kubernetes 作業，因資源限制或其他問題而無法排程所導致。

風險降低措施：請參閱檢查 Kubernetes 叢集記錄以識別詳細原因並解決。 常見的問題是由於先佔，而導致沒有可用節點。 在此情況下，請考慮新增更多節點，或為您的節點啟用自動擴充。

未經授權的資源存取

錯誤訊息：You do not have permission to perform ... If access was recently granted, please refresh your credentials。

原因：服務連接器需要權限才能代表您執行連線作業，從而操作您想要連線的 Azure 資源。 此錯誤表示部分 Azure 資源缺少必要的權限。

風險降低措施：檢查錯誤訊息中指定的 Azure 資源權限， 取得必要的權限，然後重試建立。

缺少訂用帳戶註冊

錯誤訊息：The subscription is not registered to use namespace 'Microsoft.KubernetesConfiguration'

原因：服務連接器需要為 Microsoft.KubernetesConfiguration 註冊訂用帳戶，這是已啟用 Azure Arc 的 Kubernetes 叢集延伸模組資源提供者。

風險降低：執行下列命令來註冊 Microsoft.KubernetesConfiguration 資源提供者。 如需資源提供者註冊錯誤的詳細資訊，請參閱此教學課程。

az provider register -n Microsoft.KubernetesConfiguration

其他問題

如果上述風險降低措施無法解決您的問題，請嘗試移除服務連接器叢集延伸模組，然後重試建立。 此方法應該能解決服務連接器叢集延伸模組相關的大部分問題。

使用下列 CLI 命令來重設延伸模組：

az extension add --name k8s-extension

az k8s-extension delete \
    --resource-group <MyClusterResourceGroup> \
    --cluster-name <MyCluster> \
    --cluster-type managedClusters \
    --name sc-extension

下一步

了解如何整合不同的目標服務，並閱讀其組態設定和驗證方法的相關資訊。