Migração de tabelas Apache Iceberg para OCI: como preservar metadados e garantir consultabilidade

TL;DR: Migrar tabelas Apache Iceberg não é copiar arquivos Parquet. É preciso transportar metadados, manifests, snapshots e registrar a tabela em um catálogo no destino. Este artigo mostra um padrão comprovado usando Terraform, OCI Object Storage, Spark e um catálogo JDBC, com validação via SQL. Para empresas brasileiras, o principal aprendizado é que a migração deve ser tratada como um workflow de lakehouse, não como um simples movimento de objetos.

Por que uma migração Iceberg vai além da cópia de arquivos?

Modern data lakes não são mais apenas coleções de arquivos. Com Apache Iceberg, a tabela é definida por arquivos de dados, metadados, manifests, snapshots e uma entrada de catálogo que informa aos query engines qual é a versão atual da tabela. Essa estrutura permite schema evolution, time travel e leituras consistentes em escala. Porém, ela também muda o significado de "migração".

Quando uma organização move workloads de analytics para Oracle Cloud Infrastructure (OCI), copiar apenas arquivos Parquet não é suficiente. A migração precisa preservar os metadados da tabela Iceberg e tornar a tabela copiada consultável no ambiente de destino. O objetivo não é simplesmente mover objetos de um bucket para outro, mas provar que Spark, Trino ou outro engine consegue ler a tabela depois que ela chega no OCI.

Uma jornada típica começa com uma tabela de lakehouse de origem que já tem valor de negócio, um bucket de Object Storage de destino no OCI e uma pergunta simples, mas crítica: depois que os arquivos forem movidos, a tabela ainda se comportará como a mesma tabela?

O processo descrito nesta solução percorre essa jornada de ponta a ponta. Ele cria uma fonte Iceberg realista, transporta seus dados e metadados para o OCI, registra a tabela em um catálogo e a valida com SQL. As ações individuais são automatizadas com Terraform e scripts auxiliares, mas a história é sobre como provar um padrão de migração.

O desafio da migração: manter a relação entre dados e metadados

Iceberg separa os dados da tabela do estado da tabela. Arquivos de dados contêm as linhas, enquanto arquivos JSON de metadados, manifest lists e manifests descrevem quais arquivos pertencem a cada snapshot. Se uma migração perder essa relação, os arquivos copiados podem existir no Object Storage, mas a tabela não será utilizável.

Isso é especialmente importante em migrações de lakehouse entre nuvens. Uma tabela de origem pode estar atrás de uma API compatível com S3, enquanto a tabela de destino está armazenada no OCI Object Storage e lida por meio do endpoint S3-compatible do OCI. Os paths da tabela, a configuração do catálogo e as credenciais de runtime precisam estar alinhados para que a migração seja bem-sucedida.

Esta solução foca em provar o padrão central de forma controlada: gerar uma tabela Iceberg real, mover seus arquivos para o OCI Object Storage, registrar os metadados copiados em um catálogo de destino e validar o resultado com SQL.

Simulação realista com MinIO: validando o padrão sem dependência externa

Em muitos ambientes de demonstração ou desenvolvimento, o acesso a um S3 real da AWS não está disponível. Para manter o workflow reproduzível, a solução usa o MinIO como um endpoint de origem S3-compatible simulado.

O ponto importante é que apenas o endpoint de armazenamento de origem é simulado. A tabela Iceberg em si é real. O Spark cria uma pequena tabela sales.orders, escreve arquivos Parquet, cria arquivos JSON de metadados Iceberg e gera os manifests e informações de snapshot que uma tabela Iceberg real exige.

Isso dá ao fluxo de migração um layout de objetos de origem realista, sem depender de credenciais AWS externas. O MinIO comprova o padrão de layout de objetos e acesso S3-compatible necessário para esta demonstração controlada, mas não se destina a validar todos os detalhes de produção do AWS S3, como comportamento IAM, rede, integrações de catálogo de origem existentes ou restrições operacionais em grande escala.

