docs: add cpflow vs. Terraform guidance for Control Plane#751
Conversation
Readers see the official cpln Terraform provider and ask whether the .controlplane/templates/*.yml files should be Terraform instead. Add a focused doc that answers it: the YAML covers two concerns (cpflow's own controlplane.yml orchestration config vs. cpln apply resource manifests), and Terraform only addresses the latter. Includes a decision rule and a concrete HCL mapping of app.yml + rails.yml to cpln_gvc/cpln_workload so the trade-offs (per-PR interpolation, deploy-time image injection, provision-vs-deploy separation) are visible. Linked from .controlplane/readme.md's Project Configuration section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
🚀 Quick Review App CommandsWelcome! Here are the commands you can use in this PR:
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
WalkthroughThis PR adds documentation that clarifies the division between cpflow and Terraform. A new document explains why cpflow-managed YAML is not a Terraform substitute, then provides a conceptual Terraform HCL mapping for key templates and notes feature gaps. The readme links to this resource for trade-offs context. Changescpflow vs Terraform Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
Greptile SummaryThis PR adds a new
Confidence Score: 4/5Docs-only change with no impact on deployed code or infrastructure; safe to merge after fixing the two HCL snippet issues. All changes are documentation. The new file is well-reasoned and the readme.md pointer is correct. Two HCL syntax mistakes in the appendix code block — an invalid inline multi-attribute variable declaration and a port number expressed as a string — would cause copy-paste failures for any reader who tries to apply the snippets directly. .controlplane/docs/cpflow-vs-terraform.md — the HCL appendix block has the two syntax issues; everything else in both files is fine. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Developer question:\nShould I use Terraform\nfor .controlplane/templates?] --> B{What concern?}
B --> C[App build / deploy /\nrelease-phase migrations]
B --> D[Ephemeral per-PR\nreview apps]
B --> E[Staging → production\npromotion]
B --> F[Durable shared infra:\norgs, domains, IAM,\nexternal RDS/ElastiCache]
C --> G[Use cpflow]
D --> G
E --> G
F --> H[Use Terraform\ncpln provider]
G --> I[controlplane.yml\ndrives workflow]
H --> J[cpln_gvc / cpln_workload /\ncpln_identity resources]
I --> K[build-image → deploy-image\nrelease script → promote]
J --> L[terraform apply\nstate-managed infra]
Reviews (1): Last reviewed commit: "docs: add cpflow vs. Terraform guidance ..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| # variables.tf | ||
| variable "app_name" { type = string } # cpflow injects {{APP_NAME}} per review app; | ||
| # in TF this is a -var or a workspace name. | ||
| variable "location" { type = string default = "aws-us-east-2" } |
There was a problem hiding this comment.
type and default on the same line without either separator is a parse error that terraform validate will reject. A reader who copies this snippet verbatim will get an immediate failure.
| variable "location" { type = string default = "aws-us-east-2" } | |
| variable "location" { | |
| type = string | |
| default = "aws-us-east-2" | |
| } |
|
|
||
| ports { | ||
| protocol = "http" # keep http — Thruster does HTTP/2 on the TLS frontend | ||
| number = "3000" |
There was a problem hiding this comment.
cpln_workload provider schema defines the ports.number attribute as a number type, not a string. Passing "3000" (string) instead of 3000 (integer) will produce a type-mismatch error at terraform plan time if the provider enforces strict typing, and at minimum creates misleading documentation for readers.
| number = "3000" | |
| number = 3000 |
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Code Review: docs: add cpflow vs. Terraform guidance for Control PlaneOverall: Clear, well-structured docs-only addition. The decision table and HCL appendix are genuinely useful for readers coming from a Terraform background. Two minor HCL correctness issues in the appendix worth fixing before merge. IssuesHCL type error — port number is a string Hardcoded Minor observations
SummaryConceptual content is solid. The two HCL issues (port type, secret handling) are the only changes worth making; the rest is polish. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
|
||
| ports { | ||
| protocol = "http" # keep http — Thruster does HTTP/2 on the TLS frontend | ||
| number = "3000" |
There was a problem hiding this comment.
HCL port numbers are integers, not strings — the cpln provider schema expects a number type here. This should be:
| number = "3000" | |
| number = 3000 |
Passing a string may cause a type-mismatch error on terraform apply depending on how strictly the provider validates the attribute.
| RAILS_ENV = "production" | ||
| NODE_ENV = "production" | ||
| RAILS_SERVE_STATIC_FILES = "true" | ||
| SECRET_KEY_BASE = "placeholder_secret_key_base_for_test_apps_only" |
There was a problem hiding this comment.
This is the one spot in the appendix that could teach a bad pattern. Hardcoding a secret value in a GVC env map is exactly what readers should not do when they adapt this to a real app — but the example doesn't signal that.
Two lines below, RENDERER_PASSWORD and REACT_ON_RAILS_PRO_LICENSE correctly use cpln://secret/... references. Suggest matching that style, or at minimum adding an inline comment:
| SECRET_KEY_BASE = "placeholder_secret_key_base_for_test_apps_only" | |
| SECRET_KEY_BASE = "cpln://secret/${var.app_name}-secrets.SECRET_KEY_BASE" # use a secret ref or var.secret_key_base (sensitive = true) |
Even for a tutorial placeholder, showing the cpln://secret/ pattern is consistent with the two lines below and avoids the "copy the example into prod" failure mode.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
1 participant
Summary
Readers see Control Plane's official
cplnTerraform provider and ask whether the.controlplane/templates/*.ymlfiles should be Terraform instead. This adds a focused doc that answers it.The key insight: the YAML in
.controlplane/covers two concerns, and Terraform only addresses one of them.controlplane.yml— cpflow's own orchestration config (app/org aliases,app_workloads,release_script,upstreampromotion, review-app prefix matching). No Terraform equivalent.templates/*.yml— nativecpln applyresource manifests. These could becpln_*Terraform resources.Terraform does not replace the cpflow app lifecycle (
build-image/deploy-image, release-phase migrations, ephemeral per-PR review apps, staging→production promotion), so for this tutorial app the recommendation is to stay on cpflow.What's in the doc
templates/app.yml+templates/rails.ymltocpln_gvc/cpln_identity/cpln_workload, with inline comments calling out exactly where the two models diverge (per-PR{{APP_NAME}}interpolation, deploy-time{{APP_IMAGE_LINK}}injection, and the provision-vs-deploy separation).Changes
.controlplane/docs/cpflow-vs-terraform.md..controlplane/readme.md's Project Configuration section.Docs-only; no code or deploy behavior changes.
🤖 Generated with Claude Code
Note
Low Risk
Documentation-only changes with no runtime, deploy, or infrastructure behavior impact.
Overview
Adds
.controlplane/docs/cpflow-vs-terraform.mdto explain why this tutorial app keeps cpflow instead of moving.controlplaneYAML to the officialcplnTerraform provider. The doc splitscontrolplane.yml(orchestration with no TF equivalent) fromtemplates/*.yml(could becpln_*resources), lists what Terraform does not cover (build/deploy, release migrations, review apps, promotion), and gives a cpflow vs Terraform decision table.An HCL appendix maps
templates/app.ymlandtemplates/rails.ymltocpln_gvc,cpln_identity, andcpln_workload, with comments on divergences like{{APP_NAME}}, deploy-time{{APP_IMAGE_LINK}}, and provision vs deploy..controlplane/readme.mdgains a short link under Project Configuration pointing readers to that doc.Reviewed by Cursor Bugbot for commit 8bf6e3a. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by CodeRabbit