Implantar e gerenciar extensões de cluster usando a CLI do Azure

  • Artigo

Você pode criar instâncias de extensão em um cluster do AKS, definindo parâmetros obrigatórios e opcionais incluindo opções relacionadas a atualizações e configurações. Você também pode exibir, listar, atualizar e excluir instâncias de extensão.

Antes de começar, leia sobre extensões de cluster.

Observação

Os exemplos fornecidos neste artigo não estão completos e servem apenas para demonstração da funcionalidade. Para obter uma lista abrangente de comandos e seus parâmetros, confira a referência da CLI do az k8s-extension.

Pré-requisitos

  • Uma assinatura do Azure. Caso não tenha uma assinatura do Azure, é possível criar uma conta gratuita.

  • Os provedores de recursos Microsoft.ContainerService e Microsoft.KubernetesConfiguration devem ser registrados em sua assinatura. Para registrar esses provedores, execute o seguinte comando:

    az provider register --namespace Microsoft.ContainerService --wait 
az provider register --namespace Microsoft.KubernetesConfiguration --wait

  • Uma cluster do AKS. Este cluster deve ter sido criado com uma identidade gerenciada, pois as extensões de cluster não funcionam com clusters baseados na entidade de serviço. Para novos clusters criados com az aks create, a identidade gerenciada é configurada por padrão. Para clusters baseados em entidade de serviço existentes, alterne para gerenciar a identidade executando az aks update com o sinalizador --enable-managed-identity. Para obter mais informações, confira Usar identidades gerenciadas.

  • CLI do Azure versão >= 2.16.0 instalada. Recomendamos usar a última versão.

  • A versão mais recente das extensões da CLI do Azure k8s-extension. Instale a extensão executando o seguinte comando:

    az extension add --name k8s-extension

    Se a extensão já estiver instalada, verifique se você está executando a versão mais recente usando o seguinte comando:

    az extension update --name k8s-extension

Criar instância de extensão

Crie uma instância de extensão com k8s-extension create, passando valores para os parâmetros obrigatórios. Este exemplo de comando cria uma instância de extensão do Azure Machine Learning em seu cluster do AKS:

az k8s-extension create --name azureml --extension-type Microsoft.AzureML.Kubernetes --scope cluster --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type managedClusters --configuration-settings enableInference=True allowInsecureConnections=True inferenceRouterServiceType=LoadBalancer

Este comando de exemplo cria um aplicativo do Kubernetes de exemplo (publicado no Marketplace) no cluster do AKS:

az k8s-extension create --name voteapp --extension-type Contoso.AzureVoteKubernetesAppTest --scope cluster --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type managedClusters --plan-name testPlanID --plan-product testOfferID --plan-publisher testPublisherID --configuration-settings title=VoteAnimal value1=Cats value2=Dogs

Observação

O serviço Extensões de Cluster não pode reter informações confidenciais por mais de 48 horas. Se os agentes de extensão do cluster não tiverem conectividade de rede por mais de 48 horas e não puderem determinar se uma extensão deve ser criada no cluster, a extensão passará para o estado Failed. Uma vez no estado Failed, você precisará executar k8s-extension create novamente para criar uma instância de extensão.

Parâmetros obrigatórios

Nome do parâmetro Descrição
--name Nome da instância da extensão
--extension-type O tipo de extensão que você deseja instalar no cluster. Por exemplo: Microsoft.AzureML.Kubernetes
--cluster-name Nome do cluster do AKS em que a instância da extensão precisa ser criada
--resource-group O grupo de recursos que contém o cluster do AKS
--cluster-type O tipo de cluster no qual a instância de extensão precisa ser criada. Especifique managedClusters pois ele é mapeado para clusters do AKS

Parâmetros opcionais

Nome do parâmetro Descrição
--auto-upgrade-minor-version Propriedade booliana que especifica se a versão secundária da extensão será atualizada automaticamente ou não. Padrão: true. Se esse parâmetro for definido como true, você não poderá definir o parâmetro version, pois a versão será atualizada dinamicamente. Se for definido como false, a extensão não será atualizada automaticamente nem mesmo para versões de patch.
--version Versão da extensão a ser instalada (versão específica para fixar a instância da extensão). Não deverá ser fornecida se a versão secundária da atualização automática estiver definida como true.
--configuration-settings Configurações que podem ser passadas para a extensão a fim de controlar sua funcionalidade. Passe valores como pares key=value separados por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, --configuration-settings-file não poderá ser usado no mesmo comando.
--configuration-settings-file O caminho para o arquivo JSON que tem pares chave-valor a serem usados para passar definições de configuração à extensão. Se esse parâmetro for usado no comando, --configuration-settings não poderá ser usado no mesmo comando.
--configuration-protected-settings Essas configurações não são recuperáveis usando chamadas de API GET ou comandos az k8s-extension show e, portanto, são usadas para passar configurações confidenciais. Passe valores como pares key=value separados por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, --configuration-protected-settings-file não poderá ser usado no mesmo comando.
--configuration-protected-settings-file O caminho para o arquivo JSON que tem pares chave-valor a serem usados para passar configurações confidenciais à extensão. Se esse parâmetro for usado no comando, --configuration-protected-settings não poderá ser usado no mesmo comando.
--scope Escopo da instalação da extensão – cluster ou namespace
--release-namespace Esse parâmetro indica o namespace no qual a versão deve ser criada. Esse parâmetro só será relevante se o parâmetro scope for definido como cluster.
--release-train Os autores de extensão podem publicar versões em conjuntos de versões diferentes, como Stable, Preview etc. Se esse parâmetro não for definido explicitamente, Stable será usado como padrão. Esse parâmetro não poderá ser usado quando o parâmetro --auto-upgrade-minor-version for definido como false.
--target-namespace Esse parâmetro indica o namespace no qual a versão será criada. A permissão da conta do sistema criada para esta instância de extensão será restrita a este namespace. Esse parâmetro só será relevante se o parâmetro scope for definido como namespace.
--plan-name ID do plano da extensão, encontrada na página do Marketplace no portal do Azure em Informações de Uso + Suporte.
--plan-product ID do produto da extensão, encontrada na página do Marketplace no portal do Azure em Informações de Uso + Suporte. Um exemplo disso é o nome da oferta ISV usada.
--plan-publisher ID do publicador da extensão, encontrada na página do Marketplace no portal do Azure em Informações de Uso + Suporte.

