Expand documentation (#68)

This commit significantly expands the auto-generated documentation for this provider. Go check out the `docs/` subdir to see what the Terraform documentation tool is generating.

docs/data-sources/regions.md

@@ -10,7 +10,19 @@ description: |-
 
 
 
+## Example Usage
 
+```terraform
+provider "temporalcloud" {
+
+}
+
+data "temporalcloud_regions" "regions" {}
+
+output "regions" {
+  value = data.temporalcloud_regions.regions.regions
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/index.md

@@ -3,12 +3,28 @@
 page_title: "temporalcloud Provider"
 subcategory: ""
 description: |-
-  
+  Use the Temporal Cloud provider to interact with resources supported by Temporal Cloud.
+  Use the navigation to the left to learn about the available resources supported by this provider.
+  Provider Configuration
+  Credentials for Temporal Cloud can be provided by adding an "apikey" property or by setting the environment variable "TEMPORALCLOUDAPIKEY".
+  You can generate an API key for Temporal Cloud by following the instructions here https://docs.temporal.io/cloud/api-keys.
+  !> Hard-coded credentials are not recommended in any Terraform configuration and should not be committed
+  in version control. We recommend passing credentials to this provider via environment variables.
 ---
 
 # temporalcloud Provider
 
+Use the Temporal Cloud provider to interact with resources supported by Temporal Cloud.
+
+Use the navigation to the left to learn about the available resources supported by this provider.
 
+## Provider Configuration 
+
+Credentials for Temporal Cloud can be provided by adding an "api_key" property or by setting the environment variable "TEMPORAL_CLOUD_API_KEY".
+You can generate an API key for Temporal Cloud by following the instructions [here](https://docs.temporal.io/cloud/api-keys).
+
+!> Hard-coded credentials are not recommended in any Terraform configuration and should not be committed
+in version control. We recommend passing credentials to this provider via environment variables.
 
 ## Example Usage
 
@@ -20,13 +36,24 @@ terraform {
     }
   }
 }
+
+provider "temporalcloud" {
+  # Also can be set by environment variable `TEMPORAL_CLOUD_API_KEY`
+  api_key = "my-temporalcloud-api-key"
+
+  # Also can be set by environment variable `TEMPORAL_CLOUD_ENDPOINT`
+  endpoint = "saas-api.tmprl.cloud:443"
+
+  # Also can be set by environment variable `TEMPORAL_CLOUD_ALLOW_INSECURE`
+  allow_insecure = false
+}
 ```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Optional
 
-- `allow_insecure` (Boolean)
-- `api_key` (String, Sensitive)
-- `endpoint` (String)
+- `allow_insecure` (Boolean) If set, allows for an insecure connection to the Temporal Cloud API. Defaults to `false`.
+- `api_key` (String, Sensitive) The API key for Temporal Cloud. See [this documentation](https://docs.temporal.io/cloud/api-keys) for information on how to obtain an API key.
+- `endpoint` (String) The endpoint for the Temporal Cloud API. Defaults to `saas-api.tmprl.cloud:443`.

docs/resources/namespace.md

@@ -3,57 +3,70 @@
 page_title: "temporalcloud_namespace Resource - terraform-provider-temporalcloud"
 subcategory: ""
 description: |-
-  
+  Provisions a Temporal Cloud namespace.
 ---
 
 # temporalcloud_namespace (Resource)
 
+Provisions a Temporal Cloud namespace.
 
+## Example Usage
 
+```terraform
+provider "temporalcloud" {
 
+}
+
+resource "temporalcloud_namespace" "terraform" {
+  name               = "terraform"
+  regions            = ["aws-us-east-1"]
+  accepted_client_ca = base64encode(file("${path.module}/ca.pem"))
+  retention_days     = 14
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `accepted_client_ca` (String)
-- `name` (String)
-- `regions` (List of String)
-- `retention_days` (Number)
+- `accepted_client_ca` (String) The Base64-encoded CA cert in PEM format that clients use when authenticating with Temporal Cloud.
+- `name` (String) The name of the namespace.
+- `regions` (List of String) The list of regions that this namespace is available in. If more than one region is specified, this namespace is "global" which is currently a preview feature with restricted access. Please reach out to Temporal support for more information on this feature.
+- `retention_days` (Number) The number of days to retain workflow history. Any changes to the retention period will be applied to all new running workflows.
 
 ### Optional
 
-- `certificate_filters` (Attributes List) (see [below for nested schema](#nestedatt--certificate_filters))
-- `codec_server` (Attributes) (see [below for nested schema](#nestedatt--codec_server))
+- `certificate_filters` (Attributes List) A list of filters to apply to client certificates when initiating a connection Temporal Cloud. If present, connections will only be allowed from client certificates whose distinguished name properties match at least one of the filters. (see [below for nested schema](#nestedatt--certificate_filters))
+- `codec_server` (Attributes) A codec server is used by the Temporal Cloud UI to decode payloads for all users interacting with this namespace, even if the workflow history itself is encrypted. (see [below for nested schema](#nestedatt--codec_server))
 - `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
 
 ### Read-Only
 
-- `id` (String) The ID of this resource.
+- `id` (String) The unique identifier of the namespace across all Temporal Cloud tenants.
 
 <a id="nestedatt--certificate_filters"></a>
 ### Nested Schema for `certificate_filters`
 
 Optional:
 
-- `common_name` (String)
-- `organization` (String)
-- `organizational_unit` (String)
-- `subject_alternative_name` (String)
+- `common_name` (String) The certificate's common name.
+- `organization` (String) The certificate's organization.
+- `organizational_unit` (String) The certificate's organizational unit.
+- `subject_alternative_name` (String) The certificate's subject alternative name (or SAN).
 
 
 <a id="nestedatt--codec_server"></a>
 ### Nested Schema for `codec_server`
 
 Required:
 
-- `endpoint` (String)
+- `endpoint` (String) The endpoint of the codec server. Must begin with "https".
 
 Optional:
 
-- `include_cross_origin_credentials` (Boolean)
-- `pass_access_token` (Boolean)
+- `include_cross_origin_credentials` (Boolean) If true, Temporal Cloud will include cross-origin credentials in requests to the codec server.
+- `pass_access_token` (Boolean) If true, Tempora Cloud will pass the access token to the codec server upon each request.
 
 
 <a id="nestedblock--timeouts"></a>
@@ -63,3 +76,11 @@ Optional:
 
 - `create` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours).
 - `delete` (String) A string that can be [parsed as a duration](https://pkg.go.dev/time#ParseDuration) consisting of numbers and unit suffixes, such as "30s" or "2h45m". Valid time units are "s" (seconds), "m" (minutes), "h" (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs.
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import temporalcloud_namespace.terraform terraform.badf00d
+```

docs/resources/namespace_search_attribute.md

@@ -3,24 +3,55 @@
 page_title: "temporalcloud_namespace_search_attribute Resource - terraform-provider-temporalcloud"
 subcategory: ""
 description: |-
-  
+  A search attribute for visibility of Temporal Cloud namespaces. See this documentation page https://docs.temporal.io/visibility#search-attribute for more information on search attributes.
 ---
 
 # temporalcloud_namespace_search_attribute (Resource)
 
+A search attribute for visibility of Temporal Cloud namespaces. See [this documentation page](https://docs.temporal.io/visibility#search-attribute) for more information on search attributes.
 
+## Example Usage
 
+```terraform
+provider "temporalcloud" {
 
+}
+
+resource "temporalcloud_namespace" "terraform" {
+  name               = "terraform-with-search-attributes"
+  regions            = ["aws-us-east-1"]
+  accepted_client_ca = base64encode(file("${path.module}/ca.pem"))
+  retention_days     = 14
+}
+
+resource "temporalcloud_namespace_search_attribute" "custom_search_attribute" {
+  namespace_id = temporalcloud_namespace.terraform.id
+  name         = "CustomSearchAttribute"
+  type         = "Text"
+}
+
+resource "temporalcloud_namespace_search_attribute" "custom_search_attribute2" {
+  namespace_id = temporalcloud_namespace.terraform.id
+  name         = "CustomSearchAttribute2"
+  type         = "Text"
+}
+
+resource "temporalcloud_namespace_search_attribute" "custom_search_attribute3" {
+  namespace_id = temporalcloud_namespace.terraform.id
+  name         = "CustomSearchAttribute3"
+  type         = "Text"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `name` (String) The name of the search attribute
-- `namespace_id` (String) The ID of the namespace to which this search attribute belongs
-- `type` (String) The type of the search attribute
+- `name` (String) The name of the search attribute.
+- `namespace_id` (String) The ID of the namespace to which this search attribute belongs.
+- `type` (String) The type of the search attribute. Must be one of `Bool`, `Datetime`, `Double`, `Int`, `Keyword`, or `Text`.
 
 ### Read-Only
 
-- `id` (String) The ID of this search attribute
+- `id` (String) The ID of this search attribute.

examples/provider/provider.tf

@@ -5,3 +5,14 @@ terraform {
     }
   }
 }
+
+provider "temporalcloud" {
+  # Also can be set by environment variable `TEMPORAL_CLOUD_API_KEY`
+  api_key = "my-temporalcloud-api-key"
+
+  # Also can be set by environment variable `TEMPORAL_CLOUD_ENDPOINT`
+  endpoint = "saas-api.tmprl.cloud:443"
+
+  # Also can be set by environment variable `TEMPORAL_CLOUD_ALLOW_INSECURE`
+  allow_insecure = false
+}

examples/resources/temporalcloud_namespace/import.sh

@@ -0,0 +1 @@
+terraform import temporalcloud_namespace.terraform terraform.badf00d

internal/provider/namespace_resource.go

@@ -129,65 +129,80 @@ func (r *namespaceResource) Metadata(_ context.Context, req resource.MetadataReq
 // Schema defines the schema for the resource.
 func (r *namespaceResource) Schema(ctx context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		Description: "Provisions a Temporal Cloud namespace.",
 		Attributes: map[string]schema.Attribute{
 			"name": schema.StringAttribute{
-				Required: true,
+				Description: "The name of the namespace.",
+				Required:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
 			},
 			"id": schema.StringAttribute{
-				Computed: true,
+				Description: "The unique identifier of the namespace across all Temporal Cloud tenants.",
+				Computed:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"regions": schema.ListAttribute{
+				Description: "The list of regions that this namespace is available in. If more than one region is specified, this namespace is \"global\" which is currently a preview feature with restricted access. Please reach out to Temporal support for more information on this feature.",
 				ElementType: types.StringType,
 				Required:    true,
 				PlanModifiers: []planmodifier.List{
 					listplanmodifier.RequiresReplace(),
 				},
 			},
 			"accepted_client_ca": schema.StringAttribute{
-				Required: true,
+				Description: "The Base64-encoded CA cert in PEM format that clients use when authenticating with Temporal Cloud.",
+				Required:    true,
 			},
 			"retention_days": schema.Int64Attribute{
-				Required: true,
+				Description: "The number of days to retain workflow history. Any changes to the retention period will be applied to all new running workflows.",
+				Required:    true,
 			},
 			"certificate_filters": schema.ListNestedAttribute{
-				Optional: true,
+				Description: "A list of filters to apply to client certificates when initiating a connection Temporal Cloud. If present, connections will only be allowed from client certificates whose distinguished name properties match at least one of the filters.",
+				Optional:    true,
 				NestedObject: schema.NestedAttributeObject{
 					Attributes: map[string]schema.Attribute{
 						"common_name": schema.StringAttribute{
-							Optional: true,
+							Description: "The certificate's common name.",
+							Optional:    true,
 						},
 						"organization": schema.StringAttribute{
-							Optional: true,
+							Description: "The certificate's organization.",
+							Optional:    true,
 						},
 						"organizational_unit": schema.StringAttribute{
-							Optional: true,
+							Description: "The certificate's organizational unit.",
+							Optional:    true,
 						},
 						"subject_alternative_name": schema.StringAttribute{
-							Optional: true,
+							Description: "The certificate's subject alternative name (or SAN).",
+							Optional:    true,
 						},
 					},
 				},
 			},
 			"codec_server": schema.SingleNestedAttribute{
+				Description: "A codec server is used by the Temporal Cloud UI to decode payloads for all users interacting with this namespace, even if the workflow history itself is encrypted.",
 				Attributes: map[string]schema.Attribute{
 					"endpoint": schema.StringAttribute{
-						Required: true,
+						Description: "The endpoint of the codec server. Must begin with \"https\".",
+						Required:    true,
 					},
 					"pass_access_token": schema.BoolAttribute{
-						Computed: true,
-						Default:  booldefault.StaticBool(false),
-						Optional: true,
+						Description: "If true, Tempora Cloud will pass the access token to the codec server upon each request.",
+						Computed:    true,
+						Default:     booldefault.StaticBool(false),
+						Optional:    true,
 					},
 					"include_cross_origin_credentials": schema.BoolAttribute{
-						Computed: true,
-						Default:  booldefault.StaticBool(false),
-						Optional: true,
+						Description: "If true, Temporal Cloud will include cross-origin credentials in requests to the codec server.",
+						Computed:    true,
+						Default:     booldefault.StaticBool(false),
+						Optional:    true,
 					},
 				},
 				Optional: true,

internal/provider/namespace_search_attribute_resource.go

@@ -70,27 +70,28 @@ func (r *namespaceSearchAttributeResource) Metadata(_ context.Context, req resou
 
 func (r *namespaceSearchAttributeResource) Schema(ctx context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: "A search attribute for visibility of Temporal Cloud namespaces. See [this documentation page](https://docs.temporal.io/visibility#search-attribute) for more information on search attributes.",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Description: "The ID of this search attribute",
+				Description: "The ID of this search attribute.",
 				Computed:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"namespace_id": schema.StringAttribute{
-				Description: "The ID of the namespace to which this search attribute belongs",
+				Description: "The ID of the namespace to which this search attribute belongs.",
 				Required:    true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
 			},
 			"name": schema.StringAttribute{
-				Description: "The name of the search attribute",
+				Description: "The name of the search attribute.",
 				Required:    true,
 			},
 			"type": schema.StringAttribute{
-				Description: "The type of the search attribute",
+				Description: "The type of the search attribute. Must be one of `Bool`, `Datetime`, `Double`, `Int`, `Keyword`, or `Text`.",
 				Required:    true,
 			},
 		},