docs: ShadowLink schema replication and role sync on Kubernetes (DOC-2333)

[JakeSCahill]

Documents the new ShadowLink CRD surfaces for 26.2 (DOC-2333, eng epic ENG-1232, confirmed ready for docs by David):

Changes

• Configure schema replication section in k-shadow-linking.adoc: the three schema_registry_shadowing_mode values (topic default, api for Confluent/external registries, disabled), a Confluent example with the API key/secret in a Kubernetes Secret, Operator + Helm tabs, and a pointer to the core migration guide for concepts and validation policies.
• Configure role synchronization section: on by default, interval, name filters, and the guidance to pair with ACL sync (mirrors the merged core docs).
• CRD reference regenerated from operator main using the crd-spec automation (ran its underlying crd-ref-docs invocation with main's config plus Broker.* added to the ignore list, since the dark-launched Broker CR postdates the config's exclusions). Adds the ShadowLink SR/role types and the Gateway API types.
• Verify example corrected: the ShadowLink CRD reports Synced + state: active (+ shadowTopicStatuses), not a Ready condition; the example now shows the real observed status.
• New gotcha in the cross-namespace WARNING: two Redpanda clusters on one Kubernetes cluster collide on the default external node ports (provided port is already allocated); disable external access on one or assign non-overlapping ports. Hit live during validation of the documented dev/test topology.

Validation (kind v1.34.0, operator built from main @ 550bab24b)

Cross-namespace ShadowLink (src/dst namespaces, one cluster-scoped operator): schema_registry_shadowing_mode: api pointed at the source's SR REST endpoint, roleSyncOptions enabled. Verified on the shadow: the orders topic (shadowTopicStatuses active), the orders-value subject replicated over the SR REST API, and shadow-test-role replicated. CEL admission verified (api mode requires shadowSchemaRegistryAPI).

Notes for eng (also raised on the operator side)

The crd-ref-docs-config.yaml in the operator repo needs Broker.* added to ignoreTypes before the next automated CRD regen, and the Stretch.* ignore needs REMOVING at GA so StretchCluster/RedpandaBrokerPool get reference docs.

Coordination: the Confluent-source specifics defer to Joyce's merged core page (docs#1776); role-sync core docs are #1780.

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	a3a8de5
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a63b3129e6a57000839df7c
😎 Deploy Preview	https://deploy-preview-1817--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: afb262b0-185b-4e45-a6e4-14b07553b50d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch doc-2333-shadowlink-sr-roles

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[david-yu]

Reviewed against the operator CRD on main (operator/api/redpanda/v1alpha2/shadow_link_types.go) and a validated Confluent Cloud → Redpanda ShadowLink run (repro repo, certified 2026-07-21 on merged operator main incl. #1661/#1675/#1686). The CRD-facing content is accurate; four suggestions below.

Suggested changes

1. Role sync vs. non-Redpanda sources (the Confluent case this page documents). roleSyncOptions.enabled defaults to true, and against a Confluent source the Roles Migrator task degrades to LINK_UNAVAILABLE (Failed to get supported API version for describe_redpanda_roles) while the link stays ACTIVE/Synced=True. Readers following the Confluent schema example will hit this. Suggest adding to the role-sync section (and ideally the Confluent schema example): when the source is not a Redpanda cluster, set roleSyncOptions: {enabled: false}.

2. Operator tab omits TLS for the https SR endpoint. The Helm tab sets tls_settings: {enabled: true} but the Operator tab has no tls block on shadowSchemaRegistryAPI. The validated Confluent config needed tls: {enabled: true} (public roots, no CA). Suggest adding it to the Operator example for consistency — or confirming scheme-inferred TLS and aligning both tabs.

3. Helm tab may be missing schema_registry_shadowing_mode: api. The Operator tab sets the mode explicitly, and the CRD's CEL validation rejects shadowSchemaRegistryAPI without it. Since the snake_case CRD field mirrors the core proto, the core-side shadow-config.yaml likely requires the mode key as well — worth verifying against the core config schema.

4. Nit: the role-sync Operator example is exactly the CRD defaults (enabled: true, interval: 30s, include-all literal * filter). A sentence noting the block is optional and these are the defaults would prevent readers from thinking it's required to get role sync. Relatedly, the CRD notes that pausing the SR sync task lifts the per-context write protection — could round out the "destination contexts are read-only" NOTE.

Verified against the CRD (no action)

• schema_registry_shadowing_mode enum (topic default / api / disabled), snake_case field name, and the deprecated enabled precedence mapping all match ShadowLinkSchemaRegistrySyncOptions + ShadowingMode().
• "Required when mode is api and forbidden otherwise" matches the two CEL XValidation rules.
• Role-sync fields/defaults match ShadowLinkRoleSyncOptions (enabled=true, 30s, default include-all filter, paused).
• Status example (state: active, Synced condition, shadowTopicStatuses) matches ShadowLinkStatus.
• Confluent Cloud is clearly represented (psrc-xxxxx.us-east-1.aws.confluent.cloud, SR API key/secret basic auth via Secret) and matches the shape of the working config; schema replication in api mode reproduced byte-identical schemas incl. schema IDs within the 10s tail interval in the certified run.

🤖 Generated with Claude Code

[david-yu]

Applied the review suggestions in a3a8de5:

1. Role sync vs. non-Redpanda sources — the Confluent example now sets roleSyncOptions: {enabled: false}, and the role-sync section states that role synchronization requires a Redpanda source (against a non-Redpanda source the task reports LINK_UNAVAILABLE while the link stays active).
2. Operator tab TLS — added tls: {enabled: true} to the Confluent SR example (matches CommonTLS on shadowSchemaRegistryAPI on operator main; Confluent Cloud serves publicly issued certificates, no CA needed), consistent with the Helm tab's tls_settings.
3. Helm tab schema_registry_shadowing_mode — verified against rpk's shadow config mapper: no change needed. In the core shadow-config.yaml the mode is a protobuf oneof, so the presence of shadow_schema_registry_api itself selects api mode; there is no string mode key on the create path (shadowing_mode appears only in rpk shadow describe output). The Helm tab was correct as written.
4. Nits — noted that the role-sync Operator block is optional and shows the CRD defaults, and that pausing the schema sync task (paused: true on shadowSchemaRegistryAPI) lifts the per-context write protection.

One nuance surfaced while verifying #1: on the core path, role_sync_options.role_name_filters defaults to empty (no roles synced until an include filter is added), so "on by default" is operator-CRD-specific. The applied wording keeps the disable guidance in the Operator example only.

🤖 Generated with Claude Code