O workflow também ajuda a evitar um falso positivo comum: fazer upload de pastas ou arquivos de amostra e supor que isso comprova uma migração Iceberg. Não comprova. A prova vem quando um query engine consegue registrar e ler a tabela migrada usando metadados Iceberg reais.

OCI como base do lakehouse: infraestrutura provisionada com Terraform

O Terraform provisiona o lado OCI do ambiente: rede, uma VM compute e um bucket Object Storage. O cloud-init transforma a VM em uma pequena workbench de migração, instalando Docker, Spark, pacotes runtime do Apache Iceberg, PostgreSQL, Hive Metastore para comparação, OCI CLI, AWS CLI e scripts auxiliares.

• Spark e Iceberg geram a tabela de origem contra o endpoint S3 simulado.
• As pastas data/ e metadata/ geradas são exportadas localmente.
• O OCI CLI copia esses arquivos para o OCI Object Storage usando autenticação instance principal.
• Spark encontra o último metadata JSON do Iceberg no Object Storage e registra a tabela copiada em um catálogo Iceberg JDBC apoiado por PostgreSQL.
• Spark valida a tabela descrevendo-a e executando uma query de contagem de linhas.
• Opcionalmente, o Trino pode validar que outro engine SQL consegue ler a mesma tabela Iceberg.

Essa arquitetura mantém o workflow simples o suficiente para uma demonstração, ao mesmo tempo em que preserva as peças que importam em uma migração real: object storage, registro de catálogo, credenciais de runtime e validação de queries.

Por que preservar o caminho lógico da tabela?

Uma escolha de design nesta demonstração controlada é preservar o mesmo caminho lógico s3://bucket/prefix da tabela. O Spark é configurado para rotear esse caminho estilo S3 para o OCI Object Storage por meio do endpoint S3-compatible do OCI.

Esta é uma suposição deliberada de demonstração, não uma regra universal de migração. Funciona quando a nomenclatura do bucket e prefixo, o roteamento do endpoint e a configuração de runtime são intencionalmente alinhados para que o caminho lógico da tabela permaneça estável depois que os arquivos chegarem ao OCI.

Isso evita a reescrita de metadados no caminho comprovado da demonstração. Isso importa porque os caminhos Iceberg podem aparecer não apenas em arquivos JSON de metadados, mas também em manifest lists e manifests em Avro. Uma simples substituição de string não é uma estratégia de migração segura para tabelas de produção.

Ao manter o caminho lógico estável, o workflow pode registrar a tabela copiada a partir de seu arquivo de metadados mais recente e deixar o Iceberg resolver o estado da tabela normalmente. Se uma migração de produção alterar nomes de bucket, prefixos ou esquemas URI, essa mudança de caminho deve ser tratada com uma abordagem de migração consciente do Iceberg, em vez de edição ad hoc de arquivos.

Catálogo e validação: o verdadeiro teste da migração

O caminho funcional da demonstração usa um catálogo Iceberg JDBC apoiado por PostgreSQL. O PostgreSQL armazena o estado do catálogo; os arquivos de dados e metadados da tabela Iceberg permanecem no object storage. O Hive Metastore é instalado na VM para comparação e testes futuros, mas o fluxo de registro comprovado usa o catálogo JDBC porque ele suporta claramente a estratégia atual de caminho do Object Storage.

Após a cópia dos arquivos, o script de registro descobre o último arquivo *.metadata.json sob o prefixo da tabela de destino. O Spark então chama o procedimento register_table do Iceberg e valida a tabela por meio de SQL.

A validação padrão verifica se a tabela pode ser listada, descrita e consultada. A validação opcional com Trino adiciona uma verificação de segundo engine, configurando o Trino com o mesmo catálogo JDBC e acesso ao OCI Object Storage.

Essa validação com segundo engine é útil, mas não deve ser tratada como certificação exaustiva de produção. Ela prova que outro engine SQL consegue ler essa tabela registrada com a mesma configuração de catálogo e armazenamento; a prontidão para produção ainda depende dos engines de destino, modelo de segurança, escala de workload e requisitos operacionais.

Segurança e operação: separando infraestrutura de credenciais de acesso

