Migración de recursos de Azure y plantillas de ARM JSON para usar Bicep

Hay muchas ventajas para definir los recursos de Azure en Bicep, incluida la sintaxis más sencilla, la modularización, la administración automática de dependencias, la validación de tipos de IntelliSense y una experiencia de creación mejorada.

Al migrar plantillas de Azure Resource Manager (plantillas de ARM) de JSON existentes a Bicep, se recomienda seguir el flujo de trabajo de cinco fases:

El primer paso del proceso es capturar una representación inicial de los recursos de Azure. Si procede, descompile a continuación el archivo JSON en un archivo Bicep inicial, que se mejora mediante la refactorización. Cuando tenga un archivo de trabajo, pruebe e implemente mediante un proceso que minimice el riesgo de cambios importantes en el entorno de Azure.

En este artículo hemos resumido este flujo de trabajo recomendado. Consulte el módulo Migrar recursos Azure y plantillas JSON ARM para utilizar Bicep Learn para obtener más orientación.

Fase 1: Conversión

En la fase de conversión de la migración de los recursos a Bicep, el objetivo 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, que se completan en secuencia:

1. Capture una representación de los recursos de Azure. Si tiene una plantilla JSON existente y la va a convertir a Bicep, el primer paso es sencillo: ya tiene la plantilla de origen. Si va a convertir recursos de Azure que se implementaron mediante el portal u otra herramienta, debe capturar las definiciones de recursos. Puede capturar una representación JSON de los recursos mediante Azure Portal, CLI de Azure o los cmdlets de Azure PowerShell para exportar recursos únicos, varios recursos y grupos de recursos completos. Puede usar el comando Insert Resource en Visual Studio Code para importar una representación de Bicep del recurso de Azure.

2. Si es necesario, convierta la representación JSON a Bicep mediante el comando decompile. Las herramientas de Bicep incluyen el comando decompile para convertir plantillas. Puede invocar el comando decompile desde Visual Studio Code con la extensión de Bicep, la CLI de Azure o desde la CLI de Bicep. El proceso de descompilación es un proceso de máximo esfuerzo y 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.

Nota:

Para importar un recurso, abra la paleta de comandos de Visual Studio Code. Presione Ctrl+Mayús+P en Windows y Linux y ⌘+Mayús+Pen macOS.

Visual Studio Code permite pegar JSON como Bicep. Para más información, consulte Pegar JSON como un comando Bicep.

Fase 2: Migrar

En la fase de migración de los recursos a Bicep, el objetivo 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:

1. Creación de un archivo de Bicep nuevo vacío. Es recomendable crear un nuevo archivo de Bicep. 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á.

2. Copia de los recursos de la plantilla descompilada. 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 aumenta de tamaño.

3. Identificar y volver a crear los recursos que faltan. 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. Cualquier recurso que no se haya exportado, como las extensiones de máquina virtual, tendrá que volver a crearlo en el nuevo archivo de Bicep. Puede volver a crear recursos con varias herramientas y enfoques, como Azure Resource Explorer, la documentación de referencia de Bicep y las plantillas de ARM y el sitio Plantillas de inicio rápido de Azure.

Fase 3: Refactorización

En la fase de refactorización de la migración de los recursos a Bicep, el objetivo es mejorar la calidad del código de Bicep. Estas mejoras pueden incluir cambios, como agregar comentarios de código para unificar la plantilla a sus estándares de plantilla.

La fase de refactorización consta de ocho pasos, que se pueden completar en cualquier orden:

1. Revisión de las versiones de la API de los recursos. Al exportar recursos de Azure, es posible que la plantilla exportada no contenga la versión más reciente de la API de un tipo de recurso. Si necesita propiedades específicas para futuras implementaciones, actualice la API a la versión adecuada. Se recomienda revisar las versiones de la API de cada recurso exportado.

2. Revisión de las sugerencias del linter en el nuevo archivo de Bicep. Cuando se usa la extensión de Bicep para Visual Studio Code para crear archivos de Bicep, linter de Bicep se ejecuta automáticamente y resalta sugerencias y errores en el código. Muchos de los errores y las sugerencias incluyen una opción para aplicar una corrección rápida al problema. Revise estas recomendaciones y ajuste su archivo de Bicep.

3. Revisión de los parámetros, las variables y los nombres simbólicos. Es posible que los nombres de parámetros, variables y nombres simbólicos generados por el descompilador no coincidan con la convención de nomenclatura estándar. Revise los nombres generados y realice los ajustes necesarios.

4. Simplificación de las expresiones. Es posible que el proceso de descompilación no siempre aproveche algunas de las características de Bicep. Revise las expresiones generadas en la conversión y simplifíquelas. Por ejemplo, la plantilla descompilada puede incluir una función concat() o format() que se podría simplificar con la interpolación de cadenas. Revise las sugerencias del linter y realice los ajustes necesarios.

