Configurar o Lakehouse sem fronteiras para o Snowflake

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Observação: para receber suporte durante a prévia, envie um e-mail para [e-mail].

Neste documento, descrevemos como configurar um Lakehouse sem fronteiras para consultar dados de um catálogo do Snowflake (Snowflake Horizon) diretamente noGoogle Cloud. Essa capacidade unifica a análise de dados ao integrar suas fontes de dados externas com o ambiente Google Cloudatual.

Depois, use o Lakehouse para gerenciar o acesso aos seus dados federados.

Antes de começar

1. Leia a visão geral do Lakehouse para entender como ele gerencia o acesso aos dados.
2. Leia Sobre o Lakehouse sem fronteiras para entender como ele funciona.
3. Revise os catálogos compatíveis para verificar os requisitos de local externo e as configurações aceitas.
4. Entenda como usar secrets regionais do Secret Manager. Isso é necessário para configurar um Lakehouse sem fronteiras com o Snowflake usando a autenticação baseada em segredos. Você pode escolher entre a autenticação baseada em segredo com um token de acesso pessoal (PAT, na sigla em inglês) ou usar a federação de identidade da carga de trabalho (WIF, na sigla em inglês).
5. Se você estiver usando a autenticação baseada em segredo, gere um token de acesso pessoal (PAT) no ambiente do Snowflake Horizon com acesso de leitura ao catálogo de destino. Esse processo está fora do escopo desta documentação.
6. Se você estiver usando a federação de identidade da carga de trabalho, verifique se tem acesso à UI da conta do Snowflake com privilégios de ACCOUNTADMIN para provisionar usuários de serviço.
7. Opcional: se você planeja rotear consultas por uma interconexão particular entre sua VPC Google Cloud e a VPC do provedor de nuvem remota (por exemplo, AWS), verifique se você tem uma conta ativa com o provedor remoto, provisione uma interconexão dedicada entre nuvens ou uma interconexão entre nuvens de parceiro, estabeleça sessões do BGP com o Cloud Router e verifique se você tem as permissões necessárias do Identity and Access Management (IAM) nos dois ambientes de nuvem.
Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake, Secret Manager APIs.

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 APIs

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake, Secret Manager APIs.

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 APIs

Funções exigidas

Para receber as permissões necessárias para configurar o Lakehouse sem fronteiras, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Gerenciar catálogos do Lakehouse: Administrador do BigLake (roles/biglake.admin)
• Gerenciar secrets: Administrador do Secret Manager (roles/secretmanager.admin)
• Fazer o roteamento do tráfego por interconexão particular: Administrador de rede do Compute (roles/compute.networkAdmin), leitor do Service Directory (roles/servicedirectory.viewer) e serviço autorizado do PSC do Service Directory (roles/servicedirectory.pscAuthorizedService)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Atenção: para seguir o princípio de privilégio mínimo e evitar conceder acesso a todos os secrets do projeto, peça a um administrador do Secret Manager para criar o secret e conceder permissões para modificar apenas esse secret específico para o Lakehouse sem fronteiras.

Detalhes do catálogo compatíveis

Neste guia, fornecemos instruções para configurar um Lakehouse sem fronteiras com um catálogo do Snowflake (Snowflake Horizon) na Amazon Web Services (AWS) e no Google Cloud. Para informações detalhadas sobre requisitos de local externo e configurações compatíveis, consulte Catálogos compatíveis.

Limitações e considerações

Nesta seção, listamos as limitações e considerações para usar o Lakehouse sem fronteiras.

