Criar clusters Kubernetes usando a CLI do Azure

2025-04-08

Aplica-se a: AKS no Azure Local

Este artigo descreve como criar clusters Kubernetes no Azure Local usando a CLI do Azure. O fluxo de trabalho é o seguinte:

Crie um cluster Kubernetes no Azure Local usando a CLI do Azure. O cluster é conectado ao Azure Arc por padrão.
Ao criar o cluster, você fornece um grupo do Microsoft Entra que contém a lista de usuários do Microsoft Entra com acesso de administrador de cluster do Kubernetes.
Acesse o cluster usando kubectl e sua ID do Microsoft Entra.
Corra uma aplicação de exemplo com vários contentores com uma interface web e uma instância Redis no cluster.

Antes de começar

Antes de começar, verifique se você tem os seguintes detalhes do administrador de infraestrutura local:
- ID de assinatura do Azure - O ID de assinatura do Azure onde o Azure Local é usado para implantação e registo.
- ID de Localização Personalizada - ID do Gerenciador de Recursos do Azure da localização personalizada. O local personalizado é configurado durante a implantação do cluster Local do Azure. O administrador da infraestrutura deve fornecer a ID do Gerenciador de Recursos do local personalizado. Esse parâmetro é necessário para criar clusters do Kubernetes. Você também pode obter a ID do Gerenciador de Recursos usando az customlocation show --name "<custom location name>" --resource-group <azure resource group> --query "id" -o tsv, se o administrador de infraestrutura fornecer um nome de local personalizado e um nome de grupo de recursos.
- ID de Rede - ID do Azure Resource Manager da rede lógica Local do Azure criada seguindo estas etapas. O administrador deve fornecer-lhe o ID da rede lógica. Esse parâmetro é necessário para criar clusters do Kubernetes. Você também pode obter a ID do Azure Resource Manager usando az stack-hci-vm network lnet show --name "<lnet name>" --resource-group <azure resource group> --query "id" -o tsv se souber o grupo de recursos no qual a rede lógica foi criada.
Você pode executar as etapas neste artigo em uma máquina de desenvolvimento local para criar um cluster Kubernetes em sua implantação remota do Azure Local. Certifique-se de ter a versão mais recente do Az CLI em sua máquina de desenvolvimento. Você também pode optar por atualizar a versão do Az CLI usando o az upgrade.
Para se conectar ao cluster Kubernetes de qualquer lugar, crie um grupo do Microsoft Entra e adicione membros a ele. Todos os membros do grupo Microsoft Entra têm acesso de administrador de cluster ao cluster. Certifique-se de se adicionar como membro ao grupo Microsoft Entra. Se você não se adicionar, não poderá acessar o cluster do Kubernetes usando kubectl. Para obter mais informações sobre como criar grupos do Microsoft Entra e adicionar usuários, consulte Gerenciar grupos do Microsoft Entra e associação a grupos.
Baixe e instale o kubectl em sua máquina de desenvolvimento. A ferramenta de linha de comando do Kubernetes, kubectl, permite executar comandos em clusters do Kubernetes. Você pode usar o kubectl para implantar aplicativos, inspecionar e gerenciar recursos de cluster e exibir logs.

Instalar a extensão da CLI do Azure

Execute o seguinte comando para instalar as extensões necessárias da CLI do Azure:

az extension add -n aksarc --upgrade
az extension add -n customlocation --upgrade
az extension add -n stack-hci-vm --upgrade
az extension add -n connectedk8s --upgrade

Criar um cluster do Kubernetes

Use o comando az aksarc create para criar um cluster Kubernetes no AKS Arc. Certifique-se de entrar no Azure antes de executar este comando. Se você tiver várias assinaturas do Azure, selecione a ID de assinatura apropriada usando o comando az account set . Com o comando az aksarc create, recomenda-se que utilize o sinalizador --validate, que valida os parâmetros de entrada que pretende usar. Depois que os parâmetros de entrada forem validados, você poderá executar o az aksarc create comando sem o --validate sinalizador para criar o cluster do Kubernetes.

az aksarc create -n $aksclustername -g $resource_group --custom-location $customlocationID --vnet-ids $logicnetId --aad-admin-group-object-ids $aadgroupID --generate-ssh-keys

