Pular para o conteúdo principal

ADR-007: Estratégia do adaptador AWS Glue Iceberg

Status​

Accepted

Context​

ContractForge precisa de um segundo adaptador de plataforma para validar que o núcleo é genuinamente neutro em termos de plataforma. AWS tem vários caminhos de ingestão possíveis:

  • AWS Glue Spark;
  • AWS Glue Data Catalog;
  • Apache Iceberg tables on S3;
  • Lake Formation;
  • Athena;
  • EMR Serverless;
  • AppFlow;
  • DMS;
  • conectores de fornecedor e mercado.

Um "adaptador AWS" genérico ocultaria muitas diferenças de tempo de execução e provavelmente comprometeria demais a portabilidade. O adaptador precisa de um primeiro alvo claro.

Decision​

O primeiro destino do adaptador AWS é aws_glue_iceberg.

Ele usa:

  • AWS Glue Spark como o tempo de execução principal;
  • Apache Iceberg em S3 como formato de tabela principal;
  • AWS Glue Catálogo de Dados como o catálogo de tabelas;
  • AWS Lake Formation como meta de governança;
  • Tabelas Iceberg como armazenamento de evidências padrão.

Other AWS paths are modeled as future subtargets:

  • aws_athena_iceberg;
  • aws_emr_serverless_iceberg;
  • aws_native_passthrough.

A implementação declara recursos, retorna objetos PlanningResult principais, renderiza artefatos de revisão, renderiza Iceberg DDL para tabelas de evidências/controle canônicas e gera scripts Glue Spark/Iceberg para caminhos de acréscimo, substituição, upsert e hash-diff.

O pacote base permanece importável sem dependências AWS SDK. Auxiliares de tempo de execução opcionais podem publicar artefatos no S3, criar ou atualizar trabalhos Glue, iniciar/aguardar execuções de trabalhos Glue e mapear metadados de execução Glue em registros de evidências. Esses auxiliares devem importar SDKs AWS lentamente ou aceitar clientes fornecidos pelo chamador.

Consequences​

Positive​

  • O núcleo pode ser validado em um adaptador não Databricks sem introduzir dependências AWS SDK.
  • O adaptador pode retornar resultados honestos de SUPPORTED, SUPPORTED_WITH_WARNINGS, REVIEW_REQUIRED e UNSUPPORTED.
  • Os detalhes de implementação do AWS, como os marcadores Glue, ficam fora do núcleo.
  • Os esquemas de tabelas de evidências/controle permanecem de propriedade principal; AWS apenas os renderiza como tabelas Iceberg.
  • O adaptador pode evoluir por subalvo em vez de se tornar um objeto divino.

Negative​

  • A execução do AWS pertence ao adaptador e é opcional; existem auxiliares de implantação, mas o núcleo permanece livre de execução e livre de SDK.
  • histórico, exclusão reversível de instantâneo e mapeamentos de acesso Lake Formation são inicialmente necessários para revisão.
  • O modelo atual de capacidade central é menos expressivo do que o AWS eventualmente precisa.

Política de Capacidade Inicial​

O destino aws_glue_iceberg declara acréscimo, substituição, mesclagem, comparação de hash, evolução de esquema, transformações, forma e qualidade de expressão como suportados.

Anexar, substituir, upsert do estado atual e upsert hash-diff geraram scripts de tempo de execução Glue Spark. A diferença de hash permanece SUPPORTED_WITH_WARNINGS até que o desempenho e o comportamento de simultaneidade sejam validados de forma mais ampla.

Ele marca essa semântica como necessária para revisão:

  • historical;
  • snapshot_reconcile_soft_delete;
  • row_filters;
  • column_masks;
  • algumas combinações de streaming disponíveis agora, quando a semântica de ponto de verificação/gravação não pode ser preservada.

Tipos de origem específicos de Databricks, como autoloader, não são suportados. Os contratos devem usar incremental_files portátil quando a intenção é verificar a descoberta de novos arquivos.

Alternatives Considered​

Adaptador genérico AWS​

Rejeitado. AWS tem muitos caminhos de execução materialmente diferentes. Um único adaptador genérico prometeria demais ou ocultaria decisões significativas em tempo de execução.

Athena First​

Rejeitado como primeiro alvo. Athena é valioso para acesso SQL e Iceberg, mas não é um executor de ingestão completo para semântica ContractForge.

EMR Serverless First​

Adiado. EMR Serverless oferece mais controle do que Glue, mas aumenta a superfície de configuração para a primeira prova AWS.

Passagem nativa primeiro​

Rejeitado como base. AppFlow e DMS são importantes, mas validam a delegação do conector nativo em vez da semântica de ingestão principal.

Follow-up Work​

  • Mantenha o esqueleto do pacote do adaptador AWS e a divisão do domínio alinhados com o estilo do adaptador Databricks.
  • Mantenha os testes para o planejamento principal com recursos AWS, limites de renderização e auxiliares de tempo de execução.
  • Manter a renderização de revisão e a renderização de script Glue Spark para acréscimo, substituição, upsert e comparação de hash.
  • Mantenha a evidência/estado Iceberg DDL renderizado a partir do modelo de evidência principal.
  • Preserve o caminho de implantação de um comando por meio do contractforge-aws deploy.
  • Valide a mesclagem do Iceberg e o desempenho do hash-diff antes de promover o upsert do hash-diff sem aviso prévio.
  • Valide a equivalência histórica, de exclusão reversível de instantâneo e de filtro de dados Lake Formation antes de promover essa semântica além da revisão.
  • Projete metadados de capacidade mais ricos somente depois que o esqueleto AWS comprovar a necessidade.