Creare un catalogo

Il catalogo di runtime Lakehouse consente di creare endpoint del catalogo in Lakehouse senza bordi.

Un endpoint del catalogo punta a un bucket Cloud Storage sottostante e fornisce un livello di metadati che consente ai motori di query e ai carichi di lavoro open source di interagire direttamente con le tabelle. Quando crei un endpoint del catalogo, puoi scegliere tra le credenziali dell'utente finale e la modalità di distribuzione delle credenziali per la delega dell'accesso allo spazio di archiviazione.

Prima di iniziare

1. Leggi l'articolo Informazioni sul catalogo di runtime Lakehouse per capire come funziona il catalogo di runtime Lakehouse e i limiti del servizio.
Accedi al tuo account Google Cloud . 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 carichi di lavoro.

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.

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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.

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

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare un catalogo e registrare tabelle, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Per creare un catalogo:
  • BigLake Admin (roles/biglake.admin) sul tuo progetto
  • Storage Admin (roles/storage.admin) sul progetto
• Crea (registra) tabelle: BigLake Admin (roles/biglake.admin) sul tuo progetto. La registrazione delle tabelle richiede l'autorizzazione specifica per la registrazione delle tabelle (biglake.tables.register), inclusa nel ruolo Amministratore BigLake.
• Utilizza il account di servizio del catalogo di cui è stato eseguito il provisioning automatico in modalità di distribuzione delle credenziali: Storage Object User (roles/storage.objectUser) sui bucket Cloud Storage di destinazione. Dopo aver creato il catalogo, concedi esplicitamente il ruolo Storage Object User (roles/storage.objectUser) nei bucket di archiviazione al account di servizio di cui è stato eseguito il provisioning automatico.

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.

Nota: la creazione del account di servizio del catalogo con provisioning automatico è coerente nel tempo. Ciò significa che è necessario del tempo prima che il account di servizio venga propagato nel sistema. Se provi a concedere ruoli al account di servizio subito dopo la creazione, la richiesta potrebbe non riuscire. Per scoprire il tempo medio necessario per la propagazione delle modifiche di accesso, consulta Propagazione della modifica di accesso.

Crea un catalogo

Crea un catalogo.

Crea un catalogo

Segui questi passaggi per creare un catalogo in base alla modalità di credenziali e al tipo di bucket che preferisci. Per saperne di più sui diversi tipi di catalogo, consulta Informazioni sull'endpoint del catalogo REST Apache Iceberg.

Nota :quando crei o gestisci un catalogo con più bucket in Google Cloud, specifica i percorsi Cloud Storage (gs://) per le posizioni di archiviazione predefinite e con limitazioni. Il formato URI bl://projects/PROJECT_ID/catalogs/CATALOG_ID viene utilizzato esclusivamente durante la configurazione del client per identificare il warehouse del catalogo quando ci si connette dai motori di query (come Spark o Trino).

Console

Creare un catalogo con più bucket (opzione consigliata)

Questa configurazione consente al catalogo di associare più bucket e di assegnare un nome al catalogo indipendentemente dal nome del bucket.

1. Apri la pagina Lakehouse nella console Google Cloud .

   Vai a Lakehouse

2. Fai clic su Crea catalogo.

3. Per Tipo di catalogo, seleziona Catalogo REST Iceberg.

4. Per Opzioni del bucket del catalogo Lakehouse, seleziona Catalogo con più bucket.

5. Per Percorso Cloud Storage del catalogo predefinito, inserisci o cerca il percorso Cloud Storage da utilizzare con il catalogo.

6. In ID catalogo, inserisci un nome personalizzato per il catalogo.

7. Per Località principale, seleziona una località. La località deve essere vicina alle regioni del bucket principale.

8. Fai clic su Continua.

9. Nel passaggio Percorsi dati, aggiungi altri percorsi Cloud Storage, se necessario.

10. Fai clic su Continua.

11. In Authentication method (Metodo di autenticazione), seleziona End-user credentials (Credenziali dell'utente finale) o Credential vending mode (Modalità di distribuzione delle credenziali).

12. Fai clic su Crea.

    Il catalogo viene creato e viene visualizzata la pagina Dettagli catalogo.

13. Se hai selezionato Modalità di distribuzione delle credenziali, segui questi passaggi aggiuntivi:

    1. Nella sezione Metodo di autenticazione, fai clic su Imposta autorizzazioni bucket.
    2. Nella finestra di dialogo, fai clic su Conferma.

Crea un catalogo con un singolo bucket (gs://)

Attenzione:l'utilizzo della configurazione con un singolo bucket è fortemente sconsigliato per i nuovi progetti. Questa configurazione limita il catalogo a un singolo bucket e blocca il nome del catalogo sul nome del bucket.

1. Per Tipo di catalogo, seleziona Catalogo REST Iceberg o Metastore Hive.
2. In Opzioni del bucket del catalogo Lakehouse, seleziona Catalogo di un singolo bucket.
3. Per Percorso Cloud Storage del catalogo predefinito, inserisci o cerca il percorso Cloud Storage da utilizzare con il catalogo. Per un catalogo con bucket singolo (gs://), puoi avere un solo catalogo per bucket e il nome del catalogo corrisponde al nome del bucket.
4. Fai clic su Continua.
5. In Authentication method (Metodo di autenticazione), seleziona End-user credentials (Credenziali dell'utente finale) o Credential vending mode (Modalità di distribuzione delle credenziali).
6. Fai clic su Crea.
7. Se hai selezionato Modalità di distribuzione delle credenziali, segui questi passaggi aggiuntivi:
   1. Nella sezione Metodo di autenticazione, fai clic su Imposta autorizzazioni bucket.
   2. Nella finestra di dialogo, fai clic su Conferma.

gcloud

Crea un catalogo con più bucket (opzione consigliata)

Questa configurazione consente al catalogo di associare più bucket e di assegnare un nome al catalogo indipendentemente dal nome del bucket.

Per creare un catalogo multibucket (consigliato), esegui il comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    --credential-mode CREDENTIAL_MODE \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    [--primary-location LOCATION]

Sostituisci quanto segue:

• CATALOG_NAME: un nome per il catalogo. Per i cataloghi multibrand (consigliati), questo è il nome del catalogo personalizzato.
• PROJECT_ID: il tuo Google Cloud ID progetto.
• DEFAULT_LOCATION: specifica la posizione di archiviazione predefinita per il catalogo. Puoi specificare un bucket (gs://my-bucket) o un percorso secondario (gs://my-bucket/path). Tutti gli spazi dei nomi e le tabelle nel catalogo devono trovarsi nel percorso specificato. Ad esempio, se specifichi gs://my-bucket/path, non puoi creare spazi dei nomi o tabelle in gs://my-bucket/another/path.

• CREDENTIAL_MODE: il metodo di autenticazione. Utilizza end-user per le credenziali utente finale o vended-credentials per la modalità di distribuzione delle credenziali.

  Nota: se utilizzi la modalità di distribuzione delle credenziali, devi concedere esplicitamente il ruolo Storage Object User (roles/storage.objectUser) su tutti i bucket di archiviazione associati account di serviziount del runtime Lakehouse del catalogo con provisioning automatico.

• RESTRICTED_LOCATIONS: (facoltativo) elenco separato da virgole di località di archiviazione consentite aggiuntive, nel formato gs://my-bucket-1/...,gs://my-bucket-2/.... Se specifichi un percorso (ad esempio gs://my-bucket/path), tutti gli spazi dei nomi o le tabelle all'interno di questo bucket devono trovarsi in questo percorso. Tutte le posizioni di spazio di archiviazione sul cloud configurate nella località predefinita e nelle posizioni con limitazioni devono trovarsi nello stesso gruppo di regioni geografiche o giurisdizione (ad esempio Stati Uniti, Europa, Canada o Asia). Ad esempio, non puoi combinare un bucket negli Stati Uniti con un bucket in Europa. Per un elenco delle località supportate, consulta Località del lakehouse.

  Avviso:evita di configurare percorsi sovrapposti con altri cataloghi per impedire l'esposizione non autorizzata delle credenziali. Per saperne di più, vedi Archiviazione in più bucket.

• LOCATION: (facoltativo) la regione principale per il catalogo per garantire l'interoperabilità con BigQuery. Per i bucket Cloud Storage nella regione US (ad esempio US o us-central1) o nella regione EU (ad esempio EU o europe-west4), specifica US o EU rispettivamente per garantire che il catalogo sia accessibile e disponibile per le query dalle multiregioni BigQuery corrispondenti. Per saperne di più, consulta Regioni dei bucket e dei cataloghi.

Crea un catalogo con un singolo bucket (gs://)

Attenzione:l'utilizzo della configurazione con un singolo bucket è fortemente sconsigliato per i nuovi progetti. Questa configurazione limita il catalogo a un singolo bucket e blocca il nome del catalogo sul nome del bucket.

Per creare un catalogo a un solo bucket (gs://), esegui questo comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode CREDENTIAL_MODE

Sostituisci quanto segue:

• CATALOG_NAME: un nome per il catalogo. Per i cataloghi a un solo bucket (gs://), questo corrisponde all'ID bucket Cloud Storage utilizzato con il catalogo REST.
• PROJECT_ID: il tuo Google Cloud ID progetto.
• CREDENTIAL_MODE: il metodo di autenticazione. Utilizza end-user per le credenziali utente finale o vended-credentials per la modalità di distribuzione delle credenziali.

REST

Crea un catalogo REST Iceberg

Per creare un endpoint di gestione del catalogo utilizzando l'API REST, invia una richiesta POST all'endpoint CreateIcebergCatalog:

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?icebergCatalogId=CATALOG_ID

Il corpo della richiesta deve contenere un payload JSON IcebergCatalog che definisce la configurazione del catalogo, ad esempio il warehouse del bucket Cloud Storage sottostante e la modalità di autenticazione.

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto Google Cloud .
• CATALOG_ID: l'ID del catalogo di runtime Lakehouse.