A solução separa o provisionamento de infraestrutura do acesso a dados em runtime. O Terraform cria os recursos OCI, mas as secret keys compatíveis com S3 não são armazenadas em variáveis Terraform, tfvars, outputs, logs ou state.

A operação de cópia usa o OCI CLI com autenticação instance principal. Spark e Trino usam a camada de I/O de arquivos S3 do Iceberg, portanto exigem credenciais S3-compatible do OCI em runtime. Uma versão futura de produção poderia recuperar essas credenciais do OCI Vault, mas a demonstração já as mantém fora do estado do Terraform.

Essa separação é importante para um processo de migração reproduzível. A infraestrutura deve ser reproduzível, enquanto as credenciais de acesso a dados devem permanecer preocupações de runtime.

O que este padrão comprova?

• A infraestrutura OCI pode ser criada de forma consistente com Terraform.
• Uma tabela Iceberg de origem real pode ser gerada sem acesso AWS externo.
• Arquivos de dados e metadados Iceberg podem ser copiados para o OCI Object Storage.
• A tabela copiada pode ser registrada em um catálogo Iceberg.
• Spark pode validar a tabela migrada.
• Trino pode opcionalmente validar o acesso a partir de um segundo engine SQL na mesma configuração controlada.

O resultado é uma base focada e prática para discussões de migração de lakehouse. Não pretende automatizar todos os cenários de cutover de produção, todo catálogo de origem, todo mapeamento de segurança AWS-para-OCI ou reescrita de metadados para mudanças arbitrárias de caminho. Em vez disso, prova o fluxo central de preservação de tabela que toda migração Iceberg precisa: mover os arquivos, preservar os metadados, registrar a tabela e consultá-la no OCI.

Conclusão

Migrações de Apache Iceberg exigem mais do que cópia de objetos. Exigem compreensão de como a tabela é representada, onde os metadados residem, como o catálogo vê a tabela e como os query engines acessam o armazenamento de destino.

Ao combinar Terraform, OCI Object Storage, Spark, catálogo Iceberg JDBC, PostgreSQL e validação opcional com Trino, esta solução cria uma maneira reproduzível de demonstrar esse processo no OCI. Ela transforma a migração de um exercício de movimentação de arquivos em um workflow de lakehouse validado, onde a prova final é simples: a tabela chega ao OCI e pode ser consultada com sucesso.

Perguntas Frequentes

• Por que copiar apenas arquivos Parquet não é suficiente para migrar tabelas Iceberg?
  Porque o Iceberg separa dados de metadados. Arquivos Parquet contêm apenas as linhas; os metadados (JSON, manifests, snapshots) definem a estrutura e o estado da tabela. Sem eles, a tabela não é reconhecida por query engines.

• O uso do MinIO como simulação de origem é válido para produção?
  Não. O MinIO simula o layout de objetos e o acesso S3-compatible, mas não valida comportamento IAM, integrações de catálogo existentes ou restrições operacionais da AWS real. É uma ferramenta de demonstração, não de validação de produção.

• O que fazer se o caminho da tabela mudar durante a migração?
  A solução recomenda preservar o caminho lógico para evitar reescrita de metadados. Se a mudança for inevitável, deve-se usar uma abordagem de migração consciente do Iceberg, e não substituição simples de string, pois caminhos podem aparecer em arquivos Avro e manifests.

• É seguro armazenar credenciais S3 no Terraform?
  Não. A solução separa infraestrutura (Terraform) de credenciais de runtime. As secret keys compatíveis com S3 não são armazenadas em variáveis, logs ou state. A cópia usa OCI CLI com instance principal, e Spark/Trino exigem credenciais em runtime, de preferência obtidas de um cofre como OCI Vault.

• O que a validação com Trino realmente comprova?
  Comprova que um segundo engine SQL consegue ler a tabela registrada com a mesma configuração de catálogo e armazenamento. Não certifica a prontidão para produção, que depende de fatores como escala, segurança e requisitos operacionais específicos.

---

Artigo originalmente publicado por Adina Nicolescu em cloud-infrastructure.