resource/cloudflare_certificate_pack: swap to autogenerated documenta…

…tion

docs/resources/certificate_pack.md

@@ -1,15 +1,15 @@
 ---
-layout: "cloudflare"
-page_title: "Cloudflare: cloudflare_certificate_pack"
-description: Provides a Cloudflare Certificate Pack resource.
+page_title: "cloudflare_certificate_pack Resource - Cloudflare"
+subcategory: ""
+description: |-
+  Provides a Cloudflare Certificate Pack resource that is used to provision managed TLS certificates.
 ---
 
-# cloudflare_certificate_pack
+# cloudflare_certificate_pack (Resource)
 
-Provides a Cloudflare Certificate Pack resource that is used to provision
-managed TLS certificates.
+Provides a Cloudflare Certificate Pack resource that is used to provision managed TLS certificates.
 
-~> **Important:** Certificate packs are not able to be updated in place and if
+~> Certificate packs are not able to be updated in place and if
 you require a zero downtime rotation, you need to use Terraform's meta-arguments
 for [`lifecycle`](https://www.terraform.io/docs/configuration/resources.html#lifecycle-lifecycle-customizations) blocks.
 `create_before_destroy` should be suffice for most scenarios (exceptions are
@@ -20,13 +20,7 @@ you've confirmed the certificate is available.
 
 ## Example Usage
 
-```hcl
-resource "cloudflare_certificate_pack" "dedicated_custom_example" {
-  zone_id = "1d5fdc9e88c8a8c4518b068cd94331fe"
-  type    = "dedicated_custom"
-  hosts   = ["example.com", "sub.example.com"]
-}
-
+```terraform
 # Advanced certificate manager for DigiCert
 resource "cloudflare_certificate_pack" "advanced_example_for_digicert" {
   zone_id               = "1d5fdc9e88c8a8c4518b068cd94331fe"
@@ -40,47 +34,68 @@ resource "cloudflare_certificate_pack" "advanced_example_for_digicert" {
 
 # Advanced certificate manager for Let's Encrypt
 resource "cloudflare_certificate_pack" "advanced_example_for_lets_encrypt" {
-  zone_id               = "1d5fdc9e88c8a8c4518b068cd94331fe"
-  type                  = "advanced"
-  hosts                 = ["example.com", "*.example.com"]
-  validation_method     = "http"
-  validity_days         = 90
-  certificate_authority = "lets_encrypt"
-  cloudflare_branding   = false
+  zone_id                = "1d5fdc9e88c8a8c4518b068cd94331fe"
+  type                   = "advanced"
+  hosts                  = ["example.com", "*.example.com"]
+  validation_method      = "http"
+  validity_days          = 90
+  certificate_authority  = "lets_encrypt"
+  cloudflare_branding    = false
   wait_for_active_status = true
 }
 ```
 
-## Argument Reference
-
-The following arguments are supported:
-
-- `zone_id` - (Required) The DNS zone to which the certificate pack should be added.
-- `type` - (Required) Certificate pack configuration type.
-  Allowed values: `"custom"`, `"dedicated_custom"`, `"advanced"`.
-- `hosts` - (Required) List of hostnames to provision the certificate pack for.
-  The zone name must be included as a host. Note: If using Let's Encrypt, you
-  cannot use individual subdomains and only a wildcard for subdomain is available.
-- `validation_method` - (Optional based on `type`) Which validation method to
-  use in order to prove domain ownership. Allowed values: `"txt"`, `"http"`, `"email"`.
-- `validity_days` - (Optional based on `type`) How long the certificate is valid
-  for. Note: If using Let's Encrypt, this value can only be 90 days.
-  Allowed values: 14, 30, 90, 365.
-- `certificate_authority` - (Optional based on `type`) Which certificate
-  authority to issue the certificate pack. Allowed values: `"digicert"`,
-  `"lets_encrypt"`.
-- `cloudflare_branding` - (Optional based on `type`) Whether or not to include
-  Cloudflare branding. This will add `sni.cloudflaressl.com` as the Common Name
-  if set to `true`.
-- `wait_for_active_status` - (Optional) Whether or not to wait for a certificate
-  pack to reach status `active` during creation. Defaults to `false`.
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `certificate_authority` (String) Which certificate authority to issue the certificate pack. Available values: `digicert`, `lets_encrypt`, `google`.
+- `hosts` (Set of String) List of hostnames to provision the certificate pack for. The zone name must be included as a host. Note: If using Let's Encrypt, you cannot use individual subdomains and only a wildcard for subdomain is available.
+- `type` (String) Certificate pack configuration type. Available values: `advanced`.
+- `validation_method` (String) Which validation method to use in order to prove domain ownership. Available values: `txt`, `http`, `email`.
+- `validity_days` (Number) How long the certificate is valid for. Note: If using Let's Encrypt, this value can only be 90 days. Available values: `14`, `30`, `90`, `365`.
+- `zone_id` (String) The zone identifier to target for the resource.
+
+### Optional
+
+- `cloudflare_branding` (Boolean) Whether or not to include Cloudflare branding. This will add `sni.cloudflaressl.com` as the Common Name if set to `true`.
+- `validation_records` (Block List) (see [below for nested schema](#nestedblock--validation_records))
+- `wait_for_active_status` (Boolean) Whether or not to wait for a certificate pack to reach status `active` during creation. Defaults to `false`.
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `validation_errors` (Block List) (see [below for nested schema](#nestedblock--validation_errors))
+
+<a id="nestedblock--validation_records"></a>
+### Nested Schema for `validation_records`
+
+Optional:
+
+- `cname_name` (String)
+- `cname_target` (String)
+- `emails` (List of String)
+- `http_body` (String)
+- `http_url` (String)
+- `txt_name` (String)
+- `txt_value` (String)
+
+
+<a id="nestedblock--validation_errors"></a>
+### Nested Schema for `validation_errors`
+
+Read-Only:
+
+- `message` (String)
 
 ## Import
 
-Certificate packs can be imported using a composite ID of the zone ID and
-certificate pack ID. This isn't recommended and it is advised to replace the
-certificate entirely instead.
+Import is supported using the following syntax:
 
+```shell
+$ terraform import cloudflare_certificate_pack.example 1d5fdc9e88c8a8c4518b068cd94331fe/8fda82e2-6af9-4eb2-992a-5ab65b792ef1
 ```
-$ terraform import cloudflare_certificate_pack.example cb029e245cfdd66dc8d2e570d5dd3322/8fda82e2-6af9-4eb2-992a-5ab65b792ef1
-```
+
+While supported, importing isn't recommended and it is advised to replace the
+certificate entirely instead.

examples/resources/cloudflare_certificate_pack/import.sh

@@ -0,0 +1 @@
+$ terraform import cloudflare_certificate_pack.example 1d5fdc9e88c8a8c4518b068cd94331fe/8fda82e2-6af9-4eb2-992a-5ab65b792ef1

examples/resources/cloudflare_certificate_pack/resource.tf

@@ -0,0 +1,22 @@
+# Advanced certificate manager for DigiCert
+resource "cloudflare_certificate_pack" "advanced_example_for_digicert" {
+  zone_id               = "1d5fdc9e88c8a8c4518b068cd94331fe"
+  type                  = "advanced"
+  hosts                 = ["example.com", "sub.example.com"]
+  validation_method     = "txt"
+  validity_days         = 30
+  certificate_authority = "digicert"
+  cloudflare_branding   = false
+}
+
+# Advanced certificate manager for Let's Encrypt
+resource "cloudflare_certificate_pack" "advanced_example_for_lets_encrypt" {
+  zone_id                = "1d5fdc9e88c8a8c4518b068cd94331fe"
+  type                   = "advanced"
+  hosts                  = ["example.com", "*.example.com"]
+  validation_method      = "http"
+  validity_days          = 90
+  certificate_authority  = "lets_encrypt"
+  cloudflare_branding    = false
+  wait_for_active_status = true
+}

internal/provider/resource_cloudflare_certificate_pack.go

@@ -24,6 +24,7 @@ func resourceCloudflareCertificatePack() *schema.Resource {
 		Importer: &schema.ResourceImporter{
 			StateContext: resourceCloudflareCertificatePackImport,
 		},
+		Description: "Provides a Cloudflare Certificate Pack resource that is used to provision managed TLS certificates.",
 	}
 }
 

internal/provider/schema_cloudflare_certificate_pack.go

@@ -1,6 +1,8 @@
 package provider
 
 import (
+	"fmt"
+
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/validation"
 )
@@ -18,6 +20,7 @@ func resourceCloudflareCertificatePackSchema() map[string]*schema.Schema {
 			Required:     true,
 			ForceNew:     true,
 			ValidateFunc: validation.StringInSlice([]string{"advanced"}, false),
+			Description:  fmt.Sprintf("Certificate pack configuration type. %s", renderAvailableDocumentationValuesStringSlice([]string{"advanced"})),
 		},
 		"hosts": {
 			Type:     schema.TypeSet,
@@ -26,25 +29,29 @@ func resourceCloudflareCertificatePackSchema() map[string]*schema.Schema {
 			Elem: &schema.Schema{
 				Type: schema.TypeString,
 			},
+			Description: "List of hostnames to provision the certificate pack for. The zone name must be included as a host. Note: If using Let's Encrypt, you cannot use individual subdomains and only a wildcard for subdomain is available.",
 		},
 		"validation_method": {
 			Type:         schema.TypeString,
 			Required:     true,
 			ForceNew:     true,
 			ValidateFunc: validation.StringInSlice([]string{"txt", "http", "email"}, false),
+			Description:  fmt.Sprintf("Which validation method to use in order to prove domain ownership. %s", renderAvailableDocumentationValuesStringSlice([]string{"txt", "http", "email"})),
 		},
 		"validity_days": {
 			Type:         schema.TypeInt,
 			Required:     true,
 			ForceNew:     true,
 			ValidateFunc: validation.IntInSlice([]int{14, 30, 90, 365}),
+			Description:  fmt.Sprintf("How long the certificate is valid for. Note: If using Let's Encrypt, this value can only be 90 days. %s", renderAvailableDocumentationValuesIntSlice([]int{14, 30, 90, 365})),
 		},
 		"certificate_authority": {
 			Type:         schema.TypeString,
 			Required:     true,
 			ForceNew:     true,
 			ValidateFunc: validation.StringInSlice([]string{"digicert", "lets_encrypt", "google"}, false),
 			Default:      nil,
+			Description:  fmt.Sprintf("Which certificate authority to issue the certificate pack. %s", renderAvailableDocumentationValuesStringSlice([]string{"digicert", "lets_encrypt", "google"})),
 		},
 		"validation_records": {
 			Type:     schema.TypeList,
@@ -59,15 +66,17 @@ func resourceCloudflareCertificatePackSchema() map[string]*schema.Schema {
 			Elem:     sslValidationErrorsSchema(),
 		},
 		"cloudflare_branding": {
-			Type:     schema.TypeBool,
-			Optional: true,
-			ForceNew: true,
+			Type:        schema.TypeBool,
+			Optional:    true,
+			ForceNew:    true,
+			Description: "Whether or not to include Cloudflare branding. This will add `sni.cloudflaressl.com` as the Common Name if set to `true`.",
 		},
 		"wait_for_active_status": {
-			Type:     schema.TypeBool,
-			ForceNew: true,
-			Optional: true,
-			Default:  false,
+			Type:        schema.TypeBool,
+			ForceNew:    true,
+			Optional:    true,
+			Default:     false,
+			Description: "Whether or not to wait for a certificate pack to reach status `active` during creation.",
 		},
 	}
 }

templates/resources/certificate_pack.md.tmpl

@@ -0,0 +1,34 @@
+---
+page_title: "{{.Name}} {{.Type}} - {{.RenderedProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+
+# {{.Name}} ({{.Type}})
+
+{{ .Description | trimspace }}
+
+~> Certificate packs are not able to be updated in place and if
+you require a zero downtime rotation, you need to use Terraform's meta-arguments
+for [`lifecycle`](https://www.terraform.io/docs/configuration/resources.html#lifecycle-lifecycle-customizations) blocks.
+`create_before_destroy` should be suffice for most scenarios (exceptions are
+things like missing entitlements, high ranking domain). To completely
+de-risk rotations, use you can create multiple resources using a 2-phase change
+where you have both resources live at once and you remove the old one once
+you've confirmed the certificate is available.
+
+## Example Usage
+
+{{ tffile (printf "%s%s%s" "examples/resources/" .Name "/resource.tf") }}
+
+{{ .SchemaMarkdown | trimspace }}
+
+## Import
+
+Import is supported using the following syntax:
+
+{{ codefile "shell" (printf "%s%s%s" "examples/resources/" .Name "/import.sh") }}
+
+While supported, importing isn't recommended and it is advised to replace the
+certificate entirely instead.