Backend configuration guide

docs/.vale/styles/config/vocabularies/Suga/accept.txt

@@ -9,6 +9,7 @@ Supabase
 Planetscale
 liquibase
 allowlisting
+cdktf
 
 # Defaults from mintlify
 Mintlify

docs/docs.json

@@ -40,7 +40,8 @@
             "pages": [
               "guides/add-suga",
               "guides/database-migration",
-              "guides/add-suga"
+              "guides/migrate-existing",
+              "guides/terraform-backend-config"
             ]
           }
         ]

docs/guides/overview.mdx

@@ -25,6 +25,9 @@ These guides provide practical, hands-on instructions for implementing common in
   >
     Learn how to run database migrations as part of your deployment pipeline.
   </Card>
+  <Card title="Terraform Backend Configuration" icon="cloud" href="/guides/terraform-backend-config">
+    Configure remote state management for Terraform stacks generated with Suga.
+  </Card>
 </CardGroup>
 
 ## Prerequisites

docs/guides/terraform-backend-config.mdx

@@ -0,0 +1,152 @@
+---
+title: 'Terraform Backend Configuration'
+description: 'Configure remote state management for Terraform stacks generated with Suga'
+---
+
+## Overview
+
+Suga uses [CDKTF](https://developer.hashicorp.com/terraform/cdktf) (Cloud Development Kit for Terraform) to generate Terraform configurations. By default, the generated stacks use local [state](https://developer.hashicorp.com/terraform/language/state) files. For production environments and team collaboration, you'll want to configure a remote backend to store your Terraform state securely and enable state locking.
+
+This guide covers how to add backend configuration to your Suga-generated Terraform stacks for common backend providers.
+
+## Prerequisites
+
+<Info>
+  Ensure you have completed these steps before configuring a backend.
+</Info>
+
+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
+
+## Understanding Suga's CDKTF Output
+
+When you run `suga build`, CDKTF synthesizes your infrastructure into standard Terraform JSON configuration files:
+
+```bash title="Generated Directory Structure" icon="folder-tree"
+terraform/
+└── stacks/
+    └── <stack_name>/
+        ├── cdk.tf.json      # Main configuration
+        └── ...
+```
+
+The synthesized output can be found in the `terraform` directory.
+
+## Adding Backend Configuration
+
+After running `suga build`, add a backend configuration file to the synthesized output:
+
+<Steps>
+  <Step title="Generate the Stack" icon="hammer">
+    ```bash title="Generate Terraform Stack" icon="hammer"
+    suga build
+    ```
+  </Step>
+
+  <Step title="Create Backend Configuration" icon="file-plus">
+    Create `backend.tf` in the synthesized stack directory:
+
+    ```bash title="Create Backend File" icon="file-plus"
+    touch terraform/stacks/<stack_name>/backend.tf
+    ```
+  </Step>
+
+  <Step title="Add Backend Configuration">
+    Choose your backend provider and add the appropriate configuration:
+
+    <Expandable title="AWS S3 Backend" defaultOpen={false}>
+      ```hcl title="backend.tf - AWS S3" icon="aws"
+      terraform {
+        backend "s3" {
+          bucket         = "my-terraform-state-bucket"
+          key            = "suga/terraform.tfstate"
+          region         = "us-east-1"
+          encrypt        = true
+          dynamodb_table = "terraform-locks"
+        }
+      }
+      ```
+
+      <Warning>
+        Ensure your S3 bucket has versioning enabled and consider enabling MFA delete for production environments.
+      </Warning>
+    </Expandable>
+
+    <Expandable title="Google Cloud Storage Backend" defaultOpen={false}>
+      ```hcl title="backend.tf - Google Cloud" icon="cloud"
+      terraform {
+        backend "gcs" {
+          bucket = "my-terraform-state-bucket"
+          prefix = "suga/terraform/state"
+        }
+      }
+      ```
+
+      <Tip>
+        Enable object versioning on your GCS bucket to maintain state history.
+      </Tip>
+    </Expandable>
+
+    <Expandable title="Azure Storage Backend" defaultOpen={false}>
+      ```hcl title="backend.tf - Azure Storage" icon="cloud"
+      terraform {
+        backend "azurerm" {
+          resource_group_name  = "terraform-state-rg"
+          storage_account_name = "terraformstatestorage"
+          container_name       = "terraform-state"
+          key                  = "suga.terraform.tfstate"
+        }
+      }
+      ```
+    </Expandable>
+
+    <Expandable title="Terraform Cloud Backend" defaultOpen={false}>
+      ```hcl title="backend.tf - Terraform Cloud" icon="cloud"
+      terraform {
+        backend "remote" {
+          organization = "my-org"
+          workspaces {
+            name = "suga-production"
+          }
+        }
+      }
+      ```
+    </Expandable>
+  </Step>
+
+  <Step title="Initialize and Deploy" icon="rocket">
+    ```bash title="Initialize Terraform" icon="terminal"
+    cd terraform/stacks/<stack_name>
+    terraform init
+    ```
+
+    ```bash title="Deploy Infrastructure" icon="rocket"
+    terraform apply
+    ```
+  </Step>
+</Steps>
+
+<Info>
+  Only the cdktf files are managed by Suga. You can safely add custom `.tf` files to the stack directory to extend the configuration.
+</Info>
+
+## Managing Multiple Environments
+
+For managing multiple environments, we recommend using Terraform workspaces:
+
+```bash title="Create and Switch Workspaces" icon="git-branch"
+# Create and switch to staging environment
+terraform workspace new staging
+
+# Switch to production environment
+terraform workspace new production
+terraform workspace select production
+```
+
+<Tip>
+  Each workspace maintains its own state file, allowing you to manage different environments with the same configuration.
+</Tip>
+
+For comprehensive documentation on best practices, see the [official Terraform workspace docs](https://developer.hashicorp.com/terraform/language/state/workspaces).