Tutorial: Habilitar Aplicativos de Contêiner do Azure no Kubernetes habilitado para Azure Arc

Este tutorial prepara um cluster Kubernetes suportado para rodar Aplicativos de Contêiner do Azure. Ele cria um cluster Kubernetes habilitado para Azure Arc, instala a extensão Container Apps, cria um local personalizado e cria um ambiente conectado ao Container Apps.

Completar este tutorial altera tanto sua assinatura do Azure quanto seu cluster Kubernetes. Você precisa de permissões do Azure para criar os recursos listados e acesso de administrador de cluster ao cluster Kubernetes.

Este tutorial mostra como habilitar o Aplicativos de Contêiner do Azure em um cluster Kubernetes habilitado pelo Azure Arc. Neste tutorial, você:

  • Conecte um cluster Kubernetes ao Azure Arc, caso ainda não esteja conectado.
  • Opcionalmente, crie um espaço de trabalho de Log Analytics.
  • Instale e valide a extensão Container Apps.
  • Crie e valide um local personalizado.
  • Crie e valide um ambiente conectado do Container Apps.

Antes de começar, consulte Aplicativos de Contêiner do Azure no Azure Arc. Se um recurso ou componente no cluster não ficar pronto, consulte Solucionar problemas do Aplicativos de Contêiner do Azure no Kubernetes habilitado para Azure Arc.

Pré-requisitos

Antes de começar, verifique os seguintes requisitos:

  • Uma conta do Azure com uma assinatura ativa. Se você não tiver um, crie um gratuitamente.
  • Permissão para registrar provedores de recursos e criar grupos de recursos, um recurso Kubernetes habilitado para Azure Arc, uma extensão de cluster, um local personalizado, um ambiente conectado com Apps de Contêineres e, opcionalmente, um espaço de trabalho Log Analytics.
  • A CLI do Azure e seus pré-requisitos.
  • Uma versão kubectl compatível com seu cluster do Kubernetes e acesso de rede da sua estação de trabalho ao servidor da API do Kubernetes.
  • Um cluster Kubernetes compatível com nós de trabalho Linux amd64 e acesso de administrador do cluster por meio do contexto ativo kubectl.
  • Uma implementação funcional de serviço Kubernetes LoadBalancer .
  • Conectividade de saída para os endpoints exigidos pelo Azure Arc e Container Apps.
  • CPU e memória alocáveis suficientes para as cargas de extensão e aplicação.

Antes de mudar um cluster de produção, revise a implantação do Plan a Container Apps no Kubernetes habilitado para Azure Arc.

Instalação

Instale as seguintes extensões da CLI do Azure.

az extension add --name connectedk8s --upgrade --yes
az extension add --name k8s-extension --upgrade --yes
az extension add --name customlocation --upgrade --yes
az extension add --name containerapp --upgrade --yes

Registre os namespaces necessários.

az provider register --namespace Microsoft.ExtendedLocation --wait
az provider register --namespace Microsoft.KubernetesConfiguration --wait
az provider register --namespace Microsoft.App --wait
az provider register --namespace Microsoft.Web --wait
az provider register --namespace Microsoft.OperationalInsights --wait

Defina variáveis de ambiente com base na implantação do cluster do Kubernetes.

GROUP_NAME="my-arc-cluster-group"
AKS_CLUSTER_GROUP_NAME="my-aks-cluster-group"
AKS_NAME="my-aks-cluster"
LOCATION="eastus"

Criar um cluster conectado

Se você já tem um cluster Kubernetes suportado pelo Azure Arc em $GROUP_NAME, não crie outro cluster. Defina CLUSTER_NAME para o nome do recurso do cluster conectado existente, verifique o acesso com kubectl get nodes, e continue para criar um espaço de trabalho de Log Analytics.

Os passos a seguir, crie um cluster AKS e conecte-o ao Azure Arc. Esse caminho é destinado apenas a um ambiente de avaliação hospedado no Azure para o tutorial. Para um cluster local ou multicloud existente, siga o Quickstart: Conecte um cluster Kubernetes existente ao Azure Arc e depois volte a este tutorial.

  1. Crie um cluster no Serviço de Kubernetes do Azure.

    az group create --name $AKS_CLUSTER_GROUP_NAME --location $LOCATION
az aks create \
   --resource-group $AKS_CLUSTER_GROUP_NAME \
   --name $AKS_NAME \
   --enable-aad \
   --generate-ssh-keys

  2. Obtenha o arquivo kubeconfig e teste sua conexão com o cluster. Por padrão, o arquivo kubeconfig é salvo em ~/.kube/config.

    az aks get-credentials --resource-group $AKS_CLUSTER_GROUP_NAME --name $AKS_NAME --admin

