開始在 AKS 上使用雲端儲存用分散式加速器(預覽)

此快速入門可透過受控延伸模組在現有 Azure Kubernetes Service (AKS)叢集上啟用分散式雲端儲存加速器(DACS),並授與 Azure Blob 容器讀取權限,並驗證重複讀取是否使用快取。 工作負載範例使用公開 dacs-client==0.1.0 套件。

Important

雲端儲存的分散式加速器目前處於預覽階段。 預覽功能是在沒有服務等級合約的情況下提供的,不建議用於生產工作負載。 欲了解更多資訊,請參閱 Microsoft Azure 預覽版補充使用條款。

Prerequisites

在開始之前,您需要:

  • Azure 訂用帳戶。
  • 一個符合 DACS 預覽支援需求 的現有 AKS 叢集。
  • 一個帶有本地 NVMe 資料磁碟的 Linux 快取節點池,例如 Standard_L*s_v3 VM 系列。
  • 一個 Azure 儲存體 帳號和包含代表性模型資料的 Blob 容器。
  • 一個 Bash shell,搭配 Azure CLI,kubectl以及 Docker 或其他容器映像建置工具。 在同一個殼層工作階段中執行本快速入門的命令,以保留可用的變數。
  • 允許安裝 AKS 擴充功能、管理 Kubernetes 資源、更新節點池標籤,以及指派本快速入門中使用的儲存資料存取角色。
  • 一個使用 Python 3.8 或更新版本和 glibc 2.35 或更新版本的工作負載映像檔。 這個快速入門在 x64 節點上使用 python:3.12-slim-bookworm 和 PyPI 套件 dacs-client==0.1.0。

雲端儲存的分散式加速器不會把快取節點池當作持久儲存。 Azure Blob 儲存體仍是具權威性的資料來源。

DACS 預覽支援需求

Requirement DACS 預覽支援
「Azure」區域 所有 Azure 公用雲端區域。
AKS Kubernetes 版本 1.35 或更新版本。

設定變數

替換佔位符值,然後執行以下指令:

SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group>
CLUSTER_NAME=<aks-cluster-name>
CACHE_NODE_POOL=<nvme-node-pool>
STORAGE_ACCOUNT=<storage-account-name>
STORAGE_CONTAINER=<blob-container-name>
CACHE_NAMESPACE=dacs-cache-system
CACHE_NAME=cache-sample

az account set --subscription $SUBSCRIPTION_ID
az aks get-credentials \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME

確保 AKS 預覽擴充功能

DACS 預覽版需要 aks-preview22.0.0b9 版或更新版本。 安裝或升級此擴充功能,以及用於管理和檢查 DACS 的擴充功能:

az extension add --name aks-preview --upgrade --yes
az extension show --name aks-preview --query version --output tsv
az extension add --name connectedk8s --upgrade --yes
az extension add --name k8s-extension --upgrade --yes

你不需要把 AKS 叢集連接到 Azure Arc。如果你已經手動安裝了 DACS 控制器,請先按照「升級準備」步驟再切換到管理擴充套件。 不要在同一叢集上同時使用兩個 DACS 控制器。

驗證快取節點池

確認所選節點集區是否使用 Linux,且使用具有本機 NVMe 資料磁碟的 VM 大小:

az aks nodepool show \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name $CACHE_NODE_POOL \
  --query '{osType:osType,vmSize:vmSize,count:count,powerState:powerState.code}' \
  --output table

對於雲端儲存的分散式加速器,請使用專用的快取節點池,或確認其他軟體是否會占用或格式化相同的本地 NVMe 磁碟。

在節點池層級標記快取節點池,讓標籤能在節點替換後存活。 如果集區已有自訂標籤,請在更新時一併包含這些標籤,以將其保留:

az aks nodepool update \
  --resource-group $RESOURCE_GROUP \
  --cluster-name $CLUSTER_NAME \
  --name $CACHE_NODE_POOL \
  --labels dacs.azure.com/processing-unit=cpu

Caution

啟用 DACS 會安裝必要元件 DaemonSet,以探索、格式化及掛接已標記之快取節點上的本機 NVMe 磁碟。 只標記有專用磁碟給快取的節點。

啟用雲端儲存的分散式加速器

僅傳入 distributedAccelerator 以啟用 DACS。 必須使用大寫的 A:

az aks update \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --enable-azure-container-storage distributedAccelerator

