SUP-2388 - Update docs with templates, import blocks (#588)

* Create template file for resources

* Use override template for organization_rule, regen doc

* Update imports

* Update templates

* Regen docs

docs/resources/cluster.md

@@ -60,8 +60,7 @@ emoji itself, such as 🚀.
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a cluster resource using the GraphQL ID
 #
@@ -80,3 +79,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_cluster.primary Q2x1c3Rlci0tLTI3ZmFmZjA4LTA3OWEtNDk5ZC1hMmIwLTIzNmY3NWFkMWZjYg==
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_cluster.primary
+  id = "Q2x1c3Rlci0tLTI3ZmFmZjA4LTA3OWEtNDk5ZC1hMmIwLTIzNmY3NWFkMWZjYg=="
+}
+```

docs/resources/cluster_default_queue.md

@@ -50,8 +50,7 @@ resource "buildkite_cluster_default_queue" "primary" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a clusters default queue resource using the GraphQL ID of the cluster itself
 #
@@ -70,3 +69,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_cluster_default_queue.primary Q2x1c3Rlci0tLTI3ZmFmZjA4LTA3OWEtNDk5ZC1hMmIwLTIzNmY3NWFkMWZjYg==
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_cluster_default_queue.primary
+  id = "Q2x1c3Rlci0tLTI3ZmFmZjA4LTA3OWEtNDk5ZC1hMmIwLTIzNmY3NWFkMWZjYg=="
+}
+```

docs/resources/cluster_queue.md

@@ -57,8 +57,7 @@ resource "buildkite_cluster_queue" "default" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a cluster queue resource using the GraphQL ID along with its respective cluster UUID
 #
@@ -79,3 +78,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_cluster_queue.test Q2x1c3RlclF1ZXVlLS0tYjJiOGRhNTEtOWY5My00Y2MyLTkyMjktMGRiNzg3ZDQzOTAz,35498aaf-ad05-4fa5-9a07-91bf6cacd2bd
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_cluster_queue.test
+  id = "Q2x1c3RlclF1ZXVlLS0tYjJiOGRhNTEtOWY5My00Y2MyLTkyMjktMGRiNzg3ZDQzOTAz,35498aaf-ad05-4fa5-9a07-91bf6cacd2bd"
+}
+```

docs/resources/organization.md

@@ -40,9 +40,16 @@ resource "buildkite_organization" "settings" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `organization-slug`. For example:
 ```shell
 # import the organization settings via the organization slug
-terraform import buildkite_organization.settings <organization slug>
+terraform import buildkite_organization.settings my-buildkite-organization
+```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `organization-slug`. For example:
+```terraform
+import {
+  to = buildkite_organization.settings
+  id = "my-buildkite-organization"
+}
 ```

docs/resources/organization_banner.md

@@ -35,8 +35,7 @@ resource "buildkite_organization_banner" "banner" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import an organization banner resource using the banner's GraphQL ID
 #
@@ -52,6 +51,13 @@ Import is supported using the following syntax:
 #     }
 #   }
 # }
-
 terraform import buildkite_organization_banner.banner T3JnYW5pemF0aW9uQmFubmVyLS0tNjZlMmE5YzktM2IzMy00OGE5LTk1NjItMzY2YzMwNzYzN2Uz
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_organization_banner.banner
+  id = "T3JnYW5pemF0aW9uQmFubmVyLS0tNjZlMmE5YzktM2IzMy00OGE5LTk1NjItMzY2YzMwNzYzN2Uz"
+}
+```

docs/resources/organization_rule.md

@@ -11,7 +11,7 @@ description: |-
 
 ~> Rules is a feature that is currently in development and enabled on an opt-in basis for early access. To have this enabled for your organization for utilizing this data source, please reach out to Buildkite's [Support Team](mailto:support%40buildkite.com).
 