• Provedores de nuvem compatíveis:é possível usar uma interconexão privada com seu Lakehouse sem fronteiras com os seguintes provedores de nuvem remotos: Amazon Web Services (AWS). Você pode usar uma Cross-Cloud Interconnect dedicada ou uma Cross-Cloud Interconnect por parceiro.
• Roteamento de rede:se uma interconexão privada (como CCI dedicada ou CCI de parceiro) não estiver configurada, as consultas serão roteadas pela Internet pública. Isso pode resultar em taxas de saída mais altas do seu provedor de nuvem remota e em um desempenho menos previsível.
• Atualização de dados:a flag --refresh-interval do catálogo federado determina a frequência de sincronização dos metadados. Um intervalo menor fornece dados mais recentes, mas pode gerar custos adicionais de API do provedor de catálogo remoto.
• Relatório de métricas do Iceberg:o Relatório de métricas do Iceberg não está disponível para catálogos federados. Defina a propriedade rest-metrics-reporting-enabled como false no cliente do Iceberg ao acessar um catálogo federado.

Fluxo de trabalho geral

Para configurar e usar o Lakehouse sem bordas, siga estas etapas gerais:

• Configure o Cross-Cloud Interconnect (opcional): configure uma conexão privada entre a Google Cloud VPC e o provedor de nuvem remota.
• Configurar a federação:configure um dos seguintes métodos de autenticação e crie um catálogo federado no Lakehouse.
  • Autenticação baseada em secret (PAT): crie um secret no Secret Manager com suas credenciais de catálogo remoto. Em seguida, crie um catálogo federado no Lakehouse e conceda à conta de serviço do catálogo acesso ao secret.
  • Federação de identidade da carga de trabalho (WIF): crie um catálogo federado no Lakehouse especificando a função necessária do Snowflake. Em seguida, vincule o ID da conta de serviço do catálogo a um usuário de serviço no Snowflake. O usuário do serviço Snowflake precisa ter permissões de uso no catálogo remoto do Snowflake.
• Verifique a conexão:confira se o Lakehouse pode se conectar ao catálogo remoto.
• Consultar dados:execute consultas nos seus dados federados usando o BigQuery ou o Serviço Gerenciado para Apache Spark. Para mais informações, consulte Usar Lakehouse sem fronteiras.
• Configurar permissões:use o IAM para gerenciar quem pode visualizar e consultar os dados federados.

Configurar o Interconexão entre nuvens (opcional)

Por padrão, as consultas ao catálogo remoto são transmitidas pela Internet pública. Para ajudar a melhorar a segurança e a conformidade, oferecer desempenho previsível e reduzir os custos de transferência de dados, use uma interconexão privada. Isso estabelece uma conexão de rede dedicada e privada entre sua Google Cloud nuvem privada virtual (VPC) e a rede do provedor de nuvem remota (por exemplo, AWS).

É possível provisionar e configurar uma das seguintes opções de interconexão privada entre sua Google Cloud VPC e a VPC do provedor de nuvem remota (por exemplo, AWS):

• Cross-Cloud Interconnect dedicado: uma conexão física dedicada.
• Cross-Cloud Interconnect por parceiro: uma conexão por um provedor de serviços compatível.

Crie sessões do BGP entre o Cloud Router em Google Cloud e a VPC do provedor de nuvem remota para garantir a troca de rotas.

Para ativar consultas particulares, configure um caminho do Lakehouse para seu bucket de armazenamento remoto (por exemplo, um bucket do Amazon S3 da AWS) usando sua interconexão particular. Há dois fluxos arquitetônicos que você pode seguir para configurar esse roteamento:

• Roteamento do balanceador de carga de rede de proxy interno regional:esse fluxo usa um balanceador de carga de rede de proxy interno regionalGoogle Cloud para distribuir solicitações em grupos de endpoints de rede (NEGs) de conectividade híbrida que apontam para várias interfaces de rede elásticas (ENIs) da AWS. Esse fluxo é essencial para balanceamento de carga, escalonabilidade e alta disponibilidade. É necessário para a CCI de parceiro e recomendado para a CCI dedicada para balanceamento de carga, escalonabilidade e alta disponibilidade.
• Roteamento direto de endpoint:esse fluxo conecta o Diretório de serviços diretamente a um único endereço IP de endpoint de interface da VPC da AWS. Esse fluxo só funciona para CCI dedicado e não é compatível com CCI de parceiro.

Selecione o fluxo de configuração que corresponde aos seus requisitos de arquitetura:

Balanceador de carga de rede de proxy interno regional