指令會安裝 distributedaccelerator 受管理擴充功能、DACS 控制器及 NVMe 前置 DaemonSet 於 kube-system,以及 caches.storage.azure.com 自訂資源定義(CRD)。 你不需要安裝獨立的前置需求 Chart,也不需要自己管理擴充套件的 Helm 發行版本。 如後面所示,請另行建立一個快取資源。

確認擴充功能

az k8s-extension show \
  --cluster-type managedClusters \
  --cluster-name $CLUSTER_NAME \
  --resource-group $RESOURCE_GROUP \
  --name distributedaccelerator \
  --query '{extensionType:extensionType,provisioningState:provisioningState,currentVersion:currentVersion,releaseTrain:releaseTrain}' \
  --output table

確認擴充功能類型為 microsoft.distributedaccelerator,且佈建狀態為 Succeeded。 已安裝的伺服器版本由 currentVersion 回報;請勿從用戶端套件版本或公開映像標籤推斷。

先記錄該版本以便故障排除,然後確認控制器和 CRD:

DACS_VERSION=$(az k8s-extension show \
  --cluster-type managedClusters \
  --cluster-name $CLUSTER_NAME \
  --resource-group $RESOURCE_GROUP \
  --name distributedaccelerator \
  --query currentVersion --output tsv)

echo "$DACS_VERSION"
kubectl rollout status deployment/dacs-manager --namespace kube-system --timeout=5m
kubectl get crd caches.storage.azure.com

只有在擴充功能進入 Succeeded 狀態且控制器準備好後才繼續。 如果安裝或就緒檢查失敗,請參閱針對雲端儲存分散式加速器進行疑難排解。

配置快取

驗證本地 NVMe 準備情況

受管理擴充功能透過其前置 DaemonSet 準備本地 NVMe 磁碟。 不要部署重複的磁碟設定工作負載,也不要安裝另一個必要條件 Chart。

kubectl rollout status daemonset/dacs-prereq \
  --namespace kube-system --timeout=10m

kubectl get daemonset dacs-prereq --namespace kube-system
kubectl get pods --namespace kube-system --selector app.kubernetes.io/name=dacs-prereq --output wide

確認 DaemonSet 在每個已加上標籤的快取節點上都有 Ready Pod。 掛載點為 /var/lib/ssd/cacheserver,且必須與快取資源的 spec.storage.hostPath.nodeCacheFolderPath 相符。 如果 DaemonSet 遺失或尚未就緒,請先停止,並檢查擴充功能版本和必要元件 Pod 事件,不要另行安裝圖表。

為快取建立專用命名空間並測試工作負載:

kubectl create namespace "$CACHE_NAMESPACE"

建立快取資源

建立快取資源。 範例中配置了三台快取伺服器,每個標記為 NVMe 的節點各有一台伺服器,且至少需要三個合格節點。 調整伺服器數量、快取大小、CPU 和記憶體以符合你的節點池。

cat <<EOF | kubectl apply -f -
apiVersion: storage.azure.com/v1
kind: Cache
metadata:
  name: $CACHE_NAME
  namespace: $CACHE_NAMESPACE
spec:
  scaling:
    static:
      numServers: 3
  serverSizeInGB: 1000
  serverThreads: 80
  cpuLimit: 4
  memoryLimitMB: 32000
  port: 9065
  metricsPort: 9096
  nodeSelectorKey: dacs.azure.com/processing-unit
  nodeSelectorValue: cpu
  storage:
    hostPath:
      nodeCacheFolderPath: /var/lib/ssd/cacheserver
EOF

驗證快取就緒狀態

等待指定的快取資源,而不是選擇叢集中的第一個快取:

kubectl wait \
  --namespace $CACHE_NAMESPACE \
  --for=condition=Ready \
  cache/$CACHE_NAME \
  --timeout=10m

kubectl get cache,pods \
  --namespace $CACHE_NAMESPACE \
  --output wide

確認目前與所需快取伺服器數量是否相符,且每個快取伺服器 Pod 是否運行於 NVMe 節點上。

取得工作負載用戶端使用的發現主機名稱:

CACHE_DISCOVERY_URL=$(kubectl get cache $CACHE_NAME \
  --namespace $CACHE_NAMESPACE \
  -o jsonpath='{.status.discoveryURL}')

echo $CACHE_DISCOVERY_URL

