Implemente e gere extensões de cluster usando CLI do Azure

Pode criar instâncias de extensão num cluster AKS, definindo parâmetros necessários e opcionais, incluindo opções relacionadas com atualizações e configurações. Também pode visualizar, listar, atualizar e eliminar instâncias de extensão.

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

Nota

Os exemplos fornecidos neste artigo não estão completos e destinam-se apenas a mostrar funcionalidade. Para obter uma lista exaustiva de comandos e respetivos parâmetros, consulte a referência da CLI az k8s-extension.

Prerequisites

  • Uma assinatura do Azure. Se não tiver uma subscrição do Azure, pode criar uma conta gratuita.

  • Os fornecedores de recursos Microsoft.ContainerService e Microsoft.KubernetesConfiguration devem estar registados na sua subscrição. Para registrar esses provedores, execute o seguinte comando:

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

  • Um cluster AKS. Este cluster deve ter sido criado com uma identidade gerida, pois as extensões de cluster não funcionam com clusters baseados em entidades de serviço. Para novos clusters criados com az aks create, por padrão, a identidade gerida é configurada. Para clusters baseados em principal de serviço existentes, mude para gerir a identidade correndo az aks update com a --enable-managed-identity flag. Para obter mais informações, consulte Usar identidade gerenciada.

  • CLI do Azure versão >= 2.16.0 instalada. Recomendamos que utilize a versão mais recente.

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

    az extension add --name k8s-extension

    Se a extensão já estiver instalada, certifique-se de que está a executar a versão mais recente usando o seguinte comando:

    az extension update --name k8s-extension

Criar instância de extensão

Crie uma nova instância de extensão com k8s-extension create, passando valores para os parâmetros obrigatórios. Este comando de exemplo cria uma instância de extensão do Azure Machine Learning no seu cluster 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 uma aplicação Kubernetes de exemplo (publicada no Marketplace) no seu cluster 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

Nota

O serviço Cluster Extensions não consegue reter informações sensíveis 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 conseguirem determinar se devem criar uma extensão no cluster, então a extensão transita para o estado Failed. Quando estiver no estado Failed, terá de executar k8s-extension create novamente para criar uma nova instância da extensão.

Parâmetros necessários

Nome do parâmetro Descrição
--name Nome da instância de extensão
--extension-type O tipo de extensão que queres instalar no cluster. Por exemplo: Microsoft.AzureML.Kubernetes
--cluster-name Nome do cluster AKS onde a instância de extensão tem de ser criada
--resource-group O grupo de recursos que contém o cluster AKS
--cluster-type O tipo de cluster sobre o qual a instância de extensão tem de ser criada. Especifique managedClusters como correspondendo a clusters AKS

Parâmetros opcionais

Nome do parâmetro Descrição
--auto-upgrade-minor-version Propriedade booleana que especifica se a versão menor da extensão será atualizada automaticamente ou não. Padrão: true. Se este parâmetro estiver definido como true, não pode definir version o parâmetro, pois a versão será atualizada dinamicamente. Se estiver definida para false, a extensão não será atualizada automaticamente mesmo para versões com patch.
--version Versão da extensão a instalar (versão específica para fixar a instância da extensão). Não deve ser especificado se auto-upgrade-minor-version estiver definido como true.
--configuration-settings Definições que podem ser passadas para a extensão para controlar a sua funcionalidade. Passe os valores como pares key=value separados por espaços após o nome do parâmetro. Se este parâmetro for usado no comando, então --configuration-settings-file não pode ser usado no mesmo comando.
--configuration-settings-file Caminho para o ficheiro JSON que contém pares chave-valor a utilizar para transmitir as definições de configuração à extensão. Se este parâmetro for usado no comando, então --configuration-settings não pode ser usado no mesmo comando.
--configuration-protected-settings Estas definições não podem ser obtidas utilizando chamadas à API GET ou comandos az k8s-extension show e são, por isso, usadas para transmitir definições sensíveis. Passe os valores como pares separados por espaços após o nome do parâmetro. Se este parâmetro for usado no comando, então --configuration-protected-settings-file não pode ser usado no mesmo comando.
--configuration-protected-settings-file Caminho para o ficheiro JSON com pares de valor-chave a serem usados para passar definições sensíveis à extensão. Se este parâmetro for usado no comando, então --configuration-protected-settings não pode ser usado no mesmo comando.
--scope Âmbito da instalação da extensão - cluster ou namespace
--release-namespace Este parâmetro indica o espaço de nomes dentro do qual a versão deve ser criada. Este parâmetro só é relevante se o parâmetro scope estiver definido como cluster.
--release-train Os autores de extensões podem publicar versões em diferentes sistemas de lançamento, como Stable, Preview, etc. Se este parâmetro não estiver definido explicitamente, Stable é usado como padrão. Este parâmetro não pode ser usado quando --auto-upgrade-minor-version o parâmetro está definido como false.
--target-namespace Este parâmetro indica o namespace dentro do 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. Este parâmetro só é relevante se o scope parâmetro for definido como namespace.
--plan-name ID do Plano da extensão, encontrada na página do Marketplace no portal Azure em Informação de Utilização + Suporte.
--plan-product ID do produto da extensão, encontrada na página do Marketplace no portal Azure em Informação de Utilização + Suporte. Um exemplo disso é o nome da oferta de ISV usada.
--plan-publisher Publisher ID da extensão, encontrada na página do Marketplace no portal Azure sob Informação de Utilização + Suporte.