Para configurar um balanceador de carga de rede de proxy regional interno para distribuir solicitações em várias ENIs da AWS para alta disponibilidade e balanceamento de carga, siga estas etapas:

Configurar a rede da AWS

Primeiro, crie um endpoint de interface de VPC do Amazon S3 (AWS PrivateLink):

1. No console da VPC da AWS, crie um endpoint de interface para o Amazon S3.
2. Como nome do serviço, especifique com.amazonaws.AWS_REGION.s3.
3. Selecione a VPC e as sub-redes conectadas pelo Direct Connect à sua VPC Google Cloud .
4. Anexe grupos de segurança ao endpoint para controlar o acesso de entrada.
5. Isso provisiona interfaces de rede elásticas (ENIs, na sigla em inglês) em cada sub-rede selecionada. Anote os endereços IP particulares dessas ENIs.

Em seguida, configure os grupos de segurança:

• Verifique se o grupo ou os grupos de segurança anexados às ENIs do endpoint do Amazon S3 permitem o tráfego TCP de entrada na porta 443 da sua VPC Google Cloud . Isso precisa incluir o intervalo CIDR da sua sub-rede somente proxyGoogle Cloud para permitir verificações de integridade e tráfego encaminhado.

Configurar Google Cloud rede

Importante: implante todos os recursos Google Cloud nesta seção (verificação de integridade, NEGs híbridos, serviço de back-end e balanceador de carga) na mesma região em que o anexo da VLAN do Interconexão entre nuvens está localizado. Se estiverem em regiões diferentes, o tráfego não será encaminhado para o armazenamento remoto.

Para simplificar a configuração, execute os comandos a seguir para configurar o balanceador de carga interno. Para configurações avançadas ou mais detalhes, consulte Configurar um balanceador de carga de rede de proxy interno regional para endpoints híbridos.

Observação: antes de começar, verifique se você tem uma sub-rede somente proxy configurada na sua rede VPC na região. Se você não tiver um, execute o comando a seguir para criar:

gcloud compute networks subnets create PROXY_SUBNET_NAME \
    --purpose=REGIONAL_MANAGED_PROXY \
    --role=ACTIVE \
    --region=REGION \
    --network=VPC_NETWORK \
    --range=PROXY_SUBNET_RANGE

Substitua:

• PROXY_SUBNET_NAME: um nome para a sub-rede somente proxy.
• PROXY_SUBNET_RANGE: um intervalo CIDR não utilizado na rede VPC (por exemplo, 10.129.0.0/23).

Importante: o Cloud Router não divulga automaticamente sub-redes somente de proxy usando o BGP. É necessário configurar manualmente o Cloud Router para divulgar o intervalo CIDR da sua sub-rede somente proxy para a rede remota (por exemplo, AWS) usando anúncios de rota personalizados. Isso garante que o tráfego de resposta do seu armazenamento remoto possa ser roteado de volta para o balanceador de carga.

1. Criar uma verificação de integridade regional:

   gcloud compute health-checks create tcp HEALTH_CHECK_NAME \
       --region=REGION \
       --port=443

   Substitua:

   • HEALTH_CHECK_NAME: um nome para a verificação de integridade.
   • REGION: a região Google Cloud (por exemplo, us-east4).

2. Crie grupos de endpoints de rede (NEGs) de conectividade híbrida e adicione endpoints:

   Crie um NEG híbrido (NON_GCP_PRIVATE_IP_PORT) para cada zona:

   gcloud compute network-endpoint-groups create NEG_NAME \
       --network-endpoint-type=NON_GCP_PRIVATE_IP_PORT \
       --zone=ZONE \
       --network=VPC_NETWORK

   Adicione o endereço IP particular da sua ENI da AWS ao NEG híbrido correspondente:

   gcloud compute network-endpoint-groups update NEG_NAME \
       --zone=ZONE \
       --add-endpoint="ip=AWS_S3_IP,port=443"

   Substitua:

   • NEG_NAME: um nome para o NEG híbrido.
   • ZONE: a zona Google Cloud (por exemplo, us-east4-a). Essa zona precisa estar na região do anexo da VLAN do Interconexão entre nuvens.
   • VPC_NETWORK: o nome da sua rede VPC.
   • AWS_S3_IP: o endereço IP particular do endpoint da VPC do Amazon S3 da AWS (ENI) nessa zona.

   Repita esses comandos para criar NEGs e adicionar endpoints para outras zonas se as ENIs da AWS estiverem distribuídas em várias zonas.