授權模型資料的讀取權限

此快速入門使用 AKS Kubelet 受控識別。 取得其物件 ID 和儲存帳號資源 ID:

KUBELET_OBJECT_ID=$(az aks show \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --query identityProfile.kubeletidentity.objectId \
  --output tsv)

KUBELET_CLIENT_ID=$(az aks show \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --query identityProfile.kubeletidentity.clientId \
  --output tsv)

STORAGE_ID=$(az storage account show \
  --resource-group $RESOURCE_GROUP \
  --name $STORAGE_ACCOUNT \
  --query id \
  --output tsv)

在容器範圍內指定最小權限的讀取角色:

az role assignment create \
  --assignee-object-id $KUBELET_OBJECT_ID \
  --assignee-principal-type ServicePrincipal \
  --role "Storage Blob Data Reader" \
  --scope "$STORAGE_ID/blobServices/default/containers/$STORAGE_CONTAINER"

角色指派可能需要幾分鐘才會生效。 要使用 kubelet 身分,請設定 pod 規格中所示的三個受控身分變數:AZURE_CLIENT_ID、MSI_ENDPOINT,以及非空的 MSI_SECRET。 僅設定 AZURE_CLIENT_ID 對這個用戶端組態來說是不夠的。

將用戶端加入工作負載映像檔

在你的建置目錄中建立一個名為 Dockerfile 的檔案,內容如下。 發行版名稱為 dacs-client,Python 匯入命名空間為py_dacs_client:

FROM python:3.12-slim-bookworm
RUN python3 -m pip install --no-cache-dir "dacs-client==0.1.0"

建立映像檔並推送到你的 AKS 叢集可以拉取的容器登錄。 對於 Azure Container Registry(ACR),在推送前先登入,並確保 kubelet 身份有映像拉取權限。 針對使用 RBAC 登錄權限的登錄,請在登錄範圍授與 AcrPull。 針對已啟用 ABAC 的登錄,請改用適當的存放庫讀取者角色。 如需詳細資料,請參閱從 Azure Kubernetes Service 向 Azure Container Registry 進行驗證。

WORKLOAD_IMAGE=<registry-name>.azurecr.io/dacs-test:0.1.0

docker build \
  --tag $WORKLOAD_IMAGE .
docker push $WORKLOAD_IMAGE

部署唯讀測試

選擇一個現有的模型 blob 並設定其路徑:

MODEL_BLOB=<path-to-model-blob>

建立測試 Pod。 Pod 從 blob 讀取最多 4 MiB 五次,讀取間隔一秒,並驗證所有讀取回傳相同的 SHA-256 校驗和。 快取填入是非同步的,因此立即進行第二次讀取可能會錯過快取。 這些間隔給予背景上傳完成的時間;利用用戶端指標與伺服器計數器確認快取命中,而非假設特定讀取即為命中。 要比較伺服器計數器,請在建立 Pod 前依照 「驗證 DACS 請求路徑」 擷取基準線。

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: dacs-test
  namespace: $CACHE_NAMESPACE
spec:
  restartPolicy: Never
  containers:
    - name: test
      image: $WORKLOAD_IMAGE
      env:
        - name: CACHE_DISCOVERY_URL
          value: "$CACHE_DISCOVERY_URL"
        - name: CACHE_SERVER_PORT
          value: "9065"
        - name: DACS_CPU_CORES
          value: "2"
        - name: DACS_MEMORY_MB
          value: "512"
        - name: AZURE_CLIENT_ID
          value: "$KUBELET_CLIENT_ID"
        - name: MSI_ENDPOINT
          value: "http://169.254.169.254/metadata/identity/oauth2/token"
        - name: MSI_SECRET
          value: "required-nonempty-value"
        - name: MODEL_PATH
          value: "az://$STORAGE_ACCOUNT.blob.core.windows.net/$STORAGE_CONTAINER/$MODEL_BLOB"
      command: ["python3", "-c"]
      resources:
        requests:
          cpu: "1"
          memory: 512Mi
        limits:
          cpu: "2"
          memory: 1Gi
      args:
        - |
          import asyncio
          import ctypes
          import hashlib
          import os
          import time

          from py_dacs_client.dacs_client import DACSCacheClient
          from py_dacs_client.dacs_utils import BoundedBufferManager

          async def main():
              path = os.environ["MODEL_PATH"]
              client = DACSCacheClient()
              buffers = BoundedBufferManager(max_memory_limit=64 * 1024 * 1024)
              try:
                  size = min(await client.get_file_size(path), 4 * 1024 * 1024)
                  if size == 0:
                      raise ValueError("Choose a nonempty model blob")
                  first_digest = None
                  for attempt in range(1, 6):
                      start = time.perf_counter()
                      buffer = await buffers.acquire_buffer(size)
                      try:
                          count = await client.read_blob(path, buffer, size, 0)
                          if count != size:
                              raise RuntimeError(f"Expected {size} bytes, received {count}")
                          digest = hashlib.sha256(ctypes.string_at(buffer, count)).hexdigest()
                          if first_digest is not None and digest != first_digest:
                              raise RuntimeError("Repeated reads returned different data")
                          first_digest = digest
                      finally:
                          await buffers.release_buffer(buffer)
                      elapsed = time.perf_counter() - start
                      print(f"read {attempt}: {count} bytes in {elapsed:.3f}s; sha256={digest}")
                      if attempt < 5:
                          await asyncio.sleep(1)
              finally:
                  await client.shutdown()

          asyncio.run(main())
EOF

kubectl wait \
  --namespace "$CACHE_NAMESPACE" \
  --for=jsonpath='{.status.phase}'=Succeeded \
  pod/dacs-test \
  --timeout=5m

kubectl logs dacs-test --namespace "$CACHE_NAMESPACE"

驗證 DACS 請求路徑

僅僅讀取成功或第二次讀取速度更快,並不代表請求已達 DACS,因為用戶端可以回退到 Azure Blob 儲存體。 同時設定 CACHE_DISCOVERY_URL 和 CACHE_SERVER_PORT。 如果任一者不存在,客戶端會記錄 Cache not configured. Working in Remote Blob mode only.

檢查 Pod 日誌中的客戶端關機指標 cache_client_download_cache_hits 和 cache_client_download_cache_misses。 快取命中次數非零表示請求已從快取中被送達。 用戶端計數器可以包含內部請求,且不一定等於應用程式讀取次數。

也要比較執行測試前後的快取伺服器請求計數器。 檢查每個快取伺服器 pod,因為請求可能由任何伺服器處理,不一定是第一個 pod。 要檢查一台伺服器:

CACHE_POD=$(kubectl get pods \
  --namespace $CACHE_NAMESPACE \
  --selector app=cacheserver \
  -o jsonpath='{.items[0].metadata.name}')

kubectl port-forward \
  --namespace $CACHE_NAMESPACE \
  pod/$CACHE_POD 9096:9096

在另一個終端機中,取得度量並檢查請求計數器:

curl --fail --silent --show-error http://localhost:9096/metrics > dacs-metrics.txt
grep '^cache_server_request_counter' dacs-metrics.txt

使用 request_type="Download" 和 status="Success" 確認下載要求增加,而不僅是確認計數器數列存在,因為該數列的值可能為零。 標籤值是區分大小寫的。 停止埠轉發,並對其他快取伺服器 Pod 重複此操作。 將用戶端快取命中指標與伺服器計數器及 Azure Blob 遙測數據關聯,以區分快取命中、來源流量及備援行為。

如需完整的計量參考和抓取設定,請參閱監視雲端儲存分散式加速器。

清除測試

kubectl delete pod dacs-test --namespace "$CACHE_NAMESPACE"

如果你不再需要快取,請在控制器運行時刪除快取資源:

kubectl delete cache "$CACHE_NAME" --namespace "$CACHE_NAMESPACE" --wait=true
kubectl get cache -A

只有當命名空間是專門用於此快速入門且不包含你需要保留的資源時,才刪除該命名空間:

kubectl delete namespace "$CACHE_NAMESPACE"

移除所有快取資源與相依工作負載後,停用受管理擴充功能:

az aks update \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --disable-azure-container-storage distributedAccelerator

停用 DACS 會移除其管理擴充功能、控制器及前置 DaemonSet,但保留快取 CRD。 不要分別刪除受管理的前置條件,也不要直接卸載擴充套件的 Helm 發行版本,或手動刪除 CRD。 確認沒有其他工作負載需要之後,才可移除專為此快速入門新增的角色指派或節點集區標籤。

欲了解更多資訊,請參閱 移除雲端儲存的分散式加速器。

下一步