Configurar o Dataproc Hub

---

Os notebooks gerenciados pelo usuário do Dataproc Hub e do Vertex AI Workbench foram descontinuados. Em 30 de janeiro de 2025, o suporte para notebooks gerenciados pelo usuário será encerrado, e a capacidade de criar instâncias de notebooks gerenciados pelo usuário será removida. Para soluções alternativas de notebook no Google Cloud, consulte:

• Instale o componente Jupyter no cluster do Dataproc.
• Crie uma instância do Vertex AI Workbench ativada para Dataproc.

O Dataproc Hub é um servidor JupyterHub personalizado. Os administradores configuram e criam instâncias do Dataproc Hub que podem gerar clusters do Dataproc de usuário único para hospedar ambientes de notebook Jupyter e JupyterLab (consulte Usar o Dataproc Hub).

Objetivos

1. Defina uma configuração de cluster do Dataproc ou use um dos arquivos de configuração predefinidos.

2. Definir variáveis de ambiente da instância do Dataproc Hub.

3. Crie uma instância do Dataproc Hub

Antes de começar

Se ainda não tiver feito isso, crie um projeto do Google Cloud e um bucket do Cloud Storage.

1. Como configurar o projeto

   1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

   2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

      Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

      Acessar o seletor de projetos

   3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

   4. Ative as APIs Dataproc, Compute Engine, and Cloud Storage.

      Ative as APIs

   5. Instale a CLI do Google Cloud.

   6. Para inicializar a CLI gcloud, execute o seguinte comando:

      gcloud init

   7. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

      Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

      Acessar o seletor de projetos

   8. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

   9. Ative as APIs Dataproc, Compute Engine, and Cloud Storage.

      Ative as APIs

   10. Instale a CLI do Google Cloud.

   11. Para inicializar a CLI gcloud, execute o seguinte comando:

       gcloud init

2. Como criar um bucket do Cloud Storage no projeto para armazenar os dados usados neste tutorial.

   1. No console do Cloud, acesse a página Buckets do Cloud Storage.

      Acessar a página "Buckets"

   2. Clique em Criar bucket.
   3. Na página Criar um bucket, insira as informações do seu bucket. Para ir à próxima etapa, clique em Continuar.
      • Em Nomear o bucket, insira um nome que atenda aos requisitos de nomenclatura de bucket.
      • Em Escolha um local para armazenar seus dados, faça o seguinte:
        • Selecione uma opção de Tipo de local.
        • Escolha uma opção de Local.
      • Em Escolher uma classe de armazenamento padrão para seus dados, selecione uma classe de armazenamento.
      • Em Escolha como controlar o acesso a objetos, selecione uma opção de Controle de acesso.
      • Em Configurações avançadas (opcional), especifique um método de criptografia, uma política de retenção ou rótulos de bucket.
   4. Clique em Criar.

Defina uma configuração de cluster

Uma instância do Dataproc Hub cria um cluster a partir de valores de configuração contidos em um arquivo de configuração de cluster YAML.

Configurações de cluster predefinidas: é possível usar os seguintes arquivos de configuração predefinidos, localizados no Cloud Storage:

• Configuração example-cluster: configura um cluster de componentes padrão do Jupyter com um nó mestre e dois nós de trabalho
• Configuração example-single-node: configura um cluster de componente Jupyter com um nó

Para visualizar esses arquivos de configuração públicos do Cloud Storage, execute:

gsutil cat gs://dataproc-spawner-dist/example-configs/example-cluster.yaml
gsutil cat gs://dataproc-spawner-dist/example-configs/example-single-node.yaml

Crie um hub de início rápido. Para criar um hub usando as configurações de cluster predefinidas, pule para Criar uma instância do Dataproc Hub. O local do Cloud Storage para as configurações de cluster predefinidas, listadas acima, é o valor padrão do campo da variável de ambiente DATAPROC_CONFIGS.

