Criar uma imagem personalizada do Dataproc

É possível criar um cluster do Dataproc com uma imagem personalizada que inclui os pacotes pré-instalados. Esta página mostra como criar uma imagem personalizada e instalá-la em um cluster do Dataproc.

Considerações e limitações de uso

  • Tempo de vida da imagem personalizada:para garantir que os clusters recebam as atualizações de serviços e correções de bugs mais recentes, a criação de clusters com uma imagem personalizada é limitada a 365 dias a partir da data de criação da imagem personalizada. Os clusters criados com uma imagem personalizada podem ser executados indefinidamente.

    Talvez você precise usar a automação se quiser criar clusters com uma imagem personalizada específica por um período maior que 365 dias. Para mais informações, consulte Como criar um cluster com uma imagem personalizada expirada.

  • Somente Linux:as instruções neste documento se aplicam apenas a sistemas operacionais Linux. Outros sistemas operacionais poderão ser compatíveis com versões futuras do Dataproc.

  • Imagens de base compatíveis:as criações de imagens personalizadas exigem uma imagem de base do Dataproc. As seguintes imagens de base são compatíveis: Debian, Rocky Linux e Ubuntu.

    • Disponibilidade da imagem de base: novas imagens anunciadas nas Notas de lançamento do Dataproc não estão disponíveis para uso como base para imagens personalizadas até que uma delas seja: a partir da data do anúncio.

  • Uso de componentes opcionais:por padrão, as imagens personalizadas herdam todos os componentes opcionais do Dataproc (pacotes e configurações do SO) das imagens de base. É possível personalizar as versões e configurações padrão do pacote do SO, mas é necessário especificar o nome do componente opcional ao criar o cluster.

    Exemplo de comando de criação de cluster: 

    gcloud dataproc clusters create --optional-components=COMPONENT_NAME \
    --image=CUSTOM_IMAGE_URI  \
     ... other flags

    Se o nome do componente não for especificado ao criar o cluster, o componente opcional, incluindo configurações e pacotes personalizados do SO, será excluído.

  • Como usar imagens personalizadas hospedadas:se você usa uma imagem personalizada hospedada em outro projeto, a conta de serviço do agente de serviço do Dataproc no seu projeto precisa ter a permissão compute.images.get na imagem no projeto host. Para isso, conceda o papel roles/compute.imageUser na imagem hospedada à conta de serviço do agente de serviço do Dataproc do seu projeto. Consulte Como compartilhar imagens personalizadas em uma organização.

  • Usar segredos de MOK (chave do proprietário da máquina) de inicialização segura:para ativar a inicialização segura com sua imagem personalizada do Dataproc, faça o seguinte:

    1. Ative a API Secret Manager (secretmanager.googleapis.com). O Dataproc gera e gerencia um par de chaves usando o serviço Secret Manager.

    2. Adicione a flag --service-account="SERVICE_ACCOUNT" ao comando generate_custom_image.py quando você gerar uma imagem personalizada. Observação: é necessário conceder à conta de serviço o papel de leitor do Secret Manager (roles/secretmanager.viewer) no projeto e o papel de acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) nos secrets públicos e privados.

      Para mais informações com exemplos, consulte o README.md e outros arquivos no diretório examples/secure-boot do repositório GoogleCloudDataproc/custom-images no GitHub.

      Para desativar a inicialização segura:por padrão, os scripts de imagem personalizada do Dataproc geram e gerenciam um par de chaves usando o Secret Manager quando executados em um cluster do Dataproc. Se você não quiser usar o Secure Boot com a imagem personalizada, inclua --trusted-cert="" (valor de flag vazio) no comando generate_custom_image.py ao gerar a imagem personalizada.

Antes de começar

Configure seu projeto antes de gerar a imagem personalizada.

Crie o projeto

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Dataproc API, Compute Engine API, and Cloud Storage APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Enable the Dataproc API, Compute Engine API, and Cloud Storage APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init
  12. Instalar o Python 3.11 ou versão mais recente
  13. Prepare um script de personalização que instale pacotes personalizados e/ou atualize configurações, por exemplo: 
      #! /usr/bin/bash
  apt-get -y update
  apt-get install python-dev
  apt-get install python-pip
  pip install numpy

