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

Nesta página, descrevemos como criar uma instância do Gemini Enterprise Agent Platform Workbench que acessa serviços e APIs do Google Cloud usando 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 Agent Platform Workbench, ela pode acessar serviços e APIs usando as credenciais associadas à conta de serviço da instância. Google Cloud Isso significa que sua 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 ao Google Cloud que suas credenciais de usuário.

Visão geral

O Agent Platform 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 Agent Platform 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 Agent Platform Workbench é o seguinte agente de serviço:

service-PROJECT_NUMBER@gcp-sa-notebooks-vm.iam.gserviceaccount.com.

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 do Compute Engine notebooks-managed-euc: true e a chave de metadados euc-enabled: true anexados ao recurso de VM para indicar a ativação do recurso.

Criar instâncias com scripts pós-inicialização

É possível usar scripts pós-inicialização para realizar ações depois que a instância é iniciada. Se você ativar as credenciais de usuário final na sua instância do Agent Platform Workbench, elas não estarão disponíveis na inicialização. Eles só ficam disponíveis depois que o proprietário da instância acessa a interface do JupyterLab pela primeira vez. Devido a esse atraso, o script precisa sondar a disponibilidade de credenciais antes de executar comandos que exigem autenticação. Para que o script seja executado, conceda à conta de serviço da instância permissão para ler o arquivo de script no local do Cloud Storage. Por motivos de segurança, não é possível mudar o local do script depois que a instância é criada.

O suporte a scripts de pós-inicialização para instâncias com credenciais de usuário final está em GA particular. Para informações sobre o acesso a essa versão, consulte a página de solicitação de acesso.

Limitações

Considere as seguintes limitações ao planejar seu projeto:

  • O Workbench da plataforma do agente 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 Workbench da plataforma do agente com credenciais de usuário gerenciadas, os usuários não podem:

  • 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

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Notebooks API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Notebooks API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

Funções exigidas

Para receber as permissões necessárias para criar uma instância do Agent Platform Workbench, peça ao administrador para conceder a você 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.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar uma única instância de usuário

Para criar uma instância do Agent Platform Workbench usando o console Google Cloud , 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 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ê. Confira os locais disponíveis do Workbench da plataforma de agentes.

  5. Na seção IAM e segurança, selecione Usuário único.

  6. 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) à conta de serviço da instância.

  7. Selecione Ativar credenciais gerenciadas de usuário final.

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

    O Workbench da plataforma do agente cria e inicia uma instância automaticamente. Quando a instância estiver pronta para uso, o Agent Platform Workbench vai ativar um link Abrir JupyterLab no console Google Cloud .

  9. Os usuários precisam dar consentimento ao cliente OAuth para gerenciar as credenciais de cada instância do Agent Platform 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 .

  10. 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:

    gcloud auth list

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

O Agent Platform 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 ao ADC se alguma das limitações impedir que você ative as credenciais gerenciadas.

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

Conta do Google

Depois de acessar o JupyterLab na 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 de colaboradores com login sem interface gráfica.

  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 credenciais que você criou.

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

  6. Confirme se as credenciais estão acessíveis na instância usando o seguinte comando:

    gcloud auth list