Criar uma instância com acesso às credenciais do usuário

Criar uma instância com acesso às credenciais do usuário

Esta página descreve como criar uma instância do Vertex AI Workbench que acessa serviços e APIs do Google Cloud usando suas credenciais de usuário.

As credenciais do usuário são as credenciais associadas à sua Conta do Google. Suas credenciais de usuário determinam quais serviços e APIs do Google Cloud sua conta do Google tem acesso.

Por padrão, quando você executa um código em uma instância do Vertex AI Workbench, ela pode acessar os serviços e as APIs do Google Cloud usando as credenciais associadas à conta de serviço da instância. Isso significa que a instância tem o mesmo acesso ao Google Cloud que a conta de serviço.

Esta página descreve como criar e configurar uma instância para que ela tenha o mesmo acesso ao Google Cloud que suas credenciais de usuário.

Visão geral

O Vertex AI Workbench não oferece suporte direto ao acesso às credenciais do usuário, mas você ainda pode configurar uma instância para ter acesso com base nas credenciais do usuário aos serviços e APIs do Google Cloud.

Esta página descreve como configurar e autenticar uma instância baseada em credenciais do usuário seguindo estas etapas:

1. Prepare uma conta de serviço com permissões limitadas. Essa conta de serviço não poderá acessar o Google Cloud, exceto o acesso específico necessário para a instância funcionar.

2. Crie uma instância com as seguintes especificações:

   • Acesso de um único usuário. Isso limita o acesso ao JupyterLab apenas ao usuário especificado.

   • Acesso SSH desativado. O acesso SSH à sua instância é gerenciado pelo Login do SO por padrão. A desativação do acesso SSH impede o acesso de usuários que possam ter acesso SSH à VM do Compute Engine.

   • Pertence à sua conta de serviço com permissões limitadas. Por padrão, uma nova instância é de propriedade de uma conta de serviço e pode acessar todos os serviços e APIs do Google Cloud a que ela tem acesso. Especificar a conta de serviço com permissões limitadas impede o acesso inesperado a serviços e APIs do Google Cloud para que você possa configurar o acesso controlado pelas credenciais do usuário.

3. Autenticar a instância com suas credenciais de usuário. Depois que a instância estiver em execução, forneça suas credenciais de usuário para as Application Default Credentials (ADC). O ADC autentica suas credenciais de usuário para os serviços e APIs do Google Cloud. Isso dá à sua instância do Vertex AI Workbench o mesmo acesso ao Google Cloud que suas credenciais de usuário.

Antes de começar

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

4. Enable the Notebooks API.

   Enable the API

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

7. Enable the Notebooks API.

   Enable the API

Funções exigidas

Para garantir que sua conta de usuário tenha as permissões necessárias para criar uma instância do Vertex AI Workbench, peça ao administrador para conceder à sua conta de usuário o papel do IAM Notebooks Runner (roles/notebooks.runner) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder à sua conta de usuário as permissões necessárias via funções personalizadas ou outros papéis predefinidos.

Preparar uma conta de serviço

Uma instância do Vertex AI Workbench requer uma conta de serviço para criar uma instância de VM do Compute Engine que hospeda o servidor do JupyterLab. Essa conta de serviço também gerencia as atividades de registro necessárias.

Você precisa preparar uma conta de serviço com apenas as seguintes permissões:

• logging.logEntries.create
• logging.logEntries.route
• monitoring.metricDescriptors.create
• monitoring.metricDescriptors.get
• monitoring.metricDescriptors.list
• monitoring.monitoredResourceDescriptors.get
• monitoring.monitoredResourceDescriptors.list
• monitoring.timeSeries.create

Para criar uma conta de serviço, consulte Criar contas de serviço.

Para modificar uma conta de serviço, consulte Listar e editar contas de serviço.

Criar uma instância de usuário único

É possível criar uma instância do Vertex AI Workbench usando o console do Google Cloud ou a Google Cloud CLI.

Console

Para criar uma instância do Vertex AI Workbench, faça o seguinte:

1. No Console do Google Cloud, acesse a página Instâncias.

   Acesse "Instâncias"

2. Clique em Criar.

3. Na caixa de diálogo Nova instância, clique em Opções avançadas.

4. Na caixa de diálogo Criar instância, na seção Detalhes, forneça as seguintes informações sobre a nova instância:

   • Nome: forneça um nome para a nova instância. O nome precisa começar com uma letra seguida por até 62 letras minúsculas, números ou hifens (-) e não pode terminar com um hífen.
   • Região e Zona: selecione uma região e zona para a nova instância. Para ter o melhor desempenho de rede, selecione a região mais próxima de você. Veja os locais disponíveis do Vertex AI Workbench.

5. Para desativar o acesso SSH:

   1. Na seção Ambiente, em Metadados, clique em  Adicionar metadados.

   2. Em Chave 1, insira disable-ssh.

   3. Em Valor 1, insira true.

   Observação: o acesso SSH também pode ser desativado pela política da organização constraints/compute.disableSshInBrowser.

6. Na seção IAM e segurança, selecione Usuário único e, no campo E-mail do usuário, insira a conta de usuário a que você quer conceder acesso. Se o usuário especificado não for o criador da instância, conceda a ele o papel de usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço da instância.

