建立 Azure AKS 基礎架構

在本文中，您將配置 Azure 核心資源，用於可供生產環境使用的 AKS 部署。本文驗證 Azure 存取權限，建立資源群組，建立 Azure 容器登錄檔（ACR），部署基線 AKS 叢集，並可選擇新增一個使用者工作負載的節點池，並授權叢集從 ACR 拉取資料。所有指令都依賴參數化的環境變數，確保工作流程能在不同區域和訂閱間重複使用。

先決條件

在執行本指南前，你需要具備以下工具和帳號權限。確保你已透過 Azure az login 認證，並擁有足夠的權限來建立資源群組、容器登錄檔和 AKS 叢集。

Azure 訂閱，具備指定區域的配額限制
Azure CLI （az）具有擁有者或貢獻者權利
Kubectl 本地配置用於叢集存取
JQ（可選）用於驗證時解析 JSON 輸出

執行以下指令確認你已具備所有必要的 CLI 工具及 Azure 存取權限：

command -v az >/dev/null || echo "Azure CLI missing"
command -v kubectl >/dev/null || echo "kubectl missing"
command -v jq >/dev/null || echo "jq missing (optional)"

進行環境設定

在這裡，你定義了所有在配置步驟中使用的所有環境變數。 HASH時間戳記會在重複執行時保持資源名稱唯一。叢集和登錄的預設值以最小化概念驗證的規模為目標，但您可以視需要進行調整。

以下命令用於建立 Azure 範圍、AKS 調整大小及 ACR 命名慣例，用於整個佈建序列，不受下游工作負載影響。

export HASH="${HASH:-$(date -u +"%y%m%d%H%M")}"  # YYMMDDHHMM stamp

# Azure scope and regional placement
export LOCATION="${LOCATION:-eastus2}"
export SUBSCRIPTION_ID="${SUBSCRIPTION_ID:-$(az account show --query id -o tsv)}"
export RESOURCE_GROUP="${RESOURCE_GROUP:-rg_aks_${HASH}}"

# AKS cluster naming and version control
# Hyphen required because AKS cluster names cannot include underscores
export AKS_CLUSTER_NAME="${AKS_CLUSTER_NAME:-aks-openwebsearch-${HASH}}"
export AKS_VERSION="${AKS_VERSION:-}"  # Optional Kubernetes version override

# Node pool sizing
export AKS_SYSTEM_NODE_COUNT="${AKS_SYSTEM_NODE_COUNT:-1}"
export AKS_USER_NODE_COUNT="${AKS_USER_NODE_COUNT:-1}"
export AKS_NODE_VM_SIZE="${AKS_NODE_VM_SIZE:-Standard_D4s_v5}"
export AKS_SYSTEM_NODEPOOL_NAME="${AKS_SYSTEM_NODEPOOL_NAME:-system}"
export AKS_USER_NODEPOOL_NAME="${AKS_USER_NODEPOOL_NAME:-user}"

# ACR configuration
export ACR_NAME="${ACR_NAME:-acrwebsearch${HASH}}"
export ACR_LOGIN_SERVER="${ACR_LOGIN_SERVER:-${ACR_NAME}.azurecr.io}"

驗證環境變數的值

在建立資源前，先檢視有效的配置。調整後重新執行區塊，以確保活躍值符合目標訂閱和區域。

請使用以下指令釘選啟用參數，以驗證命名、大小及區域選擇。

: "${HASH:=$(date -u +"%y%m%d%H%M")}"  # Ensure HASH exists

VARS=(
  HASH
  LOCATION
  SUBSCRIPTION_ID
  RESOURCE_GROUP
  AKS_CLUSTER_NAME
  AKS_VERSION
  AKS_SYSTEM_NODE_COUNT
  AKS_USER_NODE_COUNT
  AKS_NODE_VM_SIZE
  AKS_SYSTEM_NODEPOOL_NAME
  AKS_USER_NODEPOOL_NAME
  ACR_NAME
  ACR_LOGIN_SERVER
)
for v in "${VARS[@]}"; do
  printf "%s=%s\n" "$v" "${!v}"
done

Steps

依序執行每個步驟。每個小節都包含目的、指令及摘要以確認預期結果。

請查看 Azure 訂閱的上下文

確認 Azure 的有效訂閱，並確保 AKS 和 ACR 操作所需的資源提供者已註冊。

az account show --query id -o tsv
az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.ContainerRegistry

建立資源群組

配置一個專用資源群組，來隔離 AKS 叢集、登錄檔及支援基礎架構以支援你的工作負載。

az group create \
  --name "${RESOURCE_GROUP}" \
  --location "${LOCATION}" \
  --output table

配置 Azure 容器登錄檔

建立一個 Azure 容器登錄檔來儲存容器映像檔，並驗證本地 Docker 守護程序以推送映像檔。

az acr create \
  --name "${ACR_NAME}" \
  --resource-group "${RESOURCE_GROUP}" \
  --location "${LOCATION}" \
  --sku Basic \
  --output table
