Desarrollo de un script de implementación en Bicep

En este artículo se proporcionan ejemplos para mostrar cómo desarrollar un script de implementación en Bicep.

Los recursos del script de implementación pueden tener una duración de implementación. Para llevar a cabo un desarrollo y pruebas eficientes de estos scripts, considere la posibilidad de establecer un entorno de desarrollo dedicado, como una instancia de contenedor de Azure o una instancia de Docker. Para obtener más información, consulte Creación de un entorno de desarrollo.

Sintaxis

El siguiente archivo de Bicep es un ejemplo de un recurso de script de implementación. Para obtener más información, consulte el esquema del script de implementación más reciente.

CLI

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzureCLI'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azCliVersion: '2.52.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

PowerShell

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzurePowerShell'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azPowerShellVersion: '10.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

En el script de implementación, especifique estos valores de propiedad:

• tags: especifique etiquetas de script de implementación. Si el servicio de script de implementación crea los dos recursos de apoyo (una cuenta de almacenamiento y una instancia de contenedor), las etiquetas se pasan a ambos recursos. Puede usar las etiquetas para identificar los recursos. Otra manera de identificar estos recursos de apoyo es a través de sus sufijos, que contienen azscripts. Para obtener más información, vea Supervisión y solución de problemas de scripts de implementación.

• identity: En la versión 2020-10-01 u otra posterior de la API del script de implementación, una identidad administrada asignada por el usuario es opcional a menos que necesite realizar cualquier acción específica de Azure en el script o esté ejecutando el script de implementación en una red privada. La versión de la API 2019-10-01-preview requiere una identidad administrada porque el servicio de script de implementación lo usa para ejecutar los scripts.

  Al especificar la propiedad identity, el servicio de script llama a Connect-AzAccount -Identity antes de invocar el script de usuario. Actualmente, solo se admite una identidad asignada por el usuario. Para iniciar sesión con otra identidad en el script de implementación, puede llamar a Connect-AzAccount. Para obtener más información, consulte Configuración de los permisos mínimos.

• kind: especifique el tipo de script, ya sea AzurePowerShell o AzureCLI. Además de kind, debe especificar la propiedad azPowerShellVersion o azCliVersion.

• storageAccountSettings: permite especificar la configuración para usar una cuenta de almacenamiento existente. Si no se especifica storageAccountName, se crea una cuenta de almacenamiento automáticamente. Para obtener más información, consulte Uso de una cuenta de almacenamiento existente.

• containerSettings: personalice el nombre de la instancia de contenedor de Azure. Para obtener información sobre cómo configurar el nombre del grupo del contenedor, consulte Configuración de una instancia de contenedor más adelante en este artículo. Para obtener información sobre cómo configurar subnetIds con el fin de ejecutar el script de implementación en una red privada, consulte Acceso a una red virtual privada.

• environmentVariables: especifique las variables de entorno que se van a pasar al script.

• azPowerShellVersion/azCliVersion: especifique la versión del módulo que se va a usar.

  CLI

  Consulte una lista de versiones de la CLI de Azure compatibles.

  Importante

  El script de implementación usa las imágenes de la CLI disponibles del Registro de artefactos Microsoft. Normalmente, se necesita aproximadamente un mes para certificar una imagen de la CLI para el script de implementación. No use versiones de la CLI publicadas en los últimos 30 días. Para buscar las fechas de publicación de las imágenes, consulte las notas de la versión de la CLI de Azure. Si usa una versión no compatible, el mensaje de error mostrará las versiones admitidas.

  PowerShell

  Consulte una lista de versiones de Azure PowerShell compatibles. La versión determina qué imagen de contenedor se va a usar:

  • La versión de Az mayores o iguales que 9 usa Ubuntu 22.04.
  • La versión de Az mayor o igual que 6, pero menor que 9 usa Ubuntu 20.04.
  • La versión de Az inferior a 6 usa Ubuntu 18.04.

  Importante

  Le recomendamos que actualice a la versión más reciente de Ubuntu. Ubuntu 18.04 está cerca de su fin de soporte técnico y no recibirá actualizaciones de seguridad después del 31 de mayo de 2023.

• arguments: Especifique los valores de los parámetros. Los valores se separan con espacios.

  El script de implementación divide los argumentos en una matriz de cadenas invocando la llamada del sistema CommandLineToArgvW. Este paso es necesario porque los argumentos se pasan como una propiedad del comando a Azure Container Instances, y la propiedad del comando es una matriz de cadenas.

  Si los argumentos contienen caracteres de escape, use caracteres de doble escape. Por ejemplo, en la sintaxis de Bicep de ejemplo anterior, el argumento es -name \"John Dole\". La cadena de escape es -name \\"John Dole\\".

  Para pasar un parámetro de Bicep de tipo object como argumento, convierta el objeto en una cadena mediante la función string() y, a continuación, use la función replace() para reemplazar las comillas (") por comillas de doble escape (\\"). Por ejemplo:

  replace(string(parameters('tables')), '"', '\\"')
  

  Para obtener más información, vea el archivo de Bicep de ejemplo.

• scriptContent: especifica el contenido del script. Puede ser un script insertado o un archivo de script externo que importó mediante la función loadTextContent. Para obtener más información, consulte Archivo insertado frente a archivo externo más adelante en este artículo. Para ejecutar un script externo, use primaryScriptUri en su lugar.

• primaryScriptUri: especifique una dirección URL de acceso público al script de implementación principal con las extensiones de archivo compatibles. Para obtener más información, consulte Uso de scripts externos más adelante en este artículo.

• primaryScriptUri: especifique una matriz de direcciones URL de acceso público a los archivos auxiliares a los que se llame en supportingScriptUris o scriptContent. Para obtener más información, consulte Archivo insertado frente a archivo externo más adelante en este artículo.

• timeout: especifique el tiempo máximo permitido para la ejecución del script, en formato ISO 8601. El valor predeterminado es P1D.

• forceUpdateTag: cambiar este valor entre las implementaciones de archivos de Bicep obliga a que el script de implementación se vuelva a ejecutar. Si usa la función newGuid() o utcNow(), solo puede usarla en el valor predeterminado de un parámetro. Para más información, consulte Ejecución de un script más de una vez más adelante en este artículo.

• cleanupPreference. Especifique la preferencia para limpiar los dos recursos de implementación de apoyo (la cuenta de almacenamiento y la instancia de contenedor) cuando la ejecución del script se encuentre en estado terminal. La configuración predeterminada es Always, que llama a la eliminación de recursos auxiliares independientemente del estado del terminal (Succeeded, Failedo Canceled). Para más información, consulte Limpieza de los recursos del script de implementación más adelante en este artículo.

• retentionInterval: especifique el intervalo durante el que el servicio conserva los recursos del script de implementación cuando este llega a un estado terminal. Los recursos del script de implementación se eliminan cuando expire este periodo. La duración se basa en el patrón ISO 8601. El intervalo de retención está comprendido entre 1 hora (PT1H) y 26 horas (PT26H). Esta propiedad se usa cuando cleanupPreference se establece en OnExpiration. Para más información, consulte Limpieza de los recursos del script de implementación más adelante en este artículo.

Más ejemplos

• Ejemplo 1: cree un almacén de claves y use un script de implementación para asignar un certificado al almacén de claves.
• Ejemplo 2: cree un grupo de recursos en el nivel de suscripción, cree un almacén de claves en el grupo de recursos y, a continuación, use un script de implementación para asignar un certificado al almacén de claves.
• Ejemplo 3: cree una identidad administrada asignada por el usuario, asigne el rol de colaborador a la identidad en el nivel de grupo de recursos, cree un almacén de claves y, a continuación, use un script de implementación para asignar un certificado al almacén de claves.
• Ejemplo 4: cree manualmente una identidad administrada asignada por el usuario y asígnele permiso para usar Microsoft Graph API para crear aplicaciones de Microsoft Entra. En el archivo de Bicep, use un script de implementación para crear una aplicación y una entidad de servicio de Microsoft Entra, y para generar los identificadores de objeto e identificador de cliente.

Archivo insertado frente a externo

Un script de implementación puede residir en un archivo de Bicep o puede almacenarlo externamente como un archivo independiente.

Uso de un script insertado

El siguiente archivo de Bicep muestra cómo usar un script en línea.

CLI

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlineCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'set -e; output="Hello $1"; echo $output'
    retentionInterval: 'P1D'
  }
}

Incluya set -e en el script para permitir la salida inmediata si un comando devuelve un estado distinto de cero. Esta práctica simplifica los procesos de depuración de errores.

PowerShell

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $ErrorActionPreference = 'Stop'
      $output = "Hello {0}" -f $name
      Write-Output "Output is: '$output'."
    '''
    retentionInterval: 'P1D'
  }
}

Puede controlar el modo en el que Azure PowerShell responde a los errores de no terminación con la variable $ErrorActionPreference en el script. Si no establece la variable en el script de implementación, el servicio de script utiliza el valor predeterminado Continue. Si se establece el valor en Stop, los errores son más fáciles de depurar.

El servicio de script establece el estado de aprovisionamiento de los recursos en Failed cuando el script encuentra un error a pesar de la configuración de $ErrorActionPreference.

Carga de un archivo de script

Use la función loadTextContent para recuperar un archivo de script como una cadena. Esta función permite mantener el script en un archivo externo y acceder a él como un script de implementación. La ruta de acceso especificada para el archivo de script es relativa al archivo de Bicep.

CLI

Puede extraer el script en línea del archivo de Bicep anterior en un archivo hello.sh y, a continuación, colocar el archivo en una subcarpeta denominada scripts.

output="Hello $1"
echo $output

A continuación, puede revisar el archivo de Bicep anterior, como en el ejemplo siguiente:

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: loadTextContent('./scripts/hello.sh')
    retentionInterval: 'P1D'
  }
}

PowerShell

Puede extraer el script en línea del archivo de Bicep anterior en un archivo hello.ps1 y, a continuación, colocar el archivo en una subcarpeta denominada scripts.

param([string] $name)
$output = "Hello {0}" -f $name
Write-Output "Output is: '$output'."

A continuación, puede revisar el archivo de Bicep anterior, como en el ejemplo siguiente:

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: loadTextContent('./scripts/hello.ps1')
    retentionInterval: 'P1D'
  }
}

Uso de scripts externos

Puede usar archivos de script externos en lugar de scripts insertados. Solo se admiten scripts de PowerShell principales con la extensión .ps1. En el caso de los scripts de la CLI, los scripts principales pueden llevar cualquier extensión de script de Bash válida o no tener ninguna extensión en absoluto. Para usar archivos de script externos, intercambie scriptContent con primaryScriptUri.

CLI

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.sh'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

PowerShell

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.ps1'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

Los archivos de script externos deben ser accesibles. Para ayudar a proteger los archivos de script que se almacenan en cuentas de almacenamiento de Azure, genere un token de firma de acceso compartido (SAS) e inclúyalo en el URI de la plantilla. Establezca la expiración con un margen suficiente para completar la implementación. Para obtener más información, consulte Implementación de una plantilla de ARM privada con un token de SAS.

Es responsable de garantizar la integridad del script al que hace referencia el script de implementación (ya sea primaryScriptUri o supportingScriptUris). Haga referencia solo a scripts en los que confíe.

Uso de scripts auxiliares

Puede separar las lógicas complicadas en uno o varios archivos de script auxiliar. Use la propiedad supportingScriptUris para proporcionar una matriz de URI a los archivos de script auxiliares si es necesario.

CLI

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'output="Hello $1"; echo $output; ./hello.sh "$1"'
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.sh'
    ]
    retentionInterval: 'P1D'
  }
}

PowerShell

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $output = "Hello {0}" -f $name
      Write-Output "Output is: '$output'."
      ./hello.ps1 -name $name
    '''
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.ps1'
    ]
    retentionInterval: 'P1D'
  }
}

Puede llamar a archivos de script auxiliares tanto desde scripts insertados como desde archivos de script principal. Los archivos de scripts auxiliares no tienen ninguna restricción relativa a la extensión de archivo.

Los archivos auxiliares se copian en azscripts/azscriptinput en runtime. Use una ruta de acceso relativa para hacer referencia a los archivos auxiliares desde scripts en línea y archivos de script principal.

Acceso a recursos de Azure

Para acceder a los recursos de Azure, debe configurar el elemento identity. En el siguiente archivo de Bicep se muestra cómo recuperar una lista de almacenes de claves de Azure. También es necesario conceder el permiso de identidad de administración de asignación de usuarios para acceder al almacén de claves.

CLI

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvCLI'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'result=$(az keyvault list); echo $result | jq -c \'{Result: map({id: .id})}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

PowerShell

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvPS'
  location: location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azPowerShellVersion: '10.0'
    scriptContent: '''
      $kvs=Get-AzKeyVault

      $output = @()
      foreach($kv in $kvs){
        $newKv = @{
          id = $kv.resourceId
        }
        $output = $output + $newKv
      }
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs["kvs"] = $output
    '''
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

Nota:

La lógica de reintento de inicio de sesión de Azure está ahora integrada en el script contenedor. Si concede permisos en el mismo archivo de Bicep que los scripts de implementación, el servicio de scripts de implementación reintenta el inicio de sesión durante 10 minutos (con intervalos de 10 segundos) hasta que se replique la asignación de roles de la identidad administrada.

Trabajo con salidas

El enfoque para controlar las salidas varía en función del tipo de script que use: la CLI de Azure o Azure PowerShell.

CLI

El script de implementación de la CLI de Azure usa una variable de entorno denominada AZ_SCRIPTS_OUTPUT_PATH para indicar la ubicación del archivo para las salidas del script. Cuando se ejecuta un script de implementación dentro de un archivo de Bicep, el shell de Bash configura automáticamente esta variable de entorno automáticamente. Su valor predefinido se establece como /mnt/azscripts/azscriptoutput/scriptoutputs.json.

Las salidas deben ajustarse a una estructura de objetos de cadena JSON válida. El contenido del archivo debe tener el formato de par clave-valor. Por ejemplo, guarde una matriz de cadenas como { "MyResult": [ "foo", "bar"] }. Almacenar solo los resultados de la matriz, como [ "foo", "bar" ], no es válido.

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output text string = deploymentScript.properties.outputs.text

En el ejemplo anterior se usa jq para construir salidas. La herramienta jq incluye las imágenes de contenedor. Para obtener más información, consulte Configuración de un entorno de desarrollo.

PowerShell

Un script de implementación de Azure PowerShell expone una variable común para almacenar salidas de script.

En el siguiente archivo de Bicep, se muestra cómo pasar valores entre dos recursos deploymentScripts. En el primer recurso, defina una variable denominada $DeploymentScriptOutputs y úsela para almacenar los valores de salida. Use el nombre simbólico del recurso para obtener acceso a los valores de salida.

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript1 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputPS1'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'P1D'
  }
}

resource deploymentScript2 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputPS2'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-textToEcho \\"${deploymentScript1.properties.outputs.text}\\"'
    scriptContent: '''
      param([string] $textToEcho)
      Write-Output $textToEcho
    '''
    retentionInterval: 'P1D'
  }
}

Uso de variables de entorno

Paso de cadenas protegidas a un script de implementación

Puede establecer variables de entorno (EnvironmentVariable) en las instancias de contenedor para proporcionar la configuración dinámica de la aplicación o script que ejecuta el contenedor. Un script de implementación controla las variables de entorno no protegidas y protegidas de la misma manera que Azure Container Instances. Para más información, consulte Establecimiento de variables de entorno en instancias de contenedor.

El tamaño máximo permitido para las variables de entorno es de 64 KB.

CLI

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: 'echo "Username is :$Username"; echo "Password is: $Password"'
    retentionInterval: 'P1D'
  }
}

PowerShell

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: '''
      Write-output "Username is :$Username"
      Write-output "Password is: $Password"
    '''
    retentionInterval: 'P1D'
  }
}

Variables de entorno definidas por el sistema

En la siguiente tabla se enumeran las variables de entorno definidas por el sistema:

Variable de entorno	Valor predeterminado (CLI)	Valor predeterminado (PowerShell)	Sistema reservado
AZ_SCRIPTS_AZURE_ENVIRONMENT	AzureCloud	AzureCloud	No
AZ_SCRIPTS_CLEANUP_PREFERENCE	Always	Always	No
AZ_SCRIPTS_OUTPUT_PATH	/mnt/azscripts/azscriptoutput/scriptoutputs.json	No aplicable	Sí
AZ_SCRIPTS_PATH_INPUT_DIRECTORY	/mnt/azscripts/azscriptinput|/mnt/azscripts/azscriptinput	No aplicable	Sí
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY	/mnt/azscripts/azscriptoutput|/mnt/azscripts/azscriptoutput	No aplicable	Sí
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME	userscript.sh	userscript.ps1	Sí
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	primaryscripturi.config	primaryscripturi.config	Sí
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	supportingscripturi.config	supportingscripturi.config	Sí
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	scriptoutputs.json	scriptoutputs.json	Sí
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	executionresult.json	executionresult.json	Sí
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	No aplicable	No aplicable	No

Para obtener un ejemplo de uso de AZ_SCRIPTS_OUTPUT_PATH, consulte Trabajo con salidas anteriormente en este artículo.

Para acceder a las variables de entorno, use el siguiente código.

CLI

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'echo "AZ_SCRIPTS_AZURE_ENVIRONMENT is : $AZ_SCRIPTS_AZURE_ENVIRONMENT",echo "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : $AZ_SCRIPTS_CLEANUP_PREFERENCE",echo "AZ_SCRIPTS_OUTPUT_PATH	is : $AZ_SCRIPTS_OUTPUT_PATH",echo "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_INPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : $AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME",echo "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : $AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME",echo "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : $AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME",echo "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : $AZ_SCRIPTS_USER_ASSIGNED_IDENTITY"'
    retentionInterval: 'P1D'
  }
}

PowerShell

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    scriptContent: '''
      Write-Output "AZ_SCRIPTS_AZURE_ENVIRONMENT is : ${Env:AZ_SCRIPTS_AZURE_ENVIRONMENT}"
      Write-Output "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : ${Env:AZ_SCRIPTS_CLEANUP_PREFERENCE}"
      Write-Output "AZ_SCRIPTS_OUTPUT_PATH	is : ${Env:AZ_SCRIPTS_OUTPUT_PATH}"
      Write-Output "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : ${Env:AZ_SCRIPTS_PATH_INPUT_DIRECTORY}"
      Write-Output "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : ${Env:AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY}"
      Write-Output "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : ${Env:AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : ${Env:AZ_SCRIPTS_USER_ASSIGNED_IDENTITY}"
    '''
    retentionInterval: 'P1D'
  }
}

Uso de una cuenta de almacenamiento existente

Para que el script se ejecute y permita la solución de problemas, necesita una cuenta de almacenamiento y una instancia de contenedor. Puede designar una cuenta de almacenamiento existente o permitir que el servicio de script cree automáticamente la cuenta de almacenamiento y la instancia de contenedor.

Estos son los requisitos para usar una cuenta de almacenamiento existente:

• En la siguiente tabla se enumeran los tipos de cuenta admitidos. La columna de los niveles hace referencia al valor del parámetro -SkuName o --sku. La columna de tipos admitidos hace referencia al parámetro -Kind o --kind.

  Nivel	Tipo admitido
  Premium_LRS	FileStorage
  Premium_ZRS	FileStorage
  Standard_GRS	Storage, StorageV2
  Standard_GZRS	StorageV2
  Standard_LRS	Storage, StorageV2
  Standard_RAGRS	Storage, StorageV2
  Standard_RAGZRS	StorageV2
  Standard_ZRS	StorageV2

  Estas combinaciones admiten recursos compartidos de archivos. Para más información, vea Creación de un recurso compartido de archivos de Azure e Introducción a las cuentas de almacenamiento.

• Todavía no se admiten reglas de firewall para cuentas de almacenamiento. Para más información, vea Configuración de Firewalls y redes virtuales de Azure Storage.

• La entidad de seguridad de implementación debe tener permisos para administrar la cuenta de almacenamiento, lo que incluye leer, crear y eliminar recursos compartidos de archivos. Para obtener más información, consulte Configuración de los permisos mínimos.

Para especificar una cuenta de almacenamiento existente, agregue el siguiente código de Bicep al elemento de propiedad de Microsoft.Resources/deploymentScripts:

param storageAccountName string = 'myStorageAccount'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    storageAccountSettings: {
      storageAccountName: storageAccountName
      storageAccountKey: listKeys(resourceId('Microsoft.Storage/storageAccounts', storageAccountName), '2023-01-01').keys[0].value
    }
  }
}

Para obtener un ejemplo completo de definición de Microsoft.Resources/deploymentScripts, consulte Sintaxis anteriormente en este artículo.

Cuando se usa una cuenta de almacenamiento existente, el servicio de script crea un recurso compartido de archivos que tiene un nombre único. Para obtener información sobre cómo el servicio de script limpia el recurso compartido de archivos, consulte Limpieza de recursos de script de implementación más adelante en este artículo.

Configuración de una instancia de contenedor

Un script de implementación requiere una nueva instancia de contenedor de Azure. No se puede especificar una instancia de contenedor existente. Sin embargo, puede personalizar el nombre del grupo del contenedor mediante containerGroupName. Si no especifica un nombre de grupo, se genera automáticamente. Se requieren configuraciones adicionales para la creación de esta instancia de contenedor. Para obtener más información, consulte Configuración de los permisos mínimos.

También puede especificar valores subnetId para ejecutar el script de implementación en una red privada. Para obtener más información, consulte Acceso a una red virtual privada.

param containerGroupName string = 'mycustomaci'
param subnetId string = '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    containerSettings: {
      containerGroupName: containerGroupName
      subnetIds: [
        {
          id: subnetId
        }
      ]
    }
  }
}

Ejecución de un script más de una vez

La ejecución del script de implementación es una operación idempotente. Si no se cambia ninguna de las propiedades del recurso deploymentScripts, incluido el script en línea, el script no se ejecuta al volver a implementar el archivo de Bicep.

El servicio de scripts de implementación compara los nombres de recurso del archivo de Bicep con los recursos que hay en el mismo grupo de recursos. Hay dos opciones si quiere ejecutar el mismo script de implementación varias veces:

• Cambie el nombre del recurso deploymentScripts. Por ejemplo, use la función utcNow como nombre del recurso o como parte del nombre del recurso. Puede usar la función utcNow solo en el valor predeterminado de un parámetro.

  Al cambiar el nombre del recurso, se crea un recurso deploymentScripts. Esto es conveniente para mantener un historial de ejecución del script.

• Especifique otro valor en la propiedad forceUpdateTag. Por ejemplo, use utcNow como valor.

Escriba scripts de implementación para garantizar la idempotencia, por lo que las repeticiones accidentales no darán lugar a modificaciones del sistema. Por ejemplo, al crear un recurso de Azure a través del script de implementación, valide su ausencia antes de la creación para asegurarse de que el script se realiza correctamente o evita la creación redundante de recursos.

Uso de Microsoft Graph en un script de implementación

Un script de implementación puede usar Microsoft Graph para crear y trabajar con objetos en Microsoft Entra ID.

Comandos:

Al usar scripts de implementación de la CLI de Azure, puede usar comandos dentro del grupo de comandos az ad para trabajar con aplicaciones, entidades de servicio, grupos y usuarios. También puede invocar directamente Microsoft Graph API mediante el comando az rest.

Al usar scripts de implementación de Azure PowerShell, puede usar el cmdlet Invoke-RestMethod para invocar directamente a Microsoft Graph API.

Permisos

La identidad que usa el script de implementación debe estar autorizada para trabajar con Microsoft Graph API, con los permisos adecuados para las operaciones que realiza. Debe autorizar la identidad fuera del archivo Bicep, por ejemplo, mediante la creación previa de una identidad administrada asignada por el usuario y su asignación de un rol de aplicación para Microsoft Graph. Para más información, consulte este ejemplo de inicio rápido.

Limpieza de los recursos del script de implementación

Los dos recursos auxiliares creados automáticamente nunca pueden sobrevivir al recurso de deploymentScript, a menos que los errores los eliminen. La propiedad cleanupPreference controla el ciclo de vida de los recursos auxiliares. La propiedad retentionInterval controla el ciclo de vida de los recursos deploymentScript. Aquí se muestra cómo usar estas propiedades:

• cleanupPreference: especifique la preferencia de limpieza de los dos recursos de apoyo cuando la ejecución del script se encuentre en estado terminal. Los valores admitidos son:

  • Always: elimine los dos recursos de apoyo una vez que la ejecución del script se encuentre en un estado terminal. Si usa una cuenta de almacenamiento existente, el servicio de script elimina el recurso compartido de archivos que creó el servicio. Dado que el recurso de deploymentScripts puede estar presente después de limpiar los recursos auxiliares, el servicio de script conserva los resultados de ejecución del script (por ejemplo, stdout), las salidas y el valor devuelto antes de que se eliminen los recursos.

  • OnSuccess: elimine los dos recursos de apoyo solo cuando la ejecución del script sea correcta. Si usa una cuenta de almacenamiento existente, el servicio de script quita el recurso compartido de archivos solo cuando la ejecución del script se realiza correctamente.

    Si la ejecución de la secuencia de comandos no tiene éxito, el servicio de secuencias de comandos espera a que expire el valor retentionInterval antes de limpiar los recursos de apoyo y después el recurso de secuencias de comandos de implementación.

  • OnExpiration: elimine los dos recursos auxiliares solo cuando la configuración de retentionInterval haya expirado. Si usa una cuenta de almacenamiento existente, el servicio de script quita el recurso compartido de archivos, pero conserva la cuenta de almacenamiento.

  La instancia de contenedor y la cuenta de almacenamiento se eliminan según el valor de cleanupPreference. Sin embargo, si se produce un error en el script y cleanupPreference no está establecido en Always, el proceso de implementación mantiene automáticamente el contenedor en ejecución durante una hora o hasta que se limpie el contenedor. Puede usar ese tiempo para solucionar problemas con el script.

  Si desea mantener el contenedor en ejecución después de implementaciones correctas, agregue un paso de suspensión al script. Por ejemplo, agregue Start-Sleep (Iniciar-Suspender) al final del script. Si no agrega el paso de suspensión, el contenedor se establece en un estado de terminal y no se puede acceder a él aunque aún no lo haya eliminado.

• retentionInterval: especifique el intervalo de tiempo que se conservará un recurso de deploymentScript antes de que haya expirado y eliminado.

Nota:

No se recomienda usar la cuenta de almacenamiento y la instancia de contenedor que el servicio de script genera para otros fines. Los dos recursos se pueden quitar, en función del ciclo de vida del script.

Pasos siguientes

En este artículo, aprendió a crear recursos del script de implementación. Para obtener más información:

Uso de scripts de implementación en Bicep