Compartir vía

Uso de scripts de implementación en plantillas de Resource Manager

  • Artículo

Aprenda a usar scripts de implementación en plantillas de Azure Resource Manager (ARM). Con el recurso deploymentScripts, los usuarios pueden ejecutar scripts en implementaciones de ARM y revisar los resultados de la ejecución.

Sugerencia

Se recomienda Bicep porque ofrece las mismas funcionalidades que las plantillas de ARM y la sintaxis es más fácil de usar. Para obtener más información, consulte Script de implementación.

Estos scripts se pueden usar para realizar pasos personalizados tales como:

  • Adición de usuarios a un directorio.
  • Realización de operaciones de plano de datos como, por ejemplo, copiar blobs o una base de datos de inicialización.
  • Búsqueda y validación de una clave de licencia.
  • Cree un certificado autofirmado.
  • Cree un objeto en Microsoft Entra ID.
  • Búsqueda de bloques de direcciones IP en el sistema personalizado.

Ventajas del script de implementación:

  • Fácil de programar, usar y depurar. Puede desarrollar scripts de implementación en sus entornos de desarrollo favoritos. Los scripts se pueden insertar en plantillas o en archivos de script externos.
  • Puede especificar el lenguaje y la plataforma del script. Actualmente, se admiten scripts de implementación de Azure PowerShell y la CLI de Azure en el entorno de Linux.
  • Permite pasar cuatro argumentos de la línea de comandos al script.
  • Puede especificar salidas de script y pasarlas de nuevo a la implementación.

El recurso de script de implementación solo está disponible en las regiones donde Azure Container Instances está disponible. Consulte Disponibilidad de recursos para Azure Container Instances en las regiones de Azure. Actualmente, el script de implementación solo usa redes públicas.

Importante

El servicio de script de implementación requiere dos recursos de apoyo para la ejecución del script y la resolución de problemas: una cuenta de almacenamiento y una instancia de contenedor. Puede especificar una cuenta de almacenamiento existente; de lo contrario, el servicio de script creará una por usted. Los dos recursos de apoyo creados automáticamente suelen ser eliminados por el servicio de script cuando la ejecución del script de implementación entra en estado terminal. Se le facturarán los recursos de apoyo hasta que los elimine. Para obtener información sobre los precios, consulte los precios de Container Instances y los precios de Azure Storage. Para más información, consulte Limpieza de los recursos del script de implementación.

Nota:

La lógica de reintento de inicio de sesión de Azure está ahora integrada en el script contenedor. Si concede permisos en la misma plantilla que los scripts de implementación, el servicio de scripts de implementación vuelve a intentar iniciar sesión durante 10 minutos con intervalos de 10 segundos hasta que se replica la asignación de roles de identidad administrada.

Recursos de aprendizaje

Si quiere conocer los scripts de implementación a través de una guía paso a paso, consulte Extensión de las plantillas de ARM mediante scripts de implementación.

Configuración de los permisos mínimos

En el caso de la API de script de implementación versión 2020-10-01 o posterior, hay dos entidades de seguridad involucradas en la ejecución del script de implementación:

  • Entidad de seguridad de implementación (la entidad de seguridad usada para implementar la plantilla): esta entidad de seguridad se usa para crear los recursos subyacentes necesarios para que el recurso del script de implementación se ejecute: una cuenta de almacenamiento y una instancia de contenedor de Azure. Para configurar los permisos con menos privilegios, asigne un rol personalizado con las siguientes propiedades a la entidad de seguridad de implementación:

    {
  "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
  "description": "Configure least privilege for the deployment principal in deployment script",
  "type": "customRole",
  "IsCustom": true,
  "permissions": [
    {
      "actions": [
        "Microsoft.Storage/storageAccounts/*",
        "Microsoft.ContainerInstance/containerGroups/*",
        "Microsoft.Resources/deployments/*",
        "Microsoft.Resources/deploymentScripts/*"
      ],
    }
  ],
  "assignableScopes": [
    "[subscription().id]"
  ]
}

    Si los proveedores de recursos de Azure Storage y de Instancia de Azure Container no se han registrado, también debe agregar Microsoft.Storage/register/action y Microsoft.ContainerInstance/register/action.

  • Entidad de seguridad de implementación: Esta entidad de seguridad solo es necesaria si el script de implementación tiene que autenticarse en Azure y llamar a la CLI de Azure o PowerShell. Hay dos maneras de especificar la entidad de seguridad del script de implementación:

    • Especifique una identidad administrada asignada por el usuario en la propiedad identity (consulte Plantillas de ejemplo). Cuando se especifica, el servicio de script llama a Connect-AzAccount -Identity antes de invocar el script de implementación. La identidad administrada debe tener el acceso necesario para completar la operación del script. Actualmente, solo se admiten identidades asignadas por el usuario para la propiedad identity. Para iniciar sesión con una identidad diferente, use el segundo método de esta lista.
    • Pase las credenciales de la entidad de servicio como variables de entorno seguras y, a continuación, puede llamar a Connect-AzAccount o az login en el script de implementación.

    Si se usa una identidad administrada, la entidad de seguridad de implementación necesita que el rol Operador de identidades administradas (un rol integrado) esté asignado al recurso de identidad administrada.

