Creare un catalogo

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

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 workload open source di interagire direttamente con le tue 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 le limitazioni del servizio.

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 progetto
  • Storage Admin (roles/storage.admin) sul progetto
• Creare (registrare) 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 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 Storage Object User (roles/storage.objectUser) sui 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 finale, il che significa che la propagazione del account di servizio nel sistema richiede tempo. Se provi a concedere i ruoli al account di servizio subito dopo la creazione, la richiesta potrebbe non riuscire. Per scoprire quanto tempo è necessario, in media, 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à 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 di Cloud Storage (gs://) per le località di archiviazione predefinite e limitate. Il formato URI bl://projects/PROJECT_ID/catalogs/CATALOG_ID viene utilizzato esclusivamente durante la configurazione del client per identificare il data warehouse del catalogo durante la connessione 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 console Google Cloud .

   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 di più bucket.

5. In Percorso Cloud Storage del catalogo predefinito, inserisci o cerca il percorso Cloud Storage da utilizzare con il tuo 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 dei dati, se vuoi aggiungere altri percorsi di 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.

    Nota: se selezioni Credenziali utente finale, il catalogo di runtime Lakehouse non gestisce automaticamente le tabelle nel catalogo. Non puoi attivare le attività di gestione delle tabelle, come la compattazione e la scadenza degli snapshot.

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, esegui i seguenti passaggi aggiuntivi:

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

Crea un catalogo con bucket singolo

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

1. Nella pagina Lakehouse, fai clic su Crea catalogo, quindi seleziona Catalogo di runtime Lakehouse.
2. In Tipo di catalogo, seleziona Catalogo REST Iceberg o Metastore Hive.
3. Se hai selezionato Catalogo REST Iceberg, per Opzioni bucket catalogo Lakehouse, seleziona Catalogo bucket singolo.
4. Per 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 tuo catalogo. Per un catalogo a bucket singolo, 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 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 con più bucket (consigliati), questo è il nome del catalogo personalizzato.
• PROJECT_ID: il tuo ID progetto Google Cloud.
• DEFAULT_LOCATION: 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 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. Se specifichi end-user, il catalogo di runtime Lakehouse non gestisce automaticamente le tabelle nel catalogo. Non puoi attivare le attività di gestione delle tabelle, come la compattazione e la scadenza degli snapshot.

  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 al service account del catalogo di runtime Lakehouse con provisioning automatico del tuo catalogo.

• RESTRICTED_LOCATIONS: (facoltativo) un 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 del bucket devono trovarsi in quel 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, consulta Località di Lakehouse.

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

• LOCATION: facoltativo: la regione principale del 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 rispettivamente US o EU per assicurarti che il catalogo sia accessibile e disponibile per le query dalle corrispondenti multi-regioni BigQuery. Per saperne di più, consulta Regioni dei bucket e dei cataloghi.

Crea un catalogo con bucket singolo

Attenzione: evita di utilizzare la configurazione a bucket singolo 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 con un singolo bucket, 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 con un singolo bucket, corrisponde all'ID bucket Cloud Storage utilizzato con il catalogo.
• PROJECT_ID: il tuo ID progetto Google Cloud.
• 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 endpoint del catalogo REST Apache 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?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: il tuo ID progetto Google Cloud .
• CATALOG_ID: l'ID del tuo catalogo di runtime Lakehouse.