17 build starter set of dbt cloud topologies (#28)

* add basic topology

* bump for vulnerabilities

* bump tf lock

* bump module lock files

* update docs

Author: trouze

.github/workflows/ci.yml

@@ -6,15 +6,19 @@ on:
       - "**.tf"
       - "tests/**"
       - "schemas/**"
+      - "docs/reference/**"
+      - ".terraform-docs.yml"
       - ".github/workflows/ci.yml"
-      - "!examples/**"
+      - "!topologies/**"
   push:
     branches: [main]
     paths:
       - "**.tf"
       - "tests/**"
       - "schemas/**"
-      - "!examples/**"
+      - "docs/reference/**"
+      - ".terraform-docs.yml"
+      - "!topologies/**"
 
 permissions:
   contents: read
@@ -56,3 +60,30 @@ jobs:
 
       - name: Test (mock providers)
         run: terraform test
+
+  docs:
+    name: Docs up to date
+    runs-on: ubuntu-latest
+    env:
+      TERRAFORM_DOCS_VERSION: v0.20.0
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install terraform-docs
+        run: |
+          wget -q -O /tmp/terraform-docs.tar.gz \
+            https://github.com/terraform-docs/terraform-docs/releases/download/${TERRAFORM_DOCS_VERSION}/terraform-docs-${TERRAFORM_DOCS_VERSION}-linux-amd64.tar.gz
+          tar -xzf /tmp/terraform-docs.tar.gz -C /tmp
+          sudo mv /tmp/terraform-docs /usr/local/bin/
+          chmod +x /usr/local/bin/terraform-docs
+
+      - name: Regenerate docs
+        run: make docs
+
+      - name: Check for drift
+        run: |
+          if ! git diff --exit-code docs/reference/; then
+            echo ""
+            echo "Docs are out of date. Run 'make docs' locally and commit the result."
+            exit 1
+          fi

.github/workflows/deploy_docs.yml

@@ -13,7 +13,7 @@ on:
       - '*.tf'
       - 'modules/**'
       - 'schemas/**'
-      - 'examples/**'
+      - 'topologies/**'
       - '.github/workflows/deploy_docs.yml'
 
   pull_request:
@@ -24,7 +24,7 @@ on:
       - '*.tf'
       - 'modules/**'
       - 'schemas/**'
-      - 'examples/**'
+      - 'topologies/**'
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -77,15 +77,7 @@ jobs:
           terraform-docs --version
       
       - name: Generate Terraform documentation
-        run: |
-          # Generate main module docs
-          terraform-docs markdown table . > docs/reference/terraform.md
-          
-          # Generate submodule docs
-          for dir in modules/*/; do
-            module_name=$(basename $dir)
-            terraform-docs markdown table $dir > docs/reference/module-${module_name}.md
-          done
+        run: make docs
 
       - name: Setup Pages
         id: pages

.github/workflows/release.yml

@@ -1,7 +1,7 @@
 # release.yml — triggered by a version tag (e.g. git tag v1.2.3 && git push --tags).
 #
 # Produces two release assets:
-#   starter.tar.gz  — the examples/basic/ directory, ready to extract
+#   starter.tar.gz  — the topologies/basic/ directory, ready to extract
 #   install.sh      — bootstrap script that downloads starter.tar.gz
 
 name: Release
@@ -24,7 +24,7 @@ jobs:
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Package starter
-        run: tar -czf starter.tar.gz -C examples/basic .
+        run: tar -czf starter.tar.gz -C topologies/basic .
 
       - name: Create release with assets
         uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2

.github/workflows/test.yml

@@ -13,15 +13,15 @@ on:
       - "tests/**"
       - "schemas/**"
       - ".github/workflows/test.yml"
-      - "!examples/**"
+      - "!topologies/**"
   pull_request:
     paths:
       - "**.tf"
       - "modules/**"
       - "tests/**"
       - "schemas/**"
       - ".github/workflows/test.yml"
-      - "!examples/**"
+      - "!topologies/**"
 
 permissions:
   contents: read

.pre-commit-config.yaml

@@ -1,26 +1,23 @@
 repos:
   # Terraform formatting and documentation
-  - repo: https://github.com/terraform-docs/terraform-docs
-    rev: v0.16.0
+  - repo: local
     hooks:
       - id: terraform-docs-go
         name: terraform-docs
         description: Generate terraform documentation
         entry: terraform-docs -c .terraform-docs.yml
-        language: golang
+        language: system
         files: ^[^/]*\.tf$
         exclude: ^\.terraform/.*$
-        args: [--sort-by-required]
 
   # Terraform linting
-  - repo: https://github.com/terraform-linters/tflint
-    rev: v0.50.3
+  - repo: local
     hooks:
       - id: tflint
         name: tflint
         description: Run tflint to check terraform code quality
         entry: tflint
-        language: golang
+        language: system
         files: \.tf$
         exclude: ^\.terraform/.*$
 

.terraform-docs.yml

@@ -0,0 +1,20 @@
+formatter: "markdown table"
+
+output:
+  file: docs/reference/terraform.md
+  mode: replace
+
+sort:
+  enabled: true
+  by: required
+
+settings:
+  anchor: true
+  color: true
+  default: true
+  description: true
+  escape: true
+  indent: 2
+  required: true
+  sensitive: true
+  type: true

.terraform.lock.hcl

@@ -21,8 +21,15 @@ test: ## Run terraform test with mock providers (no credentials needed)
 test-integration: ## Run Go integration tests against a real dbt Cloud account (requires DBT_CLOUD_ACCOUNT_ID and DBT_CLOUD_TOKEN)
 	cd test && RUN_INTEGRATION_TESTS=1 go test -v -timeout 30m -run Integration ./...
 
-docs: ## Regenerate terraform-docs for all modules
-	pre-commit run terraform-docs-go --all-files
+docs: ## Regenerate terraform-docs for root module and all submodules
+	terraform-docs -c .terraform-docs.yml .
+	@for dir in modules/*/; do \
+		module=$$(basename $$dir); \
+		terraform-docs markdown table \
+			--output-file "../../docs/reference/module-$${module}.md" \
+			--output-mode replace \
+			"$$dir"; \
+	done
 
 pre-commit: ## Run all pre-commit hooks on staged files
 	pre-commit run

Makefile

@@ -1,7 +1,7 @@
 # terraform-dbtcloud-as-yaml
 
 [![Terraform Version](https://img.shields.io/badge/terraform-%3E%3D%201.0-blue?logo=terraform)](https://www.terraform.io)
-[![dbt Cloud Provider](https://img.shields.io/badge/dbt--cloud--provider-%3E%3D%201.8-blue)](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest)
+[![dbt Cloud Provider](https://img.shields.io/badge/dbt--cloud--provider-%3E%3D%201.9-blue)](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest)
 [![License](https://img.shields.io/badge/license-Apache%202.0-green)](./LICENSE)
 
 Managing dbt Cloud infrastructure shouldn't require deep Terraform expertise. Whether you've never written HCL or just don't want to untangle the provider's resource model yourself, this module gives you a single YAML file that maps to how dbt Platform actually works — projects, environments, jobs, and connections — with relationship wiring, credential handling, and production safeguards built in.
@@ -12,7 +12,7 @@ Managing dbt Cloud infrastructure shouldn't require deep Terraform expertise. Wh
 curl -fsSL https://github.com/dbt-labs/terraform-dbtcloud-as-yaml/releases/latest/download/install.sh | bash
 ```
 
-This downloads the [examples/basic/](examples/basic/) starter into `./my-dbt-cloud`. No npm, no git magic — just curl and tar. To use a different directory name: `curl -fsSL ... | bash -s -- my-project`.
+This downloads the [topologies/basic/](topologies/basic/) starter into `./my-dbt-cloud`. No npm, no git magic — just curl and tar. To use a different directory name: `curl -fsSL ... | bash -s -- my-project`.
 
 Then:
 
@@ -23,7 +23,7 @@ cp .env.example .env        # fill in your dbt Cloud credentials
 source .env && terraform init && terraform apply
 ```
 
-See [examples/basic/README.md](examples/basic/README.md) for a full walkthrough.
+See [topologies/basic/README.md](topologies/basic/README.md) for a full walkthrough.
 
 ---
 
@@ -327,7 +327,7 @@ Terraform credentials.
 ## Documentation
 
 - **Hosted docs (GitHub Pages):** [dbt-labs.github.io/terraform-dbtcloud-as-yaml](https://dbt-labs.github.io/terraform-dbtcloud-as-yaml/)
-- [examples/basic/](examples/basic/) — clone-and-go starter with step-by-step README
+- [topologies/basic/](topologies/basic/) — clone-and-go starter with step-by-step README
 - [docs/configuration/yaml-schema.md](docs/configuration/yaml-schema.md) — full YAML field reference
 - [docs/guides/cicd.md](docs/guides/cicd.md) — CI/CD setup (GitHub Actions, etc.)
 - [docs/guides/best-practices.md](docs/guides/best-practices.md) — patterns and recommendations

README.md

@@ -17,7 +17,7 @@ The simplest possible setup to get started.
 ### Directory Structure
 
 ```
-examples/basic/
+topologies/basic/
 ├── main.tf                         # Terraform module call
 ├── variables.tf                    # Input variables
 ├── dbt-config.yml                  # dbt Cloud configuration
@@ -31,7 +31,7 @@ examples/basic/
 ### Try It Out
 
 ```bash
-cd examples/basic
+cd topologies/basic
 cp .env.example .env
 # Edit .env with your credentials
 source .env
@@ -40,7 +40,7 @@ terraform plan
 terraform apply
 ```
 
-[:material-github: View Source](https://github.com/dbt-labs/terraform-dbtcloud-as-yaml/tree/main/examples/basic){ .md-button }
+[:material-github: View Source](https://github.com/dbt-labs/terraform-dbtcloud-as-yaml/tree/main/topologies/basic){ .md-button }
 
 ---
 
@@ -264,7 +264,7 @@ projects:
 
 ## CI/CD with GitHub Actions
 
-Use the two-workflow pattern from `examples/basic/.github/workflows/`:
+Use the two-workflow pattern from `topologies/basic/.github/workflows/`:
 
 - `ci.yml` — validates and plans on every PR, posts plan as a comment (updates existing comment on re-push)
 - `cd.yml` — applies on merge to main, with optional approval gate via GitHub Environments