kubectl get ns

  3. Crie um grupo de recursos para conter os recursos do Azure Arc.

    az group create --name $GROUP_NAME --location $LOCATION

  4. Conecte o cluster criado ao Azure Arc.

    CLUSTER_NAME="${GROUP_NAME}-cluster" # Name of the connected cluster resource

az connectedk8s connect --resource-group $GROUP_NAME --name $CLUSTER_NAME

  5. Espere o cluster conectado terminar de provisionar.

    CONNECTED_CLUSTER_ID=$(az connectedk8s show \
    --resource-group $GROUP_NAME \
    --name $CLUSTER_NAME \
    --query id \
    --output tsv)

az resource wait --ids $CONNECTED_CLUSTER_ID --created --timeout 600

az connectedk8s show \
    --resource-group $GROUP_NAME \
    --name $CLUSTER_NAME \
    --query "{State:provisioningState,Connectivity:connectivityStatus}" \
    --output table

    Prossiga somente quando State for Succeeded e Connectivity for Connected. Se o comando atingir o tempo limite, consulte O cluster conectado não está pronto.

Criar um espaço de trabalho do Log Analytics

Um workspace do Log Analytics fornece acesso a logs de Aplicativos de Contêiner em execução no cluster do Kubernetes habilitado para Azure Arc. Um espaço de trabalho de Log Analytics é opcional, mas recomendado para diagnósticos de aplicações.

Importante

Decida se deve usar o Log Analytics antes de instalar a extensão Container Apps. Forneça a configuração do Log Analytics durante a instalação da extensão. Você não pode adicionar a configuração do Log Analytics a essa instância de extensão depois.

  1. Criar um espaço de trabalho do Log Analytics.

    WORKSPACE_NAME="$GROUP_NAME-workspace" # Name of the Log Analytics workspace

az monitor log-analytics workspace create \
    --resource-group $GROUP_NAME \
    --workspace-name $WORKSPACE_NAME

  2. Execute os comandos a seguir para obter a ID e a chave compartilhada codificadas de um workspace existente do Log Analytics. Você precisará deles na próxima etapa.

    Caution

    A chave compartilhada do workspace é uma credencial. Não imprima isso, não faça commit disso no controle de versão, não armazene isso no histórico do shell nem inclua isso em pacotes de suporte. Os comandos a seguir mantêm o dispositivo em uma variável shell e o passam para o Azure como uma configuração de extensão protegida.

    LOG_ANALYTICS_WORKSPACE_ID=$(az monitor log-analytics workspace show \
    --resource-group $GROUP_NAME \
    --workspace-name $WORKSPACE_NAME \
    --query customerId \
    --output tsv)
LOG_ANALYTICS_WORKSPACE_ID_ENC=$(printf %s $LOG_ANALYTICS_WORKSPACE_ID | base64 -w0) # Needed for the next step
LOG_ANALYTICS_KEY=$(az monitor log-analytics workspace get-shared-keys \
    --resource-group $GROUP_NAME \
    --workspace-name $WORKSPACE_NAME \
    --query primarySharedKey \
    --output tsv)
LOG_ANALYTICS_KEY_ENC=$(printf %s $LOG_ANALYTICS_KEY | base64 -w0) # Needed for the next step

Verifique se há uma instalação KEDA existente

A extensão Container Apps instala o KEDA. Antes de instalar a extensão, verifique o cluster para componentes KEDA existentes:

kubectl get deployments -A -o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name"
kubectl get crd scaledobjects.keda.sh

Inspecione a lista de implantação dos componentes KEDA. Se algum dos comandos identificar uma instalação KEDA existente, pare e confirme a configuração de coexistência suportada antes de continuar. Não remova a instalação existente do KEDA nem aplique configurações de extensão não documentadas porque outras cargas de trabalho podem depender disso.

Instalar a extensão Aplicativos de Contêiner

Importante

