Creare un'infrastruttura di Azure AKS

In questo articolo, si effettuano il provisioning delle risorse Azure principali che servono per una distribuzione AKS pronta per la produzione. Questo articolo convalida l'accesso ad Azure, crea un gruppo di risorse, stabilisce un Registro Azure Container(ACR), distribuisce un cluster del servizio Azure Kubernetes di base, aggiunge facoltativamente un pool di nodi aggiuntivo per i carichi di lavoro utente e concede al cluster l'autorizzazione per il pull da Registro Azure Container. Tutti i comandi si basano su variabili di ambiente con parametri, in modo che il flusso di lavoro rimanga ripetibile tra aree e sottoscrizioni.

Prerequisiti

Prima di eseguire la guida, sono necessari gli strumenti e l'accesso all'account seguenti. Assicurarsi di essere autenticati in Azure usando az login e avere autorizzazioni sufficienti per creare gruppi di risorse, registri contenitori e cluster del servizio Azure Kubernetes.

  • Sottoscrizione di Azure con quota per l'area selezionata
  • Azure CLI (az) con autorizzazioni di proprietario o collaboratore
  • kubectl configurato in locale per l'accesso al cluster
  • jq (facoltativo) per l'analisi dell'output JSON durante la verifica

Eseguire i comandi seguenti per verificare di avere tutti gli strumenti necessari per l'interfaccia della riga di comando e l'accesso ad 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)"

Configurare l'ambiente

In questo caso si definiscono tutte le variabili di ambiente usate durante i passaggi di provisioning. Il HASH timestamp mantiene univoci i nomi delle risorse durante le esecuzioni ripetute. Le impostazioni predefinite del cluster e del registro sono destinate a un ingombro minimo per una prova di concetto, ma è possibile modificarle in base alle esigenze.

I comandi seguenti stabiliscono l'ambito di Azure, il dimensionamento del servizio Azure Kubernetes e le convenzioni di denominazione del Registro Azure Container per la sequenza di provisioning, a prescindere dai carichi di lavoro a valle.

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}"

Verificare i valori delle variabili di ambiente

Esaminare la configurazione effettiva prima di creare risorse. Eseguire di nuovo il blocco dopo eventuali modifiche per assicurarsi che i valori attivi siano corretti per la sottoscrizione e l'area di destinazione.

Usare i comandi seguenti per aggiungere i parametri attivi per convalidare le scelte di denominazione, ridimensionamento e area.

: "${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

Eseguire ogni passaggio in sequenza. Ogni sottosezione include scopo, comandi e un riepilogo per confermare i risultati previsti.

Controllare il contesto della sottoscrizione di Azure

Verificare la sottoscrizione Azure attiva ed assicurarsi che i provider di risorse necessari per le operazioni del Servizio Azure Kubernetes (AKS) e dell'Azure Container Registry (ACR) siano registrati.

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

Creare un gruppo di risorse

Effettuare il provisioning di un gruppo di risorse dedicato per isolare il cluster del servizio Azure Kubernetes, il registro e l'infrastruttura di supporto per i carichi di lavoro.

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

Configurare il Registro dei Contenitori di Azure

Creare un Registro Azure Container per archiviare le immagini del contenitore e autenticare il daemon Docker locale per eseguire il push delle immagini.

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

Creare il cluster servizio Azure Kubernetes

Distribuire il cluster AKS per ospitare i carichi di lavoro. Proteggersi dal riutilizzo di un nome del cluster esistente controllando prima della creazione.

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

Aggiungere un pool di nodi utente facoltativo

Effettuare il provisioning di un pool di nodi aggiuntivo quando richiesto. Il comando add viene eseguito in modo asincrono per evitare timeout dell'interfaccia della riga di comando; Il comando wait tiene traccia dello stato di avanzamento di Azure. Lo script controlla innanzitutto se il pool esiste già per evitare errori di nome duplicati.

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

Recuperare le credenziali del cluster

Integrare la configurazione Kubeconfig di AKS nel contesto locale e verificare che tutti i nodi siano raggiungibili.

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

Collegare ACR al cluster AKS

Concedere al cluster del servizio Azure Kubernetes l'autorizzazione per eseguire il pull delle immagini dall'ACR di cui è stato eseguito il provisioning affinché le distribuzioni future possano accedere alle immagini del contenitore.

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

Verifica

Verificare che il cluster AKS esista e risponda alle query di base kubectl prima di continuare con i passaggi di distribuzione downstream. Per iniziare, assicurarsi che il cluster AKS esista.

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

Se il cluster Azure Kubernetes Service (AKS) è stato creato, vedrai qualcosa del genere:

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

Verificare quindi che kubectl sia configurato correttamente:

kubectl cluster-info

Questo comando restituirà lo stato del cluster corrente, simile al seguente:

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

Assicurarsi infine che siano disponibili sia nodi di sistema che di utente:

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

Verrà restituito un conteggio dei nodi, simile al seguente:

      1 system
      1 user

Riepilogo: Convalidato che il cluster AKS sia presente, integro e raggiungibile tramite kubectl nel contesto corrente.

Riassunto

Il gruppo di risorse, il registro dei container, il cluster AKS (Azure Kubernetes Service), il pool di nodi facoltativo e l'allegato del registro vengono convalidati, lasciando il cluster pronto per tutti i carichi di lavoro containerizzati.

Passaggi successivi

  • Procedere con docs/OpenWebSearch_On_AKS.md per distribuire KMCP e il server MCP
  • Configurare le assegnazioni di ruolo o i criteri di rete in base alla postura di sicurezza
  • Integrare Monitoraggio di Azure o Log Analytics per la visibilità operativa
  • Eseguire i comandi di pulizia dell'infrastruttura dopo la sperimentazione per gestire i costi
  • Ultimo aggiornamento: