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 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:

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

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="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:

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"