Merge pull request #206 from dbt-labs/fixes-example-problems

Fixes-example-problems

docs/resources/bigquery_connection.md

@@ -13,11 +13,12 @@ Resource to create BigQuery connections in dbt Cloud. Can be set to use OAuth fo
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_bigquery_connection instead of dbtcloud_bigquery_connection for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
-resource "dbtcloud_bigquery_connection" "test_connection" {
-  project_id                  = dbtcloud_project.test_project.id
+resource "dbtcloud_bigquery_connection" "my_connection" {
+  project_id                  = dbtcloud_project.dbt_project.id
   name                        = "Project Name"
   type                        = "bigquery"
   is_active                   = true
@@ -35,8 +36,8 @@ resource "dbtcloud_bigquery_connection" "test_connection" {
 }
 
 # it is also possible to set the connection to use OAuth by filling in `application_id` and `application_secret`
-resource "dbtcloud_bigquery_connection" "test_connection_with_oauth" {
-  project_id                  = dbtcloud_project.test_project.id
+resource "dbtcloud_bigquery_connection" "my_connection_with_oauth" {
+  project_id                  = dbtcloud_project.dbt_project.id
   name                        = "Project Name"
   type                        = "bigquery"
   is_active                   = true

docs/resources/bigquery_credential.md

@@ -13,11 +13,12 @@ description: |-
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_bigquery_credential instead of dbtcloud_bigquery_credential for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
-resource "dbtcloud_bigquery_credential" "test_credential" {
-  project_id  = dbtcloud_project.my_project.id
+resource "dbtcloud_bigquery_credential" "my_credential" {
+  project_id  = dbtcloud_project.dbt_project.id
   dataset     = "my_bq_dataset"
   num_threads = 16
 }

docs/resources/connection.md

@@ -18,11 +18,12 @@ For BigQuery, due to the list of fields being very different, you can use the `d
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_connection instead of dbtcloud_connection for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
 resource "dbtcloud_connection" "databricks" {
-  project_id = dbtcloud_project.my_project_1.id
+  project_id = dbtcloud_project.dbt_project.id
   type       = "adapter"
   name       = "Databricks"
   database   = "" // currenyly need to be empty for databricks
@@ -32,7 +33,7 @@ resource "dbtcloud_connection" "databricks" {
 }
 
 resource "dbtcloud_connection" "redshift" {
-  project_id = dbtcloud_project.my_project_2.id
+  project_id = dbtcloud_project.dbt_project.id
   type       = "redshift"
   name       = "My Redshift Warehouse"
   database   = "my-database"
@@ -41,7 +42,7 @@ resource "dbtcloud_connection" "redshift" {
 }
 
 resource "dbtcloud_connection" "snowflake" {
-  project_id = dbtcloud_project.my_project_3.id
+  project_id = dbtcloud_project.dbt_project.id
   type       = "snowflake"
   name       = "My Snowflake warehouse"
   account    = "my-snowflake-account"

docs/resources/databricks_credential.md

@@ -13,12 +13,13 @@ description: |-
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_databricks_credential instead of dbtcloud_databricks_credential for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
 # when using the Databricks adapter
-resource "dbtcloud_databricks_credential" "databricks_cred" {
-  project_id   = dbtcloud_project.my_project.id
+resource "dbtcloud_databricks_credential" "my_databricks_cred" {
+  project_id   = dbtcloud_project.dbt_project.id
   adapter_id   = 123
   target_name  = "prod"
   token        = "abcdefgh"
@@ -27,8 +28,8 @@ resource "dbtcloud_databricks_credential" "databricks_cred" {
 }
 
 # when using the Spark adapter
-resource "dbtcloud_databricks_credential" "spark_cred" {
-  project_id   = dbtcloud_project.my_other_project.id
+resource "dbtcloud_databricks_credential" "my_spark_cred" {
+  project_id   = dbtcloud_project.dbt_project.id
   adapter_id   = 456
   target_name  = "prod"
   token        = "abcdefgh"
@@ -64,6 +65,6 @@ Import is supported using the following syntax:
 
 ```shell
 # Import using a project ID and credential ID found in the URL or via the API.
-terraform import dbtcloud_databricks_credential.test_databricks_credential "project_id:credential_id"
-terraform import dbtcloud_databricks_credential.test_databricks_credential 12345:6789
+terraform import dbtcloud_databricks_credential.my_databricks_credential "project_id:credential_id"
+terraform import dbtcloud_databricks_credential.my_databricks_credential 12345:6789
 ```

docs/resources/environment.md

@@ -13,27 +13,36 @@ description: |-
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_environment instead of dbtcloud_environment for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
-resource "dbtcloud_environment" "test_environment" {
+resource "dbtcloud_environment" "ci_environment" {
   // the dbt_version is always major.minor.0-latest or major.minor.0-pre
-  dbt_version   = "1.5.0-latest"
-  name          = "test"
-  project_id    = data.dbtcloud_project.test_project.id
+  dbt_version   = "1.6.0-latest"
+  name          = "CI"
+  project_id    = dbtcloud_project.dbt_project.id
   type          = "deployment"
-  credential_id = dbt_cloud_snowflake_credential.new_credential.credential_id
+  credential_id = dbtcloud_snowflake_credential.ci_credential.credential_id
 }
 
 // we can also set a deployment environment as being the production one
 resource "dbtcloud_environment" "prod_environment" {
-  dbt_version     = "1.5.0-latest"
+  dbt_version     = "1.6.0-latest"
   name            = "Prod"
-  project_id      = data.dbtcloud_project.test_project.id
+  project_id      = dbtcloud_project.dbt_project.id
   type            = "deployment"
-  credential_id   = dbt_cloud_snowflake_credential.other_credential.credential_id
+  credential_id   = dbtcloud_snowflake_credential.prod_credential.credential_id
   deployment_type = "production"
 }
+  
+// Creating a development environment
+resource "dbtcloud_environment" "dev_environment" {
+  dbt_version     = "1.6.0-latest"
+  name            = "Dev"
+  project_id      = dbtcloud_project.dbt_project.id
+  type            = "development"
+}
 ```
 
 <!-- schema generated by tfplugindocs -->
@@ -66,6 +75,6 @@ Import is supported using the following syntax:
 
 ```shell
 # Import using a project ID and environment ID found in the URL or via the API.
-terraform import dbtcloud_environment.test_environment "project_id:environment_id"
-terraform import dbtcloud_environment.test_environment 12345:6789
+terraform import dbtcloud_environment.prod_environment "project_id:environment_id"
+terraform import dbtcloud_environment.prod_environment 12345:6789
 ```

docs/resources/environment_variable.md

@@ -13,19 +13,24 @@ the same time as the environment variables, it's recommended to use the `depends
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_environment_variable instead of dbtcloud_environment_variable for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
-resource "dbtcloud_environment_variable" "my_env_var" {
+resource "dbtcloud_environment_variable" "dbt_my_env_var" {
   name       = "DBT_MY_ENV_VAR"
-  project_id = dbtcloud_project.my_project.id
+  project_id = dbtcloud_project.dbt_project.id
   environment_values = {
     "project" : "my_project_level_value",
-    "My Env" : "my_env_level_value"
+    "Dev" : "my_env_level_value",
+    "CI" : "my_ci_override_value",
+    "Prod" "my_prod_override_value"
   }
   depends_on = [
-    dbtcloud_project.my_project,
-    dbtcloud_environment.my_env
+    dbtcloud_project.dbt_project,
+    dbtcloud_environment.dev_env,
+    dbtcloud_environment.ci_env,
+    dbtcloud_environment.prod_env,
   ]
 }
 ```

docs/resources/extended_attributes.md

@@ -26,13 +26,13 @@ resource "dbtcloud_extended_attributes" "my_attributes" {
       }
     }
   )
-  project_id = var.dbt_project_id
+  project_id = var.dbt_project.id
 }
 
 resource dbtcloud_environment issue_depl {
   dbt_version            = "1.6.0-latest"
   name                   = "My environment"
-  project_id             = var.dbt_project_id
+  project_id             = var.dbt_project.id
   type                   = "deployment"
   use_custom_branch      = false
   credential_id          = var.dbt_credential_id

docs/resources/group.md

@@ -12,19 +12,20 @@ description: |-
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_group instead of dbtcloud_group for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
-resource "dbtcloud_group" "test_group" {
-  name = "Test Group"
+resource "dbtcloud_group" "tf_group_1" {
+  name = "TF Group 1"
   group_permissions {
     permission_set = "member"
     all_projects   = true
   }
   group_permissions {
     permission_set = "developer"
     all_projects   = false
-    project_id     = dbtcloud_project.test_project.id
+    project_id     = dbtcloud_project.dbt_project.id
   }
 }
 ```

docs/resources/job.md

@@ -16,21 +16,22 @@ Deferral can still be set to "self" by setting `self_deferring` to `true` but wi
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_job instead of dbtcloud_job for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
 # a job that has github_webhook and git_provider_webhook 
 # set to false will be categorized as a "Deploy Job"
-resource "dbtcloud_job" "test" {
-  environment_id = var.dbt_cloud_environment_id
+resource "dbtcloud_job" "daily_job" {
+  environment_id = dbtcloud_environment.prod_environment.environment_id
   execute_steps = [
     "dbt build"
   ]
   generate_docs        = true
   is_active            = true
   name                 = "Daily job"
   num_threads          = 64
-  project_id           = data.dbtcloud_project.test_project.id
+  project_id           = dbtcloud_project.dbt_project.id
   run_generate_sources = true
   target_name          = "default"
   triggers = {
@@ -49,15 +50,15 @@ resource "dbtcloud_job" "test" {
 # a job that has github_webhook and git_provider_webhook set 
 # to true will be categorized as a "Continuous Integration Job"
 resource "dbtcloud_job" "ci_job" {
-  environment_id = var.my_ci_environment_id
+  environment_id = dbtcloud_environment.ci_environment.environment_id
   execute_steps = [
     "dbt build -s state:modified+ --fail-fast"
   ]
   generate_docs            = false
-  deferring_environment_id = dbtcloud_environment.my_prod_env.environment_id
+  deferring_environment_id = dbtcloud_environment.prod_environment.environment_id
   name                     = "CI Job"
   num_threads              = 32
-  project_id               = data.dbtcloud_project.test_project.id
+  project_id               = dbtcloud_project.dbt_project.id
   run_generate_sources     = false
   triggers = {
     "custom_branch_only" : true,

docs/resources/license_map.md

@@ -13,9 +13,22 @@ description: |-
 ## Example Usage
 
 ```terraform
-resource "dbtcloud_license_map" "test_license_map" {
+# Developer license group mapping
+resource "dbtcloud_license_map" "dev_license_map" {
   license_type = "developer"
-  sso_license_mapping_groups = ["TEST-GROUP"]
+  sso_license_mapping_groups = ["DEV-SSO-GROUP"]
+}
+
+# Read-only license mapping
+resource "dbtcloud_license_map" "read_only_license_map" {
+  license_type = "read_only"
+  sso_license_mapping_groups = ["READ-ONLY-SSO-GROUP"]
+}
+
+# IT license mapping
+resource "dbtcloud_license_map" "it_license_map" {
+  license_type = "it"
+  sso_license_mapping_groups = ["IT-SSO-GROUP"]
 }
 ```
 

docs/resources/notification.md

@@ -16,21 +16,27 @@ description: |-
 // dbt Cloud allows us to create internal and external notifications
 
 // an internal notification will send emails to the user mentioned in `user_id`
-resource "dbtcloud_notification" "my_internal_notification" {
+//
+// NOTE: If internal notification settings already exist for a user, currently you MUST import
+// those first into the state file before you can create a new internal notification for that user.
+// Failure to do so, will result in the user losing access to existing notifications and dbt
+// support will need to be contacted to restore access.
+// cmd: terraform import dbtcloud_notification.prod_job_internal_notification <user_id>
+resource "dbtcloud_notification" "prod_job_internal_notification" {
 	// user_id is the internal ID of a given user in dbt Cloud
 	user_id           = 100
-	on_success        = [dbtcloud_job.my_job.id]
+	on_success        = [dbtcloud_job.prod_job.id]
 	on_failure        = [12345]
 	// the Type 1 is used for internal notifications
 	notification_type = 1
 }
 
 // we can also send "external" email notifications to emails to related to dbt Cloud users
-resource "dbtcloud_notification" "my_external_notification" {
+resource "dbtcloud_notification" "prod_job_external_notification" {
 	// we still need the ID of a user in dbt Cloud even though it is not used for sending notifications
 	user_id           = 100
 	on_failure        = [23456, 56788]
-	on_cancel         = [dbtcloud_job.my_other_job.id]
+	on_cancel         = [dbtcloud_job.prod_job.id]
 	// the Type 4 is used for external notifications
 	notification_type = 4
 	// the external_email is the email address that will receive the notification

docs/resources/postgres_credential.md

@@ -13,12 +13,13 @@ description: |-
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_postgres_credential instead of dbtcloud_postgres_credential for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
-resource "dbtcloud_postgres_credential" "test_credential" {
+resource "dbtcloud_postgres_credential" "postgres_prod_credential" {
   is_active      = true
-  project_id     = dbtcloud_project.test_project.id
+  project_id     = dbtcloud_project.dbt_project.id
   type           = "postgres"
   default_schema = "my_schema"
   username       = "my_username"

docs/resources/project.md

@@ -13,14 +13,15 @@ description: |-
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_project instead of dbtcloud_project for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
-resource "dbtcloud_project" "my_project" {
+resource "dbtcloud_project" "dbt_project" {
   name = "Analytics"
 }
 
-resource "dbtcloud_project" "my_project_with_subdir" {
+resource "dbtcloud_project" "dbt_project_with_subdir" {
   name                     = "Analytics in Subdir"
   dbt_project_subdirectory = "/path"
 }

docs/resources/project_artefacts.md

@@ -13,13 +13,14 @@ description: |-
 ## Example Usage
 
 ```terraform
+// NOTE for customers using the LEGACY dbt_cloud provider:
 // use dbt_cloud_project_artefacts instead of dbtcloud_project_artefacts for the legacy resource names
 // legacy names will be removed from 0.3 onwards
 
 resource "dbtcloud_project_artefacts" "my_project_artefacts" {
-  project_id       = dbtcloud_project.my_project.id
-  docs_job_id      = dbtcloud_job.my_job.id
-  freshness_job_id = dbtcloud_job.my_job.id
+  project_id       = dbtcloud_project.dbt_project.id
+  docs_job_id      = dbtcloud_job.prod_job.id
+  freshness_job_id = dbtcloud_job.prod_job.id
 }
 ```