Configurar o Dataproc Hub

O Dataproc Hub e os notebooks gerenciados pelo usuário do Vertex AI Workbench foram descontinuados. Em 30 de janeiro de 2025, o suporte a notebooks gerenciados pelo usuário será encerrado, e não será mais possível criar instâncias de notebooks gerenciados pelo usuário. Para soluções alternativas de notebook em 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).

Iniciar notebooks para vários usuários. É possível criar uma instância do Vertex AI Workbench compatível com o Dataproc ou instalar o plug-in JupyterLab do Dataproc em uma VM para disponibilizar notebooks a vários usuários.

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:

gcloud storage cat gs://dataproc-spawner-dist/example-configs/example-cluster.yaml
gcloud storage 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 substituam alguns dos parâmetros de configuração de cluster predefinidos. Para mais informações, 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:
  softwareConfig:
    imageVersion: 2.2-ubuntu22
    optionalComponents:
    - 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 e selecione e preencha os campos para especificar o tipo de cluster que será gerado pelo Dataproc Hub 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 yaml cluster-config-filename 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.

gcloud storage 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 a ser baixada 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 da página Dataproc→Workbench no console do Google Cloud , clique no botão Preencher para abrir um formulário Preencher o Dataproc Hub 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.

   gcloud storage 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 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 (consulte Conta de serviço da VM do Dataproc), precisa ter permissão de iam.serviceAccounts.actAs.

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

3. Se não estiver pré-selecionado como um 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 ser executado no cluster do Dataproc gerado.
      3. Populate Dataproc Hub (optional): clique em Populate 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 uma descrição de cada variável). O Dataproc usa valores padrão para variáveis de ambiente não definidas. Como alternativa, é possível definir pares Metadados key:value para definir variáveis de ambiente (consulte o próximo item).
      4. Metadata:
         1. Se você criou um arquivo de texto que contém as configurações variável de ambiente do hub (consulte Como definir variáveis de ambiente do hub), forneça o nome do arquivo como key e o local do arquivo no Cloud Storage como gs://bucket-name/folder-name/environment-variable-filename.value O Dataproc usa valores padrão para 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 os 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 da instância do Dataproc Hub fica ativo depois que a instância é criada. Os usuários clicam nesse link para abrir a página do servidor JupyterHub e configurar e criar um cluster do Dataproc JupyterLab (consulte Usar o Dataproc Hub).