diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index ee8e828c6c..db1d611147 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -434,6 +434,9 @@ **** xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level.adoc[] ***** xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc[] ***** xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc[] +**** xref:reference:rpk/rpk-registry/rpk-registry-context.adoc[] +***** xref:reference:rpk/rpk-registry/rpk-registry-context-delete.adoc[] +***** xref:reference:rpk/rpk-registry/rpk-registry-context-list.adoc[] **** xref:reference:rpk/rpk-registry/rpk-registry-mode.adoc[] ***** xref:reference:rpk/rpk-registry/rpk-registry-mode-get.adoc[] ***** xref:reference:rpk/rpk-registry/rpk-registry-mode-reset.adoc[] diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 0d5b53ad62..8cb179e6dc 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -83,6 +83,12 @@ xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry contexts] are na To enable contexts, set xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] to `true` and restart your brokers. Once enabled, you reference schemas using qualified subject syntax, for example `:.staging:my-topic-value`. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for configuration examples and limitations. +== Schema Registry metadata properties + +xref:manage:schema-reg/schema-reg-overview.adoc#metadata-properties[Schema Registry metadata properties] let you store and retrieve arbitrary key-value pairs alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle, making it easier to track ownership and lineage without modifying the schema itself. + +You can set metadata when registering a schema using the `POST /subjects/{subject}/versions` endpoint or with the xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[`--metadata-properties`] flag in `rpk registry schema create`. Metadata is returned in `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses, and viewable with `rpk registry schema get --print-metadata`. New schema versions automatically inherit metadata from the most recent version of the subject unless you register with an explicit empty `metadata` object. + == New configuration properties **Storage mode:** diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 5349bc4ffe..18526e3384 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -159,6 +159,53 @@ ifndef::env-cloud[] Additionally, you cannot have xref:manage:schema-reg/schema-id-validation.adoc#about-schema-id-validation[schema ID validation] with JSON schemas if the xref:manage:schema-reg/schema-id-validation.adoc#set-subject-name-strategy-per-topic[subject name strategy] _is not_ `TopicNameStrategy`. endif::[] +[#metadata-properties] +== Metadata properties + +Schema Registry lets you store and retrieve arbitrary key-value metadata properties alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle. You can register a new schema with associated metadata properties by sending a `POST` request to `/subjects/{subject}/versions` with a `metadata.properties` object in the request body: + +[,json] +---- +{ + "schema": "{\"type\":\"string\"}", + "metadata": { + "properties": { + "owner": "platform-team", + "application.version": "2.1.0" + } + } +} +---- + +To set metadata using rpk, use the xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[`--metadata-properties`] flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string (for example, `{"key":"value"}`), and you can pass it multiple times to set multiple properties: + +[,bash] +---- +# key=value pairs — pass the flag multiple times for multiple properties +rpk registry schema create my-subject --schema schema.avsc \ + --metadata-properties owner=platform-team \ + --metadata-properties env=prod + +# JSON string — useful when values contain special characters +rpk registry schema create my-subject --schema schema.avsc \ + --metadata-properties '{"owner":"platform-team","application.version":"2.1.0"}' +---- + +Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. To view metadata on an existing schema, add `--print-metadata` to `rpk registry schema get`. You can also view metadata properties in {ui}. + +When you register a new schema version without a `metadata` field, the new version automatically inherits properties from the most recent version of that subject. To avoid inheriting the previous version's metadata, you can send `"metadata": {}` to register a schema with explicitly no metadata. Registering the same schema definition with different metadata properties creates a new schema version. + +[NOTE] +==== +Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following configuration objects are not supported: + +* `metadata.tags` +* `ruleSet` +* `defaultMetadata` and `overrideMetadata` (configuration options) +* `defaultRuleSet` and `overrideRuleSet` (configuration options) +* `compatibilityGroup` (configuration option) +==== + == Next steps * xref:manage:schema-reg/schema-reg-api.adoc[] diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc new file mode 100644 index 0000000000..b972a5fd88 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc @@ -0,0 +1,42 @@ += rpk registry context delete +// tag::single-source[] + +Delete a schema registry context. + +A context can only be deleted once all subjects within it have been hard deleted. Soft-deleted subjects still block context deletion. Use `rpk registry subject delete --permanent` to hard delete subjects first. + +The default context `.` cannot be deleted. + +== Usage + +[,bash] +---- +rpk registry context delete [CONTEXT] [flags] +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|*Value* |*Type* |*Description* + +|-h, --help |- |Help for delete. + +|--no-confirm |- |Disable confirmation prompt. + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. + +|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. + +|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. + +|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. + +|--schema-context |string |Schema context to use for all registry operations. + +|--skip-context-check |- |Skip the admin API verification of schema context support. + +|-v, --verbose |- |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc new file mode 100644 index 0000000000..4954d2c028 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc @@ -0,0 +1,45 @@ += rpk registry context list +// tag::single-source[] + +List schema registry contexts. + +== Usage + +[,bash] +---- +rpk registry context list [flags] +---- + +== Aliases + +[,bash] +---- +list, ls +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|*Value* |*Type* |*Description* + +|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. + +|-h, --help |- |Help for list. + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. + +|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. + +|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. + +|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. + +|--schema-context |string |Schema context to use for all registry operations. + +|--skip-context-check |- |Skip the admin API verification of schema context support. + +|-v, --verbose |- |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc new file mode 100644 index 0000000000..181e348544 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc @@ -0,0 +1,48 @@ += rpk registry context +// tag::single-source[] + +Manage schema registry contexts. + +Schema contexts provide namespace isolation within the schema registry, allowing multiple independent sets of subjects and schemas to coexist. + +Before using schema contexts, enable the xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] cluster property: + +[,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +---- + +Use the `--schema-context` flag on the parent `registry` command to scope operations to a specific context. + +== Usage + +[,bash] +---- +rpk registry context [flags] + rpk registry context [command] +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|*Value* |*Type* |*Description* + +|-h, --help |- |Help for context. + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. + +|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. + +|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. + +|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. + +|--schema-context |string |Schema context to use for all registry operations. + +|--skip-context-check |- |Skip the admin API verification of schema context support. + +|-v, --verbose |- |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc index 523a0815c2..28933a71ab 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc @@ -38,6 +38,23 @@ Create a schema with a specific ID and version in import mode: rpk registry schema create foo --schema /path/to/file.proto --id 42 --schema-version 3 ---- +Create a schema with metadata properties as key=value pairs: + +[,bash] +---- +rpk registry schema create foo --schema /path/to/file.proto \ + --metadata-properties owner=team-a \ + --metadata-properties env=prod +---- + +Create a schema with metadata properties using JSON format: + +[,bash] +---- +rpk registry schema create foo --schema /path/to/file.proto \ + --metadata-properties '{"owner":"team-a","env":"prod"}' +---- + == Usage [,bash] @@ -55,6 +72,8 @@ rpk registry schema create SUBJECT --schema {filename} [flags] |--id |int |Optional schema ID to use when creating the schema in import mode (default `-1`). +|-p, --metadata-properties |stringArray |Schema metadata properties as key=value pairs or JSON (for example, `{"key":"value"}`). You can pass this flag multiple times. + |--references |string |Comma-separated list of references (name:subject:version) or path to reference file. |--schema |string |Schema filepath to upload, must be `.avro`, `.avsc`, or `.proto`.