From 8f060437e63db5caeb012f3a5ab95139ef68cf7b Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Sat, 25 Jul 2026 14:46:21 -0400 Subject: [PATCH 1/2] docs: DOC-2022: Add Terraform option for shadow link setup Adds a Terraform tab to the cloud-gated create and update tab blocks on the Configure Shadowing page, covering the redpanda_shadow_link resource (provider 2.0.0+), the redpanda_secret password pattern, the enable_shadow_linking prerequisite, and the allow_deletion guard. Co-Authored-By: Claude Fable 5 --- .../disaster-recovery/shadowing/setup.adoc | 63 ++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index 3a90cbf24a..c2f5a0e9e3 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -420,10 +420,65 @@ Replace the placeholders with your own values: * ``: The name of the secret containing the SASL/SCRAM password from the source cluster. * ``: Exclude topics that use this prefix, for example, `temp-`, `test-`, `debug-`. -The response object represents the xref:manage:api/cloud-byoc-controlplane-api.adoc#lro[long-running operation] of creating a shadow link. +The response object represents the xref:manage:api/cloud-byoc-controlplane-api.adoc#lro[long-running operation] of creating a shadow link. For the full API reference, see link:/api/doc/cloud-controlplane/operation/operation-shadowlinkservice_createshadowlink[Control Plane API reference]. -- + +Terraform:: ++ +-- +Manage shadow links declaratively with the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/shadow_link[`redpanda_shadow_link` resource^] in the https://registry.terraform.io/providers/redpanda-data/redpanda/latest[Redpanda Terraform provider^] (version 2.0.0 or later). The resource supports the full shadow link lifecycle: create, update, import, and destroy. + +Store the SASL/SCRAM password for the source cluster user in the shadow cluster's secret store with the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/secret[`redpanda_secret` resource^], then reference the secret from the shadow link configuration: + +[,hcl] +---- +resource "redpanda_secret" "source_password" { + name = "" + secret_data = var.source_user_password + secret_data_version = 1 + scopes = ["SCOPE_REDPANDA_CLUSTER"] + cluster_api_url = redpanda_cluster.shadow.cluster_api_url +} + +resource "redpanda_shadow_link" "production_dr" { + name = "" + shadow_redpanda_id = "" + source_redpanda_id = "" + + client_options = { + tls_settings = { + enabled = true + } + authentication_configuration = { + scram_configuration = { + scram_mechanism = "SCRAM_SHA_256" + username = "" + password = "$${secrets.${redpanda_secret.source_password.name}}" + } + } + } +} +---- + +Replace the placeholders with your own values: + +* ``: Name for the secret that stores the SASL/SCRAM password. +* ``: Unique name for this shadow link, for example, `production-dr`. +* ``: ID of the shadow (destination) cluster. +* ``: ID of the source cluster. For a source cluster that is not managed in Redpanda Cloud, omit `source_redpanda_id` and set `client_options.bootstrap_servers` instead. +* ``: SASL/SCRAM username, for example, `shadow-replication-user`. You create this user in the source cluster, and you can manage it with the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/user[`redpanda_user` resource^]. Grant it the permissions listed in <>, which you can manage with the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/acl[`redpanda_acl` resource^]. + +To configure topic, consumer group, ACL, and Schema Registry synchronization, add the corresponding option blocks (`topic_metadata_sync_options`, `consumer_offset_sync_options`, `security_sync_options`, `schema_registry_sync_options`) to the resource. For the full schema and a complete working example, see the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/shadow_link[`redpanda_shadow_link` reference^] and the https://github.com/redpanda-data/terraform-provider-redpanda/blob/main/examples/shadow_link/main.tf[provider example^]. + +[NOTE] +==== +If you manage the shadow cluster with the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/cluster[`redpanda_cluster` resource^], you can set the `enable_shadow_linking` cluster property in `cluster_configuration.custom_properties_json`. + +To protect against accidental deletion, Terraform refuses to destroy a shadow link unless the resource sets `allow_deletion = true`. +==== +-- ====== endif::[] @@ -851,6 +906,12 @@ This endpoint returns a xref:manage:api/cloud-byoc-controlplane-api.adoc#lro[lon For the full API reference, see link:/api/doc/cloud-controlplane/operation/operation-shadowlinkservice_updateshadowlink[Control Plane API reference]. -- + +Terraform:: ++ +-- +Edit the `redpanda_shadow_link` resource configuration and run `terraform apply`. The provider sends only the changed fields to the API. The shadow link name and cluster IDs are immutable: if you change them, Terraform plans a replacement (destroy and recreate) instead of an update. +-- ====== endif::[] // end::single-source[] From 769ca67eee5575678c6d78e9fc55826375667d38 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 27 Jul 2026 22:48:57 -0400 Subject: [PATCH 2/2] docs: apply review feedback on Terraform shadow link tabs Per Michele's review: - Document the uppercase-only constraint on redpanda_secret names (provider validator ^[A-Z][A-Z0-9_]*$), with an example. - Add a Terraform tab to the create-the-secret step pointing forward (the secret is defined with the shadow link), keeping tab selection in sync across the two blocks. - Tie the update tab's replacement behavior back to allow_deletion. - Cross-link Manage cluster secrets for naming/write-only/rotation. - Explain secret_data_version with an inline rotation comment. - Fix the pre-existing Console version typo: v3.30 -> v3.3.0 (the shadow-link Console support floor; the 26.2 SR-shadowing Console requirement is covered separately in DOC-2335). Co-Authored-By: Claude Fable 5 --- .../pages/disaster-recovery/shadowing/setup.adoc | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc index c2f5a0e9e3..6b86611613 100644 --- a/modules/manage/pages/disaster-recovery/shadowing/setup.adoc +++ b/modules/manage/pages/disaster-recovery/shadowing/setup.adoc @@ -39,7 +39,7 @@ endif::[] ifndef::env-cloud[] - Both clusters must be running Redpanda v25.3 or later. -- If you use Redpanda Console, ensure that it is running v3.30 or later. +- If you use Redpanda Console, ensure that it is running v3.3.0 or later. - You must have xref:get-started:licensing/overview.adoc[Enterprise Edition] licenses on both clusters. endif::[] @@ -327,6 +327,12 @@ In the shadow cluster, create a secret to store the authentication credential th Use the xref:manage:api/cloud-dataplane-api.adoc[Data Plane API] to programmatically create the secret. -- + +Terraform:: ++ +-- +With Terraform, you define the secret and the shadow link together: the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/secret[`redpanda_secret` resource^] in the next step's Terraform tab creates this secret as part of the same configuration, so there is nothing to do in this step. +-- ====== . In the shadow cluster, create a shadow link to the source cluster. @@ -430,14 +436,14 @@ Terraform:: -- Manage shadow links declaratively with the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/shadow_link[`redpanda_shadow_link` resource^] in the https://registry.terraform.io/providers/redpanda-data/redpanda/latest[Redpanda Terraform provider^] (version 2.0.0 or later). The resource supports the full shadow link lifecycle: create, update, import, and destroy. -Store the SASL/SCRAM password for the source cluster user in the shadow cluster's secret store with the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/secret[`redpanda_secret` resource^], then reference the secret from the shadow link configuration: +Store the SASL/SCRAM password for the source cluster user in the shadow cluster's secret store with the https://registry.terraform.io/providers/redpanda-data/redpanda/latest/docs/resources/secret[`redpanda_secret` resource^] (see xref:manage:terraform-provider.adoc#manage-cluster-secrets[Manage cluster secrets] for naming, write-only behavior, and rotation), then reference the secret from the shadow link configuration: [,hcl] ---- resource "redpanda_secret" "source_password" { name = "" secret_data = var.source_user_password - secret_data_version = 1 + secret_data_version = 1 # Increment when you rotate the password. scopes = ["SCOPE_REDPANDA_CLUSTER"] cluster_api_url = redpanda_cluster.shadow.cluster_api_url } @@ -464,7 +470,7 @@ resource "redpanda_shadow_link" "production_dr" { Replace the placeholders with your own values: -* ``: Name for the secret that stores the SASL/SCRAM password. +* ``: Name for the secret that stores the SASL/SCRAM password. Must be uppercase, matching `^[A-Z][A-Z0-9_]*$`, for example, `SOURCE_SCRAM_PASSWORD`. * ``: Unique name for this shadow link, for example, `production-dr`. * ``: ID of the shadow (destination) cluster. * ``: ID of the source cluster. For a source cluster that is not managed in Redpanda Cloud, omit `source_redpanda_id` and set `client_options.bootstrap_servers` instead. @@ -910,7 +916,7 @@ For the full API reference, see link:/api/doc/cloud-controlplane/operation/opera Terraform:: + -- -Edit the `redpanda_shadow_link` resource configuration and run `terraform apply`. The provider sends only the changed fields to the API. The shadow link name and cluster IDs are immutable: if you change them, Terraform plans a replacement (destroy and recreate) instead of an update. +Edit the `redpanda_shadow_link` resource configuration and run `terraform apply`. The provider sends only the changed fields to the API. The shadow link name and cluster IDs are immutable: if you change them, Terraform plans a replacement (destroy and recreate) instead of an update. The destroy step of a replacement succeeds only when the resource sets `allow_deletion = true`, the same guard described in the create step. -- ====== endif::[]