3. Crie e configure o serviço de back-end:

   Crie um serviço de back-end regional com balanceamento de carga gerenciado interno:

   gcloud compute backend-services create BACKEND_SERVICE_NAME \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --protocol=TCP \
       --region=REGION \
       --health-checks=HEALTH_CHECK_NAME \
       --health-checks-region=REGION

   Adicione seus NEGs híbridos ao serviço de back-end:

   gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
       --region=REGION \
       --network-endpoint-group=NEG_NAME \
       --network-endpoint-group-zone=ZONE \
       --balancing-mode=CONNECTION \
       --max-connections=MAX_CONNECTIONS

   Substitua:

   • BACKEND_SERVICE_NAME: um nome para o serviço de back-end.
   • NEG_NAME: o nome do NEG híbrido que você criou na etapa anterior.
   • ZONE: a Google Cloud zona (por exemplo, us-east4-a).
   • MAX_CONNECTIONS: o número máximo de conexões simultâneas que o back-end precisa processar (por exemplo, 100).

   Repita o comando add-backend para cada NEG híbrido criado.

4. Configure o front-end do balanceador de carga:

   Crie um proxy TCP de destino:

   gcloud compute target-tcp-proxies create TARGET_PROXY_NAME \
       --backend-service=BACKEND_SERVICE_NAME \
       --region=REGION

   Crie uma regra de encaminhamento para encaminhar o tráfego para o proxy de destino:

   gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
       --load-balancing-scheme=INTERNAL_MANAGED \
       --network=VPC_NETWORK \
       --subnet=VPC_SUBNET \
       --ports=443 \
       --region=REGION \
       --target-tcp-proxy=TARGET_PROXY_NAME \
       --target-tcp-proxy-region=REGION \
       --allow-global-access

   Substitua:

   • TARGET_PROXY_NAME: um nome para o proxy de destino.
   • FORWARDING_RULE_NAME: um nome para a regra de encaminhamento.
   • VPC_SUBNET: o nome da sub-rede VPC.

Depois de criar a regra de encaminhamento para o balanceador de carga, anote o endereço IP interno atribuído a ele. Esta é sua ILB_IP_ADDRESS.

Configurar o Service Directory

Registre o endereço IP do ILB no Diretório de serviços para que o Lakehouse possa descobri-lo.

1. Crie um namespace para sua nuvem remota:

   gcloud service-directory namespaces create NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   Substitua:

   • NAMESPACE: um identificador exclusivo para seu namespace.
   • PROJECT_ID: o ID do projeto do Google Cloud .
   • REGION: a Google Cloud região. Por exemplo, us-east4. Precisa ser a mesma região do catálogo federado.

2. Crie um serviço no namespace do Diretório de serviços:

   gcloud service-directory services create SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   Substitua:

   • SERVICE_NAME: um identificador exclusivo para seu serviço.

3. Crie um endpoint para o ILB no serviço:

   gcloud service-directory endpoints create ENDPOINT_NAME \
       --project=PROJECT_ID \
       --namespace=NAMESPACE \
       --service=SERVICE_NAME \
       --location=REGION \
       --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK \
       --address=ILB_IP_ADDRESS \
       --port=443

   Substitua:

   • ENDPOINT_NAME: um identificador exclusivo para seu endpoint.
   • PROJECT_NUMBER: o número do projeto do Google Cloud. Use o número do projeto na flag --network.
   • ILB_IP_ADDRESS: o endereço IP interno da regra de encaminhamento do ILB.

Endpoint direto

Para configurar o Diretório de serviços para rotear o tráfego diretamente para um único endereço IP de endpoint da VPC de interface da AWS, siga estas etapas:

1. Crie um endpoint de VPC de interface para o Amazon S3 na sua VPC da AWS. Anote o endereço IP e a porta desse endpoint.

2. Crie um namespace para sua nuvem remota:

   gcloud service-directory namespaces create NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   Substitua:

   • NAMESPACE: um identificador exclusivo para seu namespace.
   • PROJECT_ID: o ID do projeto do Google Cloud .
   • REGION: a Google Cloud região. Por exemplo, us-east4. Precisa ser a mesma região do catálogo federado.

3. Crie um serviço no namespace do Diretório de serviços:

   gcloud service-directory services create SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION

   Substitua:

   • SERVICE_NAME: um identificador exclusivo para seu serviço.

4. Crie um endpoint no serviço que contenha as informações de roteamento para o endpoint de VPC de interface do Amazon S3:

   gcloud service-directory endpoints create ENDPOINT_NAME \
       --service=SERVICE_NAME \
       --namespace=NAMESPACE \
       --project=PROJECT_ID \
       --location=REGION \
       --address=S3_VPCE_IP_ADDRESS \
       --port=S3_VPCE_PORT \
       --network=projects/PROJECT_NUMBER/global/networks/VPC_NETWORK

   Substitua:

   • ENDPOINT_NAME: um identificador exclusivo para seu endpoint.
   • S3_VPCE_IP_ADDRESS: o endereço IP do endpoint da VPC de interface do Amazon S3. Por exemplo, 10.0.1.45.
   • S3_VPCE_PORT: o número da porta do endpoint da VPC de interface do Amazon S3. Por exemplo, 443.
   • PROJECT_NUMBER: o número do projeto do Google Cloud. Use o número do projeto na flag --network.
   • VPC_NETWORK: o nome da rede VPC Google Cloud associada à sua interconexão particular.

Configurar a federação

Para consultar seus dados, configure um catálogo federado do Lakehouse que se conecte ao catálogo remoto do Snowflake.

Configurar a autenticação

A federação exige credenciais ou configuração de função para acessar o catálogo remoto do Snowflake. Escolha um dos seguintes métodos.

Baseado em secret (PAT)

Para o método baseado em segredo (PAT), use um token de acesso pessoal (PAT), que é um token de longa duração gerado pelo Snowflake, junto com a função específica do Snowflake necessária para a sessão.

Crie um secret no Secret Manager regional para armazenar as credenciais:

1. Crie um arquivo JSON chamado credentials.json com seu payload:

   {
     "client_secret": "SNOWFLAKE_PAT_TOKEN",
     "scope": "session:role:SNOWFLAKE_ROLE"
   }

   Substitua:

   • SNOWFLAKE_PAT_TOKEN: seu token de acesso pessoal (PAT) do Snowflake.
   • SNOWFLAKE_ROLE: a função específica do Snowflake necessária para a sessão. Por exemplo, ICEBERG_VIEW.
   Observação: o parâmetro client_id não é obrigatório para configurações do Snowflake Horizon porque a autenticação é processada totalmente pelo token PAT e pelo escopo.

2. Configure o endpoint regional do Secret Manager:

   Por padrão, o Secret Manager usa um endpoint global. No entanto, o Lakehouse sem fronteiras exige que seus secrets sejam armazenados na mesma região do catálogo do Lakehouse. Para interagir com Secrets regionais usando a CLI gcloud, substitua o endpoint padrão da API na sessão ou no perfil atual. Para evitar problemas de conectividade, o segredo e o catálogo precisam ser criados na mesma região.

   gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/

   Substitua:

   • REGION: a Google Cloud região em que seu secret do Secret Manager está armazenado. Por exemplo, us-east4. Para evitar problemas de conectividade, o secret e o catálogo precisam ser criados na mesma região.

3. Faça upload da carga útil para o Secret Manager:

   gcloud secrets create SNOWFLAKE_SECRET_NAME \
     --location="REGION" \
     --project="PROJECT_ID" \
     --data-file=credentials.json

   Substitua:

   • SNOWFLAKE_SECRET_NAME: um nome para o secret do Snowflake.
   • PROJECT_ID: o ID do projeto Google Cloud .

