Criar e provisionar um cluster usando a CLI do Azure

Artigo
10/29/2024

Este artigo descreve como criar um cluster usando a AzCLI (interface de linha de comando do Azure). Este documento também mostra como verificar o status, atualizar ou excluir um cluster.

Pré-requisitos

Verificar se o controlador de malha de rede e o gerenciador de cluster existem em sua região do Azure
Verificar se a malha de rede foi provisionada com êxito

Guia e métricas da API

O guia de API fornece informações sobre provedores e modelos de recursos e as APIs.

As métricas geradas com base nos dados de log estão disponíveis nas métricas do Azure Monitor.

Limitações

Nomenclatura: As regras de nomenclatura podem ser encontradas aqui.

Criar um cluster

O recurso de cluster de infraestrutura representa uma implantação local da plataforma no Gerenciador de Cluster. Todos os outros recursos específicos da plataforma dependem dele para seu ciclo de vida.

Você deve criar o Network Fabric antes dessa implantação local. Cada instância local do Nexus do Operador tem uma associação individual com uma malha de rede.

Crie o cluster usando a CLI do Azure:

az networkcloud cluster create --name "$CLUSTER_NAME" --location "$LOCATION" \
  --extended-location name="$CL_NAME" type="CustomLocation" \
  --resource-group "$CLUSTER_RG" \
  --analytics-workspace-id "$LAW_ID" \
  --cluster-location "$CLUSTER_LOCATION" \
  --network-rack-id "$AGGR_RACK_RESOURCE_ID" \
  --rack-sku-id "$AGGR_RACK_SKU"\
  --rack-serial-number "$AGGR_RACK_SN" \
  --rack-location "$AGGR_RACK_LOCATION" \
  --bare-metal-machine-configuration-data "["$AGGR_RACK_BMM"]" \
  --storage-appliance-configuration-data '[{"adminCredentials":{"password":"$SA_PASS","username":"$SA_USER"},"rackSlot":1,"serialNumber":"$SA_SN","storageApplianceName":"$SA_NAME"}]' \
  --compute-rack-definitions '[{"networkRackId": "$COMPX_RACK_RESOURCE_ID", "rackSkuId": "$COMPX_RACK_SKU", "rackSerialNumber": "$COMPX_RACK_SN", "rackLocation": "$COMPX_RACK_LOCATION", "storageApplianceConfigurationData": [], "bareMetalMachineConfigurationData":[{"bmcCredentials": {"password":"$COMPX_SVRY_BMC_PASS", "username":"$COMPX_SVRY_BMC_USER"}, "bmcMacAddress":"$COMPX_SVRY_BMC_MAC", "bootMacAddress":"$COMPX_SVRY_BOOT_MAC", "machineDetails":"$COMPX_SVRY_SERVER_DETAILS", "machineName":"$COMPX_SVRY_SERVER_NAME"}]}]'\
  --managed-resource-group-configuration name="$MRG_NAME" location="$MRG_LOCATION" \
  --network fabric-id "$NF_ID" \
  --cluster-service-principal application-id="$SP_APP_ID" \
    password="$SP_PASS" principal-id="$SP_ID" tenant-id="$TENANT_ID" \
  --subscription "$SUBSCRIPTION_ID" \
  --secret-archive "{key-vault-id:$KVRESOURCE_ID, use-key-vault:true}" \
  --cluster-type "$CLUSTER_TYPE" --cluster-version "$CLUSTER_VERSION" \
  --tags $TAG_KEY1="$TAG_VALUE1" $TAG_KEY2="$TAG_VALUE2"

Parâmetros para operações de cluster

Nome do parâmetro	Descrição
CLUSTER_NAME	Nome do recurso do cluster
LOCALIZAÇÃO	A região do Azure na qual o cluster é implantado
CL_NAME	O Local Personalizado do Gerenciador de Clusters de portal do Azure
CLUSTER_RG	O nome do grupo de recursos do cluster
LAW_ID	ID do workspace do Log Analytics para o cluster
CLUSTER_LOCATION	O nome local do cluster
AGGR_RACK_RESOURCE_ID	RackID para Rack de Agregador
AGGR_RACK_SKU	Rack SKU para Rack de Agregador *Consulte SKUs de nuvem de rede do Operador Nexus
AGGR_RACK_SN	Número de série do rack para Rack de Agregador
AGGR_RACK_LOCATION	Local físico do Rack de Agregador
AGGR_RACK_BMM	Usado somente para implantação de rack único; vazio em caso de vários racks
SA_NAME	Nome do dispositivo de armazenamento
SA_PASS	Senha de administrador do dispositivo de armazenamento
SA_USER	Usuário administrador do dispositivo de armazenamento
SA_SN	Número de série do dispositivo de armazenamento
COMPX_RACK_RESOURCE_ID	RackID para Rack CompX; repita para cada rack em compute-rack-definitions
COMPX_RACK_SKU	Rack SKU para Rack CompX; repetir para cada rack em definições de rack de computação *Consulte SKUs de nuvem de rede do Operador Nexus
COMPX_RACK_SN	Número de série de rack para Rack CompX; repita para cada rack em compute-rack-definitions
COMPX_RACK_LOCATION	Local físico do Rack CompX; repita para cada rack em compute-rack-definitions
COMPX_SVRY_BMC_PASS	Senha do BMC (Controlador BMC) do CompX Rack ServerY; repetir para cada rack em compute-rack-definitions e para cada servidor no rack
COMPX_SVRY_BMC_USER	CompX Rack ServerY usuário BMC; repita para cada rack em compute-rack-definitions e para cada servidor em rack
COMPX_SVRY_BMC_MAC	Servidor em rack CompXY Endereço MAC BMC; repita para cada rack em compute-rack-definitions e para cada servidor em rack
COMPX_SVRY_BOOT_MAC	Endereço MAC da NIC (Placa de Interface de Rede) de inicialização do CompX Rack ServerY; repetir para cada rack em compute-rack-definitions e para cada servidor no rack
COMPX_SVRY_SERVER_DETAILS	Detalhes do CompX Rack ServerY; repita para cada rack em compute-rack-definitions e para cada servidor em rack
COMPX_SVRY_SERVER_NAME	Nome CompX Rack ServerY; repetir para cada rack em compute-rack-definitions e para cada servidor no rack
MRG_NAME	Nome do grupo de recursos gerenciados do cluster
MRG_LOCATION	Região do Azure do cluster
NF_ID	Referência ao Network Fabric
SP_APP_ID	ID de aplicativo da entidade de serviço
SP_PASS	Senha da entidade de serviço
SP_ID	ID da Entidade de Serviço
TENANT_ID	ID de locatário da assinatura
SUBSCRIPTION_ID	ID da assinatura
KV_RESOURCE_ID	Key Vault ID
CLUSTER_TYPE	Tipo de cluster, Único ou MultiRack
CLUSTER_VERSION	Versão NC (Nuvem de Rede) do cluster
TAG_KEY1	Tag1 opcional para transmissão à Criação de Cluster
TAG_VALUE1	Valor de tag1 opcional para transmissão à Criação de Cluster
TAG_KEY2	Tag2 opcional para transmissão à Criação de Cluster
TAG_VALUE2	Valor de tag2 opcional para transmissão à Criação de Cluster

Identidade do cluster

A partir da versão 2024-07-01 da API, um cliente pode atribuir identidade gerenciada a um cluster. Há suporte para identidades gerenciadas atribuídas pelo sistema e pelo usuário.

A Identidade Gerenciada pode ser atribuída ao Cluster durante as operações de criação ou atualização, fornecendo os seguintes parâmetros:

--mi-system-assigned – Habilita a identidade gerenciada atribuída pelo sistema. Depois de adicionada, a Identidade só pode ser removida por meio da chamada à API no momento.
--mi-user-assigned – IDs de recurso separadas por espaço das identidades gerenciadas atribuídas pelo usuário a serem adicionadas. Depois de adicionada, a Identidade só pode ser removida por meio da chamada à API no momento.

Crie o Cluster usando o editor de modelos do Azure Resource Manager:

Uma maneira alternativa de criar um Cluster é com o editor de modelo do ARM.

Para criar o cluster dessa forma, você precisa fornecer um arquivo de modelo (cluster.jsonc) e um arquivo de parâmetro (cluster.parameters.jsonc). Você pode encontrar exemplos para um cluster de SKU 2M16C de 8 racks usando estes dois arquivos:

