Backend configuration guide

[tjholm]

Fixes NIT-186

[coderabbitai]

Walkthrough

• Added a Featured Guides card in docs/guides/overview.mdx linking to guides/terraform-backend-config (title: "Terraform Backend Configuration", icon: "cloud").
• Added docs/guides/terraform-backend-config.mdx with front matter and a guide covering prerequisites, CDKTF output locations (cdktf.out, terraform/stacks/<stack_name>/ with cdk.tf.json), adding backend.tf, backend examples, terraform init/apply, and workspace guidance.
• Added +cdktf to docs/.vale/styles/config/vocabularies/Suga/accept.txt.
• Updated docs/docs.json to replace a duplicate and add guides/migrate-existing and guides/terraform-backend-config in the Guides pages.
• No exported/public declarations changed.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between dd29862 and 4072c5b.

📒 Files selected for processing (2)

• docs/docs.json (1 hunks)
• docs/guides/overview.mdx (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/guides/overview.mdx
• docs/docs.json

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (4)

docs/guides/terraform-backend-config.mdx (4)

58-61: Link to the precise Terraform backend configuration page

Point directly to the configuration reference.

Apply this diff:

-See terraform docs on [backend configuration](https://developer.hashicorp.com/terraform/language/backend)
+See Terraform docs on [backend configuration](https://developer.hashicorp.com/terraform/language/settings/backends/configuration)

---

16-20: Add Terraform CLI as a prerequisite

Users need the Terraform CLI for init/apply steps.

Apply this diff:

 1. **Generate your Terraform stack** using `suga build` (this runs CDKTF synthesis)
-2. **Choose a backend provider** (AWS S3, Google Cloud Storage, Azure Storage, Terraform Cloud, etc.)
-3. **Create the backend storage resources** (bucket, storage account, workspace, etc.)
-4. **Ensure proper permissions** are configured for accessing the backend
+2. **Terraform CLI installed**
+3. **Choose a backend provider** (AWS S3, Google Cloud Storage, Azure Storage, Terraform Cloud, etc.)
+4. **Create the backend storage resources** (bucket, storage account, workspace, etc.)
+5. **Ensure proper permissions** are configured for accessing the backend

---

63-69: Optional: suggest plan before apply

Safer workflow for guides: run plan first.

Apply this diff:

   cd cdktf.out/stacks/<stack_name>
   terraform init
-  terraform apply
+  terraform plan
+  terraform apply

---

72-76: Add workspace-aware key example for multi-env backends

A short example avoids state collisions across workspaces.

Consider appending this snippet under the section:

# Example (S3 backend):
backend "s3" {
  bucket         = "my-tf-state"
  key            = "stacks/<stack_name>/${terraform.workspace}/terraform.tfstate"
  region         = "us-east-1"
  dynamodb_table = "tf-locks" # enables state locking
  encrypt        = true
}

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 819949d and b9791a2.

📒 Files selected for processing (2)

• docs/guides/overview.mdx (1 hunks)
• docs/guides/terraform-backend-config.mdx (1 hunks)

🔇 Additional comments (1)

docs/guides/overview.mdx (1)

19-21: New Featured Guide card looks good

Title, icon, href, and description align with the new guide.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/.vale/styles/config/vocabularies/Suga/accept.txt (1)

12-12: Add related tokens to avoid new spellcheck noise.

Consider whitelisting these literals referenced in the guide:

• cdk.tf.json
• cdktf.out
• backend.tf

Add them as separate lines in this file.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 6318e02 and 648a1e2.

📒 Files selected for processing (2)

• docs/.vale/styles/config/vocabularies/Suga/accept.txt (1 hunks)
• docs/guides/terraform-backend-config.mdx (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/guides/terraform-backend-config.mdx

🔇 Additional comments (1)

docs/.vale/styles/config/vocabularies/Suga/accept.txt (1)

12-12: Whitelist addition looks good.

Adding “cdktf” aligns with the new guide and prevents false positives.

[raksiv]

Looks good - as a bonus we could link them to this link to help them get starte with state locking since we mention it in the intro and then never again.

https://developer.hashicorp.com/terraform/language/state/locking

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/docs.json (1)

40-40: Minor readability: split long pages array across lines.

Keeps diffs cleaner as the list grows.

-            "pages": ["guides/database-migration", "guides/migrate-existing", "guides/terraform-backend-config"]
+            "pages": [
+              "guides/database-migration",
+              "guides/migrate-existing",
+              "guides/terraform-backend-config"
+            ]

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 648a1e2 and dd29862.

📒 Files selected for processing (2)

• docs/docs.json (1 hunks)
• docs/guides/terraform-backend-config.mdx (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/guides/terraform-backend-config.mdx

🔇 Additional comments (1)

docs/docs.json (1)

40-40: Verification complete: docs/docs.json is valid, docs/guides/terraform-backend-config.mdx exists, and guides/overview.mdx links to /guides/terraform-backend-config.

[nitric-bot]

🎉 This PR is included in version 0.0.3 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