Após alguns minutos, o comando conclui e retorna informações formatadas em JSON sobre o cluster.

Considerações

Observe as seguintes considerações ao criar um cluster:

As chaves SSH são essenciais para a solução de problemas e a coleta de logs. Certifique-se de salvar seu arquivo de chave privada para uso futuro. Para aceder aos nós, consulte Conectar-se a nós de trabalho Windows ou Linux com SSH.
Você pode usar uma chave SSH pré-existente ou configurar chaves SSH para um cluster AKS durante a criação do cluster. Se não houver nenhuma chave SSH pré-existente em sua máquina local, o --generate-ssh-keys parâmetro será necessário. Você também pode restringir o acesso SSH seguindo a documentação. Para obter instruções detalhadas, consulte Criar e armazenar chaves SSH com a CLI do Azure ou no portal do Azure.
Se você não incluir --generate-ssh-keys durante a criação do cluster e nenhuma chave SSH existir, receberá uma mensagem de erro. Se já tiver uma chave SSH na sua máquina local, o cluster AKS reutiliza-a. Neste caso, não faz diferença se você especifica --generate-ssh-keys ou não.
Por padrão, a chave SSH é armazenada em ~/.ssh/id_rsa.pub. Durante a criação do cluster, você pode especificar um local alternativo usando o --ssh-key-value parâmetro.

Importante

Para usar o RBAC do Azure ou a identidade da carga de trabalho para um cluster AKS, você deve passar os parâmetros necessários durante a criação do cluster usando a CLI do Azure. Atualmente, não há suporte para a atualização de um cluster AKS existente para habilitar a identidade da carga de trabalho e/ou o RBAC do Azure. Para obter mais informações, consulte Usar o RBAC do Azure para autorização do Kubernetes ou Implantar e configurar a identidade da carga de trabalho para seu cluster.

Conectar-se ao cluster do Kubernetes

Agora você pode se conectar ao cluster do Kubernetes executando o az connectedk8s proxy comando da sua máquina de desenvolvimento. Certifique-se de entrar no Azure antes de executar este comando. Se você tiver várias assinaturas do Azure, selecione a ID de assinatura apropriada usando o comando az account set .

Este comando baixa o kubeconfig do cluster do Kubernetes para a máquina de desenvolvimento e abre um canal de conexão proxy para o cluster Kubernetes local. O canal fica aberto enquanto o comando for executado. Deixe esse comando ser executado pelo tempo que você quiser acessar seu cluster. Se o tempo limite expirar, feche a janela da CLI, abra uma nova e execute o comando novamente.

Você deve ter permissões de Colaborador no grupo de recursos que hospeda o cluster do Kubernetes para executar o seguinte comando com êxito:

az connectedk8s proxy --name $aksclustername --resource-group $resource_group --file .\aks-arc-kube-config

Resultado esperado:

Proxy is listening on port 47011
Merged "aks-workload" as current context in .\\aks-arc-kube-config
Start sending kubectl requests on 'aks-workload' context using
kubeconfig at .\\aks-arc-kube-config
Press Ctrl+C to close proxy.

Mantenha esta sessão em execução e conecte-se ao cluster do Kubernetes a partir de um terminal/prompt de comando diferente. Verifique se você pode se conectar ao cluster do Kubernetes executando o comando kubectl get. Este comando retorna uma lista dos nós do cluster:

kubectl get node -A --kubeconfig .\aks-arc-kube-config

O exemplo de saída a seguir mostra o nó que foi criado nas etapas anteriores. Verifique se o status do nó está Pronto:

NAME             STATUS ROLES                AGE VERSION
moc-l0ttdmaioew  Ready  control-plane,master 34m v1.24.11
moc-ls38tngowsl  Ready  <none>               32m v1.24.11

Implantar o aplicativo e o balanceador de carga

Um arquivo de manifesto do Kubernetes define o estado desejado de um cluster, como quais imagens de contêiner devem ser executadas.

Você pode usar um manifesto para criar todos os objetos necessários para executar o aplicativo Azure Vote. Esse manifesto inclui duas implantações do Kubernetes:

O exemplo de aplicativos Python do Azure Vote.
Uma instância Redis.

