Conversión y migración de los recursos a un archivo de Bicep

10 minutos

Al iniciar el proceso de migración a Bicep, es importante seguir un proceso estructurado para garantizar que el archivo de Bicep describe correctamente los recursos de Azure. Debe asegurarse de que el código de Bicep sigue los procedimientos recomendados, se ha probado por completo y se puede usar de forma segura en implementaciones posteriores. En esta unidad, obtendrá información sobre las dos primeras fases de la migración a Bicep: la fase de conversión y la fase de migración.

Diagram that shows the convert and migrate phases of the recommended workflow for migrating Azure resources to Bicep.

El enfoque principal de estas dos fases es preparar un nuevo archivo de Bicep para refactorizarlo y probarlo posteriormente.

Fase de conversión

El objetivo de la fase de conversión de la migración de los recursos a Bicep es capturar una representación inicial de los recursos de Azure. El archivo de Bicep que se crea en esta fase está incompleto y no está listo para usarse, pero el archivo le proporciona un punto de partida para la migración.

La fase de conversión consta de dos pasos posibles, que se completan en secuencia:

Capturar una representación de recursos de Azure.
Si es necesario, use el comando decompile para convertir la representación JSON en Bicep.

Diagram that shows a JSON template decompiled to JSON, and Azure resources that are exported to a JSON template, which is then decompiled.

Si tiene una plantilla JSON existente y la va a convertir a Bicep, el primer paso es sencillo, puesto que ya tiene la plantilla de origen. Obtendrá información sobre cómo descompilarla en Bicep en esta unidad.

Si va a convertir recursos de Azure que se implementaron mediante Azure Portal u otra herramienta, debe capturar las definiciones de recursos. Puede exportar las definiciones de recursos y convertirlas a Bicep, o bien puede usar el comando Insertar recurso dentro de Visual Studio Code para insertar una representación Bicep del recurso de Azure.

Cómo representa Azure los recursos

Azure Resource Manager es el servicio que se usa para implementar y administrar recursos en Azure. Resource Manager realiza el seguimiento de todos los recursos implementados en Azure, independientemente del método que se usara para implementar el recurso. Puede usar Azure Portal, la CLI de Azure, Azure PowerShell, la API REST de Resource Manager y los SDK de Azure para interactuar con Resource Manager.

Diagram that shows Resource Manager accepting requests from all Azure clients and libraries.

Existen dos tipos de operaciones en Azure: operaciones de plano de control y operaciones de plano de datos. Las operaciones del plano de control se usan para administrar los recursos de la suscripción. mientras que las operaciones del plano de datos se usan para acceder a las características expuestas por un recurso. Por ejemplo, una operación de plano de control se usa para crear una máquina virtual, pero se usa una operación de plano de datos para conectarse a la máquina virtual mediante el Protocolo de escritorio remoto (RDP).

Exportación de recursos existentes a una plantilla JSON

Independientemente de cómo se creen los recursos de Azure, Resource Manager proporciona información sobre cada recurso en formato JSON. Cuando solicita una copia de la representación JSON de un recurso, está exportando el recurso. El archivo JSON que exporta se puede descompilar en Bicep.

Resource Manager ofrece varias maneras de exportar recursos de Azure a una plantilla. Puede usar los cmdlets de Azure Portal, la CLI de Azure y Azure PowerShell para exportar recursos únicos, varios recursos y grupos de recursos completos.

El proceso de exportación es una operación del plano de control, lo que significa que solo exporta la configuración de los recursos de Azure. Por ejemplo, al exportar una máquina virtual, los datos de la unidad de disco duro de la máquina virtual no se exportan. Además, al exportar una cuenta de almacenamiento, los blobs y otro tipo de contenido de la cuenta de almacenamiento no se incluyen en el proceso de exportación.

Debe tener en cuenta algunas cuestiones al exportar los recursos existentes:

La definición del recurso exportado es una instantánea del estado actual de ese recurso. Incluye todos los cambios realizados en el recurso desde su implementación inicial.
La plantilla exportada puede incluir algunas propiedades de recursos predeterminadas que normalmente se omiten en una definición de Bicep. Por ejemplo, el proceso de exportación podría agregar propiedades de solo lectura que Azure establece automáticamente, pero no tiene sentido incluirlas, ya que son de solo lectura. Considere la posibilidad de quitar estas propiedades de las definiciones de recursos al migrar a Bicep para que los archivos de Bicep no contengan código innecesario que pueda causar confusión.
Es probable que la plantilla exportada no incluya todos los parámetros necesarios para que la plantilla sea reutilizable. Al exportar una plantilla, muchas de las propiedades se codificarán de forma rígida en la plantilla. Obtendrá información sobre cómo agregar parámetros más adelante en este módulo.
Algunos recursos no se pueden exportar con este enfoque y deberá definirlos manualmente en el archivo de Bicep. Obtendrá información sobre cómo volver a crear estos recursos más adelante en esta unidad.