A configuração do cluster pode especificar qualquer recurso ou componente disponível para clusters do Dataproc (como tipo de máquina, ações de inicialização e componentes opcionais). A versão da imagem do cluster precisa ser 1.4.13 ou superior. A tentativa de gerar um cluster com uma versão de imagem anterior à 1.4.13 causará um erro e falhará.

Observação: os administradores podem permitir que os usuários modifiquem alguns dos parâmetros de configuração de cluster predefinidos. Consulte DATAPROC_ALLOW_CUSTOM_CLUSTERS em Definir valores de ambiente da instância do Dataproc Hub.

Amostra do arquivo de configuração do cluster YAML

clusterName: cluster-name
config:
  gceClusterConfig:
    metadata:
      'PIP_PACKAGES': 'google-cloud-core>=1.3.0 google-cloud-storage>=1.28.1'
  initializationActions:
  - executableFile: gs://dataproc-initialization-actions/python/pip-install.sh
  softwareConfig:
    imageVersion: 1.5-ubuntu18
    optionalComponents:
    - ANACONDA
    - JUPYTER

Cada configuração precisa ser salva no Cloud Storage. É possível criar e salvar vários arquivos de configuração para oferecer aos usuários uma opção quando eles usarem o Dataproc Hub para criar o ambiente de notebook do cluster do Dataproc.

Há duas maneiras de criar um arquivo de configuração de cluster YAML:

1. Crie um arquivo de configuração de cluster YAML no console

2. Exporte um arquivo de configuração de cluster YAML de um cluster existente

Crie um arquivo de configuração de cluster YAML no console

1. Abra a página Criar um cluster no console do Google Cloud, depois selecione e preencha os campos para especificar o tipo de cluster que o Dataproc Hub vai gerar para os usuários.
   As configurações de região e zona serão modificadas quando o cluster do usuário for gerado: a região do cluster gerado será a região em que o Dataproc Hub está localizado, e o usuário selecionará uma zona dentro dessa região.
   1. Na parte inferior do painel esquerdo, selecione "REST equivalente".
   2. Copie o bloco JSON gerado excluindo a linha de solicitação POST principal e cole o bloco JSON em um conversor online de JSON para YAML (pesquise "Converter JSON em YAML").
      Alguns conversores JSON para YAML geram uma primeira linha contendo "---". A inclusão dessa linha no arquivo YAML é opcional.
   3. Copie o YAML convertido em um arquivo cluster-config-filename .yaml local.

Exporte um arquivo de configuração de cluster YAML de um cluster existente

1. Crie um cluster que corresponda aos seus requisitos.
2. Exporte a configuração do cluster para um arquivo cluster-config-filename.yaml local.

   gcloud dataproc clusters export cluster-name \
       --destination cluster-config-filename.yaml  \
       --region region
    

Salve o arquivo de configuração YAML no Cloud Storage

Copie o arquivo de configuração do cluster YAML local para o bucket do Cloud Storage.

gsutil cp cluster-config-filename.yaml gs://bucket-name/

Defina variáveis de ambiente da instância do Dataproc Hub

O administrador pode definir as variáveis de ambiente do hub listadas na tabela abaixo para definir os atributos dos clusters do Dataproc que serão gerados pelos usuários do hub.

Observação: se as variáveis de ambiente de hub não estiverem definidas, o Dataproc vai usar valores padrão, incluindo a configuração de DATAPROC_CONFIGS para o local do Cloud Storage das configurações de cluster predefinidas. Veja Definir uma configuração de cluster.

