Add iceberg_default_catalog_namespace to Cloud

[kbatuigas]

Description

This pull request updates the documentation for configuring Iceberg table namespaces in Redpanda, with a focus on avoiding table name collisions when multiple clusters write to the same catalog (especially with AWS Glue and other REST catalog providers). The changes clarify when and how to set the iceberg_default_catalog_namespace property, provide updated CLI/API examples, and streamline related explanations across several pages.

Key documentation improvements:

Namespace configuration guidance:

• Added and clarified instructions that each cluster writing to the same REST catalog (such as AWS Glue) must use a distinct namespace, set via iceberg_default_catalog_namespace, and that this property cannot be changed after enabling Iceberg. This guidance is now more prominent and consistent across relevant pages. [1] [2] [3]

Updated CLI and API examples:

• Updated rpk and API command examples to show how to set a custom namespace using iceberg_default_catalog_namespace, including sample values and comments for clarity. [1] [2] [3] [4]

Streamlined and clarified documentation:

• Removed duplicated or redundant namespace explanations from non-cloud sections to avoid confusion and ensure information is presented in the most relevant context.
• Updated placeholder explanations to clarify the purpose and use of <custom-namespace>.

Consistency across integration guides:

• Updated AWS Glue, Databricks Unity, and Snowflake catalog integration docs to reference the namespace configuration and ensure users know how to find their tables/schemas based on the namespace used. [1] [2]

General cleanup:

• Removed unnecessary conditional notes and streamlined namespace replacement instructions in query and catalog usage documentation. [1] [2] [3]

Resolves https://redpandadata.atlassian.net/browse/
Review deadline:

Page previews

• About Iceberg Topics > Enable Iceberg integration
  • Self-managed
  • Cloud
• Use Iceberg Catalogs > Set cluster properties > Configure table namespace
  • Self-managed
  • Cloud
• Query Iceberg Topics Using AWS Glue
  • Self-managed
  • Cloud

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	644cb5a
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/69ea86cbc8afde0008725258
😎 Deploy Preview	https://deploy-preview-1680--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 incremental reviews are disabled on this repository.

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

Run ID: 0d53fa6d-8ad3-4bb8-85a6-18af7f06ee36

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

📝 Walkthrough

Walkthrough

This PR reorganizes Iceberg documentation across six pages by removing environment-specific conditional blocks and consolidating namespace configuration guidance into shared sections. Changes include moving the "distinct namespace to avoid table name collisions" guidance from non-cloud-only sections to shared instructions, adding explicit examples for setting iceberg_default_catalog_namespace via Cloud configuration methods, simplifying environment-agnostic content by eliminating redundant ifdef::env-cloud[] / ifndef::env-cloud[] blocks, and removing duplicate or obsolete conditional content that no longer reflects current guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• 26.1 fixes #1646: Both PRs modify the same Iceberg documentation files and update guidance around setting iceberg_default_catalog_namespace when enabling Iceberg.
• Iceberg edits #1362: Both PRs modify the same Iceberg documentation pages and consolidate how environment-specific namespace configuration guidance is presented.
• Update Glue doc with Cloud-specific guidance #1275: Both PRs modify AWS Glue and other Iceberg documentation, adjusting cloud vs non-cloud conditional blocks and Cloud configuration examples.

Suggested reviewers

• simon0191
• mattschumpert
• micheleRP
• Feediver1

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	Title is partially related to the changeset, referring to Cloud configuration but not capturing the main documentation change about namespace configuration and collision avoidance.	Consider a more descriptive title such as 'Clarify iceberg_default_catalog_namespace configuration and collision avoidance' or 'Document namespace configuration for REST catalogs to prevent table name collisions'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description is detailed and well-structured, covering namespace configuration guidance, updated CLI/API examples, streamlined documentation, consistency improvements, and general cleanup with references to specific changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DOC-2086-iceberg-in-cloud-configurable-namespace

---

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

[Feediver1]

Namespace collisions--this is the problem that Schema Registry contexts solves: provides namespaces that isolate schemas, subjects, and configuration within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings. Wondering if you should refer to it? @mattschumpert Should there be a link to SR contexts somewhere in this doc?

[kbatuigas]

I doubt it, as this applies to the Iceberg catalog namespace

[micheleRP]

A few suggestions from my docs review:

1. iceberg-topics-aws-glue.adoc — inconsistent treatment of <custom-namespace>