5. Revisión de los recursos secundarios y de extensión. En Bicep hay varias maneras de declarar recursos secundarios y recursos de extensión, incluida la concatenación de los nombres de los recursos, el uso de la palabra clave parent y el uso de recursos anidados. Considere la posibilidad de revisar estos recursos después de la descompilación y asegúrese de que la estructura cumple sus estándares. Por ejemplo, asegúrese de que no usa la concatenación de cadenas para crear los nombres de los recursos secundarios; debe usar la propiedad parent o un recurso anidado. Del mismo modo, se puede hacer referencia a las subredes como propiedades de una red virtual o como un recurso independiente.

6. Modularización. Si va a convertir una plantilla que tiene muchos recursos, considere la posibilidad de dividir los tipos de recursos individuales en módulos por razones de simplicidad. Los módulos de Bicep ayudan a reducir la complejidad de las implementaciones y a aumentar la capacidad de reutilización del código de Bicep.

   Nota:

   Es posible usar las plantillas JSON como módulos en una implementación de Bicep. Bicep tiene la capacidad de reconocer módulos de JSON y hacer referencia a ellos de forma similar a como se usan los módulos de Bicep.

7. Agregue comentarios y descripciones. Un código de Bicep en condiciones es autodocumentado; Bicep le permite agregar comentarios y atributos @description() al código para ayudarle a documentar la infraestructura. Bicep admite los comentarios de una sola línea mediante una secuencia de caracteres // y los comentarios de varias líneas que comienzan con /* y terminan con */. Puede agregar comentarios a líneas específicas del código y a secciones de código.

8. Seguimiento de los procedimientos recomendados de Bicep. Asegúrese de que el archivo de Bicep sigue las recomendaciones estándar. Revise el documento de referencia de los procedimientos recomendados de Bicep para comprobar si se ha pasado algo por alto.

Fase 4: Prueba

En la fase de prueba de la migración de sus recursos a Bicep, el objetivo es comprobar la integridad de las plantillas migradas y realizar una implementación de prueba.

La fase de prueba consta de dos pasos que se completan en secuencia:

1. Ejecución de la operación what-if de la implementación de la plantilla de ARM. Para comprobar las plantillas convertidas antes de la implementación, puede usar la operación what-if de implementación de plantillas de Azure Resource Manager. Compara el estado actual de su entorno con el estado deseado que se define en la plantilla. La herramienta genera la lista de cambios que se producirán sin aplicar los cambios a su entorno. Puede usar what-if en las implementaciones de modo incremental y completo. Incluso si tiene pensado implementar la plantilla con el modo incremental, es recomendable ejecutar la operación what-if en modo completo.

2. Realización de una implementación de prueba. Antes de introducir la plantilla de Bicep convertida en producción, considere la posibilidad de ejecutar varias implementaciones de prueba. Si tiene varios entornos (por ejemplo, desarrollo, pruebas y producción), se recomienda intentar implementar la plantilla primero en uno de los entornos que no son de producción. Después de la implementación, compare los recursos originales con las nuevas implementaciones de recursos para mantener la coherencia.

Fase 5: Implementación

En la fase de implementación de la migración de sus recursos a Bicep, el objetivo es implementar el archivo de Bicep final en producción.

La fase de implementación consta de cuatro pasos, que se completan en secuencia:

1. Preparación de un plan de reversión. La capacidad de recuperarse de una implementación con errores es fundamental. Cree una estrategia de reversión por si se incorporan cambios importantes a los entornos. Haga un inventario de los tipos de recursos que se implementan, como máquinas virtuales, aplicaciones web y bases de datos. También se debe tener en cuenta el plano de datos de cada recurso. ¿Existe alguna forma de recuperar una máquina virtual y sus datos? ¿Existe alguna forma de recuperar una base de datos tras su eliminación? Un plan de reversión bien desarrollado le ayudará a reducir el tiempo de inactividad al mínimo si surgen problemas derivados de una implementación.

2. Ejecución de la operación what-if en producción. Antes de implementar el archivo de Bicep final en producción, ejecute la operación what-if en el entorno de producción, asegúrese de usar los valores de parámetro de producción y considere la posibilidad de documentar los resultados.

3. Implementación manual. Si va a usar la plantilla convertida en una canalización, como Azure DevOps o Acciones de GitHub, considere la posibilidad de ejecutar primero la implementación desde el equipo local. Es preferible probar la funcionalidad de la plantilla antes de incorporarla a producción. De este modo, puede responder rápidamente si hay un problema.

4. Ejecución de pruebas de humo. Una vez completada la implementación, conviene ejecutar una serie de pruebas de humo para asegurarse de que la aplicación o la carga de trabajo funcionan correctamente. Por ejemplo, compruebe si su aplicación web es accesible a través de canales de acceso normal, como la red pública de Internet o a través de una VPN corporativa. En el caso de las bases de datos, intente realizar una conexión de base de datos y ejecutar una serie de consultas. Con las máquinas virtuales, inicie sesión en la máquina virtual y asegúrese de que todos los servicios están en funcionamiento.

Pasos siguientes

Para obtener más información sobre el descompilador de Bicep, consulte Descompilar JSON de la plantilla de ARM en Bicep.