Criar uma imagem personalizada do Dataproc

Os clusters do Dataproc podem ser provisionados com uma imagem personalizada que inclui os pacotes pré-instalados de um usuário. Esta página mostra como criar uma imagem personalizada e instalá-la em um cluster do Dataproc.

Considerações e limitações de uso

  • Ciclo de vida da imagem personalizada:para ajudar a garantir que os clusters recebam as informações mais recentes atualizações de serviço e correções de bug, a criação de clusters com uma imagem personalizada limitado a 365 dias a partir da data de criação da imagem personalizada. Observe que os clusters criados com uma imagem personalizada podem ser executados indefinidamente.

    Talvez seja necessário usar a automação se você 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:para criar imagens personalizadas, é preciso começar com 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 pacotes e configurações personalizadas do SO, será excluído.

  • Uso de imagens personalizadas hospedadas:se você usa uma imagem personalizada hospedada em outro projeto, o Conta de serviço do agente de serviço do Dataproc no seu projeto precisa ter a permissão compute.images.get em a imagem no projeto host. É possível dar essa permissão concedendo roles/compute.imageUser de usuário na imagem hospedada à função Conta de serviço do agente de serviço do Dataproc (consulte Como compartilhar imagens personalizadas em uma organização).

  • Como usar segredos MOK (chave de proprietário da máquina) de inicialização segura: Para ativar inicialização segura com a 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: é preciso conceder à conta de serviço o papel de Leitor do Secret Manager (roles/secretmanager.viewer). no projeto e o papel de acessador do Secret Manager (roles/secretmanager.secretAccessor) os secrets públicos e privados.

    Para mais informações com exemplos, consulte o arquivo 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, a imagem personalizada do Dataproc os scripts geram e gerenciam um par de chaves com 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. Instale o Python 3.11+
  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. Após o script de personalização é encerrado, ele encerra a instância de VM e cria uma instância Dataproc imagem do 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

Bifurque ou clone os arquivos no GitHub em 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 menos de 64 caracteres.
  • --dataproc-version: a versão de imagem do Dataproc para usar 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 executará para instalar seus pacotes personalizados ou realizar outras personalizações. Este script é são executadas apenas na VM temporária usada para criar a imagem personalizada. É possível especificar 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.
  • --zone: a zona do Compute Engine em que generate_custom_image.py criará uma VM temporária para ser usada na criação a 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 registros neste 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 uma lista de sinalizações 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. Uma imagem personalizada é salva em Imagens do Cloud Compute é válido para criar um cluster do Dataproc por 365 dias a partir do data de criação. Consulte Como criar um cluster com uma imagem personalizada expirada para usar uma imagem personalizada após a data de validade de 365 dias.

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 o Compute Engine→Imagens no console do Google Cloud e depois 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

Criar um cluster do Dataproc com uma imagem personalizada usando o comando dataproc clusters create com a sinalização --image.

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

API REST

Criar um cluster com uma imagem personalizada especificando o URI dela no InstanceGroupConfig.imageUri no campo masterConfig, workerConfig e, se for o caso, Objeto secondaryWorkerConfig incluído em um cluster.create solicitação de API.

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 o Dataproc Criar um cluster página. O painel Configurar cluster está selecionado.
  2. Na seção Controle de versões, clique em Alterar. Selecione a guia Imagem personalizada e escolha a imagem a ser usada do cluster do Dataproc e, em seguida, 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 define propriedades com valores diferentes daquelas definidas por sua imagem personalizada, a propriedade os valores definidos pela imagem personalizada têm 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 substituir dois propriedades do 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.