feat: add TF docs build workflow + initial docs

.github/workflows/build-terraform-docs.yaml

@@ -0,0 +1,38 @@
+name: Build Terraform Docs
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'examples/**'
+
+permissions: {}
+
+jobs:
+  build_tf_docs:
+    name: Build Terraform Docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+      - name: Install tfplugindocs
+        run: go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
+      - name: Build Terraform Docs
+        run: make docs
+      - name: Commit changes
+        run: |
+          git add .
+          if [[ $(git diff --staged) != '' ]]; then
+            git config --local user.email "github-actions[bot]@users.noreply.github.com"
+            git config --local user.name "github-actions[bot]"
+            git commit -m "Generate Terraform Docs"
+            git push --set-upstream origin ${{ github.event.pull_request.head.ref }}
+          else
+            echo "No changes to commit"
+          fi

Makefile

@@ -43,3 +43,8 @@ test:
 testacc:
 	TF_ACC=1 make test
 .PHONY: testacc
+
+docs:
+	mkdir -p docs
+	go generate ./...
+.PHONY: docs

examples/data-sources/prefect_account/data-source.tf

@@ -0,0 +1,3 @@
+data "prefect_account" "my_organization" {
+  id = "account-UUID"
+}

examples/data-sources/prefect_account_member/data-source.tf

@@ -0,0 +1,4 @@
+# Read down an existing Account Member by email
+data "prefect_account_member" "marvin" {
+  email = "[email protected]"
+}

examples/data-sources/prefect_account_role/data-source.tf

@@ -0,0 +1,9 @@
+# Read down the default Owner Account Role
+data "prefect_account_role" "owner" {
+  name = "Admin"
+}
+
+# Read down the default Member Account Role
+data "prefect_account_role" "member" {
+  name = "Member"
+}

examples/data-sources/prefect_service_account/data-source.tf

@@ -0,0 +1,3 @@
+data "prefect_service_account" "my_existing_bot" {
+  id = "service-acount-UUID"
+}

examples/data-sources/prefect_variable/data-source.tf

@@ -0,0 +1,7 @@
+data "prefect_variable" "existing_by_id" {
+  id = "variable-UUID"
+}
+
+data "prefect_variable" "existing_by_name" {
+  name = "my-variable-name"
+}

examples/data-sources/prefect_work_pool/data-source.tf

@@ -0,0 +1,3 @@
+data "prefect_work_pool" "my_pool" {
+  name = "my-work-pool"
+}

examples/data-sources/prefect_work_pools/data-source.tf

@@ -0,0 +1,2 @@
+# Query all Work Pools in Account/Workspace
+data "prefect_work_pools" "all_pools" {}

examples/data-sources/prefect_workspace/data-source.tf

@@ -0,0 +1,3 @@
+data "prefect_workspace" "production_environment" {
+  id = "workspace-UUID"
+}

examples/data-sources/prefect_workspace_role/data-source.tf

@@ -0,0 +1,24 @@
+# Read down the default Owner Workspace Role
+data "prefect_workspace_role" "owner" {
+  name = "Owner"
+}
+
+# Read down the default Worker Workspace Role
+data "prefect_workspace_role" "worker" {
+  name = "Worker"
+}
+
+# Read down the default Developer Workspace Role
+data "prefect_workspace_role" "developer" {
+  name = "Developer"
+}
+
+# Read down the default Viewer Workspace Role
+data "prefect_workspace_role" "viewer" {
+  name = "Viewer"
+}
+
+# Read down the default Runner Workspace Role
+data "prefect_workspace_role" "runner" {
+  name = "Runner"
+}

examples/provider/provider.tf

@@ -0,0 +1,13 @@
+terraform {
+  required_providers {
+    prefect = {
+      source = "hashicorp.com/prefecthq/prefect"
+    }
+  }
+}
+
+provider "prefect" {
+  endpoint   = "https://api.prefect.cloud"
+  api_key    = var.prefect_api_key
+  account_id = var.prefect_account_id
+}

examples/resources/prefect_account/import.sh

@@ -0,0 +1,2 @@
+# Prefect Accounts can be imported using the account's UUID
+terraform import prefect_account.example account-uuid

examples/resources/prefect_account/resource.tf

@@ -0,0 +1,6 @@
+resource "prefect_account" "example" {
+  name                    = "My Imported Account"
+  description             = "A cool account"
+  billing_email           = "[email protected]"
+  allow_public_workspaces = true
+}

examples/resources/prefect_service_account/import.sh

@@ -0,0 +1,2 @@
+# Prefect Service Accounts can be imported using the service account's name
+terraform import prefect_service_account.example name-of-service-account