cluster.jsonc, cluster.parameters.jsonc

Observação

Para obter a formatação correta, copie o arquivo de código bruto. Os valores dentro do arquivo cluster.parameters.jsonc são específicos do cliente e podem não ser uma lista completa. Atualize os campos de valor para seu ambiente específico.

Navegue até o portal do Azure em um navegador da Web e entre.
Pesquise por "Implantar um modelo personalizado" na barra de pesquisa do portal do Azure e selecione-o nos serviços disponíveis.
Clique em Criar seu próprio modelo no editor.
Clique em Carregar arquivo. Localize o arquivo de modelo cluster.jsonc e carregue-o.
Clique em Save (Salvar).
Clique em Editar parâmetros.
Clique em Carregar arquivo. Localize o arquivo de parâmetros cluster.parameters.jsonc e carregue-o.
Clique em Save (Salvar).
Selecione a Assinatura correta.
Pesquise o grupo de recursos para ver se ele já existe. Se não existir, crie um grupo de Recursos.
Verifique se todos os Detalhes da Instância estão corretos.
Clique em Revisar + Criar.

Validação de cluster

Uma criação bem-sucedida do cluster Nexus do Operador resulta na criação de um cluster do AKS dentro da sua assinatura. A ID do cluster, o estado de provisionamento de cluster e o estado de implantação são retornados como resultado de um cluster create bem-sucedido.

Exiba o status do Cluster:

az networkcloud cluster show --resource-group "$CLUSTER_RG" \
  --cluster-name "$CLUSTER_RESOURCE_NAME"

A implantação do cluster é concluída quando o provisioningState do recurso mostra: "provisioningState": "Succeeded"

Registro em log do cluster

Os logs de criação de cluster podem ser exibidos nos seguintes locais:

Logs de atividades Resource/ResourceGroup no portal do Azure.
CLI do Azure com sinalizador --debug transmitido na linha de comando.

Implantar o cluster

A ação implantar Cluster pode ser disparada após a criação do Cluster. A ação de implantação de cluster cria a imagem de inicialização e implanta o cluster.

A implantação de cluster iniciará uma sequência de eventos que ocorre no Gerenciador de Cluster.

Validação das propriedades de cluster/rack.
Geração de uma imagem inicializável para o cluster de inicialização efêmera (validação da infraestrutura).
Interação com a interface IPMI (Interface de Gerenciamento de Plataforma Inteligente) do computador inicializado de destino.
Executando verificações de validação de hardware.
Monitoramento do processo de implantação de cluster.

Implante o cluster local:

az networkcloud cluster deploy \
  --name "$CLUSTER_NAME" \
  --resource-group "$CLUSTER_RG" \
  --subscription "$SUBSCRIPTION_ID" \
  --no-wait --debug

Dica

Para verificar o status do comando az networkcloud cluster deploy, ele pode ser executado usando o sinalizador --debug. Isso permitirá que você obtenha o cabeçalho Azure-AsyncOperation ou Location usado para consultar o recurso operationStatuses. Consulte a seção Falha no cluster deploy para obter etapas mais detalhadas. Se você desejar, o comando poderá ser executado de forma assíncrona usando o sinalizador --no-wait.

Implantação de cluster com validação de hardware

Durante um processo de cluster deploy, uma das etapas executadas é a validação de hardware. O procedimento de validação de hardware executa vários testes e verificações nos computadores fornecidos por meio da definição de rack do cluster. Com base nos resultados dessas verificações e em quaisquer máquinas ignoradas pelo usuário, é feita uma determinação se nós suficientes foram passados e/ou estão disponíveis para atender aos limites necessários para que a implementação continue.

Importante

O processo de validação de hardware vai gravar os resultados no analyticsWorkspaceId especificado na criação do cluster. Além disso, a Entidade de Serviço fornecida no objeto Cluster é usada para autenticação na API de Coleta de Dados do Workspace do Log Analytics. Essa funcionalidade só fica visível durante uma nova implantação (Campo Verde); o cluster existente não terá os logs disponíveis retroativamente.

Observação

