O que são scripts de implantação?

  • 5 minutos

Nesta unidade, você aprenderá como o deploymentScripts recurso pode estender modelos do ARM (Azure Resource Manager).

Os modelos do ARM são alto maravilhoso. Você pode usá-los para declarar o estado desejado da sua infraestrutura de nuvem e permitir que as APIs e os serviços descubram como você pode obtê-lo. No entanto, ocasionalmente, você precisa executar ações que estão fora do escopo do Azure Resource Manager.

O que são scripts de implantação?

Os recursos deploymentScripts são scripts do PowerShell ou Bash executados em um contêiner do Docker como parte da implantação de modelo. As imagens de contêiner padrão têm a CLI do Azure ou o Azure PowerShell disponíveis. Esses scripts são executados durante o processamento do modelo do ARM, de modo que você pode adicionar um comportamento personalizado ao processo de implantação.

Os scripts de implantação usam uma identidade gerenciada para autenticação no Azure. Uma identidade gerenciada é uma entidade de serviço cuja credencial e ciclo de vida são gerenciados pela plataforma do Azure. Essa identidade é o que os comandos do Azure PowerShell ou da CLI do Azure usam para atuar no ambiente. Considerando que você atribui a identidade, você controla o escopo do que um recurso deploymentScripts pode afetar.

O recurso deploymentScripts produz a saída que outros recursos na implantação podem usar. Você então pode pesquisar informações de um sistema externo ou fornecer dados conforme o estado atual do ambiente para afetar o restante da implantação.

Como os scripts de implantação funcionam

Um recurso deploymentScripts usa um script fornecido pelo usuário (do modelo ou do URI) e, possivelmente, alguns scripts de suporte, e os executa em uma instância de contêiner do Azure. Essa instância de contêiner é atribuída à identidade gerenciada que você fornece. Os scripts e suas saídas são armazenados em um compartilhamento de arquivo para uma conta de armazenamento do Azure.

Quando a implantação de modelo é executada, ela verifica se há um recurso deploymentScripts no grupo de recursos de destino. Nesse caso, ela compara as propriedades. Se tudo corresponder, nada novo acontecerá. Se o recurso não existir ou tiver sido alterado, o Azure Resource Manager criará uma nova instância de contêiner e executará os scripts de implantação dentro dessa instância de contêiner. Qualquer saída definida é passada de volta para o Azure Resource Manager para uso posterior na implantação.

Estrutura de script de implantação

Para adicionar um comportamento personalizado a um modelo do ARM, você começa com o recurso deploymentScripts. No mínimo, você precisa fornecer detalhes comuns, como:

  • Um name para o recurso deploymentScripts.
  • Os valores type e apiVersion.
  • O local (location valor) em que os recursos de suporte são criados.
  • Um objeto properties vazio. Você chegará lá em breve.

São necessários dois valores deploymentScripts específicos:

  • kind: o tipo de script a ser executado (AzurePowerShell ou AzureCLI).

    {
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "myFirstDeploymentScript",
  "location": "[resourceGroup().location]",
  "kind": "AzurePowerShell",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
    }
  }
}

    resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
}

  • identity: a identidade gerenciada que a instância de contêiner usa. Você pode criar a identidade gerenciada com antecedência e especificá-la como o exemplo a seguir. Ou você pode criá-lo no modelo e referenciá-lo lá, que é o que você faz no próximo exercício.

    {
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "myFirstDeploymentScript",
  "location": "[resourceGroup().location]",
  "kind": "AzurePowerShell",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
    }
  }
}

    resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
}

Depois de definir esses elementos, você pode ir para a seção properties do recurso deploymentScripts. A parte principal da properties seção é a scriptContent, que especifica o script real a ser executado:

"properties": {
  "scriptContent": "
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
  ",
}

properties: {
  scriptContent: '''
    $output = 'Hello Learner!'
    Write-Output $output
    $DeploymentScriptOutputs = @{}
    $DeploymentScriptOutputs['text'] = $output
  '''
}

Observe que o scriptContent usa uma cadeia de caracteres de várias linhas. No Bicep, você pode especificar uma cadeia de caracteres de várias linhas usando três aspas juntas (''') antes e depois da cadeia de caracteres.

É comum que um script de implantação passe as saídas para a implantação. Por exemplo, se você estiver usando um script para pesquisar algumas informações de uma API, poderá passar as informações de volta para a implantação como uma saída. Outros recursos na implantação poderiam, então, usar as informações nas definições próprias.

Para um script do PowerShell, você passa as saídas de volta criando uma variável chamada $DeploymentScriptOutputs, que precisa ser uma tabela de hash. O script de exemplo inicializa a tabela de hash e cria uma saída chamada text, que usa seu valor da variável local $output:

$output = 'Hello Learner!'
Write-Output $output
$DeploymentScriptOutputs = @{}
$DeploymentScriptOutputs['text'] = $output

$output = 'Hello Learner!'
Write-Output $output
$DeploymentScriptOutputs = @{}
$DeploymentScriptOutputs['text'] = $output

Dica

Você também pode escrever scripts de implantação em Bash. Para criar saídas de um script Bash, você precisa criar um arquivo JSON em um local especificado pela variável de ambiente AZ_SCRIPTS_OUTPUT_PATH.

Na seção properties, você também define as várias opções que deploymentScripts pode usar. Neste módulo, mantemos isso simples e apenas adicionamos o suficiente para que o script seja executado. No mínimo, você precisa fornecer a versão do Azure PowerShell ou a CLI do Azure a ser usada, um script a ser executado e um intervalo de retenção.

O intervalo de retenção é por quanto tempo os resultados devem ser mantidos se você quiser manter os recursos. Por padrão, os resultados são removidos após a execução do script.

"properties": {
  "azPowerShellVersion": "3.0",
  "scriptContent": "
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
  ",
  "retentionInterval": "P1D"
}

properties: {
  azPowerShellVersion: '3.0'
  scriptContent: '''
    $output = 'Hello Learner!'
    Write-Output $output
    $DeploymentScriptOutputs = @{}
    $DeploymentScriptOutputs['text'] = $output
  '''
  retentionInterval: 'P1D'
}

Nosso modelo completo teria uma aparência semelhante a:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.1",
  "apiProfile": "",
  "parameters": {},
  "variables": {},
  "functions": [],
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "myFirstDeploymentScript",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid": {}
        }
      },
      "properties": {
        "azPowerShellVersion": "3.0",
        "scriptContent": "
            $output = 'Hello Learner!'
            Write-Output $output
            $DeploymentScriptOutputs = @{}
            $DeploymentScriptOutputs['text'] = $output
        ",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "scriptResult": {
      "type": "string",
      "value": "[reference('myFirstDeploymentScript').outputs.text]"
    }
  }
}

resource myFirstDeploymentScript 'Microsoft.Resources/deploymentScripts@2020-10-01' = {
  name: 'myFirstDeploymentScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/deploymenttest/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myscriptingid': {}
    }
  }
  properties: {
    azPowerShellVersion: '3.0'
    scriptContent: '''
      $output = 'Hello Learner!'
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'P1D'
  }
}

output scriptResult string = myFirstDeploymentScript.properties.outputs.text

Incluir arquivos de script

A inserção de scripts embutidos em modelos pode ser complicada, difícil de ler e entender e difícil de mudar. O Bicep usa a função loadTextContent() para inserir um arquivo de texto externo em sua implantação. Quando o Bicep transcompila seu modelo em JSON, ele insere o arquivo externo no modelo emitido.

Digamos que você tenha um arquivo do PowerShell chamado myscript.ps1 na mesma pasta que o modelo Bicep. Você pode dizer para o Bicep inserir o arquivo da seguinte maneira:

properties: {
  azPowerShellVersion: '3.0'
  scriptContent: loadTextContent('myscript.ps1')
  retentionInterval: 'P1D'
}

Você pode encontrar todas as propriedades do recurso deploymentScripts na documentação de referência do modelo do ARM.