7. Desmarque a opção Usar a conta de serviço padrão do Compute Engine e digite o endereço de e-mail da conta de serviço que você preparou anteriormente neste guia. Se você ainda não preparou uma conta de serviço, consulte Preparar uma conta de serviço.

8. Preencha o restante da caixa de diálogo de criação de instância e clique em Criar.

   O Vertex AI Workbench cria uma instância e a inicia automaticamente. Quando a instância estiver pronta para uso, o Vertex AI Workbench ativa um link Abrir JupyterLab.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

• INSTANCE_NAME: o nome da sua instância do Vertex AI Workbench. Precisa começar com uma letra seguida por até 62 letras minúsculas, números ou hifens (-) e não pode terminar com um hífen.
• PROJECT_ID: ID do projeto;
• LOCATION: a zona em que você quer que a instância esteja localizada
• VM_IMAGE_PROJECT: o ID do projeto do Google Cloud a que a imagem da VM pertence, no formato: projects/IMAGE_PROJECT_ID
• VM_IMAGE_NAME: o nome completo da imagem. Para encontrar o nome da imagem de uma versão específica, consulte Encontrar a versão específica.
• MACHINE_TYPE: o tipo de máquina da VM da instância
• METADATA: metadados personalizados a serem aplicados a esta instância. Por exemplo, para desativar o SSH, use a tag de metadados disable-ssh no formato: "--metadata=disable-ssh=true"
• SERVICE_ACCOUNT: o endereço de e-mail da conta de serviço a ser usada para a instância.
• OWNER: o endereço de e-mail da conta do único usuário que pode acessar a instância. Apenas um usuário é aceito.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud workbench instances create INSTANCE_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --vm-image-project=VM_IMAGE_PROJECT \
    --vm-image-name=VM_IMAGE_NAME \
    --machine-type=MACHINE_TYPE \
    --metadata=METADATA \
    --service-account-email=SERVICE_ACCOUNT
    --instance-owners=OWNER

Windows (PowerShell)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud workbench instances create INSTANCE_NAME `
    --project=PROJECT_ID `
    --location=LOCATION `
    --vm-image-project=VM_IMAGE_PROJECT `
    --vm-image-name=VM_IMAGE_NAME `
    --machine-type=MACHINE_TYPE `
    --metadata=METADATA `
    --service-account-email=SERVICE_ACCOUNT
    --instance-owners=OWNER

Windows (cmd.exe)

Observação: para inicializar a Google Cloud CLI com autenticação e um projeto, execute gcloud init. ou gcloud auth login e gcloud config set project.

gcloud workbench instances create INSTANCE_NAME ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --vm-image-project=VM_IMAGE_PROJECT ^
    --vm-image-name=VM_IMAGE_NAME ^
    --machine-type=MACHINE_TYPE ^
    --metadata=METADATA ^
    --service-account-email=SERVICE_ACCOUNT
    --instance-owners=OWNER

Para mais informações sobre o comando para criar uma instância usando a linha de comando, consulte a documentação da CLI gcloud.

O Vertex AI Workbench cria uma instância e a inicia automaticamente. Quando a instância estiver pronta para uso, o Vertex AI Workbench ativa um link Abrir JupyterLab no console do Google Cloud.

Autenticar a instância com suas credenciais de usuário

O Vertex AI Workbench pode usar o Application Default Credentials (ADC) para autenticar as credenciais do usuário nos serviços e APIs do Google Cloud. Esta seção descreve como fornecer suas credenciais de usuário ao ADC.

As etapas de autenticação dependem se você está usando uma Conta do Google ou credenciais de terceiros.

Conta do Google

Depois de acessar o JupyterLab na sua instância, faça o seguinte:

1. No Console do Google Cloud, acesse a página Instâncias.

   Acesse "Instâncias"

2. Ao lado do nome da instância, clique em Abrir JupyterLab.

3. No JupyterLab, selecione Arquivo > Novo > Terminal.

4. Na janela do terminal, execute o seguinte:

   gcloud auth login

5. Digite Y.

6. Siga as instruções para copiar um código de verificação e inseri-lo no terminal.

Credenciais de terceiros

Se você criou uma instância com credenciais de terceiros, faça o seguinte depois que o proxy do JupyterLab estiver disponível:

1. Abra o JupyterLab usando o proxy federado do JupyterLab.

2. No JupyterLab, selecione Arquivo > Novo > Terminal.

3. Crie um arquivo de credenciais da federação de identidade da força de trabalho com login sem cabeça.

4. Na janela do terminal, execute o seguinte:

   gcloud auth login --cred-file="CREDENTIAL_FILE"

   Substitua CREDENTIAL_FILE pelo caminho e nome do arquivo de credencial que você criou.

5. Siga as instruções para fazer a autenticação pelo portal de terceiros.

6. Confirme se as credenciais podem ser acessadas pela sua instância usando o seguinte comando:

   gcloud auth list

Limitações

• A migração de uma instância de notebooks gerenciados para instâncias do Vertex AI Workbench não retém o acesso baseado em credenciais do usuário da instância original. É necessário configurar a instância migrada e autenticar as credenciais do usuário, conforme descrito neste guia.