docs: add ADC user documentation#524
Conversation
📝 WalkthroughWalkthroughThis PR adds a new documentation suite under ChangesADC Documentation
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 6✅ Passed checks (6 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
@coderabbitai pause |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/guides/label-selector.md`:
- Around line 38-42: The fenced example in the label-selector documentation is
using a bare code fence, which triggers markdownlint. Update the example to
declare an explicit language hint on the fence (for example, text) while keeping
the existing explanatory content unchanged so the docs lint cleanly.
- Around line 34-35: The scope description in the label selector guide is too
narrow and should reflect that remote filtering applies to every top-level
resource collection except global_rules and plugin_metadata. Update the wording
in the label selector docs to make the exhaustive scope explicit, using the
surrounding explanation of ADC fetch behavior and the top-level resource
granularity to clarify that services, consumers, ssls, and any other top-level
collections are included unless explicitly exempted.
In `@docs/reference/configuration.md`:
- Around line 70-90: The sample credentials in the configuration documentation
use values that resemble real API keys, so replace them with clearly fake
placeholder strings in the consumers example. Update the example under the
consumers section to keep the same structure and symbols such as username,
credentials, and key-auth, but use unmistakable non-secret placeholder values
for each key field so readers cannot mistake them for real credentials.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 7e6fadf0-ec0b-4bd2-8453-60490846202c
📒 Files selected for processing (8)
README.mddocs/README.mddocs/guides/label-selector.mddocs/guides/resource-ids.mddocs/guides/workflow.mddocs/reference/cli.mddocs/reference/configuration.mddocs/reference/openapi-converter.md
✅ Action performedReviews paused. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eaf8a4ebe8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Pull request overview
This PR adds a set of user-facing ADC documentation pages (guides + references) within the source repository, and links to them from the root README so the repo can act as the canonical documentation source.
Changes:
- Added a docs landing page plus workflow/resource ID/label selector guides under
docs/. - Added reference docs for CLI commands, configuration format, and OpenAPI conversion behavior.
- Linked the root
README.mdto the new documentation entry point.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds a “Documentation” section linking to the new docs entry point. |
| docs/README.md | New documentation landing page that routes readers to guides and references. |
| docs/guides/workflow.md | New end-to-end workflow guide (configure, lint/validate/diff/sync, CI flow). |
| docs/guides/resource-ids.md | New explanation of how ADC generates/matches IDs and implications for adoption/renames. |
| docs/guides/label-selector.md | New guide describing label selector scoping, filtering behavior, and limits. |
| docs/reference/cli.md | New CLI reference (global options, backend options, command examples). |
| docs/reference/configuration.md | New configuration reference covering structure, variables, and core schema fields. |
| docs/reference/openapi-converter.md | New OpenAPI converter reference describing supported x-adc-* extensions and behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6f11d53e95
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: caa8691957
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3f9dddffe3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ | | ||
| | `id` | string | No | Explicit backend ID for named upstreams. | | ||
| | `name` | string | No | Upstream name. | | ||
| | `scheme` | string | No | Protocol: `http`, `https`, `grpc`, `grpcs`. | |
There was a problem hiding this comment.
For stream-route or Kafka upstream configs, this line tells users that only http, https, grpc, and grpcs are valid, but the ADC schema also accepts tcp, tls, udp, and kafka for upstream.scheme (upstreamSchemeSchema / schema.json). Following this reference can make users choose the wrong protocol for non-HTTP traffic or conclude ADC cannot manage those upstreams, so the documented valid values should match the schema.
Useful? React with 👍 / 👎.
Description
This PR adds user-facing ADC documentation to the source repo. It keeps detailed ADC docs with the ADC codebase, while the docs site can later link to this repo as the source of truth instead of duplicating the full ADC reference.
The new docs cover:
docs/README.mdThe restructure preserves the product-authored information from the original draft, but reorganizes it into clearer guide/reference categories. Factual behavior was checked against source code and tests, including CLI command definitions, label selector loading/filtering, resource ID generation/diff behavior, and OpenAPI converter implementation/test fixtures.
Validation
pnpm exec prettier --check README.md docs/README.md docs/guides/workflow.md docs/guides/resource-ids.md docs/guides/label-selector.md docs/reference/cli.md docs/reference/configuration.md docs/reference/openapi-converter.mdgit diff --checkpnpm exec nx test converter-openapiChecklist
Tests are not added because this is a documentation-only change. Targeted validation is listed above.
Summary by CodeRabbit
docs/area for CLI, configuration, and full ADC workflow guidance.--label-selectorscoping/semantics, backend resourceidhandling, and an end-to-end ADC workflow.x-adc-*extensions).