In the self-managed YAML example (around line 163), iceberg_default_catalog_namespace is shown uncommented in the required configuration:

iceberg_enabled: true
# Set a custom namespace instead of the default "redpanda"
iceberg_default_catalog_namespace: ["<custom-namespace>"]
# Glue requires Redpanda Iceberg tables to be manually deleted
iceberg_delete: false

…but <custom-namespace> is not described in the placeholder list that follows (lines 48–53 of the self-managed branch). Meanwhile, on about-iceberg-topics.adoc (around line 131) the same property is treated as an optional, commented-out line:

rpk cluster config set iceberg_enabled true
# Optional: set a custom namespace (default is "redpanda")
# rpk cluster config set iceberg_default_catalog_namespace '["<custom-namespace>"]'

So readers of the Glue page may infer that setting a custom namespace is mandatory, while readers of the general page see it as optional. The Cloud rpk tabs on the Glue page (lines ~76 and ~96) also show it uncommented without a matching placeholder entry in the self-managed list — only the Cloud placeholder list (around line 112) describes <custom-namespace>.

Suggested: pick one style and apply it consistently across the three code samples on the Glue page + about-iceberg-topics.adoc:

• Option A: Comment out the iceberg_default_catalog_namespace line in the self-managed YAML with an "Optional" prefix to match about-iceberg-topics.adoc.
• Option B: Keep it uncommented and add a <custom-namespace> entry to the self-managed placeholder list (parallel to the Cloud list at line 112), explaining when to set it vs. when to omit.

2. iceberg-topics-aws-glue.adoc — <custom-namespace> described only on the Cloud side

Related to the above: the Cloud placeholder list (around line 112) has:

* `<custom-namespace>`: A unique namespace for this cluster's Iceberg tables. Each Redpanda cluster that writes to the same Glue catalog must use a distinct namespace to avoid table name collisions. If omitted, the default namespace `redpanda` is used.

…but the self-managed placeholder list (lines 48–53) does not include a parallel entry. If you go with Option B above (keep the property uncommented), mirror this bullet in the self-managed list so both envs document the placeholder.

3. about-iceberg-topics.adoc — Cloud API namespace guidance hidden in trailing shell comments

In the Cloud API example (around lines 118–122), the new namespace guidance is delivered as comments after the closing -d '{...}' of the curl command:

curl -H "Authorization: Bearer ${RP_CLOUD_TOKEN}" -X PATCH \
  "https://api.cloud.redpanda.com/v1/clusters/${RP_CLUSTER_ID}" \
 -H 'accept: application/json'\
 -H 'content-type: application/json' \
 -d '{"cluster_configuration":{"custom_properties": {"iceberg_enabled":true}}}'
# Optional: set a custom namespace (default is "redpanda")
# Add "iceberg_default_catalog_namespace":["<custom-namespace>"] key-value pair
# to custom_properties

The shell comments instruct the reader to modify the JSON body above, which reverses reading order and is easy to miss (and unlike the rpk example, there's no commented-out alternative command they can uncomment directly).

Suggested: either

• Option A: Lift the guidance into a prose paragraph below the code block with a complete alternative -d payload that includes iceberg_default_catalog_namespace, or
• Option B: Show a second tab / second code sample with the property already embedded in custom_properties so readers can copy a working example directly.

4. about-iceberg-topics.adoc line 125 — "single global catalog per account" overgeneralizes REST catalogs

The collision-avoidance paragraph now renders on both envs:

When multiple clusters write to the same catalog, each cluster must use a distinct namespace to avoid table name collisions. This is especially critical for REST catalog providers that offer a single global catalog per account (such as AWS Glue), where there is no other isolation mechanism.

REST catalogs like Apache Polaris / Dremio Nessie aren't necessarily single-per-account, so "REST catalog providers that offer a single global catalog per account" reads as if the limitation is inherent to all REST catalogs. On iceberg-topics-aws-glue.adoc the wording is correctly Glue-specific ("Because AWS Glue provides a single catalog per account…").

Suggested: tighten the generic version, e.g. "This is especially important for catalogs that provide only a single global catalog per account — for example, AWS Glue — where there is no other isolation mechanism." Safe to leave as-is if you prefer; minor clarity nit.

[micheleRP]

@kbatuigas, @mattschumpert should this be added to the Cloud What's New?

[kbatuigas]

@kbatuigas, @mattschumpert should this be added to the Cloud What's New?

Adding to What's New in redpanda-data/cloud-docs#563