Apicurio Registry 2.4 发行注记
红帽构建的 Apicurio Registry 的新内容
摘要
前言 复制链接链接已复制到粘贴板!
使开源包含更多
红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始:master、slave、黑名单和白名单。由于此项工作十分艰巨,这些更改将在即将推出的几个发行版本中逐步实施。详情请查看 CTO Chris Wright 的信息。
第 1 章 apicurio Registry 发行注记 复制链接链接已复制到粘贴板!
红帽构建的 Apicurio Registry 2.4 作为正式发行版本提供。Apicurio Registry 是标准事件模式和 API 设计的数据存储,它基于 Apicurio Registry 开源社区项目。
红帽构建的 Apicurio Registry 是 Red Hat Integration Service Registry 的新产品名称。红帽构建的 Apicurio Registry 2.x 和 Red Hat Integration Service Registry 2.x 的功能相同。
您可以使用 Apicurio Registry 使用 Web 控制台、REST API、Maven 插件或 Java 客户端管理和共享数据的结构。例如,客户端应用程序可以在不需要重新部署的情况下动态推送或从 Apicurio Registry 中拉取最新的 schema 更新。您还可以创建可选规则来管理 Apicurio Registry 内容如何随时间发展。这些规则包括验证内容、工件引用的完整性,以及向后兼容或转发 schema 或 API 版本的兼容性。
1.1. apicurio Registry 安装选项 复制链接链接已复制到粘贴板!
您可以使用以下数据存储选项之一在 OpenShift 上安装 Apicurio Registry:
- PostgreSQL 数据库
- Red Hat AMQ Streams
如需了解更多详细信息,请参阅在 OpenShift 上安装和部署红帽构建的 Apicurio Registry。
1.2. apicurio Registry 支持的平台 复制链接链接已复制到粘贴板!
Apicurio Registry 2.4 支持以下核心平台:
- Red Hat OpenShift Container Platform 4.14, 4.13, 4.12, 4.11
- Red Hat OpenShift Service on AWS
- Microsoft Azure Red Hat OpenShift
- PostgreSQL 15、14、13、12
- Red Hat AMQ Streams 2.5, 2.2
- OpenJDK 17, 11
如需了解更多详细信息,请参阅以下文章:
1.2.1. 支持的与其他产品集成 复制链接链接已复制到粘贴板!
Apicurio Registry 2.4 还支持与以下产品集成:
- Red Hat Single Sign-On (RH-SSO) 7.6
- Red Hat build of Debezium 2.1
1.2.2. Operator 元数据版本 复制链接链接已复制到粘贴板!
有关用于安装和部署 Apicurio Registry 的对应 Service Registry Operator 元数据版本的详情,请查看以下文章:
1.3. apicurio Registry 新功能 复制链接链接已复制到粘贴板!
apicurio Registry 2.4 包括以下新功能:
Apicurio Registry 核心新功能
- 工件参考改进
- 工件参考完整性规则 :您现在可以应用新的特定于工件的规则和全局规则,以便在创建或更新工件时强制实施工件引用的完整性。对于所有工件类型,该规则会检测重复的工件引用,并防止引用不存在的工件。对于工件类型的子集(Apache Avro、Google Protobuf、OpenAPI 和 AsyncAPI),该规则可确保所有工件引用都已映射。
- Maven 插件中的自动工件引用检测 :对于工件类型的子集(Apache Avro、Google Protobuf 和 JSON Schema),在创建或更新工件时,Maven 插件现在可以自动识别并配置给定工件的所有工件引用。
- Web 控制台中的工件引用 的视觉化:您可以在新的 References 选项卡中查看工件版本的入站和出站引用。REST API 现在支持检索入站和出站引用。在以前的版本中,REST API 只检索出站引用,Web 控制台不会显示引用。
- 工件引用现在被视为内容 :此版本现在在计算内容哈希和 ID 时考虑工件引用,并在检查工件版本的兼容性时考虑工件引用。如果您上传具有不同引用的同一模式内容,您可以创建一个新的工件版本。
- OpenAPI 的客户端 SDK 生成
- 此发行版本添加了一个新的 Web 控制台功能,以便用户从 OpenAPI 工件生成客户端 SDK。此功能使用 Microsoft 中的 Kiota 生成 SDK。该功能仅在浏览器中运行,无法使用 API 自动执行。如需更多信息,请参阅 https://github.com/microsoft/kiota。
- 工件版本删除
- 此发行版本在 web 控制台中添加了新的 REST API 操作和新的 Delete 工件版本 设置,以便您通过使用 REST API 删除工件版本。在以前的版本中,工件版本不可变;您可以弃用或禁用它们,但不能删除它们。但是,有时需要删除工件版本,尽管语义有意义。例如,出于规范或策略的原因,您可能需要删除工件版本。
- Core Registry REST API 的改进
- 版本注释 API :您现在可以使用 REST API 向工件版本添加注释。Web 控制台中还不能使用管理注释。
-
export API 支持 Accept 标头中的 application/json :您现在可以在调用
/admin/exportAPI 端点中发送application/json作为Accept标头的值。在以前的版本中,返回application/json格式的响应的唯一方法是使用forBrowser查询参数。现在,您可以使用查询参数或Accept标头。 - 组管理 :您现在可以使用 REST API 直接管理工件组,而不是隐式作为工件创建的一部分。
- Confluent 兼容性 REST API 的改进
- 更新了对 Confluent 兼容性 API 的支持:添加了对 Confluent Schema Registry API 的版本 7 的支持。Apicurio Registry 现在支持不同端点上的 v6 和 v7。
-
可自定义的最多主题数 :现在,您可以使用
registry.ccompat.max-subjects动态配置属性来自定义ccompatAPI 返回的最大主题数量。 -
为组自定义添加了标头 :在使用 Confluent Schema Registry API v7 时,您现在可以使用
X-Registry-GroupId标头来指定工件组。如果不使用此标头,则假定所有工件都位于默认组中。
- 支持在 Microsoft Azure Active Directory 中进行身份验证
- 添加了对在 Microsoft Azure 中使用 Active Directory 身份验证的支持,以访问 Core Registry REST API 和 web 控制台。如需了解更多详细信息,请参阅使用 Azure Active Directory 保护 Apicurio Registry 2.4.x 的 Apicurio 博客文章。
- 支持 HTTPS 透传入口
提供配置变量以避免在使用带有 HTTPS 透传入口部署 Apicurio Registry 时重定向问题:
-
REGISTRY_URL_OVERRIDE_HOST- 覆盖用于生成外部访问 URL 的主机名。 REGISTRY_URL_OVERRIDE_PORT- 覆盖用于生成外部访问 URL 的端口。当使用 HTTPS passthrough ingress 或 route 部署 Apicurio Registry 时,这些主机和端口覆盖很有用。在这些情况下,重复使用重定向的请求 URL 和端口不属于客户端使用的实际外部 URL,因为请求被代理。然后,重定向会失败,因为目标 URL 无法访问。
-
- 其他更改
-
为基本身份验证配置客户端凭证流范围 : Apicurio Registry 使用客户端凭证流代表用户请求访问令牌,在使用基本身份验证时。此功能允许用户配置
scope请求参数。 -
serializer/deserializer 工件解析和内容哈希的解析 :SerDe 类现在可以使用 schema 的内容哈希解析工件协调。
- Maven 插件选项为 minify Avro: 当使用 Maven 插件注册 Avro 模式时,您现在可以在注册前减去内容。
-
为基本身份验证配置客户端凭证流范围 : Apicurio Registry 使用客户端凭证流代表用户请求访问令牌,在使用基本身份验证时。此功能允许用户配置
- community-only :自定义工件类型
用户可以根据自己的自定义工件类型扩展 Apicurio Registry,并删除对现有类型的支持。此功能仅适用于 Apicurio Registry 的社区版本,且不被支持。
注意为了提供此功能,REST API 中的
ArtifactType从enum改为一个简单的字符串。如果您使用 REST API 客户端进行自定义集成,则可能需要在升级到较新的客户端后编辑代码。
Apicurio Registry Operator 新功能
- 对 HTTPS 的 Operator 支持
-
添加了对在 OpenShift 集群中配置 HTTPS 连接的支持。您可以分别创建包含证书和私钥的 Secret,名为
tls.crt和tls.key,并通过在ApicurioRegistry自定义资源定义(CRD)文件中设置spec.configuration.security.https.secretName字段来引用 Secret。然后 Apicurio Registry Operator 可以在 Apicurio RegistryService资源上配置 HTTPS 端口。如果启用了 HTTPS,您可以通过将spec.security.https.disableHttp设置为true来禁用 HTTP 连接。 - 支持手动管理的 OpenShift 资源
现在,您可以禁用某些资源类型,以确保 Apicurio Registry Operator 不会创建和管理这些资源,以便您可以手动配置它们。使用 Apicurio Registry Operator 当前不支持的功能,手动配置为您提供了更大的灵活性。如果您禁用资源类型,则其现有实例将被删除。如果启用资源类型,Apicurio Registry Operator 会尝试使用 app 标签(如
app=example-apicurioregistry)查找资源,并开始管理它。否则,Apicurio Registry Operator 会创建一个新实例。您可以以这种方式禁用以下资源类型:-
入口 -
NetworkPolicy -
PodDisruptionBudget
-
- 改进了日志级别配置
-
现在,您可以使用
ApicurioRegistryCRD 文件中的spec.configuration.registryLogLevel字段,更轻松地为 Apicurio Registry 和 Apicurio Registry Operator 设置日志级别。这个新字段设置 Apicurio 应用程序组件的日志级别(不包括非Apicurio 组件和库),这与spec.configuration.logLevel字段(适用于非Apicurio 组件和库)不同。现在,您可以通过在 OperatorDeployment资源中设置LOG_LEVEL环境变量,为 Apicurio Registry Operator 设置日志级别。有效的LOG_LEVEL值是debug、info、warn和error。 - CORS 允许的源
服务器可以使用 Cross-Origin Resource Sharing (CORS)机制来控制响应是否与请求的来源共享。Apicurio Registry Operator 现在根据
ApicurioRegistryCRD 文件中的spec.deployment.host和spec.configuration.security.keycloak.url字段设置CORS_ALLOWED_ORIGINS环境变量。此环境变量控制 Apicurio Registry 发送的Access-Control-Allow-Origin标头。如果使用自定义
Ingress(例如,配置 HTTPS),您可以通过将spec.deployment.managedResources.disable字段设置为Ingresstrue来禁用 Operator 管理的 Ingress,仍然将spec.deployment.host字段设置为适当的值。如果要配置完全自定义的 CORS 策略,您可以使用spec.deployment.env字段手动设置CORS_ALLOWED_ORIGINS环境变量。- 使用 pod 模板配置 Apicurio Registry 部署
ApicurioRegistryCRD 文件现在包含spec.deployment.podTemplateSpecPreview字段作为技术预览功能。spec.deployment.podTemplateSpecPreview字段的结构与 OpenShiftDeployment资源(PodTemplateSpecstruct)中的spec.template字段相同。通过一些限制,Apicurio Registry Operator 将来自此字段的数据转发到 Apicurio RegistryDeployment资源中的对应字段。此功能提供更大的灵活性,而无需 Apicurio Registry Operator 原生支持每个用例。重要技术预览功能不受红帽产品服务等级协议(SLA)支持,且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能,并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息,请参阅技术预览功能支持范围。
apicurio Registry 用户文档和示例
文档库已更新,使用版本 2.4 中的新功能:
开源演示应用程序也已更新:
1.4. apicurio Registry 已弃用的功能 复制链接链接已复制到粘贴板!
Apicurio Registry 核心已弃用的功能
- Confluent Schema Registry API 版本 6 (compatibility API): Apicurio Registry 目前支持独立端点上的 Confluent Schema Registry API 的两个版本:版本 6 和版本 7。使用版本 6 已被弃用;v6 API 端点将在以后的版本中删除。确保您将对 v6 端点的所有引用替换为对 v7 API 端点的引用。
- Apicurio Registry Core API 版本 1: Apicurio Registry 支持 Apicurio Registry Core API (版本 1)现已弃用,旧的 API 将在下一个主发行版本中删除。
-
动态日志级别配置 :
/admin/loggers和/admin/loggers/{logger}API 端点现在在 Apicurio Registry Core API (v2)中被弃用。这些端点将在以后的发行版本中被删除。 - Registry V1 export 工具: Apicurio Registry 对命令行导出工具的支持现已弃用。导出工具用于将 Apicurio Registry 1.x 中的数据导出为可导入到 2.x 的格式,将不再发布或维护。所有客户都应该已从 1.x 升级到 2.x。
Apicurio Registry Operator 已弃用的功能
-
通过编辑 Deployment 资源来设置环境变量 :在以前的版本中,您可以通过直接编辑其
Deployment资源( Apicurio Registry Operator 支持)来为 Apicurio Registry 设置环境变量。现在,您可以使用ApicurioRegistryCRD 文件中的spec.configuration.env字段来管理环境变量,前面的流程已弃用,并将删除对它的 Operator 支持。确保使用spec.configuration.env字段来设置 Operator 未设置的所有环境变量。 - 为未启用的功能保留环境变量 : Apicurio Registry Operator 设置环境变量以启用和配置各种功能,如使用 KafkaSQL 存储时 Salted Challenge Response Authentication Mechanism (SCRAM)安全性。当禁用此类功能时,Operator 当前会保留关联的环境变量,这可能会导致问题。此类环境变量的保留已弃用,Operator 对它的支持将被删除。确保您的部署不依赖于这些环境变量的保留。
-
环境变量优先级 : Apicurio Registry Operator 可能会尝试设置已在
spec.configuration.env字段中明确指定的环境变量。如果环境变量具有冲突的值,则 Apicurio Registry Operator 设置的值会默认具有优先权。此行为将在以后改变,以便用户覆盖 Operator 设置的大部分环境变量。确保您的部署不依赖于原始优先级行为。
1.5. 升级并迁移 Apicurio Registry 部署 复制链接链接已复制到粘贴板!
您可以在 OpenShift 上自动将 Apicurio Registry 服务器从 Apicurio Registry 2.x 升级到 Apicurio Registry 2.4。不需要自动从 Apicurio Registry 1.x 升级到 Apicurio Registry 2.x,且需要迁移过程。
1.5.1. 更新 2.x 客户端依赖项 复制链接链接已复制到粘贴板!
这不是为这个版本更新客户端依赖项所必需的;现有 2.x 客户端仍可用于 Apicurio Registry 2.4。
但是,在 Apicurio Registry 的下一个发行版本前,您必须更新所有客户端应用程序依赖项,以使用最新的 Apicurio Registry 客户端版本。客户端应用程序依赖项包括 Kafka serializers/deserializers (SerDes)、Maven 插件和 Java REST 客户端的依赖项。例如,要更新 Java REST 客户端的 Maven 依赖项,请在 pom.xml 文件中指定版本,如下所示:
<dependency>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-client</artifactId>
<version>2.4.4.SP1-redhat-00001</version>
</dependency>
<dependency>
<groupId>io.apicurio</groupId>
<artifactId>apicurio-registry-client</artifactId>
<version>2.4.4.SP1-redhat-00001</version>
</dependency>
如需了解更多详细信息,请参阅 默认启用旧 REST API 日期格式。
1.5.2. 在 OpenShift 上从 Apicurio Registry 2.x 升级 复制链接链接已复制到粘贴板!
您可以在 OpenShift 4.9 上从 Apicurio Registry 2.x 升级到 OpenShift 4.10 或更高版本的 Apicurio Registry 2.4。您必须升级 Apicurio Registry 和 OpenShift 版本,并一次升级 OpenShift 次版本。
前提条件
- 您已在 OpenShift 4.9 上安装了 Apicurio Registry 2.x。
流程
- 在 OpenShift Container Platform Web 控制台中,点 Administration,然后点 Cluster Settings。
-
点 Channel 字段旁边的铅笔图标,然后选择下一个次
candidate版本(例如,从stable-4.9改为candidate-4.10)。 - 点 Save 然后点 Update,等待升级完成。
-
如果 OpenShift 版本小于 4.11,请重复步骤 2 和 3,然后选择
candidate-4.11或更高版本。 - 点 Operators > Installed Operators > Red Hat Integration - Service Registry。
-
确保 更新频道 设置为
2.x。 -
如果将 Update approval 设置为 Automatic,则在设置
2.x频道后,应该立即批准并安装升级。 - 如果 Update approval 设为 Manual,请单击 Install。
- 等待 Operator 部署并且部署了 Apicurio Registry pod。
- 验证您的 Apicurio Registry 系统是否正在运行。
其他资源
- 有关如何在 OpenShift Container Platform Web 控制台中设置 Operator 更新频道的更多详细信息,请参阅 更改 Operator 的更新频道。
1.5.3. 从 OpenShift 上的 Apicurio Registry 1.1 迁移 复制链接链接已复制到粘贴板!
有关从 Apicurio Registry 1.1 迁移到 Apicurio Registry 2.x 的详情,请参阅 迁移 Apicurio Registry 部署的红帽构建。
1.6. apicurio Registry 解决的问题 复制链接链接已复制到粘贴板!
| 问题 | 描述 |
|---|---|
| 在 SerDes 中处理 Apache Avro 复杂类型。 | |
| 在 Python SDK 中正确处理非snake case 查询参数。 | |
| 修复动态基本身份验证 Web 控制台解析。 | |
| registry 使用过时的 Keycloak 上下文路径。 |
| 问题 | 描述 |
|---|---|
| 在 web 控制台中启用 Anonymous read access 和 Artifact owner-only 授权 会失败,并显示错误。 | |
| 在将 KafkaSQL 存储配置为使用 SSL 时,密钥密码不是可选的。 | |
|
JSON 模式兼容性检查无法进行 | |
|
部署 Apicurio Registry 时 | |
|
| |
|
| |
|
无法上传引用具有 | |
| 当提供了空 schema 时,兼容性检查不会抛出异常。 | |
|
当 schema 默认值为 | |
| Kafka 消费者线程在内部数据库就绪前启动。 | |
| 重定向过滤器配置不正确。 | |
| 兼容性规则不会按版本号排序。 | |
| 除非启用了 SASL,否则 SSL 配置无法正常工作。 | |
| 'registry.ccompat.use-canonical-hash' 设置将模式更改为 save 时可以匿名化表单。 | |
| 当向 auth 服务器传递错误的凭证时,不会抛出异常。 | |
|
上传新版本的 Protobuf 模式会失败,并显示 | |
| 使用 REST API 创建工件时,名称和描述会错误填充。 | |
| 如果禁用了最新版本,则无法获得最新的 schema 版本。 | |
| 对于复杂的数组对象,JSON 模式验证失败。 |
Apicurio Registry Operator 解决的问题
| 问题 | 描述 |
|---|---|
| CORS_ALLOWED_ORIGINS 在生成的 OpenShift pod 中不会作为环境变量传播。 |
| 问题 | 描述 |
|---|---|
| Operator 创建的服务中没有提供端口名称。 | |
| 部署销毁后缺少环境变量。 | |
| 用于管理环境变量的方法不正确。 | |
| 日志级别没有正确设置。 |
1.7. apicurio Registry 解析 CVE 复制链接链接已复制到粘贴板!
Apicurio Registry 2.4 中解析的通用漏洞和风险(CVE)如下:
| 问题 | 描述 |
|---|---|
| CVE-2023-44487 undertow: HTTP/2: 启用多个 HTTP/2 的 Web 服务器会受到 DDoS 攻击(Rapid Reset Attack)的影响。 | |
| CVE-2023-44487 netty-codec-http2: HTTP/2: 多 HTTP/2 启用的 Web 服务器会受到 DDoS 攻击(Rapid Reset Attack)的影响。 | |
| CVE-2023-39325 CVE-2023-44487 integration-service-registry-operator-container: 各种漏洞。 |
| 问题 | 描述 |
|---|---|
| CVE-2022-1471 snakeyaml: Constructor Deserialization Remote Code Execution。 |
| 问题 | 描述 |
|---|---|
| CVE-2023-2976 guava:安全临时目录创建. | |
| CVE-2021-46877 jackson-databind: 如果使用 JDK 序列化序列化 JsonNode,则 Possible DoS。 | |
| CVE-2022-3510 protobuf-java: Message-Type Extensions 解析问题会导致 DoS。 | |
| CVE-2022-3509 protobuf-java: Textformat 解析问题会导致 DoS。 | |
| CVE-2023-28867 graphql-java: crafted GraphQL 查询会导致堆栈消耗。 | |
| CVE-2022-25881 http-cache-semantics: Regular Expression Denial of Service (ReDoS)安全漏洞。 | |
| CVE-2022-3782 keycloak :通过双 URL 编码的路径遍历。 | |
| CVE-2022-45787 apache-james-mime4j: Temporary File Information Disclosure in MIME4J TempFileStorageProvider. | |
| CVE-2022-4742 json-pointer: json-pointer 中的原型轮询程序。 | |
| CVE-2022-40152 woodstox-core: woodstox to serialise XML 数据容易受到 Denial Service (DoS)攻击的影响。 |
1.8. apicurio Registry 已知问题 复制链接链接已复制到粘贴板!
以下已知问题适用于 Apicurio Registry 2.4.x:
apicurio Registry 核心已知问题
registry-3413 - 默认启用旧 REST API 日期格式
为获得最大兼容性,并从旧版本的 Apicurio Registry 更轻松地升级,REST API 中使用的日期格式与 OpenAPI 标准不兼容(因为旧版本中存在错误)。
在 Apicurio Registry 的下一个发行版本前,您必须升级所有客户端应用程序以使用最新的客户端版本。下一个版本将修复日期格式 bug,这会导致旧的客户端不再与 REST API 兼容。
要将 REST API 更新至兼容 OpenAPI,您可以修复此 Apicurio Registry 中的日期格式错误,如下所示:
-
将所有客户端应用程序更新至
2.4.4.SP1-redhat-00001版本,如更新 2.x 客户端依赖项 中所述。 将以下环境变量设置为显示的值:
REGISTRY_APIS_V2_DATE_FORMAT=yyyy-MM-dd'T'HH:mm:ss'Z'
REGISTRY_APIS_V2_DATE_FORMAT=yyyy-MM-dd'T'HH:mm:ss'Z'Copy to Clipboard Copied! Toggle word wrap Toggle overflow
IPT-814 - Apicurio Registry logout 功能与 RH-SSO 7.6 不兼容
在 RH-SSO 7.6 中,与 logout 端点一起使用的 redirect_uri 参数已弃用。如需了解更多详细信息,请参阅 RH-SSO 7.6 升级指南。因此,当使用 RH-SSO Operator 保护 Apicurio Registry 时,点 Logout 按钮会显示 Invalid parameter: redirect_uri 错误。
有关临时解决方案,请参阅 https://access.redhat.com/solutions/6980926。
IPT-701 - CVE-2022-23221 H2 允许通过 JNDI 从远程服务器载入自定义类
当 Apicurio Registry 数据存储在 AMQ Streams 中时,H2 数据库控制台允许使用 JDBC URL 执行任意代码。在默认情况下,Apicurio Registry 不会受到攻击,需要进行恶意配置更改。
apicurio Registry Operator 已知问题
operator-42 - 自动生成 OpenShift 路由可能会使用错误的基本主机值
如果指定了多个 routerCanonicalHostname 值,Apicurio Registry OpenShift 路由的自动生成可能会使用错误的基本主机值。
附录 A. 使用您的订阅 复制链接链接已复制到粘贴板!
apicurio Registry 通过软件订阅提供。要管理您的订阅,请访问红帽客户门户中的帐户。
访问您的帐户
- 转至 access.redhat.com。
- 如果您还没有帐户,请创建一个帐户。
- 登录到您的帐户。
激活订阅
- 转至 access.redhat.com。
- 导航到 My Subscriptions。
- 导航到 激活订阅 并输入您的 16 位激活号。
下载 ZIP 和 TAR 文件
要访问 ZIP 或 TAR 文件,请使用客户门户网站查找下载的相关文件。如果您使用 RPM 软件包,则不需要这一步。
- 打开浏览器并登录红帽客户门户网站 产品下载页面,网址为 access.redhat.com/downloads。
- 在 Integration and Automation 类别中找到 Red Hat Integration 条目。
- 选择所需的 Apicurio Registry 产品。此时会打开 Software Downloads 页面。
- 单击组件的 Download 链接。
更新于 2023-11-07