Personalização de clusters do HDInsight através de ações de script

Artigo
07/31/2023

O Azure HDInsight fornece um método de configuração chamado ações de script que chama scripts personalizados para personalizar o cluster. Esses scripts são usados para instalar componentes adicionais e alterar definições de configuração. Ações de script podem ser usadas durante ou após a criação do cluster.

Ações de script também podem ser publicadas no Azure Marketplace como um aplicativo do HDInsight. Para saber mais sobre aplicativos do HDInsight, confira Publicar um aplicativo do HDInsight no Azure Marketplace.

Noções básicas sobre ações de script

Uma ação de script é Bash script executado em nós em um cluster HDInsight. Estas são as características e os recursos das ações de script:

O URI do script bash (o local para acessar o arquivo) deve estar acessível do provedor de recursos do HDInsight e do cluster.
Estes são os possíveis locais de armazenamento:
- Para clusters regulares (não ESP):
  - Um blob em uma conta do Armazenamento do Azure que seja a conta de armazenamento principal ou adicional para o cluster do HDInsight. O HDInsight recebe acesso a ambos esses tipos de contas de armazenamento durante a criação do cluster.
    
    Importante
    
    Não gire a chave de armazenamento nesta conta de armazenamento do Azure, pois isso causará falhas em ações de script subsequentes com scripts armazenados ali.
  - Data Lake Storage Gen1: O principal de serviço que o HDInsight usa para acessar o Data Lake Storage deve ter acesso de leitura ao script. O formato de URI de script bash é adl://DATALAKESTOREACCOUNTNAME.azuredatalakestore.net/path_to_file.
  - Não é recomendável usar o Data Lake Storage Gen2 para ações de script. abfs:// não tem suporte para o URI de script bash. https:// Os URIs são possíveis, mas eles funcionam para contêineres que têm acesso público e o firewall aberto para o Provedor de Recursos do HDInsight e, portanto, não é recomendado.
  - Um serviço público de compartilhamento de arquivos acessível por meio de https:// caminhos. Alguns exemplos são Azure Blob, GitHub ou OneDrive. Para obter exemplos de URIs, confira Exemplos de ações de script.
- Para clusters com ESP, há suporte para os URIs wasb:// ou wasbs:// ou http[s]://.
As ações de script podem estar restritas à execução somente em determinados tipos de nó. Por exemplo, nós de cabeçalho ou nós de trabalho.
As ações de script podem ser persistentes ou ad hoc.
- As ações de script persistentes devem ter um nome exclusivo. Os scripts persistentes são usados para personalizar novos nós de trabalho adicionados ao cluster por meio de operações de escalonamento. Um script persistente também pode aplicar alterações a outro tipo de nó quando ocorrem operações de escalonamento. Um exemplo é um nó de cabeçalho.
- Scripts ad hoc não são persistentes. As ações de script usadas durante a criação do cluster são mantidas automaticamente. Eles não são aplicados a nós de trabalho adicionados ao cluster após o script ter sido executado. Então é possível promover posteriormente um script ad hoc a um script persistente ou rebaixar um script persistente a um script ad hoc. Os scripts que falham não são persistentes, mesmo que você indique especificamente que eles devem ser.
Ações de script podem aceitar parâmetros usados pelo script durante a execução.
Ações de script são executadas com os privilégios de nível de raiz nos nós de cluster.
As ações de script podem ser usadas por meio do portal do Azure, do Azure PowerShell, da CLI do Azure ou do SDK do .NET do HDInsight.
Ações de script que removem ou modificam arquivos de serviço na VM podem afetar a integridade e a disponibilidade do serviço.

O cluster mantém um histórico de todos os scripts que foram executados. O histórico é útil quando você precisa localizar a ID de um script para operações de promoção ou rebaixamento.

Importante

Não há nenhuma forma automática de desfazer as alterações feitas por uma ação de script. Reverta manualmente as alterações ou forneça um script que as reverta.

Permissões

