Ações de inicialização

Ao criar um cluster do Dataproc, especifique ações de inicialização em executáveis ou scripts que o Dataproc executará em todos os nós do cluster do Dataproc logo depois da configuração do cluster. As ações de inicialização normalmente configuram dependências do job, como instalar pacotes do Python. Dessa maneira, os jobs podem ser enviados para o cluster sem a necessidade de instalar dependências quando os jobs são executados.

Verifique os locais a seguir para encontrar scripts de ação de inicialização usados com frequência e outros exemplos:

Considerações e diretrizes importantes

  • Não crie clusters de produção que façam referência a ações de inicialização localizadas em buckets públicos gs://goog-dataproc-initialization-actions-<REGION>>. Esses scripts são fornecidos como implementações de referência e são sincronizados com alterações do repositório do GitHub em andamento. Uma nova versão de uma ação de inicialização em buckets públicos pode interromper a criação do cluster. Em vez disso, copie a ação de inicialização dos buckets públicos para o bucket, conforme mostrado no exemplo a seguir:
    REGION=region
    
    gsutil cp gs://goog-dataproc-initialization-actions-${REGION}/presto/presto.sh gs://my-bucket/
    
    Em seguida, crie o cluster referenciando a cópia:
    gcloud dataproc clusters create cluster-name \
        --region=${REGION} \
        --initialization-actions=gs://my-bucket/presto.sh \
        ... other flags ...
    
    Você pode decidir quando sincronizar sua cópia da ação de inicialização com as alterações na ação de inicialização que ocorrem no bucket público ou no repositório do GitHub.
  • As ações de inicialização são executadas em cada nó durante a criação do cluster. Elas também são executados em cada nó adicionado recentemente ao fazer o escalonamento ou escalonamento automático do cluster.
  • As ações de inicialização são executadas como usuário root. Isso significa que **não** é necessário usar sudo.
  • Use caminhos absolutos nas ações de inicialização.
  • Suas ações de inicialização devem usar uma linha shebang para indicar como o script deve ser interpretado (por exemplo, #!/bin/bash ou #!/usr/bin/python).
  • Se uma ação de inicialização for encerrada com um código de saída diferente de zero, a operação de criação do cluster relatará um status "ERROR". Para depurar a ação de inicialização, execute o SSH nas instâncias de VM do cluster e examine os registros. Depois de corrigir o problema da ação de inicialização, exclua e recrie o cluster.
  • Se você criar um cluster do Dataproc apenas com endereços IP internos, as tentativas de acessar a Internet em uma ação de inicialização falharão, a menos que tenha configurado rotas para direcionar o tráfego por meio do Cloud NAT ou da Cloud VPN. Sem acesso à Internet, é possível ativar o Acesso privado do Google e colocar dependências de job no Cloud Storage. Os nós de cluster podem fazer o download das dependências do Cloud Storage de IPs internos.
  • É possível usar imagens personalizadas do Dataproc em vez de ações de inicialização para configurar as dependências do job.
  • Processamento de inicialização:
    • As ações de inicialização de nós mestres não são iniciadas até que o HDFS possa ser gravado (até que o HDFS saia do modo de segurança e pelo menos dois DataNodes HDFS entrem). Isso permite que ações de inicialização executadas em mestres gravem arquivos no HDFS.
    • Se a propriedade de cluster dataproc:dataproc.worker.custom.init.actions.mode=RUN_BEFORE_SERVICES for definida, cada worker executará as ações de inicialização antes de iniciar seu daemon do DataNode do HDFS. As ações de inicialização mestre não serão iniciadas até que pelo menos dois workers concluam as ações de inicialização, com um aumento provável no tempo de criação do cluster.
    • Em cada nó do cluster, várias ações de inicialização são executadas na ordem especificada no comando de criação do cluster. No entanto, as ações de inicialização em nós separados são processadas de maneira independente: as ações de inicialização do worker podem ser executadas simultaneamente, antes ou depois das ações de inicialização mestre.
    • Componentes opcionais selecionados por um usuário quando um cluster é criado são instalados e ativados em um cluster antes da execução das ações de inicialização no cluster.
    • Recomendações:
      • Use metadados para determinar o papel de um nó para executar condicionalmente uma ação de inicialização nos nós. Consulte Como usar metadados de cluster.
      • Bifurque uma cópia de uma ação de inicialização para um bucket do Cloud Storage para mais estabilidade. Consulte Como as ações de inicialização são usadas.
      • Adicione novas tentativas quando você fizer o download da Internet para ajudar a estabilizar a ação de inicialização.

Usar as ações de inicialização

É possível especificar ações de inicialização de cluster independentemente de como ele é criado:

Comando gcloud

Ao criar um cluster com o comando gcloud dataproc clusters create, especifique uma ou mais localizações, separadas por vírgulas, do Cloud Storage (URIs) dos arquivos de inicialização executáveis ou scripts com a sinalização --initialization-actions. Observação: vários "/"s consecutivos em um URI de local do Cloud Storage após o "gs://" inicial, como "gs://bucket/my//object//name", não são compatíveis.

A sintaxe para usar essa sinalização é mostrada abaixo, que pode ser visualizada a partir da linha de comando executando gcloud dataproc clusters create --help.

gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --initialization-actions=Cloud Storage URI(s) (gs://bucket/...) \
    --initialization-action-timeout=timeout-value (default=10m) \
    ... other flags ...
Observações:
  • Use a sinalização --initialization-action-timeout para especificar um período limite para a ação de inicialização. O valor de tempo limite padrão é 10 minutos. Se o executável ou o script de inicialização não tiver sido concluído até o final do tempo limite, o Dataproc cancelará a ação de inicialização.
  • Use a propriedade de cluster dataproc:dataproc.worker.custom.init.actions.mode para executar a ação de inicialização nos workers principais antes que o gerenciador de nós e os datanode daemons sejam inicializados.

API REST

Especifique um ou mais scripts NodeInitializationAction ou executáveis na matriz ClusterConfig.initializationActions como parte de uma solicitação de API clusters.create.

Exemplo

POST /v1/projects/my-project-id/regions/us-central1/clusters/
{
  "projectId": "my-project-id",
  "clusterName": "example-cluster",
  "config": {
    "configBucket": "",
    "gceClusterConfig": {
      "subnetworkUri": "default",
      "zoneUri": "us-central1-b"
    },
    "masterConfig": {
      "numInstances": 1,
      "machineTypeUri": "n1-standard-4",
      "diskConfig": {
        "bootDiskSizeGb": 500,
        "numLocalSsds": 0
      }
    },
    "workerConfig": {
      "numInstances": 2,
      "machineTypeUri": "n1-standard-4",
      "diskConfig": {
        "bootDiskSizeGb": 500,
        "numLocalSsds": 0
      }
    },
    "initializationActions": [
      {
        "executableFile": "gs://cloud-example-bucket/my-init-action.sh"
      }
    ]
  }
}

Console

Ao criar um cluster com o Console do Cloud, você pode especificar uma ou mais ações de inicialização no campo Initialization actions. Para ver esse campo, expanda o painel Opções avançadas.
Especifique os locais do Cloud Storage de cada ação de inicialização neste formulário. Clique em Procurar para abrir a página Navegador do Cloud Storage do Console do Cloud para selecionar um arquivo de inicialização. Cada arquivo de inicialização precisa ser especificado separadamente. Pressione <Enter> para adicionar uma nova entrada.

Como passar argumentos para ações de inicialização

O Dataproc define valores especiais de metadados para as instâncias executadas nos clusters. Defina os próprios metadados personalizados como uma maneira de passar argumentos para ações de inicialização.

gcloud dataproc clusters create cluster-name \
    --region=${REGION} \
    --initialization-actions=Cloud Storage URI(s) (gs://bucket/...) \
    --metadata=name1=value1,name2=value2... \
    ... other flags ...

Os valores de metadados podem ser lidos nas ações de inicialização da seguinte maneira:

var1=$(/usr/share/google/get_metadata_value attributes/name1)

Seleção de nós

Se você quiser limitar ações de inicialização a nós mestre ou de trabalho, será possível adicionar lógica simples de seleção de nós ao executável ou ao script.

ROLE=$(/usr/share/google/get_metadata_value attributes/dataproc-role)
if [[ "${ROLE}" == 'Master' ]]; then
  ... master specific actions ...
else
  ... worker specific actions ...
fi

Binários de preparo

Na inicialização de um cluster, é comum o teste de binários de job em um cluster para eliminar a necessidade de serem testados sempre que um job é enviado. Por exemplo, suponha que o seguinte script de inicialização esteja armazenado em gs://my-bucket/download-job-jar.sh, um local de bucket do Cloud Storage:

#!/bin/bash
ROLE=$(/usr/share/google/get_metadata_value attributes/dataproc-role)
if [[ "${ROLE}" == 'Master' ]]; then
  gsutil cp gs://my-bucket/jobs/sessionalize-logs-1.0.jar home/username
fi

A localização desse script pode ser passada para o comando gcloud dataproc clusters create:

gcloud dataproc clusters create my-dataproc-cluster \
    --region=${REGION} \
    --initialization-actions=gs://my-bucket/download-job-jar.sh

O Dataproc executará esse script em todos os nodes e, como consequência da lógica de seleção de node do script, fará o download do arquivo jar para o node mestre. Os jobs enviados podem usar o jar testado anteriormente:

gcloud dataproc jobs submit hadoop \
    --cluster=my-dataproc-cluster \
    --region=${REGION} \
    --jar=file:///home/username/sessionalize-logs-1.0.jar

Amostras de ações de inicialização

Os scripts de ações de inicialização mais usados e outros exemplos estão localizados em gs://goog-dataproc-initialization-actions-<REGION>, um intervalo público regional do Cloud Storage, e em um repositório do GitHub. Para contribuir com um script, revise o documento CONTRIBUTING.md e, em seguida, registre uma solicitação de envio.

Logging

A saída da execução de cada ação de inicialização é registrada para cada instância em /var/log/dataproc-initialization-script-X.log, onde X é o índice baseado em zero de cada script de ação de inicialização sucessivo. Por exemplo, se o cluster tiver duas ações de inicialização, as saídas serão registradas em /var/log/dataproc-initialization-script-0.log e /var/log/dataproc-initialization-script-1.log.

A seguir

Explore estas ações de inicialização: