Tutorial: Habilitar Azure Container Apps en Kubernetes habilitado para Azure Arc

Este tutorial prepara un clúster Kubernetes compatible para ejecutar Azure Container Apps. Crea un clúster Kubernetes habilitado para Azure Arc, instala la extensión Container Apps, crea una ubicación personalizada y crea un entorno conectado a Container Apps.

Completar este tutorial cambia tanto tu suscripción a Azure como tu clúster de Kubernetes. Necesitas permisos de Azure para crear los recursos listados y acceso de administrador de clúster al clúster de Kubernetes.

Este tutorial muestra cómo habilitar Azure Container Apps en un clúster Kubernetes habilitado para Azure Arc. En este tutorial, usted hará lo siguiente:

  • Conecta un clúster de Kubernetes a Azure Arc, si no está ya conectado.
  • Opcionalmente, crea un espacio de trabajo de Log Analytics.
  • Instala y valida la extensión de Container Apps.
  • Crea y valida una ubicación personalizada.
  • Crea y valida un entorno conectado con Aplicaciones de Contenedores.

Antes de comenzar, revisa Azure Container Apps on Azure Arc. Si un recurso o componente en el clúster no está listo, consulta Troubleshoot Azure Container Apps on Azure Arc-enabled Kubernetes.

Requisitos previos

Antes de empezar, verifica los siguientes requisitos:

  • Una cuenta de Azure con una suscripción activa. Si no tiene ninguna, cree una gratis.
  • Permiso para registrar proveedores de recursos y crear grupos de recursos, un recurso Kubernetes habilitado para Azure Arc, una extensión de clúster, una ubicación personalizada, un entorno conectado a Contenedores Apps y, opcionalmente, un espacio de trabajo de Log Analytics.
  • La CLI de Azure y sus requisitos previos.
  • Una kubectl versión compatible con tu clúster Kubernetes y el acceso a la red desde tu estación de trabajo al servidor API de Kubernetes.
  • Un clúster de Kubernetes compatible con nodos de trabajo Linux amd64 y acceso de administrador del clúster a través del contexto activo kubectl.
  • Una implementación funcional de servicio Kubernetes LoadBalancer .
  • Conectividad saliente a los endpoints requeridos por Azure Arc y Container Apps.
  • CPU y memoria asignables suficientes para las cargas de extensión y aplicaciones.

Antes de cambiar un clúster de producción, revisa el despliegue de Plan a Container Apps en Kubernetes habilitado para Azure Arc.

Configurar

Instale las siguientes extensiones de la CLI de 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 los espacios de nombres necesarios.

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

Establezca variables de entorno según su implementación de clúster de Kubernetes.

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

Creación de un clúster conectado

Si ya tienes un clúster Kubernetes compatible con Azure Arc en $GROUP_NAME, no crees otro clúster. Establece CLUSTER_NAME el nombre del recurso existente del clúster conectado, verifica el acceso con kubectl get nodes, y continúa creando un espacio de trabajo de Log Analytics.

Los siguientes pasos crean un clúster AKS y conéctalo a Azure Arc. Esta ruta está pensada únicamente como un entorno de evaluación alojado en Azure para el tutorial. Para un clúster local o multicloud existente, sigue Quickstart: Conecta un clúster Kubernetes existente a Azure Arc y luego vuelve a este tutorial.

  1. Cree un clúster en Azure Kubernetes Service.

    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. Obtenga el archivo kubeconfig y pruebe la conexión al clúster. De manera predeterminada, el archivo kubeconfig se guarda en ~/.kube/config.

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

kubectl get ns

  3. Cree un grupo de recursos que contenga los recursos de Azure Arc.

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

  4. Conecte el clúster que creó a Azure Arc.

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

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

  5. Espera a que el clúster conectado termine de provisionarse.

    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

    Continúa solo cuando State es Succeeded y Connectivity es Connected. Si el comando se agota, mira Clúster conectado no está listo.

Creación de un área de trabajo de Log Analytics

Un espacio de trabajo de Log Analytics proporciona acceso a los registros de aplicaciones de Contenedores que se ejecutan en el clúster Kubernetes habilitado para Azure Arc. Un espacio de trabajo de Log Analytics es opcional pero recomendado para diagnósticos de aplicaciones.

Importante

Decide si usar Log Analytics antes de instalar la extensión Contenedores de Apps. Proporciona la configuración de Log Analytics durante la instalación de la extensión. No puedes añadir la configuración de Log Analytics a esa instancia de extensión más adelante.

  1. Cree un área de trabajo de 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. Ejecute los siguientes comandos para obtener el identificador del área de trabajo codificada y la clave compartida para un área de trabajo de Log Analytics existente. Los necesitará en el paso siguiente.

    Caution

    La clave compartida del espacio de trabajo es una credencial. No lo imprimas, no lo envíes al control de código fuente, no lo guardes en el historial del shell ni lo incluyas en paquetes de soporte. Los siguientes comandos lo almacenan en una variable del shell y lo pasan a Azure como una configuración protegida de la extensión.

    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

Revisa si hay una instalación KEDA existente

La extensión de Container Apps instala KEDA. Antes de instalar la extensión, comprueba el clúster en busca de componentes KEDA existentes:

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

Inspecciona la lista de despliegue de componentes KEDA. Si alguno de los comandos identifica una instalación KEDA existente, detén y confirma la configuración de coexistencia soportada antes de continuar. No elimines la instalación existente del KEDA ni apliques configuraciones de extensiones no documentadas porque otras cargas de trabajo podrían depender de ello.