Para um cluster do HDInsight associado a domínio, há duas permissões Apache Ambari necessárias ao usar ações de script com o cluster:

AMBARI.RUN_CUSTOM_COMMAND. Função de administrador de Ambari tem essa permissão por padrão.
CLUSTER.RUN_CUSTOM_COMMAND. O administrador de Cluster HDInsight e administrador de Ambari têm essa permissão por padrão.

Para saber mais sobre como trabalhar com permissões com o HDInsight associado a um domínio, confira Gerenciar clusters do HDInsight com o Enterprise Security Package.

Controle de acesso

Se você não é o proprietário ou administrador da sua assinatura do Azure, sua conta deve ter pelo menos Contributor acesso ao grupo de recursos que contém o cluster do HDInsight.

Alguém com no mínimo acesso de Colaborador à assinatura do Azure deve ter registrado anteriormente o provedor. O registro do provedor acontece quando um usuário com acesso de Colaborador à assinatura cria um recurso nela pela primeira vez. Para não criar um recurso, veja registrar um provedor usando REST.

Saiba mais sobre como trabalhar com o gerenciamento de acesso:

Métodos para usar ações de script

Você tem a opção de configurar uma ação de script para ser executada quando o cluster é criado pela primeira vez, ou executá-lo em um cluster existente.

Ação de script no processo de criação do cluster

As ações de script usadas durante a criação do cluster são ligeiramente diferentes das ações de script executadas em um cluster existente:

O script é automaticamente persistente.
Uma falha no script pode causar falha no processo de criação do cluster.

O seguinte diagrama ilustra quando a ação de script é executada durante o processo de criação:

Stages during cluster creation.

O script é executado enquanto o HDInsight está sendo configurado. O script é executado em paralelo com todos os nós especificados no cluster. Ele é executado com privilégios de raiz nos nós.

Você pode executar operações como parar e iniciar serviços, incluindo serviços relacionados ao Apache Hadoop. Se você interromper quaisquer serviços, você deve garantir que o serviço do Ambari e outros serviços relacionados ao Hadoop estejam funcionando antes da conclusão do script. Esses serviços são necessários para determinar com êxito a integridade e o estado do cluster enquanto ele está sendo criado.

Durante a criação do cluster, você pode usar várias ações de script simultaneamente. Esses scripts são invocados na ordem em que eles foram especificados.

Observação

Se o script estiver presente em qualquer outra conta de armazenamento diferente da especificada como armazenamento de cluster (no momento da criação do cluster), será necessário um acesso público.

Importante

As ações de script devem ser concluídas dentro de 60 minutos, ou elas vão expirar. Durante o provisionamento do cluster, o script é executado simultaneamente com outros processos de instalação e configuração. A competição por recursos, como tempo de CPU ou largura de banda da rede, pode fazer com que o script demore mais para concluir em comparação ao tempo de conclusão no seu ambiente de desenvolvimento.

Para minimizar o tempo necessário de execução do script, evite tarefas como baixar e compilar aplicativos da fonte. Pré-compile aplicativos e armazene o binário no Armazenamento do Azure.

Ação de script em um cluster em execução

Uma falha em um script executado em um cluster já em execução não faz com que o cluster mude automaticamente para um estado de falha. Quando um script é concluído, o cluster deve retornar a um estado em execução. Mesmo que o cluster esteja em um estado em execução, o script com falha pode apresentar problemas. Por exemplo, um script pode excluir arquivos necessários para o cluster.

Ações de scripts executados com privilégios de raiz. Tenha certeza de que entendeu a função de um script antes de aplicá-lo ao seu cluster.

Quando você aplica um script a um cluster, o estado do cluster muda de Em execução para Aceito. Em seguida, ele é alterado para Configuração do HDInsight e, por fim, de volta para Em execução, no caso de scripts bem-sucedidos. O status do script é registrado no histórico de ação de script. Essa informação indica se o script teve êxito ou falha. Por exemplo, o cmdlet Get-AzHDInsightScriptActionHistory do PowerShell exibe o status de um script. Isso retorna informações semelhantes ao seguinte texto:

ScriptExecutionId : 635918532516474303
StartTime         : 8/14/2017 7:40:55 PM
EndTime           : 8/14/2017 7:41:05 PM
Status            : Succeeded

Importante

Se você alterar a senha do usuário (admin) do cluster após sua criação, as ações de script executadas nesse cluster podem falhar. Se houver ações de script persistente direcionadas para nós de trabalho, esses scripts poderão falhar quando você dimensionar o cluster.

Scripts de ação do de exemplo de script

Scripts de ação de script podem ser usados por meio dos utilitários a seguir:

Portal do Azure
Azure PowerShell
CLI do Azure
SDK do .NET do HDInsight

O HDInsight fornece scripts para instalar os seguintes componentes nos clusters do HDInsight:

Nome	Script
Adicionar uma conta de Armazenamento do Azure	`https://hdiconfigactions.blob.core.windows.net/linuxaddstorageaccountv01/add-storage-account-v01.sh`. Confira Adicionar outras contas de armazenamento ao HDInsight.
Instalar o Hue	`https://hdiconfigactions.blob.core.windows.net/linuxhueconfigactionv02/install-hue-uber-v02.sh`. Confira Instalar e usar o Hue em clusters Hadoop do HDInsight.
Pré-carregar bibliotecas Hive	`https://hdiconfigactions.blob.core.windows.net/linuxsetupcustomhivelibsv01/setup-customhivelibs-v01.sh`. Confira Adicionar bibliotecas Apache Hive personalizadas ao criar seu cluster do HDInsight.

Usar uma ação de script durante a criação do cluster

Esta seção explica as diferentes maneiras de usar ações de script ao criar um cluster do HDInsight.

Usar uma ação de script durante a criação do cluster no portal do Azure

Comece a criar o cluster conforme descrito em Criar clusters baseados em Linux no HDInsight usando o portal do Azure. Na guia Configuração + preço, selecione + Adicionar ação de script.

Use a entrada Selecionar um script para escolher um script criado previamente. Para usar um script personalizado, selecione Personalizado. Em seguida, forneça o Nome e o URI do script de bash para o seu script.

Add a script in the select script form.

A tabela a seguir descreve os elementos no formulário:

Propriedade	Valor
Selecionar um script	Para usar seu próprio script, selecione Personalizado. Caso contrário, selecione um dos scripts fornecidos.
Nome	Especifique um nome para a ação de script.
URI do script Bash	Especificar o URI do script.
Cabeçalho/Trabalho/Zookeeper	Especifique os nós nos quais o script é executado: Cabeçalho, Trabalho ou ZooKeeper.
Parâmetros	Especifique os parâmetros, se exigido pelo script.

Use a entrada Persista essa ação de script para garantir que o script seja aplicado durante operações de escalonamento.

Selecione Criar para salvar o script. Posteriormente, você pode usar + Enviar novo para adicionar outro script.

Quando você terminar de adicionar scripts, retorne à guia Configuração + preço.
Conclua as etapas de criação de cluster restantes como de costume.

Usar uma ação de script em modelos do Azure Resource Manager

Ações de script podem ser usadas com modelos do Azure Resource Manager. Por exemplo, confira Criar cluster Linux do HDInsight e executar uma ação de script.

Neste exemplo, a ação de script é adicionada usando o seguinte código:

"scriptActions": [
    {
        "name": "setenvironmentvariable",
        "uri": "[parameters('scriptActionUri')]",
        "parameters": "headnode"
    }
]

Saiba mais sobre como implantar um modelo:

Usar uma ação de script durante a criação do cluster no Azure PowerShell

Nesta seção, você usará o cmdlet Add-AzHDInsightScriptAction para chamar scripts para personalizar um cluster. Antes de começar, instale e configure o Azure PowerShell. Para usar esses comandos do PowerShell, você precisa do Módulo AZ.