Variável	Descrição	Exemplo
NOTEBOOKS_LOCATION	Bucket do Cloud Storage ou pasta do bucket que contém notebooks do usuário. O prefixo "gs://" é opcional. Padrão: o bucket de preparo do Dataproc	gs://bucket-name/
DATAPROC_CONFIGS	Lista delimitada por vírgulas de strings dos caminhos do Cloud Storage para arquivos de configuração do cluster YAML. O prefixo "gs://" é opcional. Padrão: gs://dataproc-spawner-dist/example-configs/. que contém example-cluster.yaml e example-single-node.yaml predefinidos.	gs://cluster-config-filename.yaml
DATAPROC_LOCATIONS_LIST	Sufixos de zona na região em que a instância do Dataproc Hub está localizada. Os usuários podem selecionar uma dessas zonas como a zona em que o cluster do Dataproc será gerado. Padrão: "b".	b,c,d
DATAPROC_DEFAULT_SUBNET	Sub-rede em que a instância do Dataproc Hub gerará clusters do Dataproc. Padrão: a sub-rede da instância do Dataproc Hub.	https://www.googleapis.com/compute/v1/projects/project-id/regions/region/subnetworks/subnet-name
DATAPROC_SERVICE_ACCOUNT	Conta de serviço em que as VMs do Dataproc serão executadas. Padrão: se não for definida, a conta de serviço padrão do Dataproc será usada.	[e-mail]
SPAWNER_DEFAULT_URL	Se a IU do Jupyter ou do JupyterLab será exibida em clusters gerados pelo Dataproc por padrão. Padrão: "/lab".	`/` ou `/lab`, para Jupyter ou JupyterLab, respectivamente.
DATAPROC_ALLOW_CUSTOM_CLUSTERS	Se os usuários podem personalizar os clusters do Dataproc. Padrão: falso.	"verdadeiro" ou "falso"
DATAPROC_MACHINE_TYPES_LIST	Lista de tipos de máquinas que os usuários podem escolher para os clusters gerados pelo Dataproc, se a personalização do cluster (DATAPROC_ALLOW_CUSTOM_CLUSTERS) estiver ativada. Padrão:vazio (todos os tipos de máquina são permitidos).	n1-standard-4,n1-standard-8,e2-standard-4,n1-highcpu-4
NOTEBOOKS_EXAMPLES_LOCATION	Caminho do Cloud Storage para o bucket de notebooks ou a pasta do bucket que será transferido por download para o cluster do Dataproc gerado quando o cluster for iniciado. Padrão:vazio.	gs://bucket-name/

Como definir variáveis de ambiente do hub

Há duas maneiras de definir variáveis de ambiente do hub:

1. Definir as variáveis de ambiente do hub no console

2. Definir as variáveis de ambiente do hub em um arquivo de texto

Definir variáveis de ambiente do hub no console

Ao criar uma instância do Dataproc Hub na guia Notebooks gerenciados pelo usuário na página Dataproc→Workbench no console do Google Cloud, clique no botão Preencher para abrir um formulário Preencher o hub do Dataproc que permite definir cada variável de ambiente.

Definir variáveis de ambiente do hub em um arquivo de texto

1. Crie o arquivo. É possível usar um editor de texto para definir variáveis de ambiente da instância do Dataproc Hub em um arquivo local. Como alternativa, crie o arquivo executando o seguinte comando depois de preencher os valores do marcador e alterar ou adicionar variáveis e seus valores.

   cat <<EOF > environment-variables-file
   DATAPROC_CONFIGS=gs://bucket/cluster-config-filename.yaml
   NOTEBOOKS_LOCATION=gs://bucket/notebooks
   DATAPROC_LOCATIONS_LIST=b,c
   EOF
   

2. Salve o arquivo no Cloud Storage. Copie o arquivo local de variáveis de ambiente da instância do Dataproc Hub para o bucket do Cloud Storage.

   gsutil cp environment-variable-filename gs://bucket-name/folder-name/
   

Definir papéis de gerenciamento de identidade e acesso (IAM, na sigla em inglês)

O Dataproc Hub inclui as seguintes identidades com as seguintes capacidades:

• Administrador: cria uma instância do Dataproc Hub
• Usuário de dados e ML: acessa a IU do Dataproc Hub
• Conta de serviço do Dataproc Hub: representa o Dataproc Hub
• Conta de serviço do Dataproc: representa o cluster do Dataproc que o Dataproc Hub cria.

Cada identidade requer papéis ou permissões específicas para realizar as tarefas associadas. A tabela abaixo resume os papéis e permissões do IAM exigidos por cada identidade.