Federação de identidade da carga de trabalho

A federação de identidade da carga de trabalho (WIF, na sigla em inglês) evita o uso de secrets de longa duração ao vincular uma conta de serviço do Lakehouse diretamente a um usuário de serviço do Snowflake. Não é necessário fazer nenhuma pré-configuração no Secret Manager antes da criação do catálogo. Continue criando o catálogo federado.

Criar um catálogo federado

Crie o catálogo federado usando o console do Google Cloud , a CLI gcloud ou a API REST.

Console

Para criar um catálogo federado:

1. No console Google Cloud , acesse Lakehouse.

   Acessar Lakehouse

2. Clique em Criar catálogo.

3. Clique em Catálogo federado.

   Os detalhes da Configuração do catálogo aparecem.

4. Em Origem do catálogo federado, selecione Snowflake Horizon.

5. Em Local dos dados, selecione a região do Lakehouse em que você quer criar o catálogo federado. Por exemplo, us-east4. Para minimizar a latência (mesmo na Internet pública), faça o seguinte ao selecionar uma região:

   • Se o catálogo do Snowflake estiver na AWS, selecione a regiãoGoogle Cloud mais próxima da sua região da AWS.

6. Clique em Continuar.

   Os detalhes da conexão aparecem.

7. Na seção Detalhes do catálogo remoto, no campo Identificador da conta do Snowflake, insira o identificador da sua conta do Snowflake. Por exemplo: my_org-my_account.

8. No campo Armazém do Snowflake, insira o nome do seu armazém do Snowflake.

9. Configure os detalhes da autenticação de acordo com o método escolhido:

   • Baseado em secret (PAT): em Secret, insira o nome do secret. Use o seguinte formato: projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME.
   • Federação de identidade da carga de trabalho:no campo Função do Snowflake, insira sua função do Snowflake. Por exemplo: ICEBERG_VIEW.

10. Opcional: no campo Nome do diretório de serviços, insira o caminho para o endpoint ou serviço do Diretório de Serviços. Isso só é necessário se você estiver configurando uma interconexão particular (Interconexão entre nuvens).

11. Clique em Criar.

CLI da gcloud

Baseado em secret (PAT)

Internet pública (sem CCI)

Se você não configurar o CCI, a conexão vai viajar com segurança pela Internet pública.

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS"

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• REGION: a região do Lakehouse em que o catálogo federado é criado. Por exemplo, us-east4. Para minimizar a latência, selecione a região do Google Cloud mais próxima da sua região do Snowflake.
• SNOWFLAKE_SECRET_NAME: o nome do secret do Snowflake.
• SNOWFLAKE_ACCOUNT_IDENTIFIER: o identificador da sua conta do Snowflake (por exemplo, my_org-my_account).
• SNOWFLAKE_WAREHOUSE: o nome do catálogo do Snowflake com que você quer fazer federação.
• REFRESH_INTERVAL (opcional): especifica a frequência com que as informações do catálogo são atualizadas. Defina esse valor como uma duração, por exemplo, 330s ou 5m30s. Intervalos mais curtos atualizam os dados com mais frequência, mas podem custar mais em chamadas de API. Intervalos mais longos podem custar menos, mas os dados consultados podem não refletir seu conjunto de dados mais atual. Se for omitido ou se o valor for definido como 0s, a atualização de metadados em segundo plano não será iniciada. Ele vai permanecer desativado até que o intervalo de atualização seja atualizado para um valor positivo.
• NAMESPACE_FILTERS: opcional. Uma lista separada por vírgulas de namespaces a serem federados. Por exemplo, ns1,ns2. Se omitido, todos os namespaces serão incluídos.

De propriedade do cliente (CCI)

