Reorganize HTTP Proxy doc

[kbatuigas]

Description

• Move Authentication sections towards beginning of doc
• Add conditionals so that the Self-managed page displays 8082 for the port, and the Cloud page displays 30082
• Use base_uri variable consistently in code examples, after Authentication
• Instead of using an alias, use rpk profile/flags/vars to set up rpk topic create

Resolves https://redpandadata.atlassian.net/browse/DOC-743
Review deadline:

Page previews

Self-managed: https://deploy-preview-1376--redpanda-docs-preview.netlify.app/current/develop/http-proxy/
Cloud: https://deploy-preview-1376--redpanda-docs-preview.netlify.app/redpanda-cloud/develop/http-proxy/

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	22b92ea
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/68e96844fb2f1f0008f0d40a
😎 Deploy Preview	https://deploy-preview-1376--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.

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

📝 Walkthrough

Walkthrough

The HTTP Proxy documentation was restructured to differentiate Cloud vs non-Cloud flows using env-cloud conditionals. A new top-level note links to the API reference and a cloud-only note. Default ports were updated (cloud 30082; private connectivity 30282), and examples now use a base_uri variable. Authentication coverage was expanded to include SCRAM and OIDC with cURL, NodeJS, and Python examples across environments. Consumer and topic workflows were unified and updated to environment-specific paths. Legacy sections were consolidated, and Swagger URLs are now conditional. Numerous ifdef/ifndef blocks separate cloud vs non-cloud content.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Dev as Client (Dev/Script)
  participant UI as Cloud UI
  participant HP as HTTP Proxy
  participant RP as Redpanda
  note over Dev,HP: Environment selection and base_uri resolution
  Dev->>UI: Retrieve proxy endpoint (cloud)
  UI-->>Dev: Return base_uri (e.g., https://...:30082)
  note over Dev: Non-cloud: base_uri uses host:8082<br/>Private connectivity: host:30282
  Dev->>HP: Request (e.g., GET {base_uri}/v1/topics)
  HP->>RP: Forward request
  RP-->>HP: Response
  HP-->>Dev: Response
  note right of HP: All examples standardize on base_uri

Loading

sequenceDiagram
  autonumber
  actor Dev as Client
  participant HP as HTTP Proxy
  participant IDP as OIDC Provider
  participant RP as Redpanda

  rect rgba(200,230,255,0.3)
  note over Dev,IDP: OIDC authentication flow (cloud and non-cloud)
  Dev->>IDP: Obtain access token (OIDC)
  IDP-->>Dev: Access token (JWT)
  Dev->>HP: HTTP request with Authorization: Bearer <token>
  HP->>RP: Authenticated request (OIDC context)
  RP-->>HP: Response
  HP-->>Dev: Response
  end

Loading

sequenceDiagram
  autonumber
  actor Dev as Client
  participant HP as HTTP Proxy
  participant RP as Redpanda

  rect rgba(220,255,220,0.4)
  note over Dev,HP: SCRAM authentication flow (cloud and non-cloud)
  Dev->>HP: HTTP request with SCRAM credentials
  HP->>RP: Authenticate via configured mechanism
  RP-->>HP: Auth result
  alt Auth success
    HP->>RP: Forward API request
    RP-->>HP: Response
    HP-->>Dev: Response
  else Auth failure
    HP-->>Dev: 401/403 error
  end
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• properties + sec: broker properties updates #1298: Also updates modules/develop/partials/http-proxy.adoc, overlapping on SCRAM/OIDC authentication guidance and broker auth references.
• http-proxy: Conditionalize links to Self-Managed topics #1315: Modifies the same file to add environment-specific conditionals, aligning with cloud vs non-cloud authentication content.

Suggested reviewers

• BenPope
• Feediver1

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes Check	⚠️ Warning	The PR introduces extensive restructuring, environment-based conditionals, OIDC authentication sections, new seed port guidance, and additional example blocks beyond the specific endpoint fixes and placeholder unification requested in DOC-743.	Consider narrowing the scope to just the incorrect endpoint corrections and placeholder consistency or splitting the broader content restructures and new examples into a separate follow-up PR.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title “Reorganize HTTP Proxy doc” succinctly captures the main change of restructuring the HTTP Proxy documentation without extraneous detail or noise, making it clear to reviewers what the PR does.
Linked Issues Check	✅ Passed	The changes correct the incorrect offset endpoints, unify base_uri usage across examples, and address the core documentation accuracy goals specified in DOC-743, thereby meeting the coding requirements of the linked issue.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.
Description Check	✅ Passed	The pull request description adheres to the repository’s template by including a detailed Description section with bullet points of changes, a “Resolves” link to the JIRA ticket, a placeholder for the review deadline, valid Page previews URLs, and the requisite Checks checklist. All required headings and structure are present and correctly formatted. Although the review deadline field is empty, its presence allows for a straightforward update.

---

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

[michael-redpanda]

Looks good, just one comment

[Feediver1]

Use xref:{install-rpk-doc}[rpk] to create a topic to use for this guide.
Kind of confused by the "to use for this guide"--is that the only context in which a created topic is to be used?