Creare un catalogo

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

Un endpoint del catalogo rimanda 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 Informazioni sul catalogo di runtime Lakehouse per capire come funziona il catalogo di runtime Lakehouse e i limiti del servizio.
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 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 le tabelle, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Crea un catalogo:
  • BigLake Admin (roles/biglake.admin) sul tuo progetto
  • Amministratore Spazio di archiviazione (roles/storage.admin) sul tuo progetto
• Crea (registra) tabelle: BigLake Admin (roles/biglake.admin) sul tuo progetto. La registrazione delle tabelle richiede l'autorizzazione di registrazione delle tabelle specifica (biglake.tables.register), inclusa nel ruolo BigLake Admin.
• Utilizza il account di servizio del catalogo con 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 Utente oggetti Storage (roles/storage.objectUser) sui bucket di archiviazione al account di servizio con 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 in modo definitivo, il che significa che è necessario del tempo prima che il account di servizio venga propagato nel sistema. Se provi a concedere i ruoli al account di servizio immediatamente 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

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

Nota: quando crei o gestisci un catalogo con più bucket in Google Cloud, specifica i percorsi Cloud Storage (gs://) per le località 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 Apache Spark o Trino).

Console

Crea un catalogo con più bucket (consigliato)

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 Google Cloud console.

   Vai a Lakehouse

2. Fai clic su Crea catalogo e poi seleziona Catalogo di runtime Lakehouse.

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

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

5. In 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. In 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, se vuoi aggiungere altri percorsi Cloud Storage, fai clic su Aggiungi percorso e inserisci o cerca un percorso.

10. Fai clic su Continua.

11. In Metodo di autenticazione, seleziona Credenziali dell'utente finale o Modalità di distribuzione delle credenziali.

12. Fai clic su Crea.

    Il catalogo viene creato e si apre la pagina Dettagli catalogo.

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

    1. In Metodo di autenticazione, fai clic su Imposta autorizzazioni bucket (o Imposta autorizzazioni per i bucket se il catalogo utilizza più di un bucket).
    2. Nella finestra di dialogo, fai clic su Conferma.

Crea un catalogo con un solo bucket

Attenzione: evita di utilizzare la configurazione con un solo bucket per i nuovi progetti. Questa configurazione limita il catalogo a un solo bucket e blocca il nome del catalogo con il nome del bucket.

1. Nella pagina Lakehouse , fai clic su Crea catalogo e poi seleziona Catalogo di runtime Lakehouse.
2. In Tipo di catalogo, seleziona Catalogo REST Iceberg o Hive Metastore.
3. Se hai selezionato Catalogo REST Iceberg, per Opzioni del bucket del catalogo Lakehouse, seleziona Catalogo con bucket singolo.
4. In Bucket Cloud Storage del catalogo predefinito (o Percorso Cloud Storage del catalogo predefinito per un endpoint del catalogo Apache Hive), inserisci o cerca il bucket Cloud Storage da utilizzare con il catalogo. Per un catalogo con un solo bucket, puoi avere un solo catalogo per bucket e il nome del catalogo corrisponde al nome del bucket.
5. Fai clic su Continua.
6. In Metodo di autenticazione, seleziona Credenziali dell'utente finale o Modalità di distribuzione delle credenziali.
7. Fai clic su Crea.
8. Se hai selezionato Modalità di distribuzione delle credenziali, segui questi passaggi aggiuntivi:
   1. In 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 (consigliato)

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 con più bucket (consigliato), esegui il gcloud biglake iceberg catalogs create comando:

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 con più bucket (consigliati), questo è il nome personalizzato del catalogo.
• PROJECT_ID: il tuo Google Cloud ID progetto.
• DEFAULT_LOCATION: la località di archiviazione predefinita per il catalogo. Puoi specificare un bucket (gs://my-bucket) o un sottopercorso (gs://my-bucket/path). Tutti gli spazi dei nomi e le tabelle del 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 dell'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) a tutti i bucket di archiviazione associati al account di servizio del catalogo di runtime Lakehouse con provisioning automatico del catalogo.

• RESTRICTED_LOCATIONS: (facoltativo) un elenco separato da virgole di altre località di archiviazione consentite, 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 del bucket devono trovarsi in questo percorso. Tutte le località Cloud Storage configurate nella località predefinita e nelle località con limitazioni devono trovarsi nello stesso gruppo di regioni geografiche o nella stessa 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, vedi Località Lakehouse.

  Avviso: evita di configurare percorsi sovrapposti con altri cataloghi per impedire l'esposizione non autorizzata delle credenziali. Per saperne di più, consulta Spazio di 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 Stati Uniti (ad esempio US o us-central1) o nella regione UE (ad esempio EU o europe-west4), specifica rispettivamente US o EU per assicurarti 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 solo bucket

Attenzione: evita di utilizzare la configurazione con un solo bucket per i nuovi progetti. Questa configurazione limita il catalogo a un solo bucket e blocca il nome del catalogo con il nome del bucket.

Per creare un catalogo con un solo bucket, esegui il comando seguente:

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 con un solo bucket, questo corrisponde all'ID bucket Cloud Storage utilizzato con il catalogo.
• PROJECT_ID: il tuo Google Cloud ID progetto.
• CREDENTIAL_MODE: il metodo di autenticazione. Utilizza end-user per le credenziali dell'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 POST richiesta al CreateIcebergCatalog endpoint:

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg-catalog-id=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: l' Google Cloud ID progetto.
• CATALOG_ID: l'ID del catalogo di runtime Lakehouse.