Instalación de la extensión de Container Apps

Importante

Si vas a desplegar en AKS en Azure Local, asegúrate de configurar HAProxy o un balanceador de carga personalizado antes de intentar instalar la extensión. También puedes usar az containerapp arc setup-core-dns --distro AksAzureLocal para configurar CoreDNS en contextos locales.

  1. Asigne nombres a la extensión de Container Apps, su espacio de nombres de Kubernetes y el entorno conectado.

    • EXTENSION_NAMEidentifica el recurso de extensión de clúster de Azure.
    • NAMESPACE se crea en el clúster Kubernetes y contiene componentes de extensión y recursos gestionados por Contenedores Apps. El parámetro appsNamespace debe coincidir exactamente con el espacio de nombres de la versión de la extensión.
    • CONNECTED_ENVIRONMENT_NAME pasa a formar parte del dominio de aplicación por defecto. Utiliza un nombre compatible con DNS que sea único dentro del grupo de recursos.

    No instales cargas de trabajo no relacionadas en el espacio de nombres de extensiones.

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

  2. Instale la extensión de Container Apps en el clúster conectado a Azure Arc con Log Analytics habilitado. Log Analytics no se podrá agregar a la extensión más adelante.

    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}"

    Nota:

    Para instalar la extensión sin integración con Log Analytics, elimina los tres parámetros relacionados con el registro del comando.

    En un clúster que usa un equilibrador de carga personalizado, establezca loadBalancerIp en una dirección reservada para la entrada de Container Apps:

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

    La dirección debe ser accesible por los clientes de la aplicación y no debe asignarse a otro servicio. Tras la instalación, usa kubectl get service -n $NAMESPACE -o wide para verificar que el servicio de ingreso de la extensión muestre esta dirección. Configura el DNS con comodines solo después de que se haya asignado la dirección. Consulta los requisitos del DNS.

    En la siguiente tabla se describen los diferentes parámetros --configuration-settings al ejecutar el comando:

    Parámetro Descripción
    Microsoft.CustomLocation.ServiceAccount Cuenta de servicio creada para la ubicación personalizada. Establezca el valor a default.
    appsNamespace Espacio de nombres que se usa para crear las definiciones y revisiones de la aplicación. Debe coincidir con el espacio de nombres de la versión de la extensión.
    clusterName Nombre del entorno de Kubernetes de la extensión Container Apps creado en esta extensión.
    logProcessor.appLogs.destination Opcional. Destino de los registros de la aplicación. Acepta log-analytics o none, si no se elije ninguno se deshabilitan los registros de la plataforma.
    logProcessor.appLogs.logAnalyticsConfig.customerId Necesario solo cuando logProcessor.appLogs.destination se establece en log-analytics. El ID del espacio de trabajo de Log Analytics codificado en Base64. Este parámetro debe configurarse como una configuración protegida.
    logProcessor.appLogs.logAnalyticsConfig.sharedKey Necesario solo cuando logProcessor.appLogs.destination se establece en log-analytics. La clave compartida del espacio de trabajo de Log Analytics codificada en base64. Este parámetro debe configurarse como una configuración protegida.
    loadBalancerIp Dirección IP de entrada del equilibrador de carga.

  3. Guarde la propiedad id de la extensión de Container Apps para más adelante.

    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. Espere a que la extensión se instale 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

    Continúa solo cuando State sea Succeeded. Si el comando expira o informa de un fallo, consulta Falla o expira la instalación de extensiones.

  5. Inspeccione las cargas de trabajo de la extensión, los servicios y los eventos recientes:

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

    No crees la ubicación personalizada mientras un pod de extensión está pendiente, se reinicia repetidamente o no está listo de forma inesperada. Para obtener más información sobre estos pods y su rol en el sistema, vea Introducción a Azure Arc.

  6. Si configuraste Log Analytics, borra las variables locales que contienen la clave del espacio de trabajo.

    unset LOG_ANALYTICS_KEY LOG_ANALYTICS_KEY_ENC

Creación de una ubicación personalizada

La ubicación personalizada es una ubicación de Azure que se asigna al entorno conectado de Azure Container Apps.

  1. Establezca las siguientes variables de entorno en el nombre que quiera de la ubicación personalizada y en el identificador del clúster conectado a 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. Cree la ubicación 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

    Nota:

    Si tienes problemas para crear una ubicación personalizada en tu clúster, puede que necesites activar la función de ubicación personalizada en tu clúster. Activa esta función cuando inicies sesión en la CLI usando un principal de servicio o un usuario de Microsoft Entra con permisos restringidos en el recurso del clúster.

  3. Espera a que la ubicación personalizada termine de aprovisionarse y guarda su ID de 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

    Comprueba que State es Succeeded, que Host identifica el clúster conectado que deseas y que Namespace coincide con $NAMESPACE. Si falla el aprovisionamiento, consulta Error al crear una ubicación personalizada.

Creación del entorno conectado de Azure Container Apps

Para poder empezar a crear aplicaciones en la ubicación personalizada, se necesita un entorno conectado de Azure Container Apps.

  1. Cree el entorno conectado de Container Apps:

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

  2. Espera a que el entorno conectado termine de aprovisionarse.

    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

    Continúa solo cuando State es Succeeded y CustomLocation coincide con la ubicación personalizada que creaste en este tutorial. Guarda lo que se muestra Domain para la configuración DNS de la aplicación. Si falla el aprovisionamiento, consulta Error al crear el entorno conectado.

Pasos siguientes

Creación de una aplicación de contenedor en Azure Arc

  • Se actualizó por última vez el