O seguinte script mostra como aplicar uma ação de script ao criar um cluster usando o PowerShell:

# Login to your Azure subscription
$context = Get-AzContext
if ($context -eq $null) 
{
    Connect-AzAccount
}
$context

# If you have multiple subscriptions, set the one to use
# $subscriptionID = "<subscription ID to use>"
# Select-AzSubscription -SubscriptionId $subscriptionID

# Get user input/default values
$resourceGroupName = Read-Host -Prompt "Enter the resource group name"
$location = Read-Host -Prompt "Enter the Azure region to create resources in"

# Create the resource group
New-AzResourceGroup -Name $resourceGroupName -Location $location

$defaultStorageAccountName = Read-Host -Prompt "Enter the name of the storage account"

# Create an Azure storae account and container
New-AzStorageAccount `
    -ResourceGroupName $resourceGroupName `
    -Name $defaultStorageAccountName `
    -Type Standard_LRS `
    -Location $location
$defaultStorageAccountKey = (Get-AzStorageAccountKey `
                                -ResourceGroupName $resourceGroupName `
                                -Name $defaultStorageAccountName)[0].Value
$defaultStorageContext = New-AzStorageContext `
                                -StorageAccountName $defaultStorageAccountName `
                                -StorageAccountKey $defaultStorageAccountKey

# Get information for the HDInsight cluster
$clusterName = Read-Host -Prompt "Enter the name of the HDInsight cluster"
# Cluster login is used to secure HTTPS services hosted on the cluster
$httpCredential = Get-Credential -Message "Enter Cluster login credentials" -UserName "admin"
# SSH user is used to remotely connect to the cluster using SSH clients
$sshCredential = Get-Credential -Message "Enter SSH user credentials"

# Default cluster size (# of worker nodes), version, type, and OS
$clusterSizeInNodes = "4"
$clusterVersion = "3.5"
$clusterType = "Hadoop"
$clusterOS = "Linux"
# Set the storage container name to the cluster name
$defaultBlobContainerName = $clusterName

# Create a blob container. This holds the default data store for the cluster.
New-AzStorageContainer `
    -Name $clusterName -Context $defaultStorageContext

# Create an HDInsight configuration object
$config = New-AzHDInsightClusterConfig
# Add the script action
$scriptActionUri="https://hdiconfigactions.blob.core.windows.net/linuxgiraphconfigactionv01/giraph-installer-v01.sh"
# Add for the head nodes
$config = Add-AzHDInsightScriptAction `
    -Config $config `
    -Name "Install Giraph" `
    -NodeType HeadNode `
    -Uri $scriptActionUri
# Continue adding the script action for any other node types
# that it must run on.
$config = Add-AzHDInsightScriptAction `
    -Config $config `
    -Name "Install Giraph" `
    -NodeType WorkerNode `
    -Uri $scriptActionUri

# Create the cluster using the configuration object
New-AzHDInsightCluster `
    -Config $config `
    -ResourceGroupName $resourceGroupName `
    -ClusterName $clusterName `
    -Location $location `
    -ClusterSizeInNodes $clusterSizeInNodes `
    -ClusterType $clusterType `
    -OSType $clusterOS `
    -Version $clusterVersion `
    -HttpCredential $httpCredential `
    -DefaultStorageAccountName "$defaultStorageAccountName.blob.core.windows.net" `
    -DefaultStorageAccountKey $defaultStorageAccountKey `
    -DefaultStorageContainer $containerName `
    -SshCredential $sshCredential

Pode levar alguns minutos até que o cluster seja criado.

Usar uma ação de script durante a criação do cluster no SDK do .NET do HDInsight

O SDK .NET do HDInsight fornece bibliotecas de cliente que facilitam o trabalho com o HDInsight por meio de um aplicativo .NET. Para obter um exemplo de código, consulte Ações de Script.

Ação de script para um cluster em execução

