domnikl/schema-registry-gitops

schema-registry-gitops

https://github.com/domnikl/schema-registry-gitops/workflows/build/badge.svg](https://github.com/domnikl/schema-registry-gitops/actions)

通过应用期望状态文件，管理Confluent Schema Registry的主题、兼容性级别和模式注册。

概述

Schema Registry GitOps是一款基础设施即代码工具，通过简单的YAML和Avro/Protobuf/JSON Schema文件配置期望状态，并将其应用到模式注册表。可保留模式的版本控制历史，在CI/CD pipeline中使用常用工具验证、审查、合并和演进模式。

!https://raw.githubusercontent.com/domnikl/schema-registry-gitops/main/schema-registry-gitops.svg

核心功能与特性

• 基础设施即代码管理：通过YAML定义模式注册表期望状态，支持版本控制与审计追踪
• 多模式类型支持：兼容Avro、Protobuf和JSON Schema（Schema Registry ≥5.5支持Protobuf/JSON）
• 兼容性控制：配置全局和主题级兼容性（如NONE、BACKWARD、FULL_TRANSITIVE等）
• 模式引用：定义模式间引用关系，需确保被引用模式已存在于注册表
• CI/CD集成：支持计划（plan）、应用（apply）和状态导出（dump）操作，适配自动化流程
• 安全配置：通过属性文件或环境变量配置连接，支持SSL等安全设置

使用场景

• 模式版本控制：通过Git管理模式变更历史，实现可追溯的模式演进
• 团队协作：结合代码审查流程，确保模式变更经验证后应用
• 自动化部署：在CI/CD中自动验证兼容性、计划变更并应用到注册表
• 多环境同步：在开发、测试和生产环境间同步模式配置，保障一致性

使用方法

命令行用法

Usage: schema-registry-gitops [-hvV] [--properties=<propertiesFilePath>]
                              [-r=<baseUrl>] [COMMAND]
通过基础设施即代码管理模式注册表
  -h, --help                 显示帮助信息并退出
      --properties=<propertiesFilePath>
                             客户端配置的Java Properties文件（可选）
  -r, --registry=<baseUrl>   模式注册表端点，覆盖properties中的'schema.registry.url'，可指定逗号分隔的多个URL
  -v, --verbose              启用详细日志
  -V, --version              打印版本信息并退出
命令:
  apply  将状态应用到指定的模式注册表
  dump   打印当前状态
  plan   验证并计划模式变更，查看所有待执行变更

查看特定命令帮助：schema-registry-gitops <命令> -h

Docker运行示例

通过https://hub.docker.com/repository/docker/domnikl/schema-registry-gitops%E8%8E%B7%E5%8F%96%E9%95%9C%E5%83%8F%EF%BC%8C%E7%A4%BA%E4%BE%8B%EF%BC%9A

sh
# 计划变更（查看待应用内容）
docker run -v "$(pwd)/examples":/data domnikl/schema-registry-gitops plan --properties /data/client.properties /data/base.yml

# 应用变更
docker run -v "$(pwd)/examples":/data domnikl/schema-registry-gitops apply --registry http://schema-registry:8081 /data/base.yml

# 导出当前状态
docker run -v "$(pwd)/output":/data domnikl/schema-registry-gitops dump --registry http://schema-registry:8081 > /data/current_state.yml

建议使用标签版本（如:v1.0.0）确保稳定性。

状态文件格式

通过YAML定义期望状态，支持多文件合并（后定义主题覆盖同名先定义主题）。示例：

yaml
# 全局兼容性级别（可选）
compatibility: FULL_TRANSITIVE
subjects:
  # 引用外部文件的主题
  - name: my-new-subject-referencing-a-schema-file
    compatibility: BACKWARD  # 主题级兼容性（可选，覆盖全局）
    file: my-actual-schema.avsc  # 路径相对于当前YAML
    type: AVRO  # 模式类型（默认AVRO，≥5.5支持PROTOBUF/JSON）
    references:  # 模式引用（可选）
      - name: dev.domnikl.schema-registry-gitops.User  # 引用名称（含命名空间）
        subject: User-value  # 被引用模式的主题名
        version: 1  # 被引用模式版本

  # 内联模式的主题（Protobuf示例）
  - name: my-new-inline-schema-subject
    schema: 'syntax = "proto3";
        package com.acme;
        
        message OtherRecord {
          int32 an_id = 1;
        }'
    type: PROTOBUF

兼容性级别

支持值：NONE、FORWARD、BACKWARD、FULL、FORWARD_TRANSITIVE、BACKWARD_TRANSITIVE、FULL_TRANSITIVE

模式定义方式

• file：外部模式文件路径（相对当前YAML）
• schema：内联模式字符串（二选一，推荐使用file）

配置说明

Properties文件配置

通过Java Properties文件配置客户端，示例（含SSL）：

properties
schema.registry.url=https://localhost:8081
security.protocol=SSL
schema.registry.ssl.truststore.location=truststore.jks
schema.registry.ssl.truststore.password=<secret>
schema.registry.ssl.keystore.location=keystore.jks
schema.registry.ssl.keystore.password=<secret>
schema.registry.ssl.key.password=<secret>

使用--properties参数指定文件：

sh
docker run -v "$(pwd)/config":/config domnikl/schema-registry-gitops apply --properties /config/client.properties /config/state.yml

环境变量配置

支持前缀SCHEMA_REGISTRY_GITOPS_的环境变量，覆盖Properties配置。示例：

sh
export SCHEMA_REGISTRY_GITOPS_SCHEMA_REGISTRY_URL=https://localhost:8081
export SCHEMA_REGISTRY_GITOPS_SECURITY_PROTOCOL=SSL
export SCHEMA_REGISTRY_GITOPS_SCHEMA_REGISTRY_SSL_TRUSTSTORE_LOCATION=truststore.jks
export SCHEMA_REGISTRY_GITOPS_SCHEMA_REGISTRY_SSL_TRUSTSTORE_PASSWORD=<secret>

Docker传递环境变量：

sh
docker run -e SCHEMA_REGISTRY_GITOPS_SCHEMA_REGISTRY_URL=http://schema-registry:8081 -v "$(pwd)/examples":/data domnikl/schema-registry-gitops plan /data/base.yml

删除主题 ⚠️

默认不删除状态文件中未列出但注册表存在的主题。如需完全同步（删除未列出主题），在plan/apply中使用-d或--enable-deletes：

sh
docker run -v "$(pwd)/examples":/data domnikl/schema-registry-gitops apply -d --registry http://localhost:8081 /data/base.yml

开发说明

使用Docker构建和测试：

sh
# 构建镜像
docker build -t domnikl/schema-registry-gitops .

# 运行测试
docker run -v ./examples:/data domnikl/schema-registry-gitops plan --registry http://localhost:8081 /data/base.yml /data/with_references.yml

致谢

灵感源自https://github.com/devshawn%E7%9A%84https://github.com/devshawn/kafka-gitops%E3%80%82%E6%84%9F%E8%B0%A2Confluent%E5%BC%80%E5%8F%91Schema Registry及客户端库。