O controlador RAID é redefinido durante a implantação do cluster, apagando todos os dados dos discos virtuais do servidor. Qualquer alerta de disco virtual do BMC (Controlador BMC) normalmente pode ser ignorado, a menos que haja alertas adicionais de disco físico e/ou controladores RAID.

Por padrão, o processo de validação de hardware grava os resultados no cluster configurado analyticsWorkspaceId. No entanto, devido à natureza da coleta de dados do Workspace do Log Analytics e à avaliação do esquema, talvez ocorra um atraso de ingestão que pode levar vários minutos ou mais. Por esse motivo, a implantação do cluster continuará mesmo se houver uma falha ao gravar os resultados no Workspace do Log Analytics. Para ajudar a resolver esse possível evento, os resultados, para redundância, também são registrados no Gerenciador de Cluster.

No Workspace do Log Analytics do objeto Cluster fornecido, uma nova tabela personalizada com o nome do cluster como prefixo e o sufixo *_CL deve aparecer. Na seção Logs do recurso LAW, uma consulta pode ser executada na nova tabela de log personalizado *_CL.

Implantação de cluster com ignorar computador bare-metal específico

O parâmetro --skip-validation-for-machines representa os nomes de computadores bare-metal no cluster que devem ser ignorados durante a validação de hardware. Os nós ignorados não são validados e não são adicionados ao pool de nós. Além disso, os nós ignorados não contam no total usado pelos cálculos de limite.

az networkcloud cluster deploy \
  --name "$CLUSTER_NAME" \
  --resource-group "$CLUSTER_RG" \
  --subscription "$SUBSCRIPTION_ID" \
  --skip-validations-for-machines "$COMPX_SVRY_SERVER_NAME"

Falha no cluster deploy

Para acompanhar o status de uma operação assíncrona, execute com um sinalizador --debug habilitado. Quando --debug é especificado, o progresso da solicitação pode ser monitorado. A URL de status da operação pode ser encontrada ao examinar a saída de depuração procurando o cabeçalho Azure-AsyncOperation ou Location na resposta HTTP à solicitação de criação. Os cabeçalhos podem fornecer o campo OPERATION_ID usado na chamada à API HTTP.

OPERATION_ID="12312312-1231-1231-1231-123123123123*99399E995..."
az rest -m GET -u "https://management.azure.com/subscriptions/${SUBSCRIPTION_ID}/providers/Microsoft.NetworkCloud/locations/${LOCATION}/operationStatuses/${OPERATION_ID}?api-version=2022-12-12-preview"

A saída é semelhante ao exemplo de struct de JSON. Quando o código de erro é HardwareValidationThresholdFailed, a mensagem de erro contém uma lista de computadores bare-metal que falharam na validação de hardware (por exemplo, COMP0_SVR0_SERVER_NAME, COMP1_SVR1_SERVER_NAME). Esses nomes podem ser usados para analisar os logs para obter mais detalhes.

{
  "endTime": "2023-03-24T14:56:59.0510455Z",
  "error": {
    "code": "HardwareValidationThresholdFailed",
    "message": "HardwareValidationThresholdFailed error hardware validation threshold for cluster layout plan is not met for cluster $CLUSTER_NAME in namespace nc-system with listed failed devices $COMP0_SVR0_SERVER_NAME, $COMP1_SVR1_SERVER_NAME"
  },
  "id": "/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.NetworkCloud/locations/$LOCATION/operationStatuses/12312312-1231-1231-1231-123123123123*99399E995...",
  "name": "12312312-1231-1231-1231-123123123123*99399E995...",
  "resourceId": "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$CLUSTER_RESOURCE_GROUP/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME",
  "startTime": "2023-03-24T14:56:26.6442125Z",
  "status": "Failed"
}

Consulte o artigo Acompanhamento de operações assíncronas usando a CLI do Azure para obter outro exemplo. Consulte o artigo Solucionar problemas de provisionamento do BMM para obter mais informações que podem ser úteis quando computadores específicos falham na validação ou implantação.

Validação de implantação de cluster

Exibir o status do cluster no portal ou por meio da CLI do Azure:

az networkcloud cluster show --resource-group "$CLUSTER_RG" \
  --name "$CLUSTER_NAME"