Esta seção explica como aplicar ações de script a um cluster em execução.

Aplicar uma ação de script em um cluster em execução no portal do Azure

Faça logon no Portal do Azure e localize o seu cluster.
Na exibição padrão, sob Configurações, selecione Ações de script.
Na parte superior da página Ações de script, selecione + Enviar novas.

Add a script in the select script form.

A tabela a seguir descreve os elementos no formulário:

Propriedade	Valor
Selecionar um script	Para usar seu próprio script, selecione personalizado. Caso contrário, selecione um script fornecido.
Nome	Especifique um nome para a ação de script.
URI do script Bash	Especificar o URI do script.
Cabeçalho/Trabalho/Zookeeper	Especifique os nós nos quais o script é executado: Cabeçalho, Trabalho ou ZooKeeper.
Parâmetros	Especifique os parâmetros, se exigido pelo script.

Use a entrada Persistir essa ação de script para garantir que o script seja aplicado durante operações de colocação em escala.

Por fim, selecione o botão Criar para aplicar o script ao cluster.

Aplicar uma ação de script em um cluster em execução no Azure PowerShell

Para usar esses comandos do PowerShell, você precisa do Módulo AZ. O seguinte exemplo mostra como aplicar uma ação de script a um cluster em execução:

# Get information for the HDInsight cluster
$clusterName = Read-Host -Prompt "Enter the name of the HDInsight cluster"
$scriptActionName = Read-Host -Prompt "Enter the name of the script action"
$scriptActionUri = Read-Host -Prompt "Enter the URI of the script action"
# The node types that the script action is applied to
$nodeTypes = "headnode", "workernode"

# Apply the script and mark as persistent
Submit-AzHDInsightScriptAction -ClusterName $clusterName `
    -Name $scriptActionName `
    -Uri $scriptActionUri `
    -NodeTypes $nodeTypes `
    -PersistOnSuccess

Após a conclusão da operação, você receberá informações semelhantes ao seguinte texto:

OperationState  : Succeeded
ErrorMessage    :
Name            : Giraph
Uri             : https://hdiconfigactions.blob.core.windows.net/linuxgiraphconfigactionv01/giraph-installer-v01.sh
Parameters      :
NodeTypes       : {HeadNode, WorkerNode}

Aplicar uma ação de script em um cluster em execução da CLI do Azure

Antes de começar, instale e configure a CLI do Azure. Verifique se você tem a versão mais recente. Para obter mais informações, consulte Instalar a CLI do Azure.

Autentique-se na assinatura do Azure:
```
az login
```
Aplique uma ação de script a um cluster em execução:
```
az hdinsight script-action execute --cluster-name CLUSTERNAME --name SCRIPTNAME --resource-group RESOURCEGROUP --roles ROLES
```
As funções válidas são headnode, workernode, zookeepernode, edgenode. Caso o script deva ser aplicado a vários tipos de nós, separe as funções usando um espaço. Por exemplo, --roles headnode workernode.

Para persistir o script, adicione --persist-on-success. Também é possível persistir o script posteriormente usando az hdinsight script-action promote.

Aplicar uma ação de script a um cluster em execução usando a API REST

Confira API REST de cluster no Azure HDInsight.

Aplicar uma ação de script a um cluster em execução no SDK do .NET do HDInsight

Para obter um exemplo de como usar o SDK .NET para aplicar scripts a um cluster, confira Aplicar uma ação de script a um cluster do HDInsight baseado em Linux em execução.

Exibir o histórico, promover e rebaixar ações de script

O portal do Azure

Faça logon no Portal do Azure e localize o seu cluster.
Na exibição padrão, sob Configurações, selecione Ações de script.
Um histórico de scripts para esse cluster é exibido na seção de ações de script. Essas informações incluem uma lista de scripts persistentes. A captura de tela a seguir mostra que o script Solr foi executado nesse cluster. A captura de tela não mostra scripts persistentes.
Selecione um script do histórico para exibir a seção Propriedades desse script. Na parte superior da tela, é possível executar novamente o script ou promovê-lo.
Também é possível usar as reticências, … , à direita das entradas na seção de ações de script para executar ações.