examples/resources/prefect_service_account/resource.tf

@@ -0,0 +1,17 @@
+# NON-EXPIRING API KEY
+resource "prefect_service_account" "example" {
+  name = "my-service-account"
+}
+
+# ROTATING API KEY
+# Use the hashicorp/time provider to generate a time_rotating resource
+provider "time" {}
+resource "time_rotating" "ninety_days" {
+  rotation_days = 90
+}
+# Pass the time_rotating resource to the `api_key_expiration` attribute
+# in order to automate the rotation of the Service Account key
+resource "prefect_service_account" "example" {
+  name               = "my-service-account"
+  api_key_expiration = time_rotating.ninety_days.rotation_rfc3339
+}

examples/resources/prefect_variable/import.sh

@@ -0,0 +1,5 @@
+# Prefect Variables can be imported via name in the form `name/name-of-variable`
+terraform import prefect_variable.example name/name-of-variable
+
+# Prefect Variables can also be imported via UUID
+terraform import prefect_variable.example variable-uuid

examples/resources/prefect_variable/resource.tf

@@ -0,0 +1,4 @@
+resource "prefect_variable" "example" {
+  name  = "My Variable"
+  value = "variable value goes here"
+}

examples/resources/prefect_work_pool/import.sh

@@ -0,0 +1,2 @@
+# Prefect Work Pools can be imported using the work pool's name
+terraform import prefect_work_pool.example name-of-work-pool

examples/resources/prefect_work_pool/resource.tf

@@ -0,0 +1,5 @@
+resource "prefect_work_pool" "example" {
+  name   = "My Work Pool"
+  type   = "Kubernetes"
+  paused = false
+}

examples/resources/prefect_workspace/import.sh

@@ -0,0 +1,5 @@
+# Prefect Workspaces can be imported via name in the form `name/name-of-workspace`
+terraform import prefect_workspace.example name/name-of-workspace
+
+# Prefect Workspaces can also be imported via UUID
+terraform import prefect_workspace.example workspace-uuid

examples/resources/prefect_workspace/resource.tf

@@ -0,0 +1,4 @@
+resource "prefect_workspace" "example" {
+  name   = "My Workspace"
+  Handle = "my-workspace"
+}

examples/resources/prefect_workspace_access/resource.tf

@@ -0,0 +1,32 @@
+# ASSIGNING WORKSPACE ACCESS TO A USER
+# Read down a default Workspace Role (or create your own)
+data "prefect_workspace_role" "developer" {
+  name = "Developer"
+}
+
+# Read down an existing Account Member by email
+data "prefect_account_member" "marvin" {
+  email = "[email protected]"
+}
+
+# Assign the Workspace Role to the Account Member
+resource "prefect_workspace_access" "marvin_developer" {
+  accessor_type     = "USER"
+  accessor_id       = prefect_account_member.marvin.user_id
+  workspace_id      = "workspace-UUID"
+  workspace_role_id = data.prefect_workspace_role.developer.id
+}
+
+# ASSIGNING WORKSPACE ACCESS TO A SERVICE ACCOUNT
+# Create a Service Account resource
+resource "prefect_service_account" "bot" {
+  name = "a-cool-bot"
+}
+
+# Assign the Workspace Role to the Service Account
+resource "prefect_workspace_access" "bot_developer" {
+  accessor_type     = "SERVICE_ACCOUNT"
+  accessor_id       = prefect_service_account.bot.id
+  workspace_id      = "workspace-UUID"
+  workspace_role_id = data.prefect_workspace_role.developer.id
+}

examples/resources/prefect_workspace_role/import.sh

@@ -0,0 +1,2 @@
+# Prefect Workspace Roles can be imported using the workspace role's UUID
+terraform import prefect_workspace_role.example workspace-role-uuid

examples/resources/prefect_workspace_role/resource.tf

@@ -0,0 +1,7 @@
+resource "prefect_workspace_role" "example" {
+  name = "Custom Workspace Role"
+  scopes = [
+    "manage_blocks",
+    "see_flows"
+  ]
+}

main.go

@@ -11,6 +11,9 @@ import (
 
 const providerAddress = "registry.terraform.io/prefecthq/prefect"
 
+// Run "go generate" to generate the docs
+//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --rendered-provider-name Prefect --provider-name prefect
+
 func main() {
 	providerServer := providerserver.NewProtocol6(&provider.PrefectProvider{})
 

tools/tools.go

@@ -0,0 +1,8 @@
+//go:build tools
+
+package tools
+
+import (
+	// Documentation generation
+	_ "github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs"
+)