Compartir a través de

Configuración de la imagen de contenedor para ejecutar implementaciones con ARM y Bicep

  • Artículo

En este artículo, aprenderá a crear imágenes de contenedor personalizadas de Azure Resource Manager (ARM) y Bicep para implementar las definiciones de entorno en Azure Deployment Environments (ADE).

Una definición de entorno consta de al menos dos archivos: un archivo de plantilla, como azuredeploy.json o main.bicep, y un archivo de manifiesto denominado environment.yaml. ADE usa contenedores para implementar definiciones de entorno y admite de forma nativa los marcos ARM y Bicep IaC.

El modelo de extensibilidad de ADE le permite crear imágenes de contenedor personalizadas para usarlas con las definiciones de entorno. Mediante el modelo de extensibilidad, puede crear sus propias imágenes de contenedor personalizadas y almacenarlas en un registro de contenedor como DockerHub. Después, puede hacer referencia a estas imágenes en las definiciones de entorno para implementar los entornos.

El equipo de ADE ofrece una selección de imágenes para comenzar a trabajar, incluidas una imagen básica y una imagen de Azure Resource Manager (ARM)/Bicep. Puede acceder a estas imágenes de muestra en la carpeta Runner-Images.

Requisitos previos

Uso de imágenes de contenedor con ADE

Puede adoptar uno de los métodos siguientes para usar imágenes de contenedor con ADE:

  • Usar la imagen de contenedor estándar: para escenarios sencillos, use la imagen de contenedor de Bicep estándar proporcionada por ADE.
  • Crear una imagen de contenedor personalizada: para escenarios más complejos, cree una imagen de contenedor personalizada que cumpla sus requisitos específicos.

Independientemente del enfoque que elija, debe especificar la imagen de contenedor en la definición de entorno para implementar los recursos de Azure.

Usar la imagen de contenedor Bicep estándar

ADE admite Bicep de forma nativa, por lo que puede configurar una definición de entorno que implemente recursos de Azure para un entorno de implementación agregando los archivos de plantilla (azuredeploy.json y environment.yaml) al catálogo. Luego, ADE usa una imagen de contenedor estándar de Bicep para crear el entorno de implementación.

En el archivo environment.yaml, la propiedad de ejecutor especifica la ubicación de la imagen de contenedor que desea usar. Para usar la imagen de ejemplo publicada en el Registro de artefactos Microsoft, use los identificadores de ejecutor respectivos, como se enumera en la tabla siguiente.

En el ejemplo siguiente, se muestra un ejecutor que hace referencia a la imagen de contenedor de Bicep de ejemplo:

    name: WebApp
    version: 1.0.0
    summary: Azure Web App Environment
    description: Deploys a web app in Azure without a datastore
    runner: Bicep
    templatePath: azuredeploy.json

Puede ver la imagen de contenedor de Bicep estándar en el repositorio de ejemplo de ADE en la carpeta Runner-Images de la imagen ARM-Bicep.

Para más información sobre cómo crear definiciones de entorno que usen las imágenes de contenedor de ADE para implementar los recursos de Azure, consulte Incorporación y configuración de una definición de entorno.

Crear una imagen de contenedor Bicep personalizada

La creación de una imagen de contenedor personalizada le permite personalizar las implementaciones para que se ajusten a sus requisitos. Puede crear imágenes personalizadas basadas en las imágenes de contenedor estándar de ADE.

Después de completar la personalización de la imagen, debe compilar la imagen e insertarla en el registro de contenedor.

Creación y personalización de una imagen de contenedor con Docker

En este ejemplo, aprenderá a crear una imagen Docker para utilizar las implementaciones de ADE y acceder a la CLI de ADE, basando su imagen en una de las imágenes creadas por ADE.

La CLI de ADE es una herramienta que le permite usar imágenes base de ADE para compilar imágenes personalizadas. Con la CLI de ADE, puede personalizar las implementaciones y las eliminaciones para ajustarse al flujo de trabajo. La CLI de ADE está preinstalada en las imágenes de muestra. Para obtener más información sobre la CLI de ADE, consulte la referencia de imagen de ejecutor personalizado de la CLI.