Mostrar detalhes de uma instância de extensão

Para exibir detalhes de uma instância de extensão instalada atualmente, use k8s-extension show, passando valores para os parâmetros obrigatórios.

az k8s-extension show --name azureml --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type managedClusters

Listar todas as extensões instaladas no cluster

Para listar todas as extensões instaladas em um cluster, use k8s-extension list, passando valores para os parâmetros obrigatórios.

az k8s-extension list --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type managedClusters

Atualizar instância de extensão

Observação

Confira a documentação do tipo de extensão específico para entender as configurações específicas em --configuration-settings e --configuration-protected-settings que podem ser atualizadas. Para --configuration-protected-settings, todas as configurações devem ser fornecidas, mesmo que apenas uma configuração esteja sendo atualizada. Se qualquer uma dessas configurações for omitida, ela será considerada obsoleta e será excluída.

Para atualizar uma instância de extensão existente, use k8s-extension update, passando valores para os parâmetros obrigatórios. O comando a seguir atualiza a configuração de atualização automática de uma instância de extensão do Azure Machine Learning:

az k8s-extension update --name azureml --extension-type Microsoft.AzureML.Kubernetes --scope cluster --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type managedClusters

Parâmetros necessários para atualização

Nome do parâmetro Descrição
--name Nome da instância da extensão
--extension-type O tipo de extensão que você deseja instalar no cluster. Por exemplo: Microsoft.AzureML.Kubernetes
--cluster-name Nome do cluster do AKS em que a instância da extensão precisa ser criada
--resource-group O grupo de recursos que contém o cluster do AKS
--cluster-type O tipo de cluster no qual a instância de extensão precisa ser criada. Especifique managedClusters pois ele é mapeado para clusters do AKS

Se estiver atualizando um aplicativo Kubernetes adquirido através do Marketplace, os seguintes parâmetros também serão necessários:

Nome do parâmetro Descrição
--plan-name ID do plano da extensão, encontrada na página do Marketplace no portal do Azure em Informações de Uso + Suporte.
--plan-product ID do produto da extensão, encontrada na página do Marketplace no portal do Azure em Informações de Uso + Suporte. Um exemplo disso é o nome da oferta ISV usada.
--plan-publisher ID do publicador da extensão, encontrada na página do Marketplace no portal do Azure em Informações de Uso + Suporte.

Parâmetros opcionais para atualização

Nome do parâmetro Descrição
--auto-upgrade-minor-version Propriedade booliana que especifica se a versão secundária da extensão será atualizada automaticamente ou não. Padrão: true. Se esse parâmetro for definido como true, você não poderá definir o parâmetro version, pois a versão será atualizada dinamicamente. Se for definido como false, a extensão não será atualizada automaticamente nem mesmo para versões de patch.
--version Versão da extensão a ser instalada (versão específica para fixar a instância da extensão). Não deverá ser fornecida se a versão secundária da atualização automática estiver definida como true.
--configuration-settings Configurações que podem ser passadas para a extensão a fim de controlar sua funcionalidade. Somente as configurações que exigem uma atualização precisam ser fornecidas. As configurações fornecidas seriam substituídas pelos valores fornecidos. Passe valores como pares key=value separados por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, --configuration-settings-file não poderá ser usado no mesmo comando.
--configuration-settings-file O caminho para o arquivo JSON que tem pares chave-valor a serem usados para passar definições de configuração à extensão. Se esse parâmetro for usado no comando, --configuration-settings não poderá ser usado no mesmo comando.
--configuration-protected-settings Essas configurações não são recuperáveis usando chamadas de API GET ou comandos az k8s-extension show e, portanto, são usadas para passar configurações confidenciais. Ao atualizar uma configuração, espera-se que todas as configurações sejam especificadas. Se algumas configurações forem omitidas, essas configurações serão consideradas obsoletas e excluídas. Passe valores como pares key=value separados por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, --configuration-protected-settings-file não poderá ser usado no mesmo comando.
--configuration-protected-settings-file O caminho para o arquivo JSON que tem pares chave-valor a serem usados para passar configurações confidenciais à extensão. Se esse parâmetro for usado no comando, --configuration-protected-settings não poderá ser usado no mesmo comando.
--scope Escopo da instalação da extensão – cluster ou namespace
--release-train Os autores de extensão podem publicar versões em conjuntos de versões diferentes, como Stable, Preview etc. Se esse parâmetro não for definido explicitamente, Stable será usado como padrão. Esse parâmetro não poderá ser usado quando o parâmetro autoUpgradeMinorVersion for definido como false.

Excluir instância de extensão

Para excluir uma instância de extensão de um cluster, use k8s-extension-delete, passando valores para os parâmetros obrigatórios.

az k8s-extension delete --name azureml --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type managedClusters

Observação

O recurso do Azure que representa essa extensão é excluído imediatamente. A versão Helm no cluster associado a essa extensão só é excluída quando os agentes em execução no cluster do Kubernetes têm conectividade de rede e podem entrar em contato com os serviços do Azure novamente para buscar o estado desejado.

Próximas etapas