Creare un'istanza con accesso alle credenziali utente

Questa pagina descrive come creare un'istanza di Agent Platform Workbench di Gemini Enterprise che accede a Google Cloud servizi e API tramite le tue credenziali utente.

Le credenziali utente sono le credenziali associate al tuo Account Google. Le credenziali utente determinano i Google Cloud servizi e le API a cui il tuo Account Google ha accesso.

Per impostazione predefinita, quando esegui il codice in un'istanza di Agent Platform Workbench, l'istanza può accedere a Google Cloud servizi e API utilizzando le credenziali associate al account di servizio dell'istanza. Ciò significa che l'istanza ha lo stesso accesso a Google Cloud del account di servizio.

Questa pagina descrive come creare e configurare un'istanza in modo che abbia lo stesso accesso a delle tue credenziali utente. Google Cloud

Panoramica

Agent Platform Workbench utilizza un client OAuth gestito da Google globale per gestire l'accesso alle credenziali utente, con ambito limitato alle Google Cloud risorse nel progetto dell'utente. Gli utenti devono concedere il consenso al client OAuth per gestire le proprie credenziali per ogni istanza di Agent Platform Workbench. Questa operazione viene eseguita una sola volta per istanza tramite una finestra di dialogo che si apre quando fai clic sul pulsando Apri JupyterLab nella Google Cloud console.

Il account di servizio utilizzato per creare l'istanza di Agent Platform Workbench è il seguente agente di servizio:

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

Questo agente di servizio fornisce autorizzazioni limitate per i servizi essenziali, come l'esportazione dei log. Gli utenti non possono specificare un account di servizio diverso se la funzionalità delle credenziali utente finale è abilitata.

Le istanze con le credenziali utente finale abilitate hanno l'etichetta Compute Engine notebooks-managed-euc: true e la chiave di metadati euc-enabled: true allegata alla risorsa VM per indicare l'abilitazione della funzionalità.

Creare istanze con script post-avvio

Puoi utilizzare gli script post-avvio per eseguire azioni dopo l'avvio dell'istanza. Se abiliti le credenziali utente finale nell'istanza di Agent Platform Workbench, le credenziali non sono disponibili all'avvio. Sono disponibili solo dopo che il proprietario dell'istanza accede per la prima volta all'interfaccia di JupyterLab. A causa di questo ritardo, lo script deve eseguire il polling per verificare la disponibilità delle credenziali prima di eseguire i comandi che richiedono l'autenticazione. Affinché lo script venga eseguito, devi concedere al account di servizio dell'istanza l'autorizzazione a leggere il file dello script dalla sua posizione in Cloud Storage. Per motivi di sicurezza, non puoi modificare la posizione dello script dopo la creazione dell'istanza.

Il supporto degli script post-avvio per le istanze con credenziali utente finale è in GA privata. Per informazioni sull'accesso a questa versione, consulta la pagina di richiesta di accesso.

Limitazioni

Quando pianifichi il progetto, tieni presente le seguenti limitazioni:

  • Agent Platform Workbench utilizza un client OAuth gestito da Google globale per gestire l'accesso alle credenziali utente. Le organizzazioni non possono applicare controlli granulari, accedere al client OAuth o utilizzare la registrazione per verificare l'utilizzo del client OAuth.

  • Per proteggere la sicurezza delle istanze di Agent Platform Workbench con credenziali utente gestite, gli utenti non possono:

    • Utilizzare SSH per accedere all'istanza.
    • Eseguire uno script di avvio di Compute Engine.
    • Accedere alla pagina dei dettagli della VM.
    • Utilizzare un'immagine non creata da Google.

  • L'utilizzo di credenziali di terze parti non è supportato perché il client OAuth supporta solo le credenziali OAuth gestite da Google.

Prima di iniziare

  1. Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  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.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare un'istanza di Agent Platform Workbench, chiedi all'amministratore di concederti il ruolo IAM Notebooks Runner (roles/notebooks.runner) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Creare un'istanza per un singolo utente