-An Organization Rule allows specifying explicit rules between two Buildkite resources and the desired effect/action. 
+An Organization Rule allows specifying explicit rules between two Buildkite resources and the desired effect/action.
 
 More information on organization rules can be found in the [documentation](https://buildkite.com/docs/pipelines/rules).
 
@@ -20,38 +20,39 @@ More information on organization rules can be found in the [documentation](https
 ```terraform
 # Creates a TRIGGER_BUILD organization rule with required attributes
 resource "buildkite_organization_rule" "trigger_build_test_dev" {
-    type = "pipeline.trigger_build.pipeline"
-    value = jsonencode({
-        source_pipeline = buildkite_pipeline.app_dev_deploy.uuid
-        target_pipeline = buildkite_pipeline.app_test_ci.uuid
-    })
+  type = "pipeline.trigger_build.pipeline"
+  value = jsonencode({
+    source_pipeline = buildkite_pipeline.app_dev_deploy.uuid
+    target_pipeline = buildkite_pipeline.app_test_ci.uuid
+  })
 }
 
 # Creates a ARTIFACTS_READ organization rule with an optional description
 resource "buildkite_organization_rule" "artifacts_read_test_dev" {
-    type = "pipeline.artifacts_read.pipeline"
-    description = "A rule to allow artifact reads by app_test_ci to app_dev_deploy"
-    value = jsonencode({
-        source_pipeline = buildkite_pipeline.app_test_ci.uuid
-        target_pipeline = buildkite_pipeline.app_dev_deploy.uuid
-    })
+  type        = "pipeline.artifacts_read.pipeline"
+  description = "A rule to allow artifact reads by app_test_ci to app_dev_deploy"
+  value = jsonencode({
+    source_pipeline = buildkite_pipeline.app_test_ci.uuid
+    target_pipeline = buildkite_pipeline.app_dev_deploy.uuid
+  })
 }
 
 # Creates a TRIGGER_BUILD organization rule with an optional description and conditions
 resource "buildkite_organization_rule" "trigger_build_test_dev_cond" {
-    type = "pipeline.trigger_build.pipeline"
-    description = "A rule to allow app_dev_deploy to trigger app_test_ci builds with conditions"
-    value = jsonencode({
-        source_pipeline = buildkite_pipeline.app_dev_deploy.uuid
-        target_pipeline = buildkite_pipeline.app_test_ci.uuid
-        conditions = [
-            "source.build.creator.teams includes 'deploy'",
-            "source.build.branch == 'main'"
-        ]
-    })
+  type        = "pipeline.trigger_build.pipeline"
+  description = "A rule to allow app_dev_deploy to trigger app_test_ci builds with conditions"
+  value = jsonencode({
+    source_pipeline = buildkite_pipeline.app_dev_deploy.uuid
+    target_pipeline = buildkite_pipeline.app_test_ci.uuid
+    conditions = [
+      "source.build.creator.teams includes 'deploy'",
+      "source.build.branch == 'main'"
+    ]
+  })
 }
 ```
 
+<!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
@@ -76,8 +77,7 @@ resource "buildkite_organization_rule" "trigger_build_test_dev_cond" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import an organization rule resource using the rules GraphQL ID
 #
@@ -124,6 +124,13 @@ Import is supported using the following syntax:
 #     }
 #   }
 # }
-
 terraform import buildkite_organization_rule.artifact_read UnVsZS0tLTAxOTE5NmU2LWNiNjctNzZiZi1iYzAyLTVhYzFiNzhhMWMyOA==
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_organization_rule.artifact_read
+  id = "UnVsZS0tLTAxOTE5NmU2LWNiNjctNzZiZi1iYzAyLTVhYzFiNzhhMWMyOA=="
+}
+```

docs/resources/pipeline.md

@@ -132,10 +132,17 @@ Optional:
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a pipeline resource using the pipelines GraphQL ID
 # GraphQL ID for a pipeline can be found on its settings page
 terraform import buildkite_pipeline.pipeline UGlwZWxpbmUtLS00MzVjYWQ1OC1lODFkLTQ1YWYtODYzNy1iMWNmODA3MDIzOGQ=
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_pipeline.pipeline
+  id = "UGlwZWxpbmUtLS00MzVjYWQ1OC1lODFkLTQ1YWYtODYzNy1iMWNmODA3MDIzOGQ="
+}
+```

docs/resources/pipeline_schedule.md

@@ -55,8 +55,7 @@ resource "buildkite_pipeline_schedule" "nightly" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a pipeline schedule resource using the schedules GraphQL ID
 #
@@ -81,3 +80,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_pipeline_schedule.test UGlwZWxpgm5Tf2hhZHVsZ35tLWRk4DdmN7c4LTA5M2ItNDM9YS0gMWE0LTAwZDUgYTAxYvRf49==
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_pipeline_schedule.test
+  id = "UGlwZWxpgm5Tf2hhZHVsZ35tLWRk4DdmN7c4LTA5M2ItNDM9YS0gMWE0LTAwZDUgYTAxYvRf49=="
+}
+```

docs/resources/pipeline_team.md

@@ -49,8 +49,7 @@ resource "buildkite_pipeline_team" "pipeline_team" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a pipeline team resource using the GraphQL ID
 #
@@ -68,3 +67,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_pipeline_team.guests VGVhbS0tLWU1YjQyMDQyLTUzN2QtNDZjNi04MjY0LTliZjFkMzkyYjZkNQ==
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_pipeline_team.guests
+  id = "VGVhbS0tLWU1YjQyMDQyLTUzN2QtNDZjNi04MjY0LTliZjFkMzkyYjZkNQ=="
+}
+```