Guardar implementaciones en una plantilla JSON

Si alguna vez ha implementado un recurso manualmente desde Azure Portal, es posible que haya observado la opción Descargar una plantilla para la automatización en la pestaña Revisar y crear. Esta opción guarda una plantilla de ARM JSON basada en los nombres y las propiedades que establezca al crear el recurso en el portal.

Resource Manager también realiza un seguimiento de las implementaciones de los recursos. Las operaciones de implementación incluyen los cambios enviados por la experiencia de creación de recursos de Azure Portal y cualquier implementación de la plantilla de ARM. Los cambios realizados en los recursos existentes mediante Azure Portal, los cmdlets de Azure PowerShell, la CLI de Azure u otras herramientas no suelen crear implementaciones.

Si las implementaciones se crearon con una herramienta compatible, puede acceder a la plantilla de implementación desde el historial de implementación del grupo de recursos. Puede usar Azure Portal, la CLI de Azure o Azure PowerShell para guardar las implementaciones.

Debe tener en cuenta algunas cuestiones al guardar las plantillas mediante este método:

La plantilla guardada muestra el estado de los recursos en el momento de la implementación. No incluye los cambios realizados después de la implementación.
Si la implementación contenía varios recursos, no puede seleccionar recursos específicos para incluirlos y excluirlos. Esta operación descarga la definición de todos los recursos que formaban parte de la implementación inicial. Aun así, al pasar a la fase de migración del proceso, puede omitir manualmente los recursos que no necesite.
La plantilla solo incluye las propiedades de los recursos que se necesitan para la implementación.
Existe la posibilidad de que la plantilla incluya parámetros que puede usar para volver a implementar la plantilla en varios entornos. Pero debe confirmar que estos parámetros se adaptan a sus necesidades.
Probablemente, la plantilla no incluirá propiedades innecesarias, pero debe comprobar que contiene todo lo que espera y quitar las propiedades que no son necesarias.

Nota:

Independientemente de cómo exporte los recursos, ya sea mediante la exportación de recursos existentes o el guardado de implementaciones, trate el archivo exportado como un punto de partida y no lo use directamente. En su lugar, úsela como punto de partida para la plantilla final.

Inserción de recursos existentes a Bicep

La extensión Bicep para Visual Studio Code incluye el comando Insertar recurso, que captura una representación Bicep de un recurso de Azure. Este comando lee la definición JSON del recurso de Azure, quita las propiedades que se reconocen como de solo lectura y descompila JSON en Bicep. Al igual que con la función de exportación, el código Bicep resultante se puede usar como punto de partida para el archivo Bicep final.

Puede insertar un recurso al abrir la paleta de comandos de Visual Studio Code. Use Ctrl+Mayús+P en Windows y Linux y ⌘+Mayús+P en macOS.

Descompilación de la plantilla de ARM JSON de origen

El segundo paso para migrar los recursos de Azure a Bicep es convertir las plantillas de ARM JSON y los recursos de Azure en plantillas de Bicep. Las herramientas de Bicep incluyen el comando decompile para convertir plantillas. Puede invocar el comando decompile desde la CLI de Azure o la CLI de Bicep.

El proceso de descompilación no garantiza una asignación completa de JSON a Bicep. Es posible que deba revisar el archivo de Bicep generado para cumplir con los procedimientos recomendados de su plantilla antes de usar el archivo para implementar recursos. Considérelo el punto de partida de la migración. Más adelante en este módulo, aprenderá a solucionar los problemas que encuentre durante el proceso de descompilación.

Una vez que haya descompilado la plantilla, habrá completado la fase de conversión. Ahora tiene un archivo de Bicep válido para empezar a trabajar.

Fase de migración

El objetivo de la fase de migración de los recursos a Bicep es crear el primer borrador del archivo de Bicep implementable y asegurarse de que define todos los recursos de Azure que están en el ámbito de la migración.

La fase de migración consta de tres pasos, que se completan en secuencia:

Creación de un archivo de Bicep nuevo vacío.
Copia de los recursos de la plantilla descompilada.
Identificar y volver a crear los recursos que faltan.

Diagram that shows the steps for migrating a template to Bicep.

Creación de un archivo de Bicep nuevo

Es recomendable crear un archivo de Bicep nuevo. El archivo que creó en la fase de conversión es un punto de referencia que puede consultar, pero no debe tratarlo como una versión final ni implementarlo tal como está.

Copia de los recursos al nuevo archivo de Bicep

Copie cada recurso del archivo de Bicep convertido al nuevo archivo de Bicep individualmente. Este proceso le ayuda a resolver los problemas por recurso y a evitar confusiones a medida que la plantilla sea mayor.

Volver a crear recursos no compatibles