Se você configurou uma interconexão particular (como CCI dedicada ou CCI de parceiro), forneça a referência do endpoint do Diretório de serviços para que o Lakehouse roteie o tráfego de forma privada.

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --secret-name="projects/PROJECT_ID/locations/REGION/secrets/SNOWFLAKE_SECRET_NAME" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME/endpoints/ENDPOINT_NAME"

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• REGION: a região do Lakehouse em que o catálogo federado é criado. Observação: precisa ser a mesma região do namespace do Diretório de Serviços e do secret regional.
• SNOWFLAKE_SECRET_NAME: o nome do secret do Snowflake.
• SNOWFLAKE_ACCOUNT_IDENTIFIER: o identificador da sua conta do Snowflake.
• SNOWFLAKE_WAREHOUSE: o nome do catálogo do Snowflake com que você quer federar.
• REFRESH_INTERVAL (opcional): especifica a frequência com que as informações do catálogo são atualizadas.
• NAMESPACE_FILTERS: opcional. Uma lista separada por vírgulas de namespaces a serem federados.
• NAMESPACE: o namespace do Diretório de serviços que você criou durante a configuração da interconexão particular.
• SERVICE_NAME: o nome do serviço do Diretório de serviços que você criou durante a configuração da interconexão privada.
• ENDPOINT_NAME: o nome do endpoint do Diretório de serviços criado durante a configuração da interconexão particular.

Federação de identidade da carga de trabalho

Internet pública (sem CCI)

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS"

De propriedade do cliente (CCI)

Se você configurou uma interconexão privada, forneça a referência do serviço do Diretório de serviços para que o Lakehouse roteie o tráfego de maneira particular.

gcloud alpha biglake iceberg catalogs create FEDERATED_CATALOG_NAME \
    --project="PROJECT_ID" \
    --primary-location="REGION" \
    --catalog-type="federated" \
    --federated-catalog-type="snowflake" \
    --snowflake-account-identifier="SNOWFLAKE_ACCOUNT_IDENTIFIER" \
    --snowflake-warehouse="SNOWFLAKE_WAREHOUSE" \
    --snowflake-role="SNOWFLAKE_ROLE" \
    --refresh-interval="REFRESH_INTERVAL" \
    --namespace-filters="NAMESPACE_FILTERS" \
    --service-directory-name="projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME/endpoints/ENDPOINT_NAME"

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• SNOWFLAKE_ACCOUNT_IDENTIFIER: o identificador da sua conta do Snowflake.
• SNOWFLAKE_WAREHOUSE: o nome do catálogo do Snowflake com que você quer fazer federação.
• SNOWFLAKE_ROLE: a função específica do Snowflake necessária para a sessão. Por exemplo, ICEBERG_VIEW.
• FEDERATED_CATALOG_NAME: um nome para o catálogo federado do Lakehouse.
• REGION: a região do Lakehouse em que o catálogo federado é criado.
• REFRESH_INTERVAL (opcional): especifica a frequência com que as informações do catálogo são atualizadas. Por exemplo, 300s.
• NAMESPACE_FILTERS: opcional. Uma lista separada por vírgulas de namespaces a serem federados. Por exemplo, ns1,ns2. Se omitido, todos os namespaces serão incluídos.
• NAMESPACE: o namespace do serviço do Diretório de serviços.
• SERVICE_NAME: o nome do serviço do Diretório de Serviços.
• ENDPOINT_NAME: o nome do endpoint do Diretório de serviços.

API REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: PROJECT_ID" \
  -d '{
    "catalog-type": "CATALOG_TYPE_FEDERATED",
    "federated-catalog-options": {
      "snowflake-catalog-info": {
        "account-identifier": "SNOWFLAKE_ACCOUNT_IDENTIFIER",
        "warehouse": "SNOWFLAKE_WAREHOUSE",
        "snowflake-role": "SNOWFLAKE_ROLE"
      },
      "refresh-options": {
        "refresh-schedule": {
          "refresh-interval": "REFRESH_INTERVAL"
        }
      }
    }
}' \
  "https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg_catalog_id=FEDERATED_CATALOG_NAME&primary_location=REGION"

Concluir a configuração da autenticação

