Criar e provisionar um cluster usando a CLI do Azure

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

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

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

Validação de cluster

Uma criação bem-sucedida do Cluster do Nexus do Operador resulta na criação de um recurso do Azure dentro de 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 --cluster-name "<clusterName>" /
--resource-group "<resourceGroupName>" /
--subscription <subscriptionID>

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:

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

Definir limites de implantação

Há dois tipos de limites de implantação que podem ser definidos em um cluster antes da implantação do cluster. Eles são compute-deployment-threshold e update-strategy.

--compute-deployment-threshold - O limite de validação que indica as falhas permitidas de nós de computação durante a validação de hardware do ambiente.

Se compute-deployment-threshold não estiver definido, os padrões serão os seguintes:

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 80,
      "waitTimeMinutes": 1

Se o cliente solicitar uma compute-deployment-threshold que ela seja diferente do padrão de 80%, você poderá executar o seguinte comando de atualização de cluster.

O exemplo abaixo é para um cliente solicitando o tipo "PercentSuccess" com uma taxa de sucesso de 97%.

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--compute-deployment-threshold type="PercentSuccess" grouping="PerCluster" value=97 /
--subscription <subscriptionID>

Validar atualização

az networkcloud cluster show --resource-group "<resourceGroup>" --name "<clusterName>" | grep -a3 computeDeploymentThreshold

  "clusterType": "MultiRack",
  "clusterVersion": "<CLUSTER_VERSION>",
  "computeDeploymentThreshold": {
    "grouping": "PerCluster",
    "type": "PercentSuccess",
    "value": 97

Neste exemplo, se menos de 97% dos nós de computação que estão sendo implantados passarem na validação de hardware, a implantação do cluster falhará. NOTA: Todos os planos de controle do kubernetes (KCP) e do plano de gerenciamento do nexus (NMP) devem passar pela validação de hardware. Se 97% ou mais dos nós de computação que estão sendo implantados passarem na validação de hardware, a implantação do cluster continuará para a fase de provisionamento de bootstrap. Durante o provisionamento de bootstrap de computação, o update-strategy (abaixo) é usado para nós de computação.

--update-strategy - A estratégia para atualizar o cluster que indica as falhas permitidas do nó de computação durante o provisionamento de bootstrap.

Se o cliente solicitar um limite de update-strategy diferente do padrão de 80%, você poderá executar o seguinte comando de atualização de cluster.

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" /
threshold-value="<thresholdValue>" wait-time-minutes=<waitTimeBetweenRacks> /
--subscription <subscriptionID>

O tipo de estratégia pode ser "Rack" (Rack por Rack) OU "PauseAfterRack" (Aguarde a resposta do cliente continuar).

O tipo de limite pode ser "PercentSuccess" OU "CountSuccess".

Se updateStrategy não estiver definido, os padrões serão os seguintes:

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 80,
      "waitTimeMinutes": 1

O exemplo abaixo é para um cliente que usa a estratégia Rack by Rack com um Percentual de Sucesso de 60% e uma pausa de 1 minuto.

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="PercentSuccess" /
threshold-value=60 wait-time-minutes=1 /
--subscription <subscriptionID>

Verifique a atualização:

az networkcloud cluster show --resource-group "<resourceGroup>" /
--name "<clusterName>" /
--subscription <subscriptionID>| grep -a5 updateStrategy

      "strategyType": "Rack",
      "thresholdType": "PercentSuccess",
      "thresholdValue": 60,
      "waitTimeMinutes": 1

Neste exemplo, se menos de 60% dos nós de computação que estão sendo provisionados em um rack não forem provisionados (rack por rack), a implantação do cluster falhará. Se 60% ou mais dos nós de computação forem provisionados com êxito, a implantação do cluster passará para o próximo rack de nós de computação.

O exemplo abaixo é para um cliente que usa a estratégia Rack por Rack com um tipo de limite CountSuccess de 10 nós por rack e uma pausa de 1 minuto.

az networkcloud cluster update --name "<clusterName>" /
--resource-group "<resourceGroup>" /
--update-strategy strategy-type="Rack" threshold-type="CountSuccess" /
threshold-value=10 wait-time-minutes=1 /
--subscription <subscriptionID>

Verifique a atualização:

az networkcloud cluster show --resource-group "<resourceGroup>" /
--name "<clusterName>" /
--subscription <subscriptionID>| grep -a5 updateStrategy

      "strategyType": "Rack",
      "thresholdType": "CountSuccess",
      "thresholdValue": 10,
      "waitTimeMinutes": 1

Neste exemplo, se menos de 10 nós de computação provisionados em um rack não forem provisionados (rack por rack), a implantação do cluster falhará. Se 10 ou mais dos nós de computação forem provisionados com êxito, a implantação do cluster passará para o próximo rack de nós de computação.

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.

1. Validação das propriedades de cluster/rack.
2. Geração de uma imagem inicializável para o cluster de inicialização efêmera (validação da infraestrutura).
3. Interação com a interface IPMI (Interface de Gerenciamento de Plataforma Inteligente) do computador inicializado de destino.
4. Executando verificações de validação de hardware.
5. 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

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.

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="aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*99399E995...",
  "name": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e*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:

1. Logs de atividades Resource/ResourceGroup no portal do Azure.
2. 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.

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