crie um bucket do Cloud Storage no seu projeto

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.

    Go to Buckets page

  2. Click Create bucket.
  3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
    • For Name your bucket, enter a name that meets the bucket naming requirements.
    • For Choose where to store your data, do the following:
      • Select a Location type option.
      • Select a Location option.
    • For Choose a default storage class for your data, select a storage class.
    • For Choose how to control access to objects, select an Access control option.
    • For Advanced settings (optional), specify an encryption method, a retention policy, or bucket labels.
  4. Click Create.

Gerar uma imagem personalizada

Você usa generate_custom_image.py, um programa Python, para criar uma imagem personalizada do Dataproc.

Como funciona

O programa generate_custom_image.py inicia uma instância de VM temporária do Compute Engine com a imagem de base do Dataproc especificada e executa o script de personalização dentro da instância de VM para instalar pacotes personalizados e/ou atualizar configurações. Depois que o script de personalização é concluído, ele encerra a instância de VM e cria uma imagem personalizada do Dataproc no disco da instância de VM. Depois da criação da imagem personalizada, a VM temporária é excluída. A imagem personalizada é salva e pode ser usada para criar clusters do Dataproc.

O programa generate_custom_image.py usa a CLI gcloud para executar fluxos de trabalho de várias etapas no Compute Engine.

Executar o código

Para bifurcar ou clonar arquivos no GitHub, acesse Imagens personalizadas do Dataproc.

Em seguida, execute o script generate_custom_image.py para que o Dataproc gere e salve sua imagem personalizada.

python3 generate_custom_image.py \
    --image-name=CUSTOM_IMAGE_NAME \
    [--family=CUSTOM_IMAGE_FAMILY_NAME] \
    --dataproc-version=IMAGE_VERSION \
    --customization-script=LOCAL_PATH \
    --zone=ZONE \
    --gcs-bucket=gs://BUCKET_NAME \
    [--no-smoke-test]

Sinalizadores obrigatórios

  • --image-name: o nome da saída da imagem personalizada. Observação:o nome da imagem precisa corresponder à expressão regular [a-z](?:[-a-z0-9]{0,61}[a-z0-9]) sem sublinhados ou espaços e ter menos de 64 caracteres.

  • --dataproc-version: a versão da imagem do Dataproc a ser usada na imagem personalizada. Especifique a versão no formato x.y.z-os ou x.y.z-rc-os, por exemplo, "2.0.69-debian10".

  • --customization-script: um caminho local para o script que a ferramenta vai executar para instalar seus pacotes personalizados ou realizar outras personalizações. Esse script é executado como um script de inicialização do Linux apenas na VM temporária usada para criar a imagem personalizada. Especifique um script de inicialização diferente para outras ações de inicialização que você quer executar ao criar um cluster com sua imagem personalizada.

    Imagens entre projetos:se a imagem personalizada for usada para criar clusters em projetos diferentes, um erro poderá ocorrer devido ao cache de comando gcloud ou gsutil armazenado na imagem. Para evitar esse problema, inclua o comando abaixo no script de personalização para limpar as credenciais armazenadas em cache. 

    rm -r /root/.gsutil /root/.config/gcloud

  • --zone: a zona do Compute Engine em que generate_custom_image.py vai criar uma VM temporária para ser usada na criação da imagem personalizada.

  • --gcs-bucket: um URI, no formato gs://BUCKET_NAME, que aponta para o bucket do Cloud Storage. generate_custom_image.py grava arquivos de registro nesse bucket.

Sinalizações opcionais

  • --family: a família da imagem personalizada. As famílias de imagens são usadas para agrupar imagens semelhantes e podem ser usadas ao criar um cluster como um ponteiro para a imagem mais recente na família. Por exemplo, custom-2-2-debian12.
  • --no-smoke-test: esta é uma sinalização opcional que desativa o teste de fumaça da imagem personalizada recém-criada. Ele cria um cluster de teste do Dataproc com a imagem recém-criada, executa um pequeno job e exclui o cluster no final do teste. Por padrão, ele é executado para verificar se a imagem personalizada recém-criada pode criar um cluster funcional do Dataproc. Desativar essa etapa usando a flag --no-smoke-test acelera o processo de criação da imagem personalizada, mas o uso dela não é recomendado.
  • --subnet: a sub-rede a ser usada para criar a VM que cria a imagem personalizada do Dataproc. Se o projeto fizer parte de uma VPC compartilhada, especifique o URL completo da sub-rede no seguinte formato: projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET.

