创建 Azure AKS 基础结构

在本文中，你将预配生产就绪的 AKS 部署所需的核心 Azure 资源。本文验证 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)"

设置环境

在这里，定义预配步骤中使用的所有环境变量。重复执行期间，时间戳可确保资源名称的唯一性。集群和注册表的默认值以概念验证的最小化影响为目标，但你可以根据需要对其进行调整。

以下命令为预配序列建立 Azure 范围、AKS 大小调整和 ACR 命名约定，而不考虑下游工作负荷。

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

# Azure scope and regional placement
export LOCATION="${LOCATION:-chinanorth3}"
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.cn}"

验证环境变量值

在创建资源之前查看有效配置。在进行任何调整后重新运行该块，以确保目标订阅和区域的活动值正确无误。

使用以下命令固定活动参数以验证命名、大小调整和区域选择。

: "${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 以实现操作可见性
在试验后运行基础结构清理命令来管理成本

Last updated on 2025-12-31

通过