Configuración de ADE para ejecutar implementaciones con Pulumi

En este artículo, aprenderá a usar Pulumi para implementaciones en Azure Deployment Environments (ADE). Aprenderá a usar una imagen estándar proporcionada por Pulumi o cómo configurar una imagen personalizada para aprovisionar la infraestructura mediante el marco Pulumi Infrastructure-as-Code (IaC).

ADE admite un modelo de extensibilidad que permite crear imágenes personalizadas que puede usar en las definiciones de entorno. Para usar este modelo de extensibilidad, puede crear sus propias imágenes personalizadas y almacenarlas en un registro de contenedor público. Después, puede hacer referencia a estas imágenes en las definiciones de entorno para implementar los entornos.

Una definición de entorno consta de al menos dos archivos: un archivo de proyecto Pulumi, Pulumi.yaml, y un archivo de manifiesto denominado environment.yaml. También puede contener un programa de usuario escrito en el lenguaje de programación preferido: C#, TypeScript, Python, etc. ADE usa contenedores para implementar definiciones de entorno.

Requisitos previos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• Azure Deployment Environments configurados en la suscripción de Azure.
  • Para configurar ADE, siga el Inicio rápido: configurar entornos de implementación de Azure.

Uso de una imagen estándar de Docker proporcionada por Pulumi

El equipo de Pulumi proporciona una imagen precompilada para empezar, que puede ver en la carpeta Runner-Image. Esta imagen está disponible públicamente en Docker Hub de Pulumi como pulumi/azure-deployment-environments, por lo que puede usarlo directamente desde las definiciones de entorno de ADE.

Este es un archivo environment.yaml de ejemplo que usa la imagen precompilada:

name: SampleDefinition
version: 1.0.0
summary: First Pulumi-Enabled Environment
description: Deploys a Storage Account with Pulumi
runner: pulumi/azure-deployment-environments:0.1.0
templatePath: Pulumi.yaml

Puede encontrar algunas definiciones de entorno de ejemplo en la Carpeta entornos.

Compilación y uso de una imagen personalizada de Docker

Puede compilar imágenes personalizadas basadas en las imágenes de ejemplo de ADE mediante la herramienta de la CLI de ADE. Use la CLI de ADE para personalizar las implementaciones y 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.

En este ejemplo, aprenderá a compilar una imagen de Docker para usar las implementaciones de ADE y acceder a la CLI de ADE; como base de la imagen, se tomará una de las imágenes creadas por 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.

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.

Instalación de Pulumi en un Dockerfile

Puede instalar la CLI de Pulumi en una ubicación ejecutable para que se pueda usar en los scripts de implementación y eliminación.

Este es un ejemplo de ese proceso, instalando la versión más reciente de la CLI de Pulumi:

RUN apk add curl
RUN curl -fsSL https://get.pulumi.com | sh
ENV PATH="${PATH}:/root/.pulumi/bin"

Dependiendo del lenguaje de programación que quiera usar para los programas Pulumi, es posible que tenga que instalar uno o varios entornos de ejecución correspondientes. El entorno de ejecución de Python ya está disponible en la imagen base.

Este es un ejemplo de instalación de Node.js y TypeScript:

# install node.js, npm, and typescript
RUN apk add nodejs npm
RUN npm install typescript -g

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 ver ejemplos de scripts de shell en el repositorio en la carpeta Runner-Image/scripts.

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 scripts de shell de operación para usar la CLI de Pulumi

Hay cuatro pasos para implementar la infraestructura mediante Pulumi:

1. pulumi login : conéctese al almacenamiento de estado, ya sea en el sistema de archivos local o en Pulumi Cloud
2. pulumi stack select : cree o seleccione la pila que se va a usar para el entorno determinado
3. pulumi config set : se pasan los parámetros de implementación como valores de configuración de Pulumi
4. pulumi up : ejecute la implementación para crear una infraestructura existente o actualizarla en Azure

Durante el punto de entrada de la imagen principal, los archivos de estado local existentes se extraen en el contenedor y el directorio guardado en la variable de entorno $ADE_STORAGE. Para acceder al archivo de estado existente, ejecute los siguientes comandos:

mkdir -p $ADE_STORAGE
export PULUMI_CONFIG_PASSPHRASE=
pulumi login file://$ADE_STORAGE

Para iniciar sesión en Pulumi Cloud en su lugar, establezca el token de acceso de Pulumi como una variable de entorno y ejecute los comandos siguientes:

export PULUMI_ACCESS_TOKEN=YOUR_PULUMI_ACCESS_TOKEN
pulumi login

Los parámetros establecidos para el entorno actual se almacenan en la variable $ADE_OPERATION_PARAMETERS. Además, la región de Azure seleccionada y el nombre del grupo de recursos se pasan ADE_ENVIRONMENT_LOCATION y ADE_RESOURCE_GROUP_NAME respectivamente. Para establecer la configuración de la pila de Pulumi, ejecute los siguientes comandos:

# Create or select the stack for the current environment
pulumi stack select $ADE_ENVIRONMENT_NAME --create

# Store configuration values in durable storage
export PULUMI_CONFIG_FILE=$ADE_STORAGE/Pulumi.$ADE_ENVIRONMENT_NAME.yaml

# Set the Pulumi stack config
pulumi config set azure-native:location $ADE_ENVIRONMENT_LOCATION --config-file $PULUMI_CONFIG_FILE
pulumi config set resource-group-name $ADE_RESOURCE_GROUP_NAME --config-file $PULUMI_CONFIG_FILE
echo "$ADE_OPERATION_PARAMETERS" | jq -r 'to_entries|.[]|[.key, .value] | @tsv' |
  while IFS=$'\t' read -r key value; do
    pulumi config set $key $value --config-file $PULUMI_CONFIG_FILE
  done

Además, para usar privilegios de ADE para implementar la infraestructura dentro de la suscripción, el script debe usar ADE Managed Service Identity (MSI) al aprovisionar la infraestructura mediante el proveedor nativo de Azure Pulumi o Azure clásico. Si su implementación necesita permisos especiales para su finalización, como roles particulares, asigne esos permisos a la identidad del tipo de entorno del proyecto que se está usando para su implementación del entorno. ADE establece las variables de entorno pertinentes, como los identificadores de cliente, inquilino y suscripción dentro del punto de entrada de la imagen principal, por lo que ejecute los siguientes comandos para asegurarse de que el proveedor usa MSI de ADE:

export ARM_USE_MSI=true
export ARM_CLIENT_ID=$ADE_CLIENT_ID
export ARM_TENANT_ID=$ADE_TENANT_ID
export ARM_SUBSCRIPTION_ID=$ADE_SUBSCRIPTION_ID

Ahora, puede ejecutar el comando pulumi up para ejecutar la implementación:

pulumi up --refresh --yes --config-file $PULUMI_CONFIG_FILE

Durante el script de eliminación, puede ejecutar el comando destroy, como se muestra en el ejemplo siguiente:

pulumi destroy --refresh --yes --config-file $PULUMI_CONFIG_FILE

Por último, para que las salidas de la implementación se carguen y sean accesibles al acceder al entorno a través de la CLI de Azure, transforme el objeto de salida de Pulumi al formato especificado por ADE a través del paquete JQ. Establezca el valor en la variable de entorno $ADE_OUTPUTS, como se muestra en el ejemplo siguiente:

stackout=$(pulumi stack output --json | jq -r 'to_entries|.[]|{(.key): {type: "string", value: (.value)}}')
echo "{\"outputs\": ${stackout:-{\}}}" > $ADE_OUTPUTS

Compilación de la imagen

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.

Creación de una instancia de Azure Container Registry y publicación de la imagen con Pulumi

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

Puede usar Pulumi para crear una instancia de Azure Container Registry y publicar la imagen en ella. Consulte el ejemplo de provisioning/custom-image para ver un proyecto Pulumi independiente que crea todos los recursos necesarios en su cuenta de Azure.

Creación de una instancia de Azure Container Registry y publicación manual de la imagen mediante la CLI

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

Acceso a registros de operaciones y detalles de errores

ADE almacena los detalles de error de una implementación con errores en el archivo $ADE_ERROR_LOG.

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.

   

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

   

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

• Referencia de imagen de ejecutor personalizado de la CLI de ADE
• Repositorio azure-deployment-environments de Pulumi