Para ver uma lista de flags opcionais adicionais, consulte Argumentos opcionais no GitHub.

Se o generate_custom_image.py for bem-sucedido, o imageURI da imagem personalizada será exibido na saída da janela do terminal (o imageUri completo é mostrado em negrito abaixo):

...
managedCluster:
    clusterName: verify-image-20180614213641-8308a4cd
    config:
      gceClusterConfig:
        zoneUri: ZONE
      masterConfig:
        imageUri: https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
...

INFO:__main__:Successfully built Dataproc custom image: CUSTOM_IMAGE_NAME
INFO:__main__:

#####################################################################
  WARNING: DATAPROC CUSTOM IMAGE 'CUSTOM_IMAGE_NAME'
           WILL EXPIRE ON 2018-07-14 21:35:44.133000.
#####################################################################

Rótulos de versão de imagem personalizados (uso avançado)

Ao usar a ferramenta de imagem personalizada padrão do Dataproc, ela define um rótulo goog-dataproc-version na imagem personalizada criada. O rótulo reflete os recursos e protocolos de recursos usados pelo Dataproc para gerenciar o software na imagem.

Uso avançado: se você usa seu próprio processo para criar uma imagem personalizada do Dataproc, é necessário adicionar o rótulo goog-dataproc-version manualmente à imagem personalizada, conforme mostrado a seguir:

  1. Extraia o rótulo goog-dataproc-version da imagem de base do Dataproc usada para criar a imagem personalizada. 

    gcloud compute images describe ${BASE_DATAPROC_IMAGE} \
    --project cloud-dataproc \
    --format="value(labels.goog-dataproc-version)"

  2. Defina o rótulo na imagem personalizada.

    gcloud compute images add-labels IMAGE_NAME --labels=[KEY=VALUE,...]

Use uma imagem personalizada

Você especifica a imagem personalizada ao criar um cluster do Dataproc. A imagem personalizada será salva em Imagens do Cloud Compute e poderá criar um cluster do Dataproc por 365 dias a partir da data de criação dela. Para saber como usar uma imagem personalizada após a data de validade, consulte Como criar um cluster com uma imagem personalizada expirada.

URI de imagem personalizada