az acr login --name "${ACR_NAME}"

建立 AKS 叢集

部署 AKS 叢集來承載你的工作負載。建立前請先檢查，避免重複使用現有叢集名稱。

if az aks show \
  --name "${AKS_CLUSTER_NAME}" \
  --resource-group "${RESOURCE_GROUP}" >/dev/null 2>&1; then
  echo "AKS cluster ${AKS_CLUSTER_NAME} already exists in ${RESOURCE_GROUP}";
  echo "Skip creation or provide a new AKS_CLUSTER_NAME.";
else
  az aks create \
    --name "${AKS_CLUSTER_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --location "${LOCATION}" \
    --generate-ssh-keys \
    --node-count "${AKS_SYSTEM_NODE_COUNT}" \
    --nodepool-name "${AKS_SYSTEM_NODEPOOL_NAME}" \
    --node-vm-size "${AKS_NODE_VM_SIZE}" \
    ${AKS_VERSION:+--kubernetes-version "${AKS_VERSION}"} \
    --output table
fi

新增可選的使用者節點池

在需要時，配置額外的節點池。 add 指令會非同步執行以避免 CLI 逾時;等待指令追蹤 Azure 的進度。腳本會先檢查該池是否已經存在，以防止重複名稱錯誤。

if [ "${AKS_USER_NODE_COUNT}" -gt 0 ]; then
  if az aks nodepool show \
    --cluster-name "${AKS_CLUSTER_NAME}" \
    --resource-group "${RESOURCE_GROUP}" \
    --name "${AKS_USER_NODEPOOL_NAME}" >/dev/null 2>&1; then
    echo "Node pool ${AKS_USER_NODEPOOL_NAME} already exists; skipping add.";
  else
    az aks nodepool add \
      --cluster-name "${AKS_CLUSTER_NAME}" \
      --resource-group "${RESOURCE_GROUP}" \
      --name "${AKS_USER_NODEPOOL_NAME}" \
      --node-count "${AKS_USER_NODE_COUNT}" \
      --node-vm-size "${AKS_NODE_VM_SIZE}" \
      --no-wait
    az aks nodepool wait \
      --cluster-name "${AKS_CLUSTER_NAME}" \
      --resource-group "${RESOURCE_GROUP}" \
      --name "${AKS_USER_NODEPOOL_NAME}" \
      --created
  fi
fi

取得叢集憑證

將 AKS 的 kubeconfig 合併到本地情境，並確認所有節點都可被存取。

az aks get-credentials \
  --name "${AKS_CLUSTER_NAME}" \
  --resource-group "${RESOURCE_GROUP}" \
  --overwrite-existing
kubectl get nodes -o wide

把 ACR 附加到 AKS 叢集

授權 AKS 叢集從已配置的 ACR 拉取映像檔，讓未來部署能存取你的容器映像檔。

az aks update \
  --name "${AKS_CLUSTER_NAME}" \
  --resource-group "${RESOURCE_GROUP}" \
  --attach-acr "${ACR_NAME}" \
  --output table

驗證

確認 AKS 叢集存在並回應基本 kubectl 查詢，然後再進行下游部署步驟。首先確認 AKS 叢集的存在。

if ! az aks show \
  --name "${AKS_CLUSTER_NAME}" \
  --resource-group "${RESOURCE_GROUP}" \
  --query "{name:name,provisioningState:provisioningState,location:location}" \
  --output table; then
  echo "AKS cluster '${AKS_CLUSTER_NAME}' not found in resource group '${RESOURCE_GROUP}'."
else
  echo "AKS cluster '${AKS_CLUSTER_NAME}' exists in resource group '${RESOURCE_GROUP}'."
fi

如果 AKS 叢集已經建立，你會看到類似這樣的情況：

AKS cluster ${AKS_CLUSTER_NAME} exists in resource group ${RESOURCE_GROUP}.

接著，檢查是否 kubectl 正確設定：

kubectl cluster-info

此指令會輸出當前叢集的狀態，大致如下：

Kubernetes control plane is running at ...
CoreDNS is running at https://...
Metrics-server is running at https://...

最後，確保系統與使用者節點同時可用：

kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.labels.agentpool}{"\n"}{end}' |
  sort |
  uniq -c

這會輸出節點數量，大致如下：

      1 system
      1 user

摘要：已驗證 AKS 叢集存在且健康，且在當前情境下可透過 kubectl 取得。

總結

資源群組、容器登錄檔、AKS 叢集、可選節點池及登錄檔附件都會被驗證，讓叢集準備好應付任何容器化的工作負載。

後續步驟

繼續使用 docs/OpenWebSearch_On_AKS.md 來部署 KMCP 與 MCP 伺服器
根據你的安全態勢設定角色分配或網路政策
整合 Azure Monitor 或 Log Analytics 以提升營運可視性
實驗後執行基礎設施清理指令以控制成本

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2025-12-16