Identidade	Tipo	Papel ou permissão
Administrador do Dataproc Hub	Usuário ou conta de serviço	roles/notebooks.admin
Usuário do Dataproc Hub	Usuário	notebooks.instances.use, dataproc.clusters.use
Dataproc Hub	Conta de serviço	roles/dataproc.hubAgent
Dataproc	Conta de serviço	roles/dataproc.worker

Por padrão, a instância do Dataproc Hub e os nós do cluster do Dataproc são executados como a conta de serviço padrão do Compute Engine do projeto.

Crie uma instância do Dataproc Hub

1. Antes de começar: para criar uma instância do Dataproc Hub no console do Google Cloud, sua conta de usuário precisa ter a permissão compute.instances.create. Além disso, a conta de serviço da instância, ou seja, a conta de serviço padrão do Compute Engine ou a conta de serviço especificada pelo usuário, listada em IAM e administrador > Contas de serviço, também precisa ter permissão. Veja Conta de serviço da VM do Dataprociam.serviceAccounts.actAs.

2. Acesse a página Dataproc→Workbench no console do Google Cloud e selecione a guia Notebooks gerenciados pelo usuário.

3. Se não estiver pré-selecionado como filtro, clique na caixa Filtro e selecione **Ambiente:Hub do Dataproc"".

4. Clique em Novo notebook→Dataproc Hub.

5. Na página Criar um notebook gerenciado pelo usuário, forneça as seguintes informações:

   1. Nome do notebook: nome da instância do Dataproc Hub.
   2. Região: selecione uma região para a instância do Dataproc Hub. Os clusters do Dataproc gerados por essa instância do Dataproc Hub também serão criados nessa região.
      Para um melhor desempenho, selecione uma região geograficamente próxima.
   3. Zona: selecione uma zona na região selecionada.
   4. Ambiente:
      1. Environment: selecione Dataproc Hub.
      2. Select a script to run after creation (opcional): é possível inserir ou procurar e selecionar um script ou executável de ação de inicialização para execução no cluster gerado pelo Dataproc.
      3. Populate Dataproc Hub (optional): clique em Preencher para abrir um formulário que permite definir cada uma das variáveis de ambiente do hub. Consulte Definir variáveis de ambiente da instância do Dataproc Hub para conferir a descrição de cada variável. O Dataproc usa valores padrão para qualquer variável de ambiente não definida. Como alternativa, você pode definir pares de key:value de metadados para definir variáveis de ambiente (consulte o próximo item).
      4. Metadata:
         1. Se você criou um arquivo de texto com as configurações da variável de ambiente de hub (consulte Como definir variáveis de ambiente de hub), forneça o nome do arquivo como key e o local do Cloud Storage gs://bucket-name/folder-name/environment-variable-filename do arquivo como value. O Dataproc usa valores padrão para todas as variáveis de ambiente não definidas.
   5. Configuração da máquina:
      1. Machine Type: selecione o tipo de máquina do Compute Engine.
      2. Defina outras opções de configuração de máquina.
   6. Outras opções:
      1. É possível expandir e definir ou substituir valores padrão nas seções Discos, Rede, Permissão, Segurança e Upgrade do ambiente e integridade do sistema.
   7. Clique em Criar para iniciar a instância do Dataproc Hub.

6. O link Abrir JupyterLab para a instância do Dataproc Hub fica ativo após a criação da instância. Os usuários clicam neste link para abrir a página do servidor do JupyterHub para configurar e criar um cluster JupyterLab do Dataproc (consulte Usar o Dataproc Hub).

Limpar

Excluir a instância do Dataproc Hub

• Para excluir a instância do Dataproc Hub:

  gcloud compute instances delete --project=${PROJECT} ${INSTANCE_NAME}
  

Excluir o bucket

• Para excluir o bucket do Cloud Storage criado em Antes de começar, incluindo os arquivos de dados armazenados no bucket:

  gsutil -m rm -r gs://${BUCKET_NAME}
  

A seguir

• Usar o Dataproc Hub