Creare un catalogo

La creazione di un endpoint del catalogo (ad esempio un endpoint del catalogo REST Apache Iceberg o un endpoint del catalogo Apache Hive) stabilisce un endpoint di gestione all'interno del catalogo runtime Lakehouse.

Questo endpoint punta a un bucket Cloud Storage sottostante, fornendo 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 l'endpoint del catalogo per Lakehouse per Apache Iceberg, puoi scegliere tra credenziali dell'utente finale o modalità di distribuzione delle credenziali per la delega dell'accesso allo spazio di archiviazione.

Prima di iniziare

1. Leggi l'articolo Informazioni sul catalogo runtime Lakehouse per capire come funziona il catalogo 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.

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

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.

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

Ruoli obbligatori

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

• Crea un catalogo:
  • BigLake Admin (roles/biglake.admin) sul tuo progetto
  • Storage Admin (roles/storage.admin) sul tuo progetto
• Registra tabelle: BigLake Admin (roles/biglake.admin) sul tuo progetto. La registrazione delle tabelle in un catalogo multibucket 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 di provisioning automatico del catalogo è coerente nel tempo. Ciò significa che è necessario del tempo prima che il account di servizio venga propagato nel sistema. Se tenti di concedere ruoli al account di servizio subito dopo la creazione, la richiesta potrebbe non riuscire. Per scoprire i tempi medi di propagazione delle modifiche di accesso, consulta Propagazione della modifica di accesso.

Crea un catalogo

Crea un catalogo.

Console

Creare un catalogo multibrand (bl://) (consigliato)

Nota: i cataloghi multi-bucket (bl://) (consigliati) non sono supportati nella console Google Cloud . Per aggiornare questo tipo di catalogo, utilizza gcloud o l'API REST.

Crea un catalogo a un solo bucket (gs://)

1. Nella console Google Cloud , apri la pagina Lakehouse.

   Vai a Lakehouse

2. Seleziona Crea catalogo. Viene visualizzata la pagina Crea catalogo.

3. Seleziona la configurazione del catalogo:

   • Per creare un catalogo REST Apache Iceberg, seleziona Catalogo REST Iceberg.

4. Configura il catalogo:

   • Se scegli Catalogo REST di Iceberg, seleziona Bucket Cloud Storage per il tipo di catalogo e seleziona il bucket Cloud Storage da utilizzare con il catalogo.
   • Se scegli Catalogo Hive, inserisci un nome di catalogo univoco e seleziona il percorso Cloud Storage associato.

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

   Se selezioni Modalità di distribuzione delle credenziali, il account di servizio di catalogo del runtime Lakehouse di cui è stato eseguito il provisioning automatico richiede il ruolo esplicito Utente oggetto Storage (roles/storage.objectUser) su tutti i bucket Cloud Storage associati. Per impostazione predefinita, non ha alcun accesso. Senza questo ruolo, le credenziali vendute non hanno un ambito sufficiente per eseguire scritture di archiviazione.

6. Seleziona Crea.

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

7. Nella sezione Metodo di autenticazione, seleziona Imposta autorizzazioni bucket.

8. Nella finestra di dialogo, seleziona Conferma.

   In questo modo viene verificato che il account di servizio del catalogo disponga del ruolo Utente oggetti Storage (roles/storage.objectUser) su tutti i bucket di archiviazione associati. Se crei cataloghi utilizzando gcloud o Terraform, devi concedere questo ruolo manualmente.

gcloud

Creare un catalogo multibrand (bl://) (consigliato)

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="biglake" \
    --default-location="DEFAULT_LOCATION" \
    [--restricted-locations="RESTRICTED_LOCATIONS"] \
    [--credential-mode="CREDENTIAL_MODE"] \
    [--primary-location="PRIMARY_LOCATION"]

Sostituisci quanto segue:

• CATALOG_ID: l'ID del catalogo runtime Lakehouse.
• PROJECT_ID: il tuo ID progetto Google Cloud .
• DEFAULT_LOCATION: il percorso di base di Cloud Storage per i dati e i metadati del catalogo, nel formato gs://my-bucket/path o gs://my-bucket. Tutti gli spazi dei nomi e le tabelle del catalogo devono trovarsi in questo percorso. Ad esempio, se specifichi gs://my-bucket/path, non puoi ospitare spazi dei nomi o tabelle in gs://my-bucket/another/path.
• RESTRICTED_LOCATIONS: (facoltativo) un elenco separato da virgole di bucket o percorsi di archiviazione consentiti aggiuntivi. Analogamente, se specifichi un percorso (ad esempio gs://my-bucket/path), tutti gli spazi dei nomi e le tabelle creati nel bucket di quel percorso devono risiedere all'interno del percorso. Avviso di sicurezza: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.
• CREDENTIAL_MODE: il metodo di autenticazione. Utilizza end-user per Credenziali utente finale o vended-credentials per Modalità di distribuzione delle credenziali.
• PRIMARY_LOCATION: (facoltativo) la regione principale per il catalogo (ad esempio US o EU) per garantire la compatibilità con BigQuery.

Crea un catalogo a un solo bucket (gs://)

Nota: Catalogo con bucket singolo. L'utilizzo della configurazione a 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 con un solo bucket (gs://), imposta --catalog-type su gcs-bucket:

gcloud biglake iceberg catalogs create CATALOG_ID \
    --project="PROJECT_ID" \
    --catalog-type="gcs-bucket" \
    [--credential-mode="CREDENTIAL_MODE"]

Sostituisci quanto segue:

• CATALOG_ID: l'ID del catalogo runtime Lakehouse. Per i cataloghi a un solo bucket (gs://), questo valore deve corrispondere al nome del bucket Cloud Storage.
• PROJECT_ID: il tuo ID progetto Google Cloud .
• CREDENTIAL_MODE: il metodo di autenticazione. Utilizza end-user per Credenziali utente finale o vended-credentials per 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 bucket Cloud Storage sottostante del warehouse e la modalità di autenticazione.

Sostituisci quanto segue:

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