Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Criar uma instância com acesso às credenciais do usuário
Nesta página, descrevemos como criar uma instância do Vertex AI Workbench que
acessa serviços e APIs do Google Cloud com suas credenciais de usuário.
Suas credenciais de usuário são as credenciais associadas à sua Conta do Google.
Suas credenciais de usuário determinam a quais serviços e APIs sua Conta do Google tem acesso. Google Cloud
Por padrão, quando você executa um código em uma instância do Vertex AI Workbench,
ela pode acessar serviços e 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 a Google Cloud que a conta de serviço.
Nesta página, descrevemos como criar e configurar uma instância para que ela
tenha o mesmo acesso a Google Cloud que suas credenciais de usuário.
Visão geral
O Vertex AI Workbench usa um cliente OAuth global gerenciado pelo Google
para gerenciar o acesso às credenciais do usuário, com escopo para os recursos Google Cloud
no projeto do usuário. Os usuários precisam dar consentimento ao cliente OAuth para
gerenciar as credenciais de cada instância do Vertex AI Workbench.
Isso é feito uma vez por instância em uma caixa de diálogo que aparece quando você clica no botão Abrir JupyterLab no console do Google Cloud .
A conta de serviço usada para criar a instância do Vertex AI Workbench é o seguinte agente de serviço:
Esse agente de serviço oferece permissões limitadas para serviços essenciais, como exportação de registros. Os usuários não podem especificar uma conta de serviço diferente
se o recurso de credenciais do usuário final estiver ativado.
As instâncias com credenciais de usuário final ativadas têm o rótulo notebooks-managed-euc: true
do Compute Engine e a chave de metadados euc-enabled: true
anexada ao recurso de VM para indicar a ativação do recurso.
Limitações
Considere as seguintes limitações ao planejar seu projeto:
O Vertex AI Workbench usa um cliente OAuth global gerenciado pelo Google
para gerenciar o acesso às credenciais do usuário. As organizações não podem
ativar controles refinados, acessar o cliente OAuth ou usar o registro em
log para verificar o uso do cliente OAuth.
Para proteger a segurança das instâncias do Vertex AI Workbench com
credenciais de usuário gerenciadas, os usuários não podem:
Use SSH para acessar a instância.
Execute um script pós-inicialização.
Acesse a página detalhada da VM.
Usar uma imagem que não foi criada pelo Google.
O uso de credenciais de terceiros não é compatível porque o cliente OAuth aceita apenas credenciais OAuth gerenciadas pelo Google.
Antes de começar
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.
In the Google Cloud console, on the project selector page,
select or create a Google Cloud project.
Para receber as permissões necessárias para criar uma instância do Vertex AI Workbench,
peça ao administrador para conceder a você o
papel do IAM de Executor de notebooks (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.
Na caixa de diálogo Nova instância, clique em Opções avançadas.
Na caixa de diálogo Criar instância, na seção Detalhes, forneça as seguintes informações para 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.
Na seção IAM e segurança, selecione Usuário único.
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, você precisará conceder o papel de usuário da conta de serviço (roles/iam.serviceAccountUser) ao conta de serviço da instância.
Selecione Ativar credenciais gerenciadas de usuário final.
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 no console Google Cloud .
Os usuários precisam dar consentimento ao cliente OAuth para gerenciar as credenciais
de cada instância do Vertex AI Workbench. Isso é feito uma vez por instância. Para conceder consentimento, clique em Abrir JupyterLab e conclua
a caixa de diálogo que aparece.
Se você tentar acessar a instância sem dar consentimento, o JupyterLab
vai mostrar uma mensagem para autenticar abrindo o JupyterLab no
consoleGoogle Cloud .
Para verificar se as credenciais do usuário final estão disponíveis no JupyterLab,
abra um terminal no JupyterLab e insira o seguinte comando:
gcloudauthlist
Autentique a instância com suas credenciais de usuário.
O Vertex AI Workbench pode usar o Application Default Credentials (ADC)
para autenticar suas credenciais de usuário em serviços e APIs do Google Cloud .
Esta seção descreve como fornecer suas credenciais de usuário à ADC se alguma das limitações impedir que você ative as credenciais gerenciadas.
As etapas de autenticação dependem do uso de uma Conta do Google ou de credenciais de terceiros.
Conta do Google
Depois de acessar o JupyterLab na instância, faça o seguinte:
No console Google Cloud , acesse a página Instâncias.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-04 UTC."],[],[],null,["Create an instance with user credential access\n| **Preview**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nThis page describes how to create a Vertex AI Workbench instance that\naccesses Google Cloud services and APIs through your user credentials.\n\nYour user credentials are the credentials associated with your Google Account.\nYour user credentials determine which Google Cloud services and APIs your\nGoogle Account has access to.\n\nBy default, when you run code in a Vertex AI Workbench instance,\nyour instance can access Google Cloud services and APIs by using\nthe credentials associated with your instance's service account. This\nmeans that your instance has the same access to Google Cloud as\nthe service account.\n\nThis page describes how to create and configure an instance so that it\nhas the same access to Google Cloud as your user credentials.\n\nOverview\n\nVertex AI Workbench uses a global google-managed OAuth client\nto manage user credential access, scoped for the Google Cloud resources\nin the user's project. Users must grant consent to the OAuth Client to\nmanage their credentials for each Vertex AI Workbench instance.\nThis is done one time per instance through a dialog that opens when\nyou click the **Open JupyterLab** button in the Google Cloud console.\n\nThe service account used to create the Vertex AI Workbench instance is the\nfollowing service agent:\n\n`service-`\u003cvar translate=\"no\"\u003ePROJECT_NUMBER\u003c/var\u003e`@gcp-sa-notebooks-vm.``iam.``gserviceaccount.``com`.\n\nThis service agent provides limited permissions for essential services such\nas exporting logs. Users can't specify a different service account\nif the end user credentials feature is enabled.\n\nInstances with end user credentials enabled have the `notebooks-managed-euc: true`\nCompute Engine label and the `euc-enabled: true` metadata key\nattached to the VM resource to denote the feature enablement.\n\nLimitations\n\nConsider the following limitations when you plan your project:\n\n- Vertex AI Workbench uses a global google-managed OAuth client\n to manage user credential access. Organizations can't\n enact fine grain controls, access the OAuth client, or use logging\n to check for use of the OAuth client.\n\n- To protect the security of Vertex AI Workbench instances with\n managed user credentials, **users aren't able to**:\n\n - Use SSH to access the instance.\n - Run a post-startup script.\n - Access the detailed VM page.\n - Use an image that isn't created by Google.\n- Using [third party\n credentials](/vertex-ai/docs/workbench/instances/create-third-party-instance)\n isn't supported because the OAuth client only supports Google-managed\n OAuth credentials.\n\nBefore you begin\n\n- Sign in to your Google Cloud account. If you're new to Google Cloud, [create an account](https://console.cloud.google.com/freetrial) to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.\n- In the Google Cloud console, on the project selector page,\n select or create a Google Cloud project.\n\n | **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.\n\n [Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard)\n-\n [Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n-\n\n\n Enable the Notebooks API.\n\n\n [Enable the API](https://console.cloud.google.com/flows/enableapi?apiid=notebooks.googleapis.com&redirect=https://console.cloud.google.com)\n\n- In the Google Cloud console, on the project selector page,\n select or create a Google Cloud project.\n\n | **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.\n\n [Go to project selector](https://console.cloud.google.com/projectselector2/home/dashboard)\n-\n [Verify that billing is enabled for your Google Cloud project](/billing/docs/how-to/verify-billing-enabled#confirm_billing_is_enabled_on_a_project).\n\n-\n\n\n Enable the Notebooks API.\n\n\n [Enable the API](https://console.cloud.google.com/flows/enableapi?apiid=notebooks.googleapis.com&redirect=https://console.cloud.google.com)\n\n\u003cbr /\u003e\n\nRequired roles\n\n\nTo get the permissions that\nyou need to create a Vertex AI Workbench instance,\n\nask your administrator to grant you the\n\n\n[Notebooks Runner](/iam/docs/roles-permissions/notebooks#notebooks.runner) (`roles/notebooks.runner`)\nIAM role on the project.\n\n\nFor more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\nYou might also be able to get\nthe required permissions through [custom\nroles](/iam/docs/creating-custom-roles) or other [predefined\nroles](/iam/docs/roles-overview#predefined).\n\nCreate a single user instance\n\nTo create a Vertex AI Workbench instance by using\nthe Google Cloud console, do the following:\n\n1. In the Google Cloud console, go to the **Instances** page.\n\n [Go to Instances](https://console.cloud.google.com/vertex-ai/workbench/instances)\n2. Click add_box **Create new**.\n\n3. In the **New instance** dialog, click **Advanced options**.\n\n4. In the **Create instance** dialog, in the **Details** section,\n provide the following information for your new instance:\n\n - **Name**: Provide a name for your new instance. The name must start with a letter followed by up to 62 lowercase letters, numbers, or hyphens (-), and cannot end with a hyphen.\n - **Region** and **Zone** : Select a region and zone for the new instance. For best network performance, select the region that is geographically closest to you. See the available [Vertex AI Workbench\n locations](/vertex-ai/docs/general/locations#instances).\n5. In the **IAM and Security** section, select **Single user**.\n\n6. In the **User email** field,\n enter the user account that you want to grant access. If the\n specified user is not the creator of the instance, you must grant\n the specified user the [Service Account User\n role](/iam/docs/service-account-permissions#user-role)\n (`roles/iam.serviceAccountUser`) on the instance's service account.\n\n7. Select **Enable managed end user credentials**.\n\n8. Complete the rest of the instance creation dialog, and then\n click **Create**.\n\n Vertex AI Workbench creates an instance and automatically starts it.\n When the instance is ready to use, Vertex AI Workbench\n activates an **Open JupyterLab** link in the Google Cloud console.\n9. Users must grant consent to the OAuth client to manage their credentials\n for each Vertex AI Workbench instance. This is done one time\n per instance. To grant consent, click **Open JupyterLab** and complete\n the dialog that appears.\n\n If you try to access the instance without granting consent, JupyterLab\n displays a message to authenticate by opening JupyterLab from the\n Google Cloud console.\n10. To verify that your end user credentials are available within JupyterLab,\n open a Terminal in JupyterLab, and enter the following command:\n\n ```bash\n gcloud auth list\n ```\n\nAuthenticate the instance with your user credentials\n\nVertex AI Workbench can use Application Default Credentials (ADC)\nto authenticate your user credentials to Google Cloud services and APIs.\nThis section describes how to provide your user credentials to ADC if any of\nthe limitations prevent you from enabling managed credentials.\n\nThe authentication steps depend on whether you are using a Google Account\nor third party credentials. \n\nGoogle Account\n\nAfter you can access JupyterLab on your instance, do the following:\n\n1. In the Google Cloud console, go to the **Instances** page.\n\n [Go to Instances](https://console.cloud.google.com/vertex-ai/workbench/instances)\n2. Next to your instance's name, click **Open JupyterLab**.\n\n3. In JupyterLab, select\n **File \\\u003e New \\\u003e Terminal**.\n\n4. In the terminal window, run the following:\n\n ```bash\n gcloud auth login\n ```\n5. Enter `Y`.\n\n6. Follow the instructions to copy a verification code and enter it into\n the terminal.\n\nThird party credentials\n\nIf you [created an instance with\nthird party credentials](/vertex-ai/docs/workbench/instances/create-third-party-instance),\nthen after the JupyterLab proxy is available, do the following:\n\n1. Open JupyterLab by using the federated JupyterLab proxy.\n\n2. In JupyterLab, select\n **File \\\u003e New \\\u003e Terminal**.\n\n3. Create a Workforce Identity Federation\n [credential file](/iam/docs/workforce-sign-in-okta) with headless sign-in.\n\n4. In the terminal window, run the following:\n\n ```bash\n gcloud auth login --cred-file=\"\u003cvar translate=\"no\"\u003eCREDENTIAL_FILE\u003c/var\u003e\"\n ```\n\n Replace \u003cvar translate=\"no\"\u003eCREDENTIAL_FILE\u003c/var\u003e with the path and name of the\n credential file that you created.\n5. Follow the instructions to authenticate through the\n third party authentication portal.\n\n6. Confirm that your credentials are accessible through your instance\n by using the following command:\n\n ```bash\n gcloud auth list\n ```"]]
