Ações de inicialização

Ao criar um cluster do Serviço Gerenciado para Apache Spark, é possível especificar ações de inicialização em executáveis ou scripts que o Serviço Gerenciado para Apache Spark vai executar em todos os nós do cluster imediatamente após a 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.

Confira exemplos de scripts de ação de inicialização nos seguintes locais: Observação: o Google não oferece suporte a esses 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 nos buckets públicos gs://goog-dataproc-initialization-actions-REGION. Esses scripts são fornecidos como implementações de referência. Eles são sincronizados com as mudanças em andamento no repositório do GitHub, e as atualizações desses scripts podem interromper a criação do cluster. Em vez disso, copie a ação de inicialização do bucket público para uma pasta de bucket do Cloud Storage com controle de versões, conforme mostrado no exemplo a seguir: 

    REGION=COMPUTE_REGION
gcloud storage cp gs://goog-dataproc-initialization-actions-${REGION}/cloud-sql-proxy/cloud-sql-proxy.sh \
    gs://my-bucket/cloud-sql-proxy/v1.0/cloud-sql-proxy.sh
    Em seguida, crie o cluster referenciando a cópia no Cloud Storage: 
    gcloud dataproc clusters create CLUSTER_NAME \
    --region=${REGION} \
    --initialization-actions=gs://my-bucket/cloud-sql-proxy/v1.0/cloud-sql-proxy.sh \
    ...other flags...

  • As ações de inicialização são executadas em cada nó em série durante a criação do cluster. Eles também são executados em cada nó adicionado ao escalonar ou escalonar automaticamente clusters.

  • Ao atualizar as ações de inicialização, por exemplo, ao sincronizar as ações de inicialização do Cloud Storage com as alterações feitas nas ações de inicialização do bucket público ou do repositório do GitHub, crie uma nova pasta (preferencialmente com o nome da versão) para receber as ações de inicialização atualizadas. Se, em vez disso, você atualizar a ação de inicialização no local, os novos nós, como aqueles adicionados pelo escalonador automático, executarão a ação de inicialização atualizada no local, não a ação de inicialização da versão anterior que foi executada nos nós existentes. Essas diferenças podem resultar em nós de cluster inconsistentes ou com falhas.

  • As ações de inicialização são executadas como usuário root. Não é necessário usar sudo.

  • Use caminhos absolutos em ações de inicialização.

  • Use uma linha shebang nas ações de inicialização para indicar como o script precisa ser interpretado (como #!/bin/bash ou #!/usr/bin/python).

  • Use terminações de linha no estilo Unix (LF) em ações de inicialização. Se você criar ações de inicialização no Windows, elas poderão conter finais de linha no estilo do Windows (CRLF), o que pode causar falhas na execução do script.

  • 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, use SSH para se conectar às instâncias de VM do cluster e, em seguida, 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 Serviço Gerenciado para Apache Spark com apenas endereços IP internos, as tentativas de acessar o github.com pela internet em uma ação de inicialização vão falhar, a menos que você tenha configurado rotas para direcionar o tráfego pelo Cloud NAT ou por uma Cloud VPN. Sem acesso à Internet, é possível ativar o Acesso privado do Google e colocar as dependências de jobs no Cloud Storage. Os nós do cluster podem fazer o download das dependências do Cloud Storage de IPs internos.

  • É possível usar imagens personalizadas do Serviço Gerenciado para Apache Spark em vez de ações de inicialização para configurar dependências de jobs.

  • Processamento de inicialização:

    • Clusters de imagem anteriores à 2.0:
      • Mestre: para permitir que as ações de inicialização executadas em mestres gravem arquivos no HDFS, as ações de inicialização do nó mestre não são iniciadas até que o HDFS seja gravável (até que o HDFS tenha saído do modo de segurança e pelo menos dois DataNodes do HDFS tenham ingressado).
      • Worker: se você definir a dataproc:dataproc.worker.custom.init.actions.mode propriedade do cluster como RUN_BEFORE_SERVICES, cada worker executará as ações de inicialização antes de iniciar os daemons do datanode do HDFS e do nodemanager do YARN. Como o Serviço Gerenciado para Apache Spark não executa ações de inicialização mestre até que o HDFS seja gravável, o que requer a execução de dois daemons de nó de dados do HDFS, a definição dessa propriedade pode aumentar o tempo de criação do cluster.

    • Clusters de imagem 2.0+:

      • Mestre: as ações de inicialização do nó mestre podem ser executadas antes do HDFS ser gravável. Se você executar ações de inicialização que organizem arquivos no HDFS ou dependam da disponibilidade de serviços dependentes do HDFS, como o Ranger, defina a propriedade de cluster {dataproc.master.custom.init.actions.mode} 101}para RUN_AFTER_SERVICES. Observação: como essa configuração de propriedade pode aumentar o tempo de criação do cluster, consulte a explicação sobre o atraso na criação do cluster para workers de cluster de imagem anteriores à versão 2.0. Use-a apenas quando necessário (como prática geral, use a configuração padrão RUN_BEFORE_SERVICES para essa propriedade).
      • Worker: a propriedade do cluster dataproc:dataproc.worker.custom.init.actions.mode está definida como RUN_BEFORE_SERVICES e não pode ser transmitida ao cluster quando ele é criado (não é possível alterar a configuração da propriedade). Cada worker executa as ações de inicialização antes de iniciar o datanode HDFS e os daemons do nodenode YARN. Como o Serviço Gerenciado para Apache Spark não espera que o HDFS seja gravável antes de executar as ações de inicialização mestre, as ações de inicialização mestre e de worker são executadas em paralelo.

    • 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 ao fazer o download da Internet para ajudar a estabilizar a ação de inicialização.

Usar ações de inicialização

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

Console doGoogle Cloud

  • Abra a página Criar cluster.
  • Clique em Configuração adicional para abrir a seção.
  • Edite Personalização e outros.
  • No painel que será aberto, clique em Adicionar ações de inicialização e insira ou procure o local do Cloud Storage de uma ação de inicialização.

    • CLI da gcloud

    Ao criar um cluster com o comando gcloud dataproc clusters create, especifique um ou mais locais (URIs) do Cloud Storage separados por vírgulas dos executáveis ou scripts de inicialização com a flag --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. Execute gcloud dataproc clusters create --help para ver informações sobre o comando.

    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 script de inicialização não for concluído até o final do período de tempo limite, o Serviço Gerenciado para Apache Spark 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 em workers primários antes que os daemons do gerenciador de nós e do datanode sejam iniciados.

    API REST

    Especifique um ou mais scripts ou executáveis em uma 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"
      }
    ]
  }
}

    Transmitir argumentos para ações de inicialização

    O Serviço Gerenciado para Apache Spark define valores de metadados especiais 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 as ações de inicialização aos nós mestre, de driver ou de trabalho, adicione a lógica de seleção de nós ao executável ou script.

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

    Preparar binários

    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 script de inicialização a seguir 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
  gcloud storage 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 Serviço Gerenciado para Apache Spark vai executar esse script em todos os nós e, como consequência da lógica de seleção de nós do script, vai fazer o download do jar para o nó 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 de amostra e outros usados com frequência estão localizados em gs://goog-dataproc-initialization-actions-<REGION>, um bucket regional público do Cloud Storage, e em um repositório do GitHub. Para contribuir com um script, consulte o documento CONTRIBUTING.md e envie 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

    Conheça as ações de inicialização do GitHub.