Plantillas de ejemplo

El siguiente código JSON es un ejemplo: Para más información, consulte el esquema de plantilla más reciente.

{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "runPowerShellInline",
  "location": "[resourceGroup().location]",
  "tags": {
    "tagName1": "tagValue1",
    "tagName2": "tagValue2"
  },
  "kind": "AzurePowerShell", // or "AzureCLI"
  "identity": {
    "type": "userAssigned",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID": {}
    }
  },
  "properties": {
    "forceUpdateTag": "1",
    "containerSettings": {
      "containerGroupName": "mycustomaci"
    },
    "storageAccountSettings": {
      "storageAccountName": "myStorageAccount",
      "storageAccountKey": "myKey"
    },
    "azPowerShellVersion": "9.7",  // or "azCliVersion": "2.47.0",
    "arguments": "-name \\\"John Dole\\\"",
    "environmentVariables": [
      {
        "name": "UserName",
        "value": "jdole"
      },
      {
        "name": "Password",
        "secureValue": "jDolePassword"
      }
    ],
    "scriptContent": "
      param([string] $name)
      $output = 'Hello {0}. The username is {1}, the password is {2}.' -f $name,${Env:UserName},${Env:Password}
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    ", // or "primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",
    "supportingScriptUris":[],
    "timeout": "PT30M",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}

Nota:

Este ejemplo se ofrece con fines de demostración. Las propiedades scriptContent y primaryScriptUri no pueden coexistir en una plantilla.

Nota:

El valor de scriptContent muestra un script con varias líneas. Azure Portal y la canalización de Azure DevOps no pueden analizar un script de implementación con varias líneas. Puede encadenar los comandos de PowerShell (usando punto y coma, \r\n o \n) en una sola línea, o bien usar la propiedad primaryScriptUri con un archivo de script externo. Hay muchas herramientas gratuitas disponibles de los valores "escape" o "unescape" de la cadena JSON. Por ejemplo, https://www.freeformatter.com/json-escape.html.

Detalles de los valores de propiedad:

  • 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. En la versión 2019-10-01-preview de la API se requiere una identidad administrada, ya que el servicio del script de implementación la usa para ejecutar los scripts. Cuando se especifica la propiedad de identidad, el servicio de script llama a Connect-AzAccount -Identity antes de invocar el script de usuario. Actualmente, solo se admiten identidades asignadas por el usuario. Para iniciar sesión con otra identidad, puede llamar a Connect-AzAccount en el script.

  • tags: etiquetas de script de implementación. Si el servicio de script de implementación genera una cuenta de almacenamiento y una instancia de contenedor, las etiquetas se pasan a ambos recursos, que pueden utilizarse para la identificarlos. Otra manera de identificar estos recursos 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.

  • kind: especifica el tipo de script. Actualmente, se admiten los scripts de Azure PowerShell y de la CLI de Azure. Los valores son AzurePowerShell y AzureCLI.

  • forceUpdateTag: el cambio de este valor entre implementaciones de plantilla obliga a que se vuelva a ejecutar el script de implementación. Si usa la función newGuid() o utcNow(), ambas funciones solo se pueden usar en el valor predeterminado de un parámetro. Para más información, consulte la sección Ejecución de un script varias veces.

  • containerSettings: permite especificar la configuración para personalizar la instancia de contenedor de Azure. El script de implementación requiere una nueva instancia de Azure Container Instance. No se puede especificar una instancia de Azure Container Instance existente. Sin embargo, puede personalizar el nombre del grupo de contenedores mediante containerGroupName. Si no se especifica, el nombre de grupo se genera automáticamente.

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

  • azPowerShellVersion/azCliVersion: Especifique la versión del módulo que se va a usar. Consulte una lista de versiones de Azure PowerShell compatibles. La versión determina qué imagen de contenedor se va a usar:

    • Las versiones de Az mayores o iguales que 9 usan Ubuntu 22.04.
    • Las versiones de Az mayores o iguales que 6, pero menores que 9, usan Ubuntu 20.04.
    • Las versiones de Az inferiores a 6 usan Ubuntu 18.04.

    Importante

    Es aconsejable actualizar a la versión más reciente de Ubuntu, ya que Ubuntu 18.04 está cerca del final de su vida y ya no recibirá actualizaciones de seguridad más allá del 31 de mayo de 2023.

    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 de Microsoft Container Registry (MCR). Normalmente, se tarda aproximadamente un mes en certificar una imagen de la CLI para el script de implementación. No utilice las versiones de la CLI que se publicaron en un plazo de 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 se usa una versión no compatible, el mensaje de error muestra las versiones admitidas.

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

    Los scripts de implementación dividen los argumentos en una matriz de cadenas mediante la invocación de 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 cadena.

    Si los argumentos contienen caracteres de escape, use JsonEscaper para que estos caracteres sean de escape doble. Pegue la cadena de escape original en la herramienta y, a continuación, seleccione Escape. La herramienta genera una cadena de escape doble. Por ejemplo, en la plantilla de ejemplo anterior, el argumento es -name \"John Dole\". La cadena de escape es -name \\\"John Dole\\\".

    Para pasar un parámetro de plantilla de Resource Manager de tipo objeto como argumento, convierta el objeto en una cadena mediante la función string() y, luego, use la función replace() para reemplazar cualquier \" por \\\". Por ejemplo:

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

    Para más información, consulte la plantilla de ejemplo.

  • environmentVariables: especifique las variables de entorno que se van a pasar al script. Para más información, consulte Desarrollo de scripts de implementación.

  • scriptContent: especifica el contenido del script. Para ejecutar un script externo, use primaryScriptUri en su lugar. Para ver ejemplos, consulte Uso scripts en línea y Uso de scripts externos.

  • 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.

  • 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 Uso de scripts externos.

  • timeout: especifique el tiempo máximo de ejecución de scripts permitido en formato ISO 8601. El valor predeterminado es P1D.

  • cleanupPreference. Especifique la preferencia de limpieza de 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, lo que significa eliminar los recursos de apoyo independientemente del estado terminal (Correcto, Fallido, Cancelado). Para obtener más información, vea el artículo sobre limpieza de los recursos del script de implementación.

  • 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 se sitúa entre 1 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 ejemplos

  • Ejemplo 1: cree un almacén de claves y use el 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 el 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 el script de implementación para asignar un certificado al almacén de claves.
  • Ejemplo 4: es el mismo escenario que el ejemplo 1 de esta lista. Se crea un nuevo grupo de recursos para ejecutar el script de implementación. Esta plantilla es una plantilla de nivel de suscripción.
  • Ejemplo 5: es el mismo escenario que el ejemplo 4. Esta plantilla es una plantilla de nivel de grupo de recursos.
  • Ejemplo 6: Cree manualmente una identidad administrada asignada por el usuario y asígnele permiso para que use Microsoft Graph API para crear aplicaciones de Microsoft Entra. En la plantilla de ARM, use un script de implementación para crear una aplicación de Microsoft Entra y una entidad de servicio, y genere los id. de objeto y el id. de cliente.

Uso de scripts en línea

La plantilla siguiente tiene un recurso definido con el tipo Microsoft.Resources/deploymentScripts. La parte resaltada es el script insertado.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "\\\"John Dole\\\""
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runPowerShellInlineWithOutput",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "scriptContent": "
          param([string] $name)
          $output = \"Hello {0}\" -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "arguments": "[concat('-name', ' ', parameters('name'))]",
        "timeout": "PT1H",
        "cleanupPreference": "OnSuccess",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('runPowerShellInlineWithOutput').outputs.text]",
      "type": "string"
    }
  }
}

Nota:

Como los scripts de implementación insertados se escriben entre comillas dobles, las cadenas dentro de los scripts de implementación deben incluirse entre comillas simples o entre caracteres de escape con una barra diagonal inversa (\). También puede plantearse la posibilidad de usar la sustitución de cadenas tal y como se muestra en el ejemplo anterior de JSON.

El script toma un parámetro y genera el valor del parámetro. DeploymentScriptOutputs se usa para almacenar las salidas. En la sección de salidas, la línea value muestra cómo acceder a los valores almacenados. Write-Output se utiliza con fines de depuración. Para obtener información sobre cómo acceder al archivo de salida, consulte la sección sobre cómo supervisar y solucionar problemas de los scripts de implementación. Para ver las descripciones de las propiedades, consulte Plantillas de ejemplo.

Para ejecutar el script, seleccione Pruébelo para abrir Cloud Shell y luego pegue el código siguiente en el panel de Shell.

$resourceGroupName = Read-Host -Prompt "Enter the name of the resource group to be created"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.json"

Write-Host "Press [ENTER] to continue ..."

El resultado tendrá una apariencia similar a la siguiente:

Captura de pantalla de la salida del script Hola mundo de implementación de la plantilla de Resource Manager.

Uso de scripts externos

Además de los scripts en línea, también puede usar archivos de script externos. Solo se admiten scripts de PowerShell principales con la extensión de archivo ps1. En el caso de los scripts de la CLI, los scripts principales pueden tener extensiones (o no), siempre que los scripts sean scripts de Bash válidos. Para usar archivos de script externos, reemplace scriptContent por primaryScriptUri. Por ejemplo:

"primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",

Para más información, consulte la plantilla de ejemplo.

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

Tiene la responsabilidad de garantizar la integridad de los scripts a los 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. En caso necesario, la propiedad supportingScriptUris le permite especificar una matriz de identificadores URI para los archivos de script auxiliar:

"scriptContent": "
    ...
    ./Create-Cert.ps1
    ...
"

"supportingScriptUris": [
  "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/create-cert.ps1"
],

Se puede llamar a archivos de script auxiliar desde scripts en línea y 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 el entorno de ejecución. Use la ruta de acceso relativa para hacer referencia a los archivos auxiliares desde scripts en línea y archivos de script principal.

Trabajo con salidas de scripts de PowerShell

En la plantilla siguiente se muestra cómo pasar valores entre dos recursos deploymentScripts:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "John Dole"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate1",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-name', ' ', concat('\\\"', parameters('name'), '\\\"'))]",
        "scriptContent": "
          param([string] $name)
          $output = 'Hello {0}' -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    },
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate2",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "dependsOn": [
        "scriptInTemplate1"
      ],
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-textToEcho', ' ', concat('\\\"', reference('scriptInTemplate1').outputs.text, '\\\"'))]",
        "scriptContent": "
          param([string] $textToEcho)
          Write-Output $textToEcho
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $textToEcho
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('scriptInTemplate2').outputs.text]",
      "type": "string"
    }
  }
}

En el primer recurso, defina una variable denominada $DeploymentScriptOutputs y úsela para almacenar los valores de salida. Para acceder al valor de salida de otro recurso dentro de la plantilla, use:

reference('<ResourceName>').outputs.text

Trabajo con salidas de scripts de la CLI

A diferencia de los scripts de implementación de Azure PowerShell, la CLI o bash no expone una variable común para almacenar salidas de script. En su lugar, utiliza una variable de entorno denominada AZ_SCRIPTS_OUTPUT_PATH para indicar la ubicación del archivo de salidas de scripts. Al ejecutar un script de implementación dentro de una plantilla de ARM, el shell de Bash configura automáticamente esta variable de entorno. Su valor predefinido se establece como /mnt/azscripts/azscriptoutput/scriptoutputs.json. Las salidas deben ajustarse a una estructura válida de objetos de cadena JSON. El contenido del archivo debe tener el formato de par clave-valor. Por ejemplo, una matriz de cadenas debe guardarse como { "MyResult": [ "foo", "bar"] }. Almacenar solo los resultados de la matriz, como [ "foo", "bar" ], no se considera válido.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "identity": {
      "type": "string"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runBashWithOutputs",
      "location": "[resourceGroup().location]",
      "kind": "AzureCLI",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "[parameters('identity')]": {
          }
        }
      },
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "AzCliVersion": "2.40.0",
        "timeout": "PT30M",
        "arguments": "'foo' 'bar'",
        "environmentVariables": [
          {
            "name": "UserName",
            "value": "jdole"
          },
          {
            "name": "Password",
            "secureValue": "jDolePassword"
          }
        ],
        "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo \"arg2 is: $2\"; echo \"Username is: $UserName\"; echo \"password is: $Password\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
        "cleanupPreference": "OnExpiration",
        "retentionInterval": "P1D"

jq se usa en el ejemplo anterior. Se incluye con las imágenes de contenedor. Consulte Configuración del entorno de desarrollo.

Uso de la cuenta de almacenamiento existente

Se necesita una cuenta de almacenamiento y una instancia de contenedor para la ejecución de scripts y la solución de problemas. Tiene las opciones para especificar una cuenta de almacenamiento existente; de lo contrario, el servicio de script crea automáticamente la cuenta de almacenamiento, junto con la instancia de contenedor. Requisitos para usar una cuenta de almacenamiento existente:

  • Tipos de cuenta de almacenamiento admitidos:

    SKU 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 las reglas de firewall de la cuenta de almacenamiento. Para más información, vea Configuración de Firewalls y redes virtuales de Azure Storage.

  • La entidad de seguridad de la implementación debe tener permisos para administrar la cuenta de almacenamiento, lo que incluye los recursos compartidos de archivos de lectura, creación y eliminación.

  • La propiedad allowSharedKeyAccess de la cuenta de almacenamiento debe establecerse en true. La única manera de montar una cuenta de almacenamiento en Azure Container Instance (ACI) es mediante una clave de acceso.

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