Mostrar detalhes de uma instância de extensão

Para visualizar detalhes de uma instância de extensão atualmente instalada, 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 num 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 da extensão

Nota

Consulte a documentação do tipo específico de extensão para compreender as definições específicas em --configuration-settings e --configuration-protected-settings que podem ser atualizadas. Para --configuration-protected-settings, espera-se que todas as definições sejam fornecidas, mesmo que apenas uma configuração esteja a ser atualizada. Se alguma destas definições for omitida, essas definições serão consideradas obsoletas e apagadas.

Para atualizar uma instância de extensão existente, use k8s-extension update, passando valores para os parâmetros obrigatórios. O comando seguinte atualiza a definição de atualização automática para 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 de extensão
--extension-type O tipo de extensão que queres instalar no cluster. Por exemplo: Microsoft. AzureML.Kubernetes
--cluster-name Nome do cluster AKS onde a instância de extensão tem de ser criada
--resource-group O grupo de recursos que contém o cluster AKS
--cluster-type O tipo de cluster sobre o qual a instância de extensão tem de ser criada. Especifique managedClusters à medida que mapeia para clusters AKS

Ao atualizar uma aplicação Kubernetes adquirida através do Marketplace, são também necessários os seguintes parâmetros:

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

Parâmetros opcionais para atualização

Nome do parâmetro Descrição
--auto-upgrade-minor-version Propriedade booleana que especifica se a versão menor da extensão será atualizada automaticamente ou não. Padrão: true. Se este parâmetro estiver definido como true, não pode definir version o parâmetro, pois a versão será atualizada dinamicamente. Se estiver definida para false, a extensão não será atualizada automaticamente mesmo para versões com patch.
--version Versão da extensão a instalar (versão específica para fixar a instância da extensão). Não deve ser especificado se auto-upgrade-minor-version estiver definido como true.
--configuration-settings Definições que podem ser passadas para a extensão para controlar a sua funcionalidade. Só é necessário fornecer as definições que exigem uma atualização. As definições fornecidas eram substituídas pelos valores fornecidos. Passe os valores como pares key=value separados por espaços após o nome do parâmetro. Se este parâmetro for usado no comando, então --configuration-settings-file não pode ser usado no mesmo comando.
--configuration-settings-file Caminho para o ficheiro JSON que contém pares chave-valor a utilizar para transmitir as definições de configuração à extensão. Se este parâmetro for usado no comando, então --configuration-settings não pode ser usado no mesmo comando.
--configuration-protected-settings Estas configurações não podem ser obtidas através de chamadas à API GET ou de comandos az k8s-extension show e são, por isso, utilizadas para fornecer configurações sensíveis. Quando atualizas uma definição, todas as definições devem ser especificadas. Se algumas definições forem omitidas, essas definições seriam consideradas obsoletas e eliminadas. Passe os valores como pares separados por espaços após o nome do parâmetro. Se este parâmetro for usado no comando, então --configuration-protected-settings-file não pode ser usado no mesmo comando.
--configuration-protected-settings-file Caminho para o ficheiro JSON com pares de valor-chave a serem usados para passar definições sensíveis à extensão. Se este parâmetro for usado no comando, então --configuration-protected-settings não pode ser usado no mesmo comando.
--scope Âmbito da instalação da extensão - cluster ou namespace
--release-train Os autores de extensões podem publicar versões em diferentes sistemas de lançamento, como Stable, Preview, etc. Se este parâmetro não estiver definido explicitamente, Stable é usado como padrão. Este parâmetro não pode ser usado quando autoUpgradeMinorVersion o parâmetro está definido como false.

Excluir instância de extensão

Para eliminar uma instância de extensão num 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

Nota

O recurso do Azure que representa esta extensão é eliminado imediatamente. A versão do Helm no cluster associada a esta extensão só é eliminada quando os agentes a correr no cluster Kubernetes têm conectividade de rede e podem voltar a contactar os serviços do Azure para obter o estado desejado.

Passos seguintes

  • Last updated on