Rpk Registry

rpk registry: Schema Registry

The rpk registry command group (alias rpk sr) is the CLI front-end to the Redpanda Schema Registry running on port 8081 by default. It lets you register Avro, Protobuf, and JSON schemas, manage subjects and versions, enforce compatibility rules, control registry operating mode, and isolate schemas into named contexts.

The Schema Registry is built directly into the Redpanda broker binary — no separate service is required. Schemas are stored in a compacted internal topic (_schemas). Every broker accepts mutating calls; there is no single leader to configure.

The registry endpoint is configurable via -X registry.hosts=: or in an rpk profile.

Quickstart

# 1. Point rpk at your cluster (skip if you already have a profile)
rpk profile create local --set brokers=localhost:9092 \
  --set registry.hosts=localhost:8081

# 2. Save an Avro schema to a file
cat > sensor.avsc ` — scope all operations to a named context (names start with `.`)
- `--skip-context-check` — bypass admin API verification of context support
- `-X registry.hosts=:` — override the registry endpoint
- `--format json|yaml|text|wide|help` — persistent flag inherited by all subcommand groups (`schema`, `subject`, `compatibility-level`, `mode`, `context`); controls output format

## Schema Registry Concepts

**Subject** — a logical grouping for schemas. By default rpk topic produce/consume uses the **TopicNameStrategy**: `-value` for value schemas and `-key` for key schemas. One subject can hold many versions.

**Version** — an integer (1, 2, 3…). `latest` is accepted anywhere a version is required. Each version has a unique **schema ID** that is globally unique across all subjects (in the default context; within a context, IDs are context-scoped).

**Wire format** — producers prepend a magic byte (`0x00`) + 4-byte big-endian schema ID before the serialized payload. Consumers read the ID and fetch the schema from the registry to deserialize.

**Schema types** — `AVRO`, `PROTOBUF`, `JSON`. The type is auto-detected from the file extension (`.avsc`/`.avro` → Avro, `.proto`/`.protobuf` → Protobuf, `.json` → JSON). Override with `--type`.

**_schemas topic** — the internal compacted Kafka topic that persists all registry state. Do not edit it directly.

## Compatibility Levels

Compatibility governs which schema versions can coexist. The default is `BACKWARD`. Set globally (no subject arg) or per-subject.

| Level | Guarantee |
|---|---|
| `BACKWARD` | New schema readers can read old schema data (previous version only) |
| `BACKWARD_TRANSITIVE` | New schema readers can read data from all previous versions |
| `FORWARD` | Old schema readers can read new schema data (previous version only) |
| `FORWARD_TRANSITIVE` | Old schema readers can read data from all future versions |
| `FULL` | BACKWARD + FORWARD with the immediately preceding version |
| `FULL_TRANSITIVE` | BACKWARD_TRANSITIVE + FORWARD_TRANSITIVE with all versions |
| `NONE` | No compatibility checks performed |

```bash
# Set globally
rpk registry compatibility-level set --level BACKWARD

# Set for a subject
rpk registry compatibility-level set my-topic-value --level FULL_TRANSITIVE

# Set for multiple subjects plus global in one call
rpk registry compatibility-level set subjectA subjectB --global --level BACKWARD

# Read back
rpk registry compatibility-level get              # global
rpk registry compatibility-level get my-topic-value --global  # subject + global

Registry Mode

Mode controls whether the registry accepts writes. Supported values: READONLY, READWRITE, IMPORT.

• READWRITE (normal operation) — allows schema registration and deletion.
• READONLY — accepts reads; rejects all writes.
• IMPORT — allows registering schemas with explicit IDs and versions (for migration). Can only be set on an empty registry/subject (or use --force to override the emptiness check).

rpk registry mode get                        # get global mode
rpk registry mode set --mode READONLY        # go read-only globally
rpk registry mode set --mode READWRITE       # restore normal operation
rpk registry mode set my-subject --mode READONLY  # per-subject
rpk registry mode reset my-subject          # revert subject to global default

Schema Contexts

Contexts provide namespace isolation within a single registry instance. Each context has its own independent schema ID counter, mode settings, and compatibility settings. Requires schema_registry_enable_qualified_subjects = true (cluster config) and a broker restart.

Context names must start with . and must not contain :. Qualified subjects use the syntax ::.

# Enable contexts (requires broker restart)
rpk cluster config set schema_registry_enable_qualified_subjects true

# Use --schema-context to scope all registry operations to a context
rpk registry --schema-context .staging schema create my-topic-value --schema schema.avsc
rpk registry --schema-context .staging schema list
rpk registry --schema-context .staging compatibility-level set --level FULL

# Alternatively, use qualified subject names directly
rpk registry schema create ":.staging:my-topic-value" --schema schema.avsc

# List and delete contexts
rpk registry context list
rpk registry context delete .staging   # all subjects must be hard-deleted first

Schema References

Schemas can reference other schemas registered under different subjects (supported for Protobuf and Avro). Pass references at registration time with --references.

# Reference format: name:subject:version (comma-separated for multiple)
rpk registry schema create my-topic-value \
  --schema my-schema.proto \
  --references "google/protobuf/timestamp.proto:google-timestamp:1"

# Find schemas that reference a given subject/version
rpk registry schema references common-types --schema-version 1

Producing and Consuming with Schema Registry

rpk topic produce and rpk topic consume can encode/decode using the registry automatically.

# Produce with Avro encoding (registry encodes the value)
rpk topic produce sensor \
  --schema-id topic \
  --format "%v\n" ` for OIDC. TLS/mTLS via `registry.tls.*` X-options. (OIDC authentication is Enterprise.)

## Reference Directory

- [schemas-and-subjects.md](references/schemas-and-subjects.md): Registering, fetching, listing, and deleting schemas and subjects; TopicNameStrategy; soft vs hard delete; metadata properties; schema references.
- [compatibility.md](references/compatibility.md): All compatibility levels (BACKWARD/FORWARD/FULL/NONE + TRANSITIVE variants), get/set at global and subject scope, checking a candidate schema, registry mode, and schema contexts.
- [enterprise-security.md](references/enterprise-security.md): Enterprise-licensed registry features — Schema Registry Authorization (`schema_registry_enable_authorization`, `registry`/`subject` ACL resource types, `--registry-global`/`--registry-subject`, operation mapping, RBAC roles, migration ACLs) and Server-Side Schema ID Validation (`enable_schema_id_validation`, per-topic `redpanda.*`/`confluent.*` validation + subject-name-strategy keys), plus registry authentication (HTTP Basic, OIDC/OAUTHBEARER, mTLS X-options) and license-compliance checks.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [redpanda-data](https://github.com/redpanda-data)
- **Source:** [redpanda-data/skills](https://github.com/redpanda-data/skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.