Para crear una imagen configurada para ADE, siga estos pasos:

  1. Base la imagen en una imagen de muestra creada por ADE o en una imagen de su elección mediante la instrucción FROM.
  2. Instale los paquetes necesarios para la imagen mediante la instrucción RUN.
  3. Cree una carpeta de scripts en el mismo nivel que Dockerfile, almacene en ella sus archivos deploy.sh y delete.sh y asegúrese de que esos scripts se puedan detectar y ejecutar dentro del contenedor que ha creado. Este paso es necesario para que la implementación funcione con la imagen principal de ADE.

Seleccione una imagen de contenedor de ejemplo mediante la instrucción FROM

Incluya una instrucción FROM en un DockerFile creado para la nueva imagen que apunte a una imagen de ejemplo hospedada en el Registro de artefactos Microsoft.

A continuación, se muestra una instrucción FROM de ejemplo que hace referencia a la imagen principal de muestra:

FROM mcr.microsoft.com/deployment-environments/runners/core:latest

Esta instrucción extrae la última imagen principal publicada y la convierte en base de la imagen personalizada.

Instalación de Bicep en un Dockerfile

Puede instalar el paquete de Bicep con la CLI de Azure mediante la instrucción RUN, como se muestra en el siguiente ejemplo:

RUN az bicep install

Las imágenes de muestra de ADE se basan en la imagen de la CLI de Azure y tienen preinstalados los paquetes JQ y la CLI de ADE. Aquí puede obtener más información sobre la CLI de Azurey el paquete JQ.

Para instalar otros paquetes que necesite en la imagen, use la instrucción RUN.

Ejecución de scripts del shell de operaciones

En las imágenes de muestra, las operaciones se determinan y ejecutan en función de su nombre. Actualmente, los dos nombres de operación admitidos son deploy y delete.

Para configurar la imagen personalizada de forma que use esta estructura, especifique una carpeta en el nivel de Dockerfile denominada scripts y especifique dos archivos, deploy.sh y delete.sh. El script del shell deploy se ejecuta al crear o volver a implementar el entorno y el script del shell delete se ejecuta al eliminar el entorno. Puede consultar ejemplos de scripts de shell en el repositorio bajo la carpeta Runner-Images para la imagen ARM-Bicep.

Para asegurarse de que estos scripts de shell sean ejecutables, agregue las siguientes líneas al Dockerfile:

COPY scripts/* /scripts/
RUN find /scripts/ -type f -iname "*.sh" -exec dos2unix '{}' '+'
RUN find /scripts/ -type f -iname "*.sh" -exec chmod +x {} \;

Creación de secuencias de comandos de shell para implementar plantillas de ARM o Bicep

Para asegurarse de que puede implementar correctamente la infraestructura de ARM o Bicep a través de ADE, debe hacer lo siguiente:

  • Conversión de parámetros de ADE en parámetros aceptables para ARM
  • Resolución de plantillas vinculadas si se usan en la implementación
  • Uso de la identidad administrada con privilegios para realizar la implementación

Durante el punto de entrada de la imagen principal, los parámetros establecidos para el entorno actual se almacenan en la variable $ADE_OPERATION_PARAMETERS. Para convertirlos en parámetros aceptables para ARM, puede ejecutar el siguiente comando mediante JQ:

# format the parameters as arm parameters
deploymentParameters=$(echo "$ADE_OPERATION_PARAMETERS" | jq --compact-output '{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", "parameters": (to_entries | if length == 0 then {} else (map( { (.key): { "value": .value } } ) | add) end) }' )

A continuación, para resolver cualquier plantilla vinculada utilizada dentro de una plantilla de ARM basada en JSON, puede descompilar el archivo de plantilla principal, que resuelve todos los archivos de infraestructura local utilizados en muchos módulos Bicep. A continuación, vuelva a compilar esos módulos en una única plantilla de ARM con las plantillas vinculadas insertadas en la plantilla de ARM principal como plantillas anidadas. Este paso solo es necesario durante la operación de implementación. El archivo de plantilla principal se puede especificar utilizando el $ADE_TEMPLATE_FILE establecido durante el punto de entrada de la imagen principal, y debe restablecer esta variable con el archivo de plantilla recompilado. Observe el ejemplo siguiente:

if [[ $ADE_TEMPLATE_FILE == *.json ]]; then

    hasRelativePath=$( cat $ADE_TEMPLATE_FILE | jq '[.. | objects | select(has("templateLink") and (.templateLink | has("relativePath")))] | any' )

    if [ "$hasRelativePath" = "true" ]; then
        echo "Resolving linked ARM templates"

        bicepTemplate="${ADE_TEMPLATE_FILE/.json/.bicep}"
        generatedTemplate="${ADE_TEMPLATE_FILE/.json/.generated.json}"

        az bicep decompile --file "$ADE_TEMPLATE_FILE"
        az bicep build --file "$bicepTemplate" --outfile "$generatedTemplate"

        # Correctly reassign ADE_TEMPLATE_FILE without the $ prefix during assignment
        ADE_TEMPLATE_FILE="$generatedTemplate"
    fi
fi

Para proporcionar los permisos que requiere una implementación para ejecutar la implementación y eliminación de recursos dentro de la suscripción, use la identidad administrada con privilegios asociada al tipo de entorno de proyecto de ADE. Si la implementación necesita permisos especiales para completarse, como roles concretos, asígnelos a la identidad del tipo de entorno del proyecto. A veces, la identidad administrada no está disponible inmediatamente al entrar en el contenedor; puede volver a intentarlo hasta que el inicio de sesión tenga éxito.

echo "Signing into Azure using MSI"
while true; do
    # managed identity isn't available immediately
    # we need to do retry after a short nap
    az login --identity --allow-no-subscriptions --only-show-errors --output none && {
        echo "Successfully signed into Azure"
        break
    } || sleep 5
done

Para comenzar la implementación de las plantillas de ARM o Bicep, ejecute el comando az deployment group create. Al ejecutar este comando dentro del contenedor, elija un nombre de implementación que no invalide las implementaciones anteriores y use las marcas --no-prompt true y --only-show-errors para asegurarse de que la implementación no produce errores en ninguna advertencia o se detiene en la espera de la entrada del usuario, como se muestra en el siguiente ejemplo:

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --subscription $ADE_SUBSCRIPTION_ID \
    --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait \
    --template-file "$ADE_TEMPLATE_FILE" \
    --parameters "$deploymentParameters" \
    --only-show-errors

Para eliminar un entorno, realice una implementación en modo completo y proporcione una plantilla de ARM vacía, que quita todos los recursos del grupo de recursos de ADE especificado, como se muestra en el siguiente ejemplo:

deploymentName=$(date +"%Y-%m-%d-%H%M%S")
az deployment group create --resource-group "$ADE_RESOURCE_GROUP_NAME" \
    --name "$deploymentName" \
    --no-prompt true --no-wait --mode Complete \
    --only-show-errors \
    --template-file "$DIR/empty.json"

Para comprobar el estado de aprovisionamiento y los detalles, ejecute los siguientes comandos. ADE utiliza algunas funciones especiales para leer y proporcionar más contexto basado en los detalles de aprovisionamiento, que puede encontrar en la carpeta Runner-Images. Una implementación sencilla podría ser la siguiente:

if [ $? -eq 0 ]; then # deployment successfully created
    while true; do

        sleep 1

        ProvisioningState=$(az deployment group show --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName" --query "properties.provisioningState" -o tsv)
        ProvisioningDetails=$(az deployment operation group list --resource-group "$ADE_RESOURCE_GROUP_NAME" --name "$deploymentName")

        echo "$ProvisioningDetails"

        if [[ "CANCELED|FAILED|SUCCEEDED" == *"${ProvisioningState^^}"* ]]; then

            echo -e "\nDeployment $deploymentName: $ProvisioningState"

            if [[ "CANCELED|FAILED" == *"${ProvisioningState^^}"* ]]; then
                exit 11
            else
                break
            fi
        fi
    done
fi

Por último, para ver las salidas de la implementación y pasarlas a ADE para que sean accesibles a través de la CLI de Azure, puede ejecutar los siguientes comandos:

deploymentOutput=$(az deployment group show -g "$ADE_RESOURCE_GROUP_NAME" -n "$deploymentName" --query properties.outputs)
if [ -z "$deploymentOutput" ]; then
    deploymentOutput="{}"
fi
echo "{\"outputs\": $deploymentOutput}" > $ADE_OUTPUTS

Hacer que la imagen personalizada sea accesible para ADE

Debe compilar la imagen de Docker e insertarla en el registro de contenedor para que esté disponible para su uso en ADE. Puede compilar la imagen mediante la CLI de Docker o mediante un script proporcionado por ADE.

Seleccione la pestaña adecuada para obtener más información sobre cada enfoque.

Antes de compilar la imagen para insertarla en el registro, asegúrese de que Docker Engine esté instalado en el equipo. A continuación, vaya al directorio del Dockerfile y ejecute el siguiente comando:

docker build . -t {YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}

Por ejemplo, si quiere guardar la imagen en un repositorio dentro del registro denominado customImage y cargar la versión de etiqueta de 1.0.0, debería ejecutar:

docker build . -t {YOUR_REGISTRY}.azurecr.io/customImage:1.0.0

Inserción de la imagen de Docker en un registro

Para usar imágenes personalizadas, debe configurar un registro de imágenes accesible de forma pública que tenga habilitada la extracción anónima de imágenes. De este modo, Azure Deployment Environments puede acceder a la imagen personalizada para ejecutarla en nuestro contenedor.

Azure Container Registry es una oferta de Azure que almacena imágenes de contenedor y artefactos similares.

Para crear un registro, lo cual puede realizarse mediante la CLI de Azure, Azure Portal o comandos de PowerShell entre otros métodos, siga uno de los inicios rápidos correspondientes.

Para configurar el registro de forma que tenga habilitada la extracción anónima de imágenes, ejecute los siguientes comandos en la CLI de Azure:

az login
az acr login -n {YOUR_REGISTRY}
az acr update -n {YOUR_REGISTRY} --public-network-enabled true
az acr update -n {YOUR_REGISTRY} --anonymous-pull-enabled true

Cuando esté listo para insertar la imagen en el registro, ejecute el siguiente comando:

docker push {YOUR_REGISTRY}.azurecr.io/{YOUR_IMAGE_LOCATION}:{YOUR_TAG}

Conexión de la imagen a la definición del entorno

Al crear definiciones de entorno para usar la imagen personalizada en su implementación, edite la propiedad runner en el archivo de manifiesto (environment.yaml o manifest.yaml).

runner: "{YOUR_REGISTRY}.azurecr.io/{YOUR_REPOSITORY}:{YOUR_TAG}"

Para más información sobre cómo crear definiciones de entorno que usen las imágenes de contenedor de ADE para implementar los recursos de Azure, consulte Incorporación y configuración de una definición de entorno.

Acceso a registros de operaciones y detalles de errores

ADE almacena los detalles de los errores de una implementación incorrecta en el archivo $ADE_ERROR_LOG dentro del contenedor.

Para solucionar los problemas de una implementación con errores:

  1. Inicie sesión en el Portal para desarrolladores.

  2. Identifique el entorno que no se ha podido implementar y seleccione Ver detalles.

    Captura de pantalla que muestra los detalles de error de la implementación incorrecta; en concreto, un nombre no válido para una cuenta de almacenamiento.

  3. Revise los detalles correspondientes en la sección Detalles del error.

    Captura de pantalla que muestra una implementación incorrecta donde aparece el botón Ver detalles.

También puede usar la CLI de Azure para ver los detalles de los errores de un entorno con el siguiente comando:

az devcenter dev environment show --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}

Para ver los registros de operaciones de la implementación o eliminación de un entorno, use la CLI de Azure a fin de recuperar la operación más reciente para el entorno y, a continuación, consulte los registros de ese identificador de operación.

# Get list of operations on the environment, choose the latest operation
az devcenter dev environment list-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME}
# Using the latest operation ID, view the operation logs
az devcenter dev environment show-logs-by-operation --environment-name {YOUR_ENVIRONMENT_NAME} --project {YOUR_PROJECT_NAME} --operation-id {LATEST_OPERATION_ID}

Contenido relacionado