Per creare un'istanza di Agent Platform Workbench utilizzando la Google Cloud console, procedi nel seguente modo:

  1. Nella Google Cloud console, vai alla pagina Istanze.

    Vai a Istanze

  2. Fai clic su  Crea nuovo.

  3. Nella finestra di dialogo Nuova istanza, fai clic su Opzioni avanzate.

  4. Nella finestra di dialogo Crea istanza, nella sezione Dettagli , fornisci le seguenti informazioni per la nuova istanza:

    • Nome: fornisci un nome per la nuova istanza. Il nome deve iniziare con una lettera seguita da un massimo di 62 lettere minuscole, numeri o trattini (-) e non può terminare con un trattino.
    • Regione e zona: seleziona una regione e una zona per la nuova istanza. Per prestazioni di rete ottimali, seleziona la regione geograficamente più vicina a te. Consulta le località di Agent Platform Workbench disponibili.

  5. Nella sezione IAM e sicurezza, seleziona Utente singolo.

  6. Nel campo Email utente , inserisci l'account utente a cui vuoi concedere l'accesso. Se l' utente specificato non è il creatore dell'istanza, devi concedergli il ruolo Utente account di servizio (roles/iam.serviceAccountUser) nel service account dell'istanza.

  7. Seleziona Abilita credenziali utente finale gestite.

  8. Completa il resto della finestra di dialogo di creazione dell'istanza e poi fai clic su Crea.

    Agent Platform Workbench crea un'istanza e la avvia automaticamente. Quando l'istanza è pronta per l'uso, Agent Platform Workbench attiva un link Apri JupyterLab nella Google Cloud console.

  9. Gli utenti devono concedere il consenso al client OAuth per gestire le proprie credenziali per ogni istanza di Agent Platform Workbench. Questa operazione viene eseguita una sola volta per istanza. Per concedere il consenso, fai clic su Apri JupyterLab e completa la finestra di dialogo visualizzata.

    Se provi ad accedere all'istanza senza concedere il consenso, JupyterLab visualizza un messaggio per eseguire l'autenticazione aprendo JupyterLab dalla Google Cloud console.

  10. Per verificare che le credenziali utente finale siano disponibili in JupyterLab, apri un terminale in JupyterLab ed esegui il seguente comando:

    gcloud auth list

Autenticare l'istanza con le credenziali utente

Agent Platform Workbench può utilizzare le credenziali predefinite dell'applicazione (ADC) per autenticare le credenziali utente per Google Cloud servizi e API. Questa sezione descrive come fornire le credenziali utente ad ADC se una delle limitazioni ti impedisce di abilitare le credenziali gestite.

I passaggi di autenticazione dipendono dall'utilizzo di un Account Google o di credenziali di terze parti.

Account Google

Dopo aver eseguito l'accesso a JupyterLab sull'istanza, procedi nel seguente modo:

  1. Nella Google Cloud console, vai alla pagina Istanze.

    Vai a Istanze

  2. Fai clic su Apri JupyterLab accanto al nome dell'istanza.

  3. In JupyterLab, seleziona File > Nuovo > Terminale.

  4. Nella finestra del terminale, esegui il seguente comando:

    gcloud auth login

  5. Inserisci Y.

  6. Segui le istruzioni per copiare un codice di verifica e inserirlo nel terminale.

Credenziali di terze parti

Se hai creato un'istanza con credenziali di terze parti, dopo che il proxy JupyterLab è disponibile, procedi nel seguente modo:

  1. Apri JupyterLab utilizzando il proxy JupyterLab federato.

  2. In JupyterLab, seleziona File > Nuovo > Terminale.

  3. Crea un file di credenziali della federazione delle identità per la forza lavoro con accesso headless.

  4. Nella finestra del terminale, esegui il seguente comando:

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

    Sostituisci CREDENTIAL_FILE con il percorso e il nome del file di credenziali che hai creato.

  5. Segui le istruzioni per eseguire l'autenticazione tramite il portale di autenticazione di terze parti.

  6. Verifica che le credenziali siano accessibili tramite l'istanza utilizzando il seguente comando:

    gcloud auth list