Se você está implantando no AKS no Azure Local, certifique-se de configurar o HAProxy ou um balanceador de carga personalizado antes de tentar instalar a extensão. Você também pode usar az containerapp arc setup-core-dns --distro AksAzureLocal para configurar o CoreDNS para contextos locais.

  1. Defina os nomes da extensão Container Apps, do namespace Kubernetes e do ambiente conectado.

    • EXTENSION_NAME identifica o recurso de extensão de cluster do Azure.
    • NAMESPACE é criado no cluster Kubernetes e contém componentes de extensão e recursos gerenciados pelo Container Apps. A appsNamespace configuração deve corresponder exatamente ao namespace de lançamento da extensão.
    • CONNECTED_ENVIRONMENT_NAME Torna-se parte do domínio padrão da aplicação. Use um nome compatível com DNS, único dentro do grupo de recursos.

    Não instale cargas de trabalho não relacionadas no namespace da extensão.

    EXTENSION_NAME="appenv-ext"
NAMESPACE="appplat-ns"
CONNECTED_ENVIRONMENT_NAME="<connected-environment-name>"

  2. Instale a extensão do Aplicativos de Contêiner no cluster conectado ao Azure Arc, com o Log Analytics habilitado. O Log Analytics não pode ser adicionado à extensão mais tarde.

    az k8s-extension create \
    --resource-group $GROUP_NAME \
    --name $EXTENSION_NAME \
    --cluster-type connectedClusters \
    --cluster-name $CLUSTER_NAME \
    --extension-type 'Microsoft.App.Environment' \
    --release-train stable \
    --auto-upgrade-minor-version true \
    --scope cluster \
    --release-namespace $NAMESPACE \
    --configuration-settings "Microsoft.CustomLocation.ServiceAccount=default" \
    --configuration-settings "appsNamespace=${NAMESPACE}" \
    --configuration-settings "clusterName=${CONNECTED_ENVIRONMENT_NAME}" \
    --configuration-settings "logProcessor.appLogs.destination=log-analytics" \
    --config-protected-settings "logProcessor.appLogs.logAnalyticsConfig.customerId=${LOG_ANALYTICS_WORKSPACE_ID_ENC}" \
    --config-protected-settings "logProcessor.appLogs.logAnalyticsConfig.sharedKey=${LOG_ANALYTICS_KEY_ENC}"

    Observação

    Para instalar a extensão sem integração com o Log Analytics, remova os três parâmetros relacionados ao logging do comando.

    Para um cluster que usa um balanceador de carga personalizado, defina loadBalancerIp como um endereço reservado para ingresso do Container Apps:

    --configuration-settings "loadBalancerIp=<LOAD_BALANCER_INGRESS_IP>"

    O endereço deve ser acessível pelos clientes de aplicação e não deve ser atribuído a outro serviço. Após a instalação, use-o kubectl get service -n $NAMESPACE -o wide para verificar se o serviço de entrada de extensão reporta esse endereço. Configure o DNS coringa somente depois que o endereço for atribuído. Veja os requisitos do DNS.

    A seguinte tabela descreve os vários parâmetros --configuration-settings durante a execução do comando:

    Parâmetro Descrição
    Microsoft.CustomLocation.ServiceAccount A conta de serviço criada para o local personalizado. Defina o valor como default.
    appsNamespace O namespace usado para criar as definições e revisões do aplicativo. Precisa corresponder àquele do namespace de versão da extensão.
    clusterName O nome do ambiente kubernetes de extensão de Aplicativos de Contêiner criado em relação a essa extensão.
    logProcessor.appLogs.destination Opcional. Destino para logs de aplicativo. Aceita log-analytics ou none, escolher nenhum desabilita os logs da plataforma.
    logProcessor.appLogs.logAnalyticsConfig.customerId Obrigatório somente quando logProcessor.appLogs.destination estiver definido como log-analytics. O ID do espaço de trabalho do Log Analytics codificado em base64. Esse parâmetro deve ser definido como uma configuração protegida.
    logProcessor.appLogs.logAnalyticsConfig.sharedKey Obrigatório somente quando logProcessor.appLogs.destination estiver definido como log-analytics. A chave compartilhada do espaço de trabalho Log Analytics codificada em base64. Esse parâmetro deve ser definido como uma configuração protegida.
    loadBalancerIp O IP de entrada do balanceador de carga.

  3. Salve a propriedade id da extensão dos Aplicativos de Contêiner para mais tarde.

    EXTENSION_ID=$(az k8s-extension show \
    --cluster-type connectedClusters \
    --cluster-name $CLUSTER_NAME \
    --resource-group $GROUP_NAME \
    --name $EXTENSION_NAME \
    --query id \
    --output tsv)

  4. Aguarde até que a extensão seja instalada por completo antes de continuar.

    az resource wait --ids $EXTENSION_ID --created --timeout 1200

az k8s-extension show \
    --cluster-type connectedClusters \
    --cluster-name $CLUSTER_NAME \
    --resource-group $GROUP_NAME \
    --name $EXTENSION_NAME \
    --query "{State:provisioningState,Version:currentVersion}" \
    --output table

    Continue somente quando State for Succeeded. Se o comando exceder o tempo limite ou retornar uma falha, consulte A instalação da extensão falha ou excede o tempo limite.

  5. Inspecione as cargas de trabalho da extensão, os serviços e os eventos recentes:

    kubectl get pods -n $NAMESPACE
kubectl get services -n $NAMESPACE -o wide
kubectl get events -n $NAMESPACE --sort-by=.lastTimestamp

    Não crie o local personalizado enquanto um pod de extensão estiver pendente, reiniciando repetidamente ou não estiver pronto de forma inesperada. Para saber mais sobre esses pods e sua função no sistema, confira Visão geral do Azure Arc.

  6. Se você configurou o Log Analytics, limpe as variáveis locais que contêm a chave do workspace.

    unset LOG_ANALYTICS_KEY LOG_ANALYTICS_KEY_ENC

Criar uma localização personalizada

O local personalizado é um local do Azure que você atribui ao ambiente conectado dos Aplicativos de Contêiner do Azure.

  1. Defina as variáveis de ambiente a seguir para o nome desejado da localização personalizada e para a ID do cluster conectado do Azure Arc.

    CUSTOM_LOCATION_NAME="my-custom-location" # Name of the custom location
CONNECTED_CLUSTER_ID=$(az connectedk8s show --resource-group $GROUP_NAME --name $CLUSTER_NAME --query id --output tsv)

  2. Crie a localização personalizada:

    az customlocation create \
    --resource-group $GROUP_NAME \
    --name $CUSTOM_LOCATION_NAME \
    --host-resource-id $CONNECTED_CLUSTER_ID \
    --namespace $NAMESPACE \
    --cluster-extension-ids $EXTENSION_ID

    Observação

    Se você tiver dificuldade para criar uma localização personalizada no seu cluster, talvez precise ativar o recurso de localização personalizada no seu cluster. Ative esse recurso ao fazer login na CLI usando um principal de serviço ou um usuário do Microsoft Entra com permissões restritas no recurso do cluster.

  3. Espere o local personalizado terminar de provisionar e salve o ID do recurso.

    CUSTOM_LOCATION_ID=$(az customlocation show \
    --resource-group $GROUP_NAME \
    --name $CUSTOM_LOCATION_NAME \
    --query id \
    --output tsv)

az resource wait --ids $CUSTOM_LOCATION_ID --created --timeout 600

az customlocation show \
    --resource-group $GROUP_NAME \
    --name $CUSTOM_LOCATION_NAME \
    --query "{State:provisioningState,Host:hostResourceId,Namespace:namespace}" \
    --output table

    Verifique se State é Succeeded, Host identifica o cluster conectado desejado e Namespace corresponde a $NAMESPACE. Se o provisionamento falhar, veja Falhas na criação de localização personalizada.

Criar o ambiente conectado dos Aplicativos de Contêiner do Azure

Antes de começar a criar aplicativos no local personalizado, você precisa de um ambiente conectado dos Aplicativos de Contêiner do Azure.

  1. Crie o ambiente conectado dos Aplicativos de Contêiner:

    az containerapp connected-env create \
    --resource-group $GROUP_NAME \
    --name $CONNECTED_ENVIRONMENT_NAME \
    --custom-location $CUSTOM_LOCATION_ID \
    --location $LOCATION

  2. Espere o ambiente conectado terminar de provisionar.

    CONNECTED_ENVIRONMENT_ID=$(az containerapp connected-env show \
    --resource-group $GROUP_NAME \
    --name $CONNECTED_ENVIRONMENT_NAME \
    --query id \
    --output tsv)

az resource wait --ids $CONNECTED_ENVIRONMENT_ID --created --timeout 900

az containerapp connected-env show \
    --resource-group $GROUP_NAME \
    --name $CONNECTED_ENVIRONMENT_NAME \
    --query "{State:properties.provisioningState,Location:location,CustomLocation:extendedLocation.name,Domain:properties.defaultDomain}" \
    --output yaml

    Continue apenas quando State for Succeeded e CustomLocation corresponder à localização personalizada que você criou neste tutorial. Salve o Domain exibido para a configuração do DNS da aplicação. Se o provisionamento falhar, veja Falha na criação de ambiente conectado.

Próximas etapas

Criar um aplicativo de contêiner no Azure Arc

  • Última atualização em