docs/resources/pipeline_template.md

@@ -49,8 +49,7 @@ resource "buildkite_pipeline_template" "template_full" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a pipeline template resource using the templates GraphQL ID
 #
@@ -69,3 +68,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_pipeline_template.template UGlwZWxpbmVUZW1wbGF0ZS0tLWU0YWQ3YjdjLTljZDYtNGM0MS1hYWE0LTY2ZmI3ODY0MTMwNw==
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_pipeline_template.template
+  id = "UGlwZWxpbmVUZW1wbGF0ZS0tLWU0YWQ3YjdjLTljZDYtNGM0MS1hYWE0LTY2ZmI3ODY0MTMwNw=="
+}
+```

docs/resources/team.md

@@ -44,8 +44,7 @@ resource "buildkite_team" "everyone" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a team resource using the GraphQL ID
 #
@@ -64,3 +63,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_team.everyone UGlwZWxpbmUtLS00MzVjYWQ1OC1lODFkLTQ1YWYtODYzNy1iMWNmODA3MDIzOGQ=
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_team.everyone
+  id = "UGlwZWxpbmUtLS00MzVjYWQ1OC1lODFkLTQ1YWYtODYzNy1iMWNmODA3MDIzOGQ="
+}
+```

docs/resources/team_member.md

@@ -43,8 +43,7 @@ resource "buildkite_team_member" "a_smith" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a team member resource using the GraphQL ID
 #
@@ -68,3 +67,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_team_member.a_smith VGVhbU1lbWJlci0tLTVlZDEyMmY2LTM2NjQtNDI1MS04YzMwLTc4NjRiMDdiZDQ4Zg==
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_team_member.a_smith
+  id = "VGVhbU1lbWJlci0tLTVlZDEyMmY2LTM2NjQtNDI1MS04YzMwLTc4NjRiMDdiZDQ4Zg=="
+}
+```

docs/resources/test_suite.md

@@ -36,3 +36,33 @@ resource "buildkite_test_suite" "main" {
 - `id` (String) The GraphQL ID of the test suite.
 - `slug` (String) The generated slug of the test suite.
 - `uuid` (String) The UUID of the test suite.
+
+## Import
+
+Using `terraform import`, import resources using the `id`. For example:
+```shell
+# import a test suite resource using the GraphQL ID
+#
+# you can use this query to find the ID:
+# query getSuiteIds {
+#   organization(slug: "ORGANIZATION_SLUG") {
+#     suites(first: 1, search:"SUITE_SEARCH_TERM") {
+#       edges {
+#         node {
+#           id
+#           name
+#         }
+#       }
+#     }
+#   }
+# }
+terraform import buildkite_test_suite.acceptance VGVhbvDf4eRef20tMzIxMGEfYTctNzEF5g00M8f5s6E2YjYtODNlOGNlZgD6HcBi
+```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_test_suite.acceptance
+  id = "VGVhbvDf4eRef20tMzIxMGEfYTctNzEF5g00M8f5s6E2YjYtODNlOGNlZgD6HcBi"
+}
+```

docs/resources/test_suite_team.md

@@ -44,8 +44,7 @@ resource "buildkite_test_suite_team" "main_everyone" {
 
 ## Import
 
-Import is supported using the following syntax:
-
+Using `terraform import`, import resources using the `id`. For example:
 ```shell
 # import a test suite team resource using the GraphQL ID
 #
@@ -75,3 +74,11 @@ Import is supported using the following syntax:
 # }
 terraform import buildkite_test_suite_team.main_everyone VGVhbvDf4eRef20tMzIxMGEfYTctNzEF5g00M8f5s6E2YjYtODNlOGNlZgD6HcBi
 ```
+
+In Terraform v1.5.0 and later, use an [`import` block](https://developer.hashicorp.com/terraform/language/import) to import instances using the `id`. For example:
+```terraform
+import {
+  to = buildkite_test_suite_team.main_everyone
+  id = "VGVhbvDf4eRef20tMzIxMGEfYTctNzEF5g00M8f5s6E2YjYtODNlOGNlZgD6HcBi"
+}
+```

examples/resources/buildkite_cluster/import.tf

@@ -0,0 +1,4 @@
+import {
+  to = buildkite_cluster.primary
+  id = "Q2x1c3Rlci0tLTI3ZmFmZjA4LTA3OWEtNDk5ZC1hMmIwLTIzNmY3NWFkMWZjYg=="
+}