No todos los tipos de recursos de Azure se pueden exportar a través de Azure Portal, la CLI de Azure o Azure PowerShell. Por ejemplo, las extensiones de máquina virtual como DependencyAgentWindows y MMAExtension (Microsoft Monitoring Agent) son tipos de recursos que no se pueden exportar.

Cuando intenta exportar un recurso mediante Azure Portal, la CLI de Azure o Azure PowerShell e incluye un tipo de recurso no compatible, se genera un mensaje de error detallado. Debe volver a crear los recursos que no se hayan exportado, como las extensiones de máquina virtual, en el nuevo archivo de Bicep. Puede usar varias herramientas y enfoques para volver a crear recursos, incluidos Azure Resource Explorer, la referencia de la plantilla de ARM y las plantillas de inicio rápido de Azure.

Azure Resource Explorer

Azure Resource Explorer es una herramienta que está insertada en el Azure Portal. El portal no muestra determinados tipos de recursos, pero Resource Explorer le proporciona una representación JSON de sus recursos. Para acceder a Resource Explorer, búsquelo en el cuadro de búsqueda:

Screenshot of the Azure portal that shows the search box with resource explorer entered.

En el panel de resultados se muestra una lista de los proveedores de recursos registrados para la suscripción y los detalles de todos los recursos, grupos de recursos y suscripciones que tiene permiso para ver. Para ver una representación JSON de un recurso, seleccione la jerarquía en el lado izquierdo del panel:

Screenshot of the Azure portal that shows Azure Resource Explorer.

Al seleccionar un recurso, puede ver la representación JSON, como en este ejemplo:

{
    "name": "DependencyAgentWindows",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-app-prod-truckline/providers/Microsoft.Compute/virtualMachines/vm-prod-001/extensions/DependencyAgentWindows",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "eastus",
    "properties": {
        "autoUpgradeMinorVersion": true,
        "provisioningState": "Succeeded",
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentWindows",
        "typeHandlerVersion": "9.10"
    }
}

Puede usar la representación JSON para definir un recurso de Bicep:

resource dependencyAgentWindows 'Microsoft.Compute/virtualMachines/extensions@2022-08-01' = {
  parent: virtualMachine
  name: 'DependencyAgentWindows'
  location: 'eastus'
  properties: {
    autoUpgradeMinorVersion: true
    publisher: 'Microsoft.Azure.Monitoring.DependencyAgent'
    type: 'DependencyAgentWindows'
    typeHandlerVersion: '9.10'
  }
}

Nota:

La representación JSON incluye una propiedad denominada provisioningState. La propiedad provisioningState es de solo lectura y Azure la establece automáticamente, por lo que no se incluye en la definición de recursos de Bicep.

Sugerencia

La extensión Bicep para Visual Studio Code le ayuda a definir los recursos de Azure en Bicep. Por ejemplo, la representación Bicep del recurso incluye una versión de API, pero la versión JSON exportada no. En Visual Studio Code, cuando empiece a escribir el tipo de recurso, se le sugerirá automáticamente una versión de API.

Referencia de plantilla de Resource Manager

La referencia de la plantilla de ARM es una fuente de información sobre la estructura de la plantilla de ARM, los tipos de recursos, las versiones de API y las definiciones de propiedades de los recursos de Azure. En la documentación se proporcionan ejemplos en formatos Bicep y JSON.

Puede elegir tipos de recursos y proveedores de recursos específicos, como Microsoft.Web/serverfarms y sus versiones de API. Puede consultar qué propiedades de recursos son necesarias y cuáles son opcionales. También puede ver descripciones de propiedades que le ayudarán a comprender lo que hacen las propiedades.

Plantillas de inicio rápido de Azure

El repositorio de plantillas de inicio rápido de Azure es una colección de plantillas aportadas por la comunidad. Este repositorio de plantillas que se pueden buscar proporciona ejemplos de muchos recursos y soluciones de Azure. En algunos inicios rápidos, se pueden ver tanto una plantilla de ARM JSON como una plantilla de ARM Bicep. Puede usar estas plantillas como punto de referencia para crear y comprobar las plantillas para la implementación.

Supongamos que quiere encontrar una plantilla que genere un plan y una aplicación de Azure App Service. Cada plantilla de inicio rápido le ofrece la opción de implementar la plantilla directamente en Azure o verla en GitHub.

Screenshot that shows an Azure Quickstart Template that deploys a basic Linux web app.

Tenga en cuenta que las plantillas de inicio rápido de Azure son contribuciones de la comunidad. Algunos de los ejemplos pueden estar obsoletos, ya que se agregan funciones a los servicios de Azure de manera periódica. Los ejemplos también podrían incluir recursos y propiedades que no necesita para el uso de la plantilla. Aun así, el repositorio de plantillas de inicio rápido es un recurso útil que le permitirá comprender cómo puede implementar los recursos mediante plantillas de ARM.