Operación what-if de implementación de Bicep

Antes de implementar un archivo Bicep, puede obtener una vista previa de los cambios que se producirán. Azure Resource Manager proporciona la operación what-if que le permite ver cómo cambiarán los recursos si implementa el archivo Bicep. La operación hipotética no realiza ningún cambio en los recursos existentes. En su lugar, predice los cambios si se implementa el archivo Bicep.

Puede usar la operación what-if con Azure PowerShell, la CLI de Azure o las operaciones de la API REST. La operación what-if se admite en las implementaciones de grupos de recursos, nivel de suscripción, grupos de administración e inquilinos.

Durante las operaciones hipotéticas, no se admite la evaluación y la expansión de templateLink. Como resultado, los recursos implementados mediante vínculos de plantilla dentro de implementaciones anidadas, incluidas las referencias a especificaciones de plantilla, no serán visibles en los resultados de la operación hipotética.

Recursos de aprendizaje

Para más información sobre la operación hipotética y una guía paso a paso, consulte Vista previa de los cambios de implementación de Azure mediante el uso de hipótesis.

Permisos necesarios

Para implementar un archivo de Bicep o una plantilla de ARM, se necesita acceso de escritura en los recursos que implementa y acceso a todas las operaciones del tipo de recurso Microsoft.Resources/deployments. Por ejemplo, para implementar una máquina virtual, necesita los permisos Microsoft.Compute/virtualMachines/write y Microsoft.Resources/deployments/*. La operación what-if tiene los mismos requisitos de permisos.

Para obtener una lista de roles y permisos, consulte Roles integrados de Azure.

Límites de hipótesis

Una hipótesis expande plantillas anidadas hasta que se alcancen estos límites:

• 500 plantillas anidadas.
• 800 grupos de recursos en una implementación entre grupos de recursos.
• 5 minutos para expandir las plantillas anidadas.

Cuando se alcanza uno de los límites, el tipo de cambio de los recursos restantes se establece en Omitir.

Instalación del módulo de Azure PowerShell

Para usar operaciones what-if en PowerShell, debe tener la versión 4.2 o posterior del módulo Az.

Para instalar el módulo, use:

Install-Module -Name Az -Force

Para más información sobre cómo instalar los módulos, consulte Instalación de Azure PowerShell.

Instalación del módulo de la CLI de Azure

Para usar what-if en la CLI de Azure, debe tener la CLI de Azure versión 2.14.0 o posterior. Si es necesario, instale la versión más reciente de la CLI de Azure.

Ver los resultados

Cuando se usa what-if en PowerShell o la CLI de Azure, la salida incluye resultados codificados por colores que le ayudarán a apreciar los distintos tipos de cambios.

La salida de texto es:

Resource and property changes are indicated with these symbols:
  - Delete
  + Create
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
    - tags.Owner: "Team A"
    ~ properties.addressSpace.addressPrefixes: [
      - 0: "10.0.0.0/16"
      + 0: "10.0.0.0/15"
      ]
    ~ properties.subnets: [
      - 0:

          name:                     "subnet001"
          properties.addressPrefix: "10.0.0.0/24"

      ]

Resource changes: 1 to modify.

Nota

La operación what-if no puede resolver la función de referencia. Cada vez que se establece una propiedad en una expresión de plantilla que incluye la función de referencia, la operación what-if informa que la propiedad cambiará. Este comportamiento se produce porque la operacióno what-if compara el valor actual de la propiedad (como true o false para un valor booleano) con la expresión de plantilla sin resolver. Obviamente, estos valores no coinciden. Cuando se implementa el archivo Bicep, la propiedad solo cambia cuando la expresión de plantilla se resuelve en un valor diferente.

Comandos what-if

Azure PowerShell

Para obtener una vista previa de los cambios antes de implementar un archivo Bicep, use New-AzResourceGroupDeployment o New-AzSubscriptionDeployment. Agregue el parámetro de modificador -Whatif al comando de implementación.

• New-AzResourceGroupDeployment -Whatif para implementaciones de grupos de recursos
• New-AzSubscriptionDeployment -Whatif y New-AzDeployment -Whatif para implementaciones de nivel de suscripción

Puede usar el parámetro de modificador -Confirm para obtener una vista previa de los cambios y recibir un aviso para continuar con la implementación.

• New-AzResourceGroupDeployment -Confirm para implementaciones de grupos de recursos
• New-AzSubscriptionDeployment -Confirm y New-AzDeployment -Confirm para implementaciones de nivel de suscripción

Los comandos anteriores devuelven un resumen de texto que puede inspeccionar manualmente. Para obtener un objeto que se pueda inspeccionar mediante programación en busca de cambios, use Get-AzResourceGroupDeploymentWhatIfResult o Get-AzSubscriptionDeploymentWhatIfResult.

• $results = Get-AzResourceGroupDeploymentWhatIfResult para implementaciones de grupos de recursos
• $results = Get-AzSubscriptionDeploymentWhatIfResult o $results = Get-AzDeploymentWhatIfResult para implementaciones de nivel de suscripción

Azure CLI

Para obtener una vista previa de los cambios antes de implementar una plantilla, use:

• az deployment group what-if para implementaciones de grupos de recursos
• az deployment sub what-if para implementaciones de nivel de suscripción
• az deployment mg what-if para implementaciones de grupos de administración
• az deployment tenant what-if para implementaciones de inquilinos

Puede usar el modificador --confirm-with-what-if (o su forma abreviada -c) para obtener una vista previa de los cambios y recibir un aviso para continuar con la implementación. Agregue este modificador a:

• az deployment group create
• az deployment sub create
• az deployment mg create
• az deployment tenant create

Por ejemplo, use az deployment group create --confirm-with-what-if o -c para implementaciones de grupos de recursos.

Los comandos anteriores devuelven un resumen de texto que puede inspeccionar manualmente. Para obtener un objeto JSON en el que pueda inspeccionar los cambios mediante programación, use el modificador --no-pretty-print. Por ejemplo, use az deployment group what-if --no-pretty-print para implementaciones de grupos de recursos.

Si quiere devolver los resultados sin colores, abra el archivo de configuración de la CLI de Azure. Establezca no_color en yes.

API REST de Azure

Para la API REST, use:

• Implementaciones: What If para implementaciones de grupos de recursos
• Implementaciones: What If en el ámbito de suscripción para implementaciones de nivel de suscripción.
• Implementaciones: What If en el ámbito del grupo de administración para implementaciones de grupos de administración.
• Implementaciones: What If en el ámbito de inquilino para implementaciones de inquilinos.

Tipos de cambio

La operación hipotética muestra siete tipos diferentes de cambios:

• Create: el recurso no existe actualmente, pero se define en el archivo Bicep. Se creará el recurso.
• Delete: este tipo de cambio solo se aplica cuando se usa el modo completo para la implementación de plantillas JSON. El recurso existe, pero no se define en el archivo Bicep. Con el modo completo, se eliminará el recurso. Solo los recursos que admiten la eliminación de modo completo se incluyen en este tipo de cambio.
• Ignore: el recurso existe, pero no está definido en el archivo Bicep. No se implementará ni modificará el recurso. Cuando alcance los límites para expandir plantillas anidadas, encontrará este tipo de cambio. Consulte Límites de hipótesis.
• NoChang: : el recurso existe y se define en el archivo Bicep. El recurso se volverá a implementar, pero las propiedades del recurso no cambiarán. Este tipo de cambio se devuelve cuando ResultFormat se establece en FullResourcePayloads, que es el valor predeterminado.
• NoEffect: la propiedad es de solo lectura y el servicio la omitirá. Por ejemplo, la propiedad sku.tier siempre se establece para que coincida con sku.name en el espacio de nombres Microsoft.ServiceBus.
• Modify: el recurso existe y se define en el archivo Bicep. El recurso se volverá a implementar y las propiedades del recurso cambiarán. Este tipo de cambio se devuelve cuando ResultFormat se establece en FullResourcePayloads, que es el valor predeterminado.
• Deploy: el recurso existe y se define en el archivo Bicep. El recurso será reimplementado. Es posible que las propiedades del recurso cambien o no. La operación devuelve este tipo de cambio cuando no tiene información suficiente para determinar si cualquier propiedad cambiará. Solo verá esta condición cuando ResultFormat se establece en ResourceIdOnly.

Formato de resultado

Puede controlar el nivel de detalle que se devuelve sobre la predicción de cambios. Tiene dos opciones:

• FullResourcePayloads: devuelve una lista de los recursos que van a cambiar y detalles sobre las propiedades que cambiarán.
• ResourceIdOnly: devuelve una lista de los recursos que cambiarán.

El valor predeterminado es FullResourcePayloads.

Para los comandos de implementación de PowerShell, use el parámetro -WhatIfResultFormat. En los comandos de objeto de programación, use el parámetro ResultFormat.

Para la CLI de Azure, use el parámetro --result-format.

Los resultados siguientes muestran los dos formatos de salida diferentes:

• Cargas de recursos completas

  Resource and property changes are indicated with these symbols:
    - Delete
    + Create
    ~ Modify
  
  The deployment will update the following scope:
  
  Scope: /subscriptions/./resourceGroups/ExampleGroup
  
    ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
      - tags.Owner: "Team A"
      ~ properties.addressSpace.addressPrefixes: [
        - 0: "10.0.0.0/16"
        + 0: "10.0.0.0/15"
        ]
      ~ properties.subnets: [
        - 0:
  
          name:                     "subnet001"
          properties.addressPrefix: "10.0.0.0/24"
  
        ]
  
  Resource changes: 1 to modify.
  

• Solo identificador de recurso

  Resource and property changes are indicated with this symbol:
    ! Deploy
  
  The deployment will update the following scope:
  
  Scope: /subscriptions/./resourceGroups/ExampleGroup
  
    ! Microsoft.Network/virtualNetworks/vnet-001
  
  Resource changes: 1 to deploy.
  

Ejecutar la operación hipotética

Configuración de entorno

Para ver cómo funciona, vamos a ejecutar algunas pruebas. En primer lugar, implemente un archivo Bicep que cree una red virtual. Usará esta red virtual para probar cómo se registran los cambios con what-if. Descargue una copia del archivo Bicep.

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: 'vnet-001'
  location: resourceGroup().location
  tags: {
    CostCenter: '12345'
    Owner: 'Team A'
  }
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/16'
      ]
    }
    enableVmProtection: false
    enableDdosProtection: false
    subnets: [
      {
        name: 'subnet001'
        properties: {
          addressPrefix: '10.0.0.0/24'
        }
      }
      {
        name: 'subnet002'
        properties: {
          addressPrefix: '10.0.1.0/24'
        }
      }
    ]
  }
}

Para implementar el archivo de Bicep, use lo siguiente:

PowerShell

New-AzResourceGroup `
  -Name ExampleGroup `
  -Location centralus
New-AzResourceGroupDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile "what-if-before.bicep"

CLI de Azure

az group create \
  --name ExampleGroup \
  --location "Central US"
az deployment group create \
  --resource-group ExampleGroup \
  --template-file "what-if-before.bicep"

Modificación de prueba

Una vez finalizada la implementación, está listo para probar la operación hipotética. Esta vez se implementa un archivo Bicep que cambia la red virtual. Falta una de las etiquetas originales, se ha quitado una subred y el prefijo de dirección ha cambiado. Descargue una copia del archivo Bicep.

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: 'vnet-001'
  location: resourceGroup().location
  tags: {
    CostCenter: '12345'
  }
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/15'
      ]
    }
    enableVmProtection: false
    enableDdosProtection: false
    subnets: [
      {
        name: 'subnet002'
        properties: {
          addressPrefix: '10.0.1.0/24'
        }
      }
    ]
  }
}

Para ver los cambios, use lo siguiente:

PowerShell

New-AzResourceGroupDeployment `
  -Whatif `
  -ResourceGroupName ExampleGroup `
  -TemplateFile "what-if-after.bicep"

CLI de Azure

az deployment group what-if \
  --resource-group ExampleGroup \
  --template-file "what-if-after.bicep"

La salida de what-if es similar a esta:

La salida de texto es:

Resource and property changes are indicated with these symbols:
  - Delete
  + Create
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
    - tags.Owner:                    "Team A"
    + properties.enableVmProtection: false
    ~ properties.addressSpace.addressPrefixes: [
      - 0: "10.0.0.0/16"
      + 0: "10.0.0.0/15"
      ]
    ~ properties.subnets: [
      - 0:

          name:                     "subnet001"
          properties.addressPrefix: "10.0.0.0/24"

      ]

Resource changes: 1 to modify.

Observe en la parte superior de la salida que los colores están definidos para indicar el tipo de cambios.

En la parte inferior de la salida, se muestra que se eliminó el propietario de la etiqueta. El prefijo de dirección cambió de 10.0.0.0/16 a 10.0.0.0/15. Se eliminó la subred denominada subnet001. Recuerde que estos cambios no se implementaron. Obtendrá una vista previa de los cambios que se producirán si implementa la plantilla.

Algunas de las propiedades que se enumeran como eliminadas no cambiarán realmente. Las propiedades se pueden notificar incorrectamente como eliminadas cuando no están en el archivo Bicep, pero se establecen de forma automática durante la implementación como valores predeterminados. Este resultado se considera "ruido" en la respuesta what-if. El recurso implementado final tendrá los valores establecidos para las propiedades. A medida que la operación what-if evolucione, estas propiedades se excluirán del resultado.

Evaluación de los resultados de what-if mediante programación

Ahora, vamos a establecer el comando en una variable para evaluar mediante programación los resultados de what-if.

PowerShell

$results = Get-AzResourceGroupDeploymentWhatIfResult `
  -ResourceGroupName ExampleGroup `
  --template-file "what-if-after.bicep"

Puede ver un resumen de cada cambio.

foreach ($change in $results.Changes)
{
  $change.Delta
}

CLI de Azure

results=$(az deployment group what-if --resource-group ExampleGroup --template-file "what-if-after.bicep" --no-pretty-print)

Confirmar eliminación

Para obtener una vista previa de los cambios antes de implementar un archivo Bicep, use el parámetro de modificador confirm con el comando de implementación. Si los cambios son los esperados, responda que desea que se complete la implementación.

PowerShell

New-AzResourceGroupDeployment `
  -ResourceGroupName ExampleGroup `
  -Confirm `
  -TemplateFile "what-if-after.bicep"

CLI de Azure

az deployment group create \
  --resource-group ExampleGroup \
  --confirm-with-what-if \
  --template-file "what-if-after.bicep"

La salida de texto es:

Resource and property changes are indicated with these symbols:
  - Delete
  + Create
  ~ Modify

The deployment will update the following scope:

Scope: /subscriptions/./resourceGroups/ExampleGroup

  ~ Microsoft.Network/virtualNetworks/vnet-001 [2018-10-01]
    - tags.Owner:                    "Team A"
    + properties.enableVmProtection: false
    ~ properties.addressSpace.addressPrefixes: [
      - 0: "10.0.0.0/16"
      + 0: "10.0.0.0/15"
      ]
    ~ properties.subnets: [
      - 0:

          name:                     "subnet001"
          properties.addressPrefix: "10.0.0.0/24"

      ]

Resource changes: 1 to modify.

Are you sure you want to execute the deployment?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"):

Verá los cambios esperados y puede confirmar que desea que se ejecute la implementación.

Limpieza de recursos

Cuando ya no necesite los recursos de ejemplo, use la CLI de Azure o Azure PowerShell para eliminar el grupo de recursos.

CLI

az group delete --name ExampleGroup

PowerShell

Remove-AzResourceGroup -Name ExampleGroup

SDK

Puede usar la operación "what-if" a través de los SDK de Azure.

• Para Python, use what-if.

• Para Java, use la clase DeploymentWhatIf.

• Para .NET, use la clase DeploymentWhatIf.

Pasos siguientes

• Para usar la operación what-if en una canalización, consulte Prueba de plantillas de Resouce Manager con What-If en una canalización.
• Si observa resultados incorrectos de la operación hipotética, informe de los problemas en https://aka.ms/whatifissues.
• Para información sobre un módulo de Learn que muestre el uso de hipótesis, consulte Vista previa de los cambios y validación de los recursos de Azure mediante hipótesis y el kit de herramientas de prueba de las plantillas de Resource Manager.