docs: Update README with up-to-date information #587
Conversation
jeanduplessis
requested review from
erhancagirici,
sergenyalcin and
ulucinar
as code owners
Completely rewrite README.md to align with open-source best practices: - Add Key Features section highlighting Terraform execution modes - Add "When to Use Upjet" guidance vs native providers - Include architecture narrative with build-time vs runtime flow - Expand provider list with accurate GitHub links - Add comprehensive documentation table linking all guides - Remove Quick Start (too complex for README scope) - Update copyright year to 2026 - Improve descriptions and structure throughout The README now provides clear value proposition, technical context, and proper navigation to detailed documentation. Signed-off-by: Jean du Plessis <jean@upbound.io>
jeanduplessis
force-pushed
the
readme-update
branch
from
a91a5b5 to
afd0e68
Compare
|
@CodeRabbit please review |
|
@jeanduplessis I'll review the README updates for you now! ✅ Actions performedReview triggered.
|
📝 WalkthroughWalkthroughREADME.md comprehensively restructured with updated copyright year, new Table of Contents, expanded sections covering Key Features, Architecture, providers, documentation guides, and community resources. Overall shift from minimal description to detailed, organized documentation layout. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
133-153: Consider wrapping line 139 for consistency with the 100-character guideline.The Contributing, Community, Prior Art, and License sections are well-organized and CONTRIBUTING.md is properly referenced. However, line 139 (the Slack community link) extends to 123 characters, which exceeds the 100-character wrapping guideline. Consider breaking this into two lines to maintain consistency:
- **Slack:** [#upjet](https://crossplane.slack.com/archives/C05T19TB729) on [Crossplane Slack](https://slack.crossplane.io)This keeps the link definitions readable while respecting the formatting standards for the documentation.
🤖 Fix all issues with AI agents
In @README.md:
- Around line 106-119: Update the provider list entry that currently uses the
incorrect capitalization "Github" to the correct "GitHub" by editing the README
list item text (the line containing the "-
[Github](https://github.com/crossplane-contrib/provider-upjet-github)" entry);
leave the URL unchanged and only adjust the displayed link text to "GitHub".
- Around line 86-104: The README references an image at
docs/images/framework-overview.jpg that couldn't be found and two list lines
exceed the 100-char limit; confirm the image file exists in the repo or update
the path in the README to the correct location (or remove the image tag), and
wrap the long list entries (the lines for "3. Documentation Scraper - Extracts
and generates API documentation from Terraform docs" and "4. Migration Framework
- Supports migrating resources between provider versions") so each line is <=100
characters while preserving wording and list numbering.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
docs/images/framework-overview.jpgis excluded by!**/*.jpgand included by nonedocs/images/upjet-build-runtime.jpgis excluded by!**/*.jpgand included by none
📒 Files selected for processing (1)
README.md
🧰 Additional context used
📓 Path-based instructions (1)
**/*.md
⚙️ CodeRabbit configuration file
**/*.md: Ensure Markdown files are wrapped at 100 columns for consistency and
readability. Lines can be longer if it makes links more readable, but
otherwise should wrap at 100 characters. Check for proper heading
structure, clear language, and that documentation is helpful for users.
Files:
README.md
🪛 LanguageTool
README.md
[uncategorized] ~117-~117: The official name of this software platform is spelled with a capital “H”.
Context: ...grafana/crossplane-provider-grafana) - [Github](https://github.com/crossplane-contrib/...
(GITHUB)
🔍 Remote MCP
Summary of Relevant Context for PR Review
Based on my research, here is the additional context that would help effectively review this README update:
Project Context and Purpose
Upjet is a code generation framework and runtime for Crossplane providers. More specifically, the Crossplane steering committee voted to accept the donation of Upbound's provider framework (Upjet) as well as key Crossplane providers for the major cloud providers, making it a foundational component of the Crossplane ecosystem. Upjet automates the creation of Crossplane providers based on existing Terraform providers by transforming Terraform provider schemas into Crossplane CRDs.
Technology Evolution and Capabilities
Upjet is the second generation approach that is more stable, has more customization points, and includes new code generators that enable automatically generating API documentation and example YAMLs. Upbound's engineering team made a breakthrough to improve the overall efficiency of Upjet-based providers significantly, bringing faster provisioning and reconciliation of resources while reducing running costs.
Project Maturity and Governance
Upbound donated their entire Upjet provider framework to the Crossplane project, with this technology making the move from being a vendor-driven project to being completely owned and driven by the CNCF and Crossplane community. Upjet and the providers it generates use the permissive Apache 2 license.
Community and Documentation Resources
The project has comprehensive documentation available, including guides on generating a Crossplane provider based on an existing Terraform provider using Upjet, using the Terraform GitHub provider as an example. The README update aligns with the project's emphasis on clear documentation and navigation, which the PR accomplishes through the new documentation table and structured sections.
[::web_search::]
🔇 Additional comments (6)
README.md (6)
1-18: LGTM! Clean header and badges.The copyright update to 2026 is appropriate, and the badge section is well-formatted. The badge links exceed 100 characters, but this is acceptable per the coding guidelines for improving link readability.
32-42: Excellent Table of Contents!The TOC is comprehensive and well-organized, providing clear navigation to all major sections.
44-68: Great feature breakdown!The Key Features section effectively highlights Upjet's capabilities with appropriate technical detail. The three-tier approach to Terraform execution modes (CLI, SDK v2, Framework) is particularly valuable information for users.
70-84: Valuable guidance for users!This section provides balanced, practical advice that will help users make informed decisions. Thank you for including scenarios where a native provider might be more appropriate—this shows project maturity and user-focused thinking.
121-131: Great documentation table with correct file paths!The documentation table provides excellent navigation for new contributors. All referenced documentation files exist and are properly linked. The table structure is clean and easy to follow.
20-29: Overview section is clear—let's verify a couple of details.The overview effectively communicates Upjet's purpose and value proposition. Before merging, could you help verify:
- The image path
docs/images/upjet-build-runtime.jpgis correct and the file exists in the repository- The claim of "50+ community providers" is current—could you point to where this count comes from or any documentation that tracks these providers?
These small clarifications will help ensure the README is accurate and maintainable going forward.
| ## Architecture | ||
|
|
||
| Upjet bridges the gap between Terraform's vast provider ecosystem and | ||
| Kubernetes-native infrastructure management. At build time, Upjet reads a | ||
| Terraform provider's schema and generates everything needed for a Crossplane | ||
| provider: Go types, Custom Resource Definitions, and reconciliation controllers. | ||
| At runtime, these controllers use Terraform's proven resource logic to manage | ||
| infrastructure, while exposing a pure Kubernetes API to users. | ||
|
|
||
| <div align="center"> | ||
|
|
||
|  | ||
|
|
||
| </div> | ||
|
|
||
| 1. **Code Generation Pipeline** - Transforms Terraform schemas into Go types, CRDs, and controllers | ||
| 2. **Generic CRD Reconciler** - Runtime that handles reconciliation for all generated resources | ||
| 3. **Documentation Scraper** - Extracts and generates API documentation from Terraform docs | ||
| 4. **Migration Framework** - Supports migrating resources between provider versions |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's check if the image file exists
if [ -f "docs/images/framework-overview.jpg" ]; then
echo "✓ Image file exists"
else
echo "✗ Image file does NOT exist"
# List what's actually in the docs/images directory if it exists
if [ -d "docs/images" ]; then
echo "Contents of docs/images:"
ls -la docs/images/
else
echo "docs/images/ directory does not exist"
fi
fiRepository: crossplane/upjet
Length of output: 176
🏁 Script executed:
# Check the exact line lengths in the Architecture section
# First, find the README.md file
find . -name "README.md" -type f | head -5Repository: crossplane/upjet
Length of output: 176
🏁 Script executed:
# Get lines 86-104 from README.md and count characters
sed -n '86,104p' README.md | cat -n | while IFS= read -r line; do
line_num=$(echo "$line" | awk '{print $1}')
content=$(echo "$line" | cut -d' ' -f2-)
char_count=${#content}
actual_line=$((85 + line_num))
if [ $char_count -gt 100 ]; then
echo "Line $actual_line: $char_count characters (EXCEEDS 100)"
echo " Content: $content"
else
echo "Line $actual_line: $char_count characters ✓"
fi
doneRepository: crossplane/upjet
Length of output: 790
🏁 Script executed:
# Let's search for the image file in the repository on GitHub
# Check if the image file is referenced or mentioned in the codebase
rg "framework-overview" --type md --type txt || echo "No matches found"Repository: crossplane/upjet
Length of output: 125
🌐 Web query:
crossplane/upjet github repository framework-overview.jpg image docs
💡 Result:
I searched the Upjet repository and docs but could not find a file named framework-overview.jpg in the crossplane/upjet repo. The repository and docs (which list the docs/ folder) are here for reference:
- crossplane/upjet (repo). [1]
- Upjet docs index / overview (third‑party index of repo docs). [2]
Do you want me to (a) search the repo for similarly named images (PNG/SVG) and return any matches, or (b) open the docs folder and list its images/diagrams for you?
🏁 Script executed:
# Get the exact lines with content
sed -n '101,102p' README.md | cat -nRepository: crossplane/upjet
Length of output: 269
Please verify the image file and wrap two lines to meet the 100-character guideline.
The architecture description is clear and informative. However, there are two items to address:
-
The image path
docs/images/framework-overview.jpgcould not be verified in the repository. Please confirm the file exists or update the reference if it's located elsewhere. -
Lines 101 and 102 exceed the 100-character wrapping guideline:
- Line 101: 105 characters
- Line 102: 101 characters
Consider wrapping these lines for consistency:
-1. **Code Generation Pipeline** - Transforms Terraform schemas into Go types, CRDs, and controllers
+1. **Code Generation Pipeline** - Transforms Terraform schemas into Go types,
+ CRDs, and controllers
-2. **Generic CRD Reconciler** - Runtime that handles reconciliation for all generated resources
+2. **Generic CRD Reconciler** - Runtime that handles reconciliation for all
+ generated resources🤖 Prompt for AI Agents
In @README.md around lines 86 - 104, The README references an image at
docs/images/framework-overview.jpg that couldn't be found and two list lines
exceed the 100-char limit; confirm the image file exists in the repo or update
the path in the README to the correct location (or remove the image tag), and
wrap the long list entries (the lines for "3. Documentation Scraper - Extracts
and generates API documentation from Terraform docs" and "4. Migration Framework
- Supports migrating resources between provider versions") so each line is <=100
characters while preserving wording and list numbering.
| ## Providers Built with Upjet | ||
|
|
||
| ### Major Cloud Providers | ||
|
|
||
| - [Amazon Web Services](https://github.com/crossplane-contrib/provider-upjet-aws) | ||
| - [Microsoft Azure](https://github.com/crossplane-contrib/provider-upjet-azure) | ||
| - [Google Cloud Platform](https://github.com/crossplane-contrib/provider-upjet-gcp) | ||
|
|
||
| ### Additional Providers | ||
|
|
||
| - [Grafana](https://github.com/grafana/crossplane-provider-grafana) | ||
| - [Github](https://github.com/crossplane-contrib/provider-upjet-github) | ||
|
|
||
| - [upbound/provider-aws](https://github.com/upbound/provider-aws) | ||
| - [upbound/provider-azure](https://github.com/upbound/provider-azure) | ||
| - [upbound/provider-gcp](https://github.com/upbound/provider-gcp) | ||
| - [aviatrix/crossplane-provider-aviatrix](https://github.com/Aviatrix/crossplane-provider-aviatrix) | ||
| Browse the [Upbound Marketplace](https://marketplace.upbound.io/providers) for a full list of available providers. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, find and read the README.md file
fd -t f "README.md" -x wc -l {} \;
# Find the README.md and read lines around 106-119
fd -t f "README.md" -x sed -n '100,125p' {} \; -x echo "File: {}"Repository: crossplane/upjet
Length of output: 1271
🏁 Script executed:
# Check exact line lengths for the Providers section
sed -n '106,119p' ./README.md | while IFS= read -r line; do
length=${#line}
echo "Length $length: $line"
doneRepository: crossplane/upjet
Length of output: 796
🌐 Web query:
crossplane-contrib/provider-upjet-aws github repository
💡 Result:
The crossplane-contrib/provider-upjet-aws repository is the Upjet-based Crossplane AWS provider (XRM-conformant managed resources for AWS). It’s hosted on GitHub (Apache‑2.0) and uses a family-based packaging model (individual service packages plus a provider-family coordinator). See the README for quickstart, build, and contribution instructions. [1][2]
Links:
- Repository (README, code, docs): https://github.com/crossplane-contrib/provider-upjet-aws. [1]
- Releases & change notes (versions, breaking changes): Releases page. [2]
🌐 Web query:
crossplane-contrib/provider-upjet-azure github repository
💡 Result:
The GitHub repository "crossplane-contrib/provider-upjet-azure" is the Upjet-based Azure provider for Crossplane (managed resources generated with Upjet). See the repository README for installation, usage, and API details. [1]
For context, the older crossplane-contrib/provider-azure repo has been archived and users are recommended to use the upjet-based provider instead. [2]
🌐 Web query:
crossplane-contrib/provider-upjet-gcp github repository
💡 Result:
The repository "provider-upjet-gcp" is the Upjet-based Crossplane GCP provider (source, docs, CRDs & controllers) hosted under crossplane-contrib on GitHub: github.com/crossplane-contrib/provider-upjet-gcp. It’s Apache‑2.0 licensed, intended as the Upjet replacement for the older provider-gcp, and includes README, examples, and a releases page with changelogs and upgrade notes. [1][2][3]
Sources:
- Repo: github.com/crossplane-contrib/provider-upjet-gcp. [1]
- Note recommending provider-upjet-gcp over provider-gcp (archived). [2]
- Releases / changelog and upgrade notes. [3]
🌐 Web query:
grafana/crossplane-provider-grafana github repository
💡 Result:
The Grafana Crossplane provider repository (grafana/crossplane-provider-grafana) is on GitHub — a Crossplane provider built with Upjet that exposes managed Grafana resources (CRDs) and is published as an Upbound package. The repo includes README, examples, CRDs and install instructions (e.g., up ctp provider install or applying the packaged crossplane.yaml). [1][2][3]
Key links:
- GitHub repo (README, code, install examples). [1]
- API/CRD listings and releases (tags such as v0.40.0 shown). [2]
- Grafana blog/docs describing using Crossplane provider for “Grafana as code.” [3]
If you want, I can:
- open the repo and list latest release/tag and recent commits, or
- show install steps or example CRs from the repo. Which would you like?
🌐 Web query:
crossplane-contrib/provider-upjet-github repository
💡 Result:
provider-upjet-github is a Crossplane provider (under crossplane-contrib) that uses Upjet code generation to expose XRM-style managed resources for the GitHub API. The repository contains the provider code, README, supported resource list (repos, teams, actions secrets/variables, organization rulesets, etc.), installation examples (pkg Provider and up ctp provider install), and provider-config examples for PAT and GitHub App authentication. See the repository for full API/resource details and examples. [1]
Key points:
- Built with Upjet and follows Crossplane XRM conventions. [1]
- Authentication supports personal access tokens and GitHub App (PEM) formats; owner scope determines resource scope. [1]
- Shows supported managed resources (Actions, Teams, Repository, Organization, etc.). [1]
Sources: crossplane-contrib/provider-upjet-github repository README. [1]
Fix "Github" capitalization—all provider links verified accurate.
Thanks for the careful review! The "Github" capitalization error on line 117 does need fixing. I've verified all five provider repositories and the Marketplace link, and they're all current and accurate:
✓ All provider repos exist and are active (AWS, Azure, GCP, Grafana, GitHub)
✓ Upbound Marketplace link is valid
Line 119 exceeds 100 characters, but per guidelines this is acceptable since it contains a link and breaking it would reduce readability.
Fix needed:
- Line 117: Change "Github" to "GitHub"
🧰 Tools
🪛 LanguageTool
[uncategorized] ~117-~117: The official name of this software platform is spelled with a capital “H”.
Context: ...grafana/crossplane-provider-grafana) - [Github](https://github.com/crossplane-contrib/...
(GITHUB)
🤖 Prompt for AI Agents
In @README.md around lines 106 - 119, Update the provider list entry that
currently uses the incorrect capitalization "Github" to the correct "GitHub" by
editing the README list item text (the line containing the "-
[Github](https://github.com/crossplane-contrib/provider-upjet-github)" entry);
leave the URL unchanged and only adjust the displayed link text to "GitHub".
Completely rewrite README.md to align with open-source best practices:
The README now provides clear value proposition, technical context, and proper navigation to detailed documentation.
Description of your changes
I have:
make reviewableto ensure this PR is ready for review.Addedbackport release-x.ylabels to auto-backport this PR if necessary.How has this code been tested