É possível transferir o imageUri da imagem personalizada para a operação de criação do cluster. Esse URI pode ser especificado de três maneiras:

  1. URI completo:
    https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/`gs://`BUCKET_NAME`
  2. URI parcial: projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
  3. Nome curto: CUSTOM_IMAGE_NAME

As imagens personalizadas também podem ser especificadas pelo URI da família, que sempre escolhe a imagem mais recente dentro da família de imagens.

  1. URI completo:
    https://www.googleapis.com/compute/beta/projects/PROJECT_ID/global/images/family/CUSTOM_IMAGE_FAMILY_NAME/var>
  2. URI parcial: projects/PROJECT_ID/global/images/family/CUSTOM_IMAGE_FAMILY_NAME

Como encontrar o URI da imagem personalizada

Google Cloud CLI

Execute o comando a seguir para listar os nomes das imagens personalizadas.

gcloud compute images list

Transmita o nome da imagem personalizada para o comando abaixo para listar o URI (selfLink) da imagem personalizada.

gcloud compute images describe custom-image-name

Snippet de saída:

...
name: CUSTOM_IMAGE_NAME
selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME
...

Console

  1. Abra a página Compute Engine → Imagens no console do Google Cloud e clique no nome da imagem. Para limitar o número de imagens exibidas, insira uma consulta no campo filter images.
  2. A página Detalhes das imagens é aberta. Clique em REST equivalente.
  3. A resposta REST lista informações adicionais sobre a imagem, incluindo o selfLink, que é o URI da imagem.
    {
  ...
  "name": "my-custom-image",
  "selfLink": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME",
  "sourceDisk": ...,
  ...
}

Criar um cluster com uma imagem personalizada

Crie um cluster com nós mestre e de trabalho que usam uma imagem personalizada usando a CLI gcloud, a API Dataproc ou o console do Google Cloud.

CLI da gcloud

Crie um cluster do Dataproc com uma imagem personalizada usando o comando dataproc clusters create com a flag --image.

Exemplo: 
gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM_IMAGE_URI \
    --region=REGION \
    ... other flags ...

API REST

Crie um cluster com uma imagem personalizada especificando o URI da imagem no campo InstanceGroupConfig.imageUri com os objetos masterConfig, workerConfig e, se aplicável, secondaryWorkerConfig incluídos em uma solicitação de API cluster.create.

Exemplo: uma solicitação REST para criar um cluster padrão do Dataproc (um mestre, dois nós de trabalho) com uma imagem personalizada.

POST /v1/projects/PROJECT_ID/regions/REGION/clusters/
{
  "clusterName": "CLUSTER_NAME",
  "config": {
    "masterConfig": {
      "imageUri": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME"
    },
    "workerConfig": {
      "imageUri": "projects/PROJECT_ID/global/images/CUSTOM_IMAGE_NAME"
    }
  }
}

Console

  1. Abra a página Criar um cluster do Dataproc. O painel Configurar cluster está selecionado.
  2. Na seção Controle de versão, clique em Alterar. Selecione a guia Imagem personalizada, escolha a imagem personalizada a ser usada no cluster do Dataproc e clique em Selecionar. As VMs do cluster serão provisionadas com a imagem personalizada selecionada.

Substituir propriedades do cluster do Dataproc por uma imagem personalizada

É possível usar imagens personalizadas para substituir propriedades de cluster definidas durante a criação do cluster. Se você criar um cluster com uma imagem personalizada e a operação de criação do cluster definir propriedades com valores diferentes daqueles definidos pela imagem personalizada, os valores de propriedade definidos pela imagem personalizada terão precedência.

Para definir as propriedades do cluster com sua imagem personalizada:

  1. No script de personalização de imagens personalizadas, crie um arquivo dataproc.custom.properties em /etc/google-dataproc e defina os valores da propriedade do cluster no arquivo.

    • Arquivo dataproc.custom.properties de amostra:
    dataproc.conscrypt.provider.enable=VALUE
dataproc.logging.stackdriver.enable=VALUE
    • Exemplo de snippet de criação de arquivo de script de personalização para modificar duas propriedades de cluster:
    cat <<EOF >/etc/google-dataproc/dataproc.custom.properties
dataproc.conscrypt.provider.enable=true
dataproc.logging.stackdriver.enable=false
EOF

Como criar um cluster com uma imagem personalizada expirada

Por padrão, as imagens personalizadas expiram 365 dias após a data de criação. É possível criar um cluster com uma imagem personalizada expirada seguindo estas etapas.

  1. Tente criar um cluster do Dataproc com uma imagem personalizada expirada ou uma imagem personalizada que expire em 10 dias.

    gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM-IMAGE-NAME \
    --region=REGION \
    ... other flags ...

  2. A CLI gcloud vai emitir uma mensagem de erro que inclui o nome da propriedade dataproc:dataproc.custom.image.expiration.token do cluster e o valor do token.

dataproc:dataproc.custom.image.expiration.token=TOKEN_VALUE

Copie a string TOKEN_VALUE para a área de transferência.

  1. Use a CLI gcloud para criar o cluster do Dataproc novamente, adicionando o TOKEN_VALUE copiado como uma propriedade do cluster.

    gcloud dataproc clusters create CLUSTER-NAME \
    --image=CUSTOM-IMAGE-NAME \
    --properties=dataproc:dataproc.custom.image.expiration.token=TOKEN_VALUE \
    --region=REGION \
    ... other flags ...

É necessário que a criação do cluster, com a imagem personalizada, seja bem-sucedida.