"storageAccountSettings": {
  "storageAccountName": "myStorageAccount",
  "storageAccountKey": "myKey"
},

  • storageAccountName: especifica el nombre de la cuenta de almacenamiento.

  • storageAccountKey: especifica una de las claves de cuenta de almacenamiento. Se puede usar la función listKeys() para recuperar la clave. Por ejemplo:

    "storageAccountSettings": {
    "storageAccountName": "[variables('storageAccountName')]",
    "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

Consulte Plantillas de ejemplo para obtener una muestra de definición de Microsoft.Resources/deploymentScripts completa.

Cuando se usa una cuenta de almacenamiento existente, el servicio de script crea un recurso compartido de archivos con un nombre único. Consulte Limpieza de los recursos del script de implementación para obtener información sobre cómo el servicio de script limpia el recurso compartido de archivos.

Desarrollo de scripts de implementación

Control de errores de no terminación

Puede controlar el modo en el que PowerShell responde a los errores de no terminación con la variable $ErrorActionPreference en el script de implementación. Si la variable no se establece en el script de implementación, el servicio de script utiliza el valor predeterminado Continuar.

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

Uso de variables de entorno

El script de implementación usa estas variables de entorno:

Variable de entorno Valor predeterminado Sistema reservado
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud No
AZ_SCRIPTS_CLEANUP_PREFERENCE OnExpiration No
AZ_SCRIPTS_OUTPUT_PATH <AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY>/<AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME> Y
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput Y
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput Y
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME Azure PowerShell: userscript.ps1; Azure CLI: userscript.sh Y
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config Y
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config Y
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json Y
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json Y
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY /subscriptions/ No

Para más información sobre el uso de AZ_SCRIPTS_OUTPUT_PATH, consulte Trabajo con salidas de los scripts de implementación.

Paso de cadenas protegidas al script de implementación

El establecimiento de variables de entorno (EnvironmentVariable) en las instancias de contenedor le permite proporcionar configuración dinámica de la aplicación o el script ejecutados por el contenedor. El script de implementación controla las variables de entorno no protegidas y protegidas de la misma manera que Azure Container Instance. Para más información, consulte Establecimiento de variables de entorno en instancias de contenedor. Por ejemplo, consulte Plantillas de ejemplo.

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

Supervisar y solucionar problemas de los scripts de implementación

El servicio de script crea una cuenta de almacenamiento (a menos que especifique una cuenta de almacenamiento existente) y una instancia de contenedor para la ejecución de scripts. Si el servicio de script crea estos recursos automáticamente, ambos recursos tienen el sufijo azscripts en los nombres de los recursos.

Captura de pantalla de los nombres de recursos del script de implementación de la plantilla de Resource Manager.

El script de usuario, los resultados de la ejecución y el archivo stdout se almacenan en los recursos compartidos de archivos de la cuenta de almacenamiento. Hay una carpeta llamada azscripts. En la carpeta hay otras dos carpetas para los archivos de entrada y salida: azscriptinput y azscriptoutput.

La carpeta de salida contiene un archivo executionresult.json y el archivo de salida del script. Puede ver el mensaje de error de ejecución del script en executionresult.json. El archivo de salida solo se crea cuando el script se ejecuta correctamente. La carpeta de entrada contiene un archivo de script de PowerShell del sistema y los archivos de script de implementación del usuario. Puede reemplazar el archivo de script de implementación de usuario por uno revisado y volver a ejecutar el script de implementación en la instancia de Azure Container.

Uso de Azure Portal

Después de implementar un recurso de script de implementación, el recurso se muestra en el grupo de recursos de Azure Portal. En la captura de pantalla siguiente se muestra la página Información general de un recurso de script de implementación:

Captura de pantalla de información general del portal de script de implementación de plantilla de Resource Manager.

En la página de información general se muestra información importante del recurso, como Estado de aprovisionamiento, Cuenta de almacenamiento, Instancia de contenedor y Registros.

En el menú de la izquierda, puede ver el contenido del script de implementación, los argumentos pasados al script y la salida. También puede exportar una plantilla para el script de implementación, incluido el script de implementación.

Uso de PowerShell

Al usar Azure PowerShell, puede administrar scripts de implementación en el ámbito del grupo de recursos o la suscripción:

La salida Get-AzDeploymentScript es parecida a esta:

Name                : runPowerShellInlineWithOutput
Id                  : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput
ResourceGroupName   : myds0618rg
Location            : centralus
SubscriptionId      : aaaabbbb-0000-cccc-1111-dddd2222eeee
ProvisioningState   : Succeeded
Identity            : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mydentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 9.7
StartTime           : 5/11/2023 7:46:45 PM
EndTime             : 5/11/2023 7:49:45 PM
ExpirationDate      : 5/12/2023 7:49:45 PM
CleanupPreference   : OnSuccess
StorageAccountId    : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Storage/storageAccounts/ftnlvo6rlrvo2azscripts
ContainerInstanceId : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.ContainerInstance/containerGroups/ftnlvo6rlrvo2azscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole

RetentionInterval   : P1D
Timeout             : PT1H

Uso de CLI de Azure

Al usar la CLI de Azure, puede administrar scripts de implementación en el ámbito del grupo de recursos o la suscripción:

La salida del comando de lista es similar a:

[
  {
    "arguments": "'foo' 'bar'",
    "azCliVersion": "2.40.0",
    "cleanupPreference": "OnExpiration",
    "containerSettings": {
      "containerGroupName": null
    },
    "environmentVariables": null,
    "forceUpdateTag": "20231101T163748Z",
    "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runBashWithOutputs",
    "identity": {
      "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
      "type": "userAssigned",
      "userAssignedIdentities": {
        "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myidentity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
          "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
        }
      }
    },
    "kind": "AzureCLI",
    "location": "centralus",
    "name": "runBashWithOutputs",
    "outputs": {
      "Result": [
        {
          "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mytest/providers/Microsoft.KeyVault/vaults/mykv1027",
          "resourceGroup": "mytest"
        }
      ]
    },
    "primaryScriptUri": null,
    "provisioningState": "Succeeded",
    "resourceGroup": "mytest",
    "retentionInterval": "1 day, 0:00:00",
    "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "status": {
      "containerInstanceId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mytest/providers/Microsoft.ContainerInstance/containerGroups/eg6n7wvuyxn7iazscripts",
      "endTime": "2023-11-01T16:39:12.080950+00:00",
      "error": null,
      "expirationTime": "2023-11-02T16:39:12.080950+00:00",
      "startTime": "2023-11-01T16:37:53.139700+00:00",
      "storageAccountId": null
    },
    "storageAccountSettings": {
      "storageAccountKey": null,
      "storageAccountName": "dsfruro267qwb4i"
    },
    "supportingScriptUris": null,
    "systemData": {
      "createdAt": "2023-10-31T19:06:57.060909+00:00",
      "createdBy": "someone@contoso.com",
      "createdByType": "User",
      "lastModifiedAt": "2023-11-01T16:37:51.859570+00:00",
      "lastModifiedBy": "someone@contoso.com",
      "lastModifiedByType": "User"
    },
    "tags": null,
    "timeout": "0:30:00",
    "type": "Microsoft.Resources/deploymentScripts"
  }
]

Use la API de REST

Puede obtener la información de implementación de recursos del script de implementación en el nivel de grupo de recursos y en el nivel de suscripción mediante API REST:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>?api-version=2020-10-01

/subscriptions/<SubscriptionID>/providers/microsoft.resources/deploymentScripts?api-version=2020-10-01

En el ejemplo siguiente se usa ARMClient:

armclient login
armclient get /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

La salida es parecida a esta:

{
  "kind": "AzurePowerShell",
  "identity": {
    "type": "userAssigned",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myidentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
        "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444"
      }
    }
  },
  "location": "centralus",
  "systemData": {
    "createdBy": "someone@contoso.com",
    "createdByType": "User",
    "createdAt": "2023-05-11T02:59:04.7501955Z",
    "lastModifiedBy": "someone@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2023-05-11T02:59:04.7501955Z"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "forceUpdateTag": "20220625T025902Z",
    "azPowerShellVersion": "9.7",
    "scriptContent": "\r\n          param([string] $name)\r\n          $output = \"Hello {0}\" -f $name\r\n          Write-Output $output\r\n          $DeploymentScriptOutputs = @{}\r\n          $DeploymentScriptOutputs['text'] = $output\r\n        ",
    "arguments": "-name \\\"John Dole\\\"",
    "retentionInterval": "P1D",
    "timeout": "PT1H",
    "containerSettings": {},
    "status": {
      "containerInstanceId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.ContainerInstance/containerGroups/64lxews2qfa5uazscripts",
      "storageAccountId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Storage/storageAccounts/64lxews2qfa5uazscripts",
      "startTime": "2023-05-11T02:59:07.5951401Z",
      "endTime": "2023-05-11T03:00:16.7969234Z",
      "expirationTime": "2023-05-12T03:00:16.7969234Z"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "runPowerShellInlineWithOutput"
}

La siguiente API REST devuelve el registro:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>/logs?api-version=2020-10-01

Solo funciona antes de que se eliminen los recursos del script de implementación.

Para ver el recurso deploymentScripts en el portal, seleccione Mostrar tipos ocultos:

Captura de pantalla del script de implementación de la plantilla de Resource Manager con la opción de mostrar tipos ocultos en el portal.

Limpieza de los recursos del script de implementación

Los dos recursos de apoyo creados automáticamente nunca pueden sobrevivir al recurso deploymentScript, a menos que haya errores al eliminarlos. El ciclo de vida de los recursos de apoyo se controla mediante la propiedad cleanupPreference, el ciclo de vida del recurso deploymentScript se controla mediante la propiedad retentionInterval:

  • 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: eliminar los dos recursos de apoyo una vez que la ejecución del script se encuentre en un estado terminal. Si se usa una cuenta de almacenamiento existente, el servicio de script elimina el recurso compartido de archivos creado por 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 la ejecución del script, por ejemplo, stdout, salidas y valor devuelto antes de que se eliminen los recursos.

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

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

    • OnExpiration: eliminar los dos recursos de apoyo solo cuando la configuración retentionInterval haya expirado. Si se 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 lo establecido en 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 terminal y no se puede acceder a él aunque aún no se haya eliminado.

  • retentionInterval: especifique el intervalo de tiempo que se conservará un recurso deploymentScript y tras el que expirará y se eliminará.

Nota:

No se recomienda usar la cuenta de almacenamiento ni la instancia de contenedor que genera el servicio de script para otros fines. Los dos recursos podrían quitarse en función del ciclo de vida del script.

La cuenta de almacenamiento y la instancia de contenedor creadas automáticamente no se pueden eliminar si el script de implementación se implementa en un grupo de recursos con un bloqueo CanNotDelete. Para solucionar este problema, puede implementar el script de implementación en otro grupo de recursos sin bloqueos. Vea los ejemplos 4 y 5 en las plantillas de ejemplo.

Ejecución del 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 ejecutará al volver a implementar la plantilla. El servicio de scripts de implementación compara los nombres de recursos de la plantilla con los recursos existentes 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 de plantilla utcNow como nombre del recurso o como parte del nombre del recurso. Al cambiar el nombre del recurso, se crea un recurso deploymentScripts. Esto es conveniente para mantener un historial de ejecución del script.

    Nota:

    La función utcNow solo puede utilizarse en el valor predeterminado de un parámetro.

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

Nota:

Escriba los scripts de implementación que son idempotentes. Esto garantiza que si se ejecutan de nuevo accidentalmente, no van a provocar cambios en el sistema. Por ejemplo, si el script de implementación se usa para crear un recurso de Azure, compruebe que el recurso no exista antes de crearlo, para que el script se realice correctamente o no se vuelva a crear el recurso.

Configuración del entorno de desarrollo

Puede usar una imagen de contenedor preconfigurada como entorno de desarrollo del script de implementación. Para más información, vea Configuración del entorno de desarrollo para scripts de implementación en plantillas.

Después de que el script se pruebe correctamente, puede usarlo como script de implementación en sus plantillas.

Códigos de error del script de implementación

Código de error Descripción
DeploymentScriptInvalidOperation La definición de recursos del script de implementación de la plantilla contiene nombres de propiedad no válidos.
DeploymentScriptResourceConflict No se puede eliminar un recurso del script de implementación que se encuentra en estado no terminal cuando la ejecución no ha superado 1 hora. O bien, no puede volver a ejecutar el mismo script de implementación con el mismo identificador de recurso (la misma suscripción, el mismo nombre de grupo de recursos y el mismo nombre de recurso) pero un contenido de cuerpo del script diferente al mismo tiempo.
DeploymentScriptOperationFailed Error interno en la operación del script de implementación. Póngase en contacto con el soporte técnico de Microsoft.
DeploymentScriptStorageAccountAccessKeyNotSpecified No se ha especificado la clave de acceso para la cuenta de almacenamiento existente.
DeploymentScriptContainerGroupContainsInvalidContainers Un grupo de contenedores creado por el servicio de script de implementación se modificó externamente y se agregaron contenedores no válidos.
DeploymentScriptContainerGroupInNonterminalState Dos o más recursos del script de implementación usan el mismo nombre de instancia de contenedor de Azure en el mismo grupo de recursos, y uno de ellos todavía no ha terminado de ejecutarse.
DeploymentScriptStorageAccountInvalidKind La cuenta de almacenamiento existente del tipo BlobBlobStorage o BlobStorage no admite recursos compartidos de archivos y, por tanto, no se puede usar.
DeploymentScriptStorageAccountInvalidKindAndSku La cuenta de almacenamiento existente no admite recursos compartidos de archivos. Para obtener una lista de los tipos de cuenta de almacenamiento admitidos, vea Uso de la cuenta de almacenamiento existente.
DeploymentScriptStorageAccountNotFound La cuenta de almacenamiento no existe, o bien una herramienta o proceso externo la ha eliminado.
DeploymentScriptStorageAccountWithServiceEndpointEnabled La cuenta de almacenamiento especificada tiene un punto de conexión de servicio. No se admite una cuenta de almacenamiento con un punto de conexión de servicio.
DeploymentScriptStorageAccountInvalidAccessKey Se ha especificado una clave de acceso no válida para la cuenta de almacenamiento existente.
DeploymentScriptStorageAccountInvalidAccessKeyFormat Formato no válido de la clave de la cuenta de almacenamiento. Vea Administración de las claves de acceso de la cuenta de almacenamiento.
DeploymentScriptExceededMaxAllowedTime El tiempo de ejecución del script de implementación superó el valor de tiempo de espera especificado en la definición de recursos del script de implementación.
DeploymentScriptInvalidOutputs La salida del script de implementación no es un objeto JSON válido.
DeploymentScriptContainerInstancesServiceLoginFailure La identidad administrada asignada por el usuario no pudo iniciar sesión después de 10 intentos con un intervalo de 1 minuto.
DeploymentScriptContainerGroupNotFound Un grupo de contenedores creado por el servicio del script de implementación se eliminó mediante una herramienta o un proceso externo.
DeploymentScriptDownloadFailure Error al descargar un script auxiliar. Vea Uso de scripts auxiliares.
DeploymentScriptError El script de usuario generó un error.
DeploymentScriptBootstrapScriptExecutionFailed El script de arranque produjo un error. Script de arranque es el script del sistema que organiza la ejecución del script de implementación.
DeploymentScriptExecutionFailed Error desconocido durante la ejecución del script de implementación.
DeploymentScriptContainerInstancesServiceUnavailable Al crear la instancia de contenedor de Azure (ACI), ACI generó un error de servicio no disponible.
DeploymentScriptContainerGroupInNonterminalState Al crear la instancia de contenedor de Azure (ACI), otro script de implementación usa el mismo nombre de ACI en el mismo ámbito (la misma suscripción, el mismo nombre de grupo de recursos y el mismo nombre de recurso).
DeploymentScriptContainerGroupNameInvalid El nombre de la instancia de contenedor de Azure (ACI) especificado no cumple los requisitos de ACI. Vea Solución de problemas habituales de Azure Container Instances.

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 de la implementación de la plantilla, 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.

Acceso a la red virtual privada

Con Microsoft.Resources/deploymentScripts versión 2023-08-01, puede ejecutar scripts de implementación en redes privadas con algunas configuraciones adicionales.

  • Cree una identidad administrada asignada por el usuario y especifíquela en la propiedad identity. Para asignar la identidad, consulte Identidad.

  • Cree una cuenta de almacenamiento con allowSharedKeyAccess establecido en true y especifique el script de implementación para usar la cuenta de almacenamiento existente. Para especificar una cuenta de almacenamiento existente, consulte Uso de una cuenta de almacenamiento existente. Se requiere alguna configuración adicional para la cuenta de almacenamiento.

    1. Abra la cuenta de almacenamiento en Azure Portal.

    2. En el menú de la izquierda, seleccione Control de acceso (IAM) y después, la pestaña Asignaciones de roles.

    3. Agregue el rol Storage File Data Privileged Contributor a la identidad administrada de asignación de usuarios.

    4. En el menú de la izquierda, en Seguridad y redes, seleccione Redes y después, Firewalls y redes de virtuales.

    5. Seleccione Habilitado desde redes virtuales y direcciones IP seleccionadas.

      Captura de pantalla de la configuración de la cuenta de almacenamiento para acceder a la red privada.

    6. En Redes virtuales, agregue una subred. En la captura de pantalla, la subred se denomina dspvnVnet.

    7. En Excepciones, seleccione Allow Azure services on the trusted services list to access this storage account (Permitir que los servicios de Azure de la lista de servicios de confianza accedan a esta cuenta de almacenamiento).

La siguiente plantilla de ARM muestra cómo configurar el entorno para ejecutar un script de implementación:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string",
      "maxLength": 10
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "userAssignedIdentityName": {
      "type": "string",
      "defaultValue": "[format('{0}Identity', parameters('prefix'))]"
    },
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[format('{0}stg{1}', parameters('prefix'), uniqueString(resourceGroup().id))]"
    },
    "vnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Vnet', parameters('prefix'))]"
    },
    "subnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Subnet', parameters('prefix'))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2023-09-01",
      "name": "[parameters('vnetName')]",
      "location": "[parameters('location')]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "10.0.0.0/16"
          ]
        },
        "enableDdosProtection": false,
        "subnets": [
          {
            "name": "[parameters('subnetName')]",
            "properties": {
              "addressPrefix": "10.0.0.0/24",
              "serviceEndpoints": [
                {
                  "service": "Microsoft.Storage"
                }
              ],
              "delegations": [
                {
                  "name": "Microsoft.ContainerInstance.containerGroups",
                  "properties": {
                    "serviceName": "Microsoft.ContainerInstance/containerGroups"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2023-01-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "networkAcls": {
          "bypass": "AzureServices",
          "virtualNetworkRules": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]",
              "action": "Allow",
              "state": "Succeeded"
            }
          ],
          "defaultAction": "Deny"
        },
        "allowSharedKeyAccess": true
      },
      "dependsOn": [
        "[resourceId('Microsoft.Network/virtualNetworks', parameters('vnetName'))]"
      ]
    },
    {
      "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
      "apiVersion": "2023-07-31-preview",
      "name": "[parameters('userAssignedIdentityName')]",
      "location": "[parameters('location')]"
    },
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2022-04-01",
      "scope": "[format('Microsoft.Storage/storageAccounts/{0}', parameters('storageAccountName'))]",
      "name": "[guid(tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd'), resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName')))]",
      "properties": {
        "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), '2023-07-31-preview').principalId]",
        "roleDefinitionId": "[tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd')]",
        "principalType": "ServicePrincipal"
      },
      "dependsOn": [
        "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
      ]
    }
  ]
}

Puede usar la siguiente plantilla de ARM para probar la implementación:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    },
    "storageAccountName": {
      "type": "string"
    },
    "vnetName": {
      "type": "string"
    },
    "subnetName": {
      "type": "string"
    },
    "userAssignedIdentityName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2023-08-01",
      "name": "[format('{0}DS', parameters('prefix'))]",
      "location": "[parameters('location')]",
      "identity": {
        "type": "userAssigned",
        "userAssignedIdentities": {
          "[format('{0}', resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')))]": {}
        }
      },
      "kind": "AzureCLI",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azCliVersion": "2.47.0",
        "storageAccountSettings": {
          "storageAccountName": "[parameters('storageAccountName')]"
        },
        "containerSettings": {
          "subnetIds": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]"
            }
          ]
        },
        "scriptContent": "echo \"Hello world!\"",
        "retentionInterval": "P1D",
        "cleanupPreference": "OnExpiration"
      }
    }
  ]
}

Pasos siguientes

En este artículo, aprendió a usar scripts de implementación. Para seguir un tutorial sobre scripts de implementación:

Tutorial: Uso de scripts de implementación en plantillas de Azure Resource Manager.

Módulo de aprendizaje: Extensión de las plantillas de Resource Manager mediante scripts de implementación