A implantação do cluster está em andamento quando detailedStatus é definido como Deploying e detailedStatusMessage mostra o progresso da implantação. Alguns exemplos de progresso da implantação mostrados em detailedStatusMessage são Hardware validation is in progress. (se o cluster for implantado com validação de hardware), Cluster is bootstrapping., KCP initialization in progress., Management plane deployment in progress., Cluster extension deployment in progress., waiting for "<rack-ids>" to be ready, etc.

A implantação do cluster é concluída quando detailedStatus é definido como Running e detailedStatusMessage mostra a mensagem Cluster is up and running.

Veja a versão de gerenciamento do cluster:

az k8s-extension list --cluster-name "$CLUSTER_NAME" --resource-group "$MRG_NAME" --cluster-type connectedClusters --query "[?name=='nc-platform-extension'].{name:name, extensionType:extensionType, releaseNamespace:scope.cluster.releaseNamespace,provisioningState:provisioningState,version:version}" -o table --subscription "$SUBSCRIPTION_ID"

Registro em log de implantação de cluster

Os logs de criação de cluster podem ser exibidos nos seguintes locais:

Logs de atividades Resource/ResourceGroup no portal do Azure.
CLI do Azure com sinalizador --debug transmitido na linha de comando.

Atualizar identidades de cluster por meio de APIs

As identidades gerenciadas por cluster podem ser atribuídas por meio da CLI. A desatribuição das identidades pode ser feita por meio de chamadas de API. Observe que <APIVersion> é a versão 2024-07-01 ou mais recente da API.

Para remover todas as identidades gerenciadas, execute:

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body "{\"identity\":{\"type\":\"None\"}}"

Se as identidades gerenciadas atribuídas pelo usuário e pelo sistema tiverem sido adicionadas, a atribuição do usuário poderá ser removida atualizando o type para SystemAssigned:

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

O exemplo do corpo da solicitação (uai-body.json):

{
  "identity": {
      "type": "SystemAssigned"
  }
}

Se as identidades gerenciadas atribuídas pelo usuário e pelo sistema tiverem sido adicionadas, a atribuição do Sistema poderá ser removida atualizando o type para UserAssigned:

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

O exemplo do corpo da solicitação (uai-body.json):

{
  "identity": {
      "type": "UserAssigned",
  	"userAssignedIdentities": {
  		"/subscriptions/$SUB_ID/resourceGroups/$UAI_RESOURCE_GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$UAI_NAME": {}
  	}
  }
}

Se várias identidades gerenciadas atribuídas pelo usuário tiverem sido adicionadas, uma delas poderá ser removida executando:

az rest --method PATCH --url /subscriptions/$SUB_ID/resourceGroups/$CLUSTER_RG/providers/Microsoft.NetworkCloud/clusters/$CLUSTER_NAME?api-version=<APIVersion> --body @~/uai-body.json

O exemplo do corpo da solicitação (uai-body.json):

{
  "identity": {
      "type": "UserAssigned",
  	"userAssignedIdentities": {
  		"/subscriptions/$SUB_ID/resourceGroups/$UAI_RESOURCE_GROUP/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$UAI_NAME": null
  	}
  }
}

Excluir um cluster

A exclusão de um cluster exclui os recursos no Azure e no cluster que reside no ambiente local.

Observação

Se houver algum recurso de locatário existente no cluster, ele não será excluído até que esses recursos sejam excluídos.

az networkcloud cluster delete --name "$CLUSTER_NAME" --resource-group "$CLUSTER_RG"

Compartilhar via

Criar e provisionar um cluster usando a CLI do Azure

Pré-requisitos

Guia e métricas da API

Limitações

Criar um cluster

Crie o cluster usando a CLI do Azure:

Parâmetros para operações de cluster

Identidade do cluster

Crie o Cluster usando o editor de modelos do Azure Resource Manager:

Validação de cluster

Registro em log do cluster

Implantar o cluster

Implantação de cluster com validação de hardware

Implantação de cluster com ignorar computador bare-metal específico

Falha no cluster deploy

Validação de implantação de cluster

Registro em log de implantação de cluster

Atualizar identidades de cluster por meio de APIs

Excluir um cluster

Comentários

Recursos adicionais