Dois serviços Kubernetes também são criados:

Um serviço interno para a instância Redis.
Um serviço externo para acessar o aplicativo Azure Vote da Internet.

Crie um arquivo chamado azure-vote.yaml e copie no seguinte manifesto:

apiVersion: apps/v1 
    kind: Deployment 
    metadata: 
      name: azure-vote-back 
    spec: 
      replicas: 1 
      selector: 
        matchLabels: 
          app: azure-vote-back 
      template: 
        metadata: 
          labels: 
            app: azure-vote-back 
        spec: 
          nodeSelector: 
            "kubernetes.io/os": linux 
          containers: 
          - name: azure-vote-back 
            image: <path to image>/oss/bitnami/redis:6.0.8 
            env: 
            - name: ALLOW_EMPTY_PASSWORD 
              value: "yes" 
            resources: 
              requests: 
                cpu: 100m 
                memory: 128Mi 
              limits: 
                cpu: 250m 
                memory: 256Mi 
            ports: 
            - containerPort: 6379 
              name: redis 
    ---
    apiVersion: v1
    kind: Service 
    metadata: 
      name: azure-vote-back 
    spec: 
      ports: 
      - port: 6379 
      selector: 
        app: azure-vote-back 
    --- 
    apiVersion: apps/v1 
    kind: Deployment 
    metadata: 
      name: azure-vote-front 
    spec: 
      replicas: 1 
      selector: 
        matchLabels: 
          app: azure-vote-front 
      template: 
        metadata: 
          labels: 
            app: azure-vote-front 
        spec: 
          nodeSelector: 
            "kubernetes.io/os": linux 
          containers: 
          - name: azure-vote-front 
            image: <path to image>/azure-vote-front:v1 
            resources: 
              requests: 
                cpu: 100m 
                memory: 128Mi 
              limits: 
                cpu: 250m 
                memory: 256Mi 
            ports: 
            - containerPort: 80 
            env: 
            - name: REDIS 
              value: "azure-vote-back" 
    --- 
    apiVersion: v1 
    kind: Service 
    metadata: 
      name: azure-vote-front 
    spec: 
      type: LoadBalancer 
      ports: 
      - port: 80 
      selector: 
        app: azure-vote-front

Implante o aplicativo usando o comando kubectl apply e especifique o nome do seu YAML:

kubectl apply -f azure-vote.yaml --kubeconfig .\\aks-arc-kube-config

A saída de exemplo a seguir mostra as implementações e serviços criados com sucesso.

deployment "azure-vote-back" created
service "azure-vote-back" created
deployment "azure-vote-front" created
service "azure-vote-front" created

Implante um balanceador de carga MetalLB para que ele possa atribuir um IP externo para o front-end do aplicativo. Você pode seguir estas instruções para implantar a extensão MetalLB a partir do portal do Azure ou usando a CLI.

Testar a aplicação

Quando o aplicativo é executado, um serviço Kubernetes expõe o frontend do aplicativo à Internet. Este processo pode demorar alguns minutos a concluir.

Monitore o progresso usando o comando kubectl get service com o argumento --watch.

kubectl get service azure-vote-front --watch --kubeconfig .\aks-arc-kube-config

A saída EXTERNAL-IP para o serviço azure-vote-front inicialmente mostra como pendente.

NAME             TYPE         CLUSTER-IP EXTERNAL-IP PORT(S)      AGE
azure-vote-front LoadBalancer 10.0.37.27 <pending>   80:30572/TCP 6s

Quando o endereço EXTERNAL-IP mudar de pendente para um endereço IP público real, use CTRL-C para parar o processo de observação kubectl. A saída de exemplo a seguir mostra um endereço IP público válido atribuído ao serviço:

azure-vote-front LoadBalancer 10.0.37.27 52.179.23.131 80:30572/TCP 2m

Para ver o aplicativo Azure Vote em ação, abra um navegador da Web para o endereço IP externo do seu serviço.

Eliminar o cluster

Execute o az aksarc delete comando para limpar o cluster que você criou:

az aksarc delete --name $aksclustername --resource-group $resource_group

Próximos passos

Solucionar problemas e problemas conhecidos com o provisionamento de cluster do Azure 6