Conclua o processo de autenticação usando o tipo escolhido.

Baseado em secret (PAT)

Quando o catálogo é criado, o Lakehouse provisiona uma conta de serviço exclusiva para ele (retornada como biglake-service-account na descrição do recurso).

Você precisa conceder a essa conta de serviço permissão para acessar o secret que criou antes. A propagação das políticas do IAM pode levar alguns minutos.

Conceda à conta de serviço do catálogo permissão para acessar o secret:

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets add-iam-policy-binding SNOWFLAKE_SECRET_NAME \
  --project="PROJECT_ID" \
  --location="REGION" \
  --member="serviceAccount:$(gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
      --project="PROJECT_ID" \
      --location="REGION" \
      --format='value(biglake-service-account)')" \
  --role="roles/secretmanager.secretAccessor"

Para verificar se a conta de serviço do catálogo federado tem acesso ao secret, execute o seguinte comando:

gcloud config set api_endpoint_overrides/secretmanager https://secretmanager.REGION.rep.googleapis.com/
gcloud secrets get-iam-policy SNOWFLAKE_SECRET_NAME \
    --project="PROJECT_ID" \
    --location="REGION"

Na saída, verifique se a conta de serviço biglake-service-account tem o papel roles/secretmanager.secretAccessor atribuído a ela.

Federação de identidade da carga de trabalho

Depois de criar o catálogo, vincule a identidade da conta de serviço a um usuário de serviço no Snowflake.

1. Extraia o ID da conta de serviço do Lakehouse (assunto) dos detalhes do catálogo.

   Você pode encontrar essa informação na resposta JSON do comando de criação (campo biglake-service-account-id).

   Como alternativa, execute o comando de descrição no catálogo para receber o valor:

   gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
     --project="PROJECT_ID"

   Procure o biglake-service-account-id na saída.

2. Faça login na instância de gerenciamento do Snowflake e execute o script a seguir para estabelecer a relação de confiança com a identidade de serviço do Lakehouse:

   USE ROLE ACCOUNTADMIN;
   
   CREATE USER SNOWFLAKE_SERVICE_USER
     TYPE = SERVICE
     WORKLOAD_IDENTITY = (
       TYPE = GCP
       SUBJECT = 'LAKEHOUSE_SERVICE_ACCOUNT_ID'
     )
     DEFAULT_ROLE = SNOWFLAKE_ROLE
     COMMENT = 'Service user for Lakehouse federation over WIF';
   
   -- Also explicitly GRANT permissions to the role
   GRANT ROLE SNOWFLAKE_ROLE TO USER SNOWFLAKE_SERVICE_USER;

   Substitua:

   • SNOWFLAKE_SERVICE_USER: um nome para o novo usuário de serviço no Snowflake.
   • LAKEHOUSE_SERVICE_ACCOUNT_ID: o ID da conta de serviço extraído na etapa anterior.
   • SNOWFLAKE_ROLE: a função do Snowflake (precisa corresponder à função especificada durante a criação do catálogo).

Verifique a conexão

Verifique se o ciclo de atualização dos metadados em segundo plano do catálogo foi concluído com sucesso e se os namespaces estão sincronizados.

CLI da gcloud

1. Verifique se o status da atualização indica sucesso:

   gcloud alpha biglake iceberg catalogs describe FEDERATED_CATALOG_NAME \
     --project="PROJECT_ID" \
     --location="REGION"

2. Confirme se os esquemas de banco de dados remotos aparecem como namespaces sincronizados:

   gcloud alpha biglake iceberg namespaces list \
     --catalog="FEDERATED_CATALOG_NAME" \
     --project="PROJECT_ID" \
     --location="REGION"

API REST

1. Verifique o status da sincronização da federação de catálogos:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME"

2. Liste os namespaces sincronizados:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME/namespaces"

3. Liste as tabelas em um namespace sincronizado:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME/namespaces/NAMESPACE_NAME/tables"

A seguir

• Usar tabelas de consulta e do Lakehouse sem bordas.
• Resolver problemas do Lakehouse sem bordas.