PowerShell do Azure

cmdlet	Função
`Get-AzHDInsightPersistedScriptAction`	Recuperar informações sobre as ações de script persistentes. Esse cmdlet não desfaz as ações executadas por um script, apenas remove o sinalizador de persistente.
`Get-AzHDInsightScriptActionHistory`	Recuperar um histórico das ações de script aplicadas no cluster ou detalhes de um script específico.
`Set-AzHDInsightPersistedScriptAction`	Promover uma `ad hoc` ação de script para uma ação de script persistente.
`Remove-AzHDInsightPersistedScriptAction`	Rebaixar uma ação de script persistente a uma ação `ad hoc`.

O exemplo de script a seguir demonstra como usar os cmdlets para promover e depois rebaixar um script.

# Get a history of scripts
Get-AzHDInsightScriptActionHistory -ClusterName mycluster

# From the list, we want to get information on a specific script
Get-AzHDInsightScriptActionHistory -ClusterName mycluster `
    -ScriptExecutionId 635920937765978529

# Promote this to a persisted script
# Note: the script must have a unique name to be promoted
# if the name is not unique, you receive an error
Set-AzHDInsightPersistedScriptAction -ClusterName mycluster `
    -ScriptExecutionId 635920937765978529

# Demote the script back to ad hoc
# Note that demotion uses the unique script name instead of
# execution ID.
Remove-AzHDInsightPersistedScriptAction -ClusterName mycluster `
    -Name "Install Giraph"

CLI do Azure

Comando	Descrição
`az hdinsight script-action delete`	Exclui uma ação de script persistente especificada do cluster. Esse comando não desfaz as ações executadas por um script, apenas remove o sinalizador de persistente.
`az hdinsight script-action execute`	Execute ações de script no cluster HDInsight especificado.
`az hdinsight script-action list`	Lista todas as ações de script persistentes para o cluster especificado.
`az hdinsight script-action list-execution-history`	Lista o histórico de execução de todos os scripts para o cluster especificado.
`az hdinsight script-action promote`	Promove a execução do script ad hoc especificado a um script persistente.
`az hdinsight script-action show-execution-details`	Obtém os detalhes de execução de script para a ID de execução de script fornecida.

SDK do .NET do HDInsight

Para obter um exemplo de como usar o SDK .NET para recuperar o histórico de scripts de um cluster, promover ou rebaixar scripts, confira Aplicar uma Ação de Script em um cluster do HDInsight baseado em Linux em execução.

Observação

Este exemplo também demonstra como instalar um aplicativo do HDInsight usando o SDK .NET.

Personalização de clusters do HDInsight através de ações de script

Noções básicas sobre ações de script

Permissões

Controle de acesso

Métodos para usar ações de script

Ação de script no processo de criação do cluster

Ação de script em um cluster em execução

Scripts de ação do de exemplo de script

Usar uma ação de script durante a criação do cluster

Usar uma ação de script durante a criação do cluster no portal do Azure

Usar uma ação de script em modelos do Azure Resource Manager

Usar uma ação de script durante a criação do cluster no Azure PowerShell

Usar uma ação de script durante a criação do cluster no SDK do .NET do HDInsight

Ação de script para um cluster em execução

Aplicar uma ação de script em um cluster em execução no portal do Azure

Aplicar uma ação de script em um cluster em execução no Azure PowerShell

Aplicar uma ação de script em um cluster em execução da CLI do Azure

Aplicar uma ação de script a um cluster em execução usando a API REST

Aplicar uma ação de script a um cluster em execução no SDK do .NET do HDInsight

Exibir o histórico, promover e rebaixar ações de script

O portal do Azure

PowerShell do Azure

CLI do Azure

SDK do .NET do HDInsight

Próximas etapas

Recursos adicionais