diff --git a/README.md b/README.md index 1b522b4..f5524c8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Qwilt Terraform Provider -> ⚠️ **Disclaimer**: the project is still in the 0.x.x version, which means it’s still in the experimental phase. +> ⚠️ **Disclaimer**: This provider is currently in limited availability. ## Requirements @@ -9,8 +9,8 @@ ## Building The Provider -1. Clone the repository -1. Enter the repository directory +1. Clone the repository. +1. Enter the repository directory. 1. Build the provider using the Go `install` command: ```shell @@ -35,7 +35,7 @@ Then commit the changes to `go.mod` and `go.sum`. ## Developing the Provider -Configure `~/.terraformrc` with the name of your provider and go +Configure `~/.terraformrc` with the name of your provider and Go installation. For example: ``` @@ -47,7 +47,7 @@ provider_installation { # For all other providers, install them directly from their origin provider # registries as normal. If you omit this, Terraform will _only_ use - # the dev_overrides block, and so no other providers will be available. + # the dev_overrides block, so no other providers will be available. direct {} } ``` @@ -62,7 +62,7 @@ To generate or update documentation, run `go generate`. In order to run the full suite of Acceptance tests, run `make testacc`. -*Note:* Acceptance tests create real resources, and often cost money to run. Don'r run it on production environment. +*Note:* Acceptance tests create real resources, and often cost money to run. Don't run them on a production environment. ```shell make testacc diff --git a/examples/README.md b/examples/README.md index 71368d6..bb31f6b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,11 +1,14 @@ # Examples -This directory contains examples that are mostly used for documentation, but can also be run/tested manually via the Terraform CLI. +The examples in this directory are mostly used to generate documentation, with the exception of the files under Playground (see below). -The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or ar testable even if some parts are not relevant for the documentation. +The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or are testable even if some parts are not relevant for the documentation. * **provider/provider.tf** example file for the provider index page * **data-sources/`full data source name`/data-source.tf** example file for the named data source page * **resources/`full resource name`/resource.tf** example file for the named data source page -Run: go generate -v ./... to generate documentation \ No newline at end of file +Run: go generate -v ./... to generate documentation + + +The sample configuration files under Playground demonstrate how to use the Qwilt Terraform provider. They can be used as starter files for provisioning and managing resources via the Terraform CLI. They are designed for customization-- replace placeholder values with your own specific configuration details. Replace the example certificate and key values with your own. diff --git a/examples/playground/README.md b/examples/playground/README.md index 47f7264..bef33f5 100644 --- a/examples/playground/README.md +++ b/examples/playground/README.md @@ -1,10 +1,13 @@ # Qwilt Provider Usage Examples -This directory contains examples that comprehensively demonstrate how to use Qwilt's Terraform Provider. These examples demonstrate various common use cases. +This examples in this directory demonstrate how to use the Qwilt Terraform Provider. They cover various common use cases. Inside this directory, you will find the following examples: -* *provider-install-verification*: Very bare-bones example to verify that you have the Qwilt Terraform Provider installed correctly. -* *qwilt-config-basic*: A simple example with 1 site, site configuration, certificate, and activation resource. -* *qwilt-config-multi*: A more complex example involving 2 sites, site configurations, certificates, and activation resources. -* *qwilt-config-multi-workspace*: An advanced demonstration for how to use the Terraform workspaces capability to manage multiple instances of the same configuration. This manages 2 configurations, and allows you to create production and non-production instances. -* *qwilt-datasource*: A practical demonstration of how to use the sites and certificates data sources to query for various resources. +* *provider-install-verification*: Demonstrates how to confirm that the Qwilt Terraform Provider is installed correctly. +* *qwilt-config-basic*: Demonstrates how to configure a single site, site configuration, certificate, and activation resource. +* *qwilt-config-multi*: Demonstrates how to manage two sites, site configurations, certificates, and activation resources within a single Terraform configuration. +* *qwilt-config-multi-workspace*: (Advanced) Demonstrates how to use the Terraform workspaces capability to manage multiple instances of the same configuration. Specifically, this example illustrates how to manage both production and non-production instances of a configuration that defines two sites. +* *qwilt-datasource*: A practical example demonstrating how to use the *sites* and *certificates* data sources to query various resources. + + +**TIP:** The sample configuration files in this directory can also be used as starter files for provisioning and managing resources via the Terraform CLI. They are designed for customization-- replace placeholder values with your own specific configuration details. Replace the example certificate and key values with your own. \ No newline at end of file diff --git a/examples/playground/provider-install-verification/README.md b/examples/playground/provider-install-verification/README.md index d682353..8a7c25d 100644 --- a/examples/playground/provider-install-verification/README.md +++ b/examples/playground/provider-install-verification/README.md @@ -1,11 +1,15 @@ # Qwilt Provider Install Verification -This is a very trivial, bare-bones example to verify that you have the Qwilt Terraform Provider installed correctly. +This is a minimal, verification-only example intended solely to confirm that the Qwilt Terraform Provider is installed correctly. -First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication. -See other authentication alternatives in details in the provider documentation. +To use this example: -To use it, run 'apply': -``` -$ terraform apply -``` \ No newline at end of file +1. Make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.) + + For more information on authentication, see the provider documentation, which also covers alternative methods. + +2. Apply the configuration: + + ``` + $ terraform apply + ``` \ No newline at end of file diff --git a/examples/playground/qwilt-config-basic/README.md b/examples/playground/qwilt-config-basic/README.md index 4b4dce5..dfb57bb 100644 --- a/examples/playground/qwilt-config-basic/README.md +++ b/examples/playground/qwilt-config-basic/README.md @@ -1,13 +1,21 @@ # Qwilt Basic Resource Example -This is a simple example demonstrating how to configure 1 site, site configuration, certificate, and activation resource. +This is a simple example demonstrating how to configure a single site, site configuration, certificate, and activation resource. -The example by default uses the embedded host_index JSON configuration in main.tf. Optionally, this can be removed, and "examplesitejson.json" can be included instead to maintain the SVTA configuration in a separate file. +In this example, the host_index JSON configuration is embedded in main.tf. -First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication. -See other authentication alternatives in details in the provider documentation. +If you prefer to maintain the SVTA configuration in a separate file, remove the embedded host_index, and use the reference to "examplesitebasic.json" ```host_index = file("./examplesitebasic.json")``` instead. -To use it, define your API token and run 'apply': -``` -$ terraform apply -``` \ No newline at end of file +To use this example: + +1. Make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.) + + For more information on authentication, see the provider documentation, which also covers alternative methods. + +2. Replace the placeholder values with your own specific configuration details. Replace the example certificate and key values with your own. + +3. Apply the configuration: + + ``` + $ terraform apply + ``` \ No newline at end of file diff --git a/examples/playground/qwilt-config-basic/main.tf b/examples/playground/qwilt-config-basic/main.tf index 7a44372..9cfc573 100644 --- a/examples/playground/qwilt-config-basic/main.tf +++ b/examples/playground/qwilt-config-basic/main.tf @@ -43,7 +43,7 @@ resource "qwilt_cdn_site_configuration" "example" { ] } EOT - change_description = "Basic example demonstrating the Terraform plugin" + change_description = "Basic example demonstrating the Terraform plugin." } resource "qwilt_cdn_certificate" "example" { diff --git a/examples/playground/qwilt-config-multi-workspace/README.md b/examples/playground/qwilt-config-multi-workspace/README.md index a2928cc..aef9a9f 100644 --- a/examples/playground/qwilt-config-multi-workspace/README.md +++ b/examples/playground/qwilt-config-multi-workspace/README.md @@ -1,47 +1,55 @@ # Qwilt Multi-Config Resource Example Using Workspaces -This is our most complex example. If you are not comfortable with how to use the Qwilt Terraform Provider, we suggest reviewing some of the other examples first. +⚠️This is our most complex example. If you are not yet comfortable using the Qwilt Terraform Provider, we suggest reviewing the other examples first. -This is an advanced demonstration for how to use the Terraform workspaces capability to manage multiple instances of the same configuration. This example manages 2 configurations, and allows you to create production and non-production instances. This strategy may be used to manage more complex workflows, where different teams (e.g. dev, qa, etc.) may need to work on different instances of a site. +This example demonstrates how to use Terraform workspaces to manage multiple instances of the same configuration. Specifically, it illustrates how to manage both production and non-production instances of a Terraform configuration that defines two sites. -This example may be more complex than your individual needs. Qwilt's system provides a method for simple staging of sites for verification prior to production that does not require workspaces. If your needs are more modest, we encourage you to try this staging capability instead. +This approach is ideal for managing advanced use cases where different teams (e.g. dev, qa, etc.) need to work on different instances of a site. -In this example, configurations are managed through separate Terraform configuration files (e.g. examplesite.tf and examplesite2.tf), and SVTA configurations are managed through corresponding JSON files that are included in the configuration. Both the configuration and JSON configuration are templated to allow variable substitution based on what type of site is being managed. Each site and instance has its own associated certificate and private key. +If this level of complexity is not needed for your use case, Qwilt provides a simpler method for staging sites for verification before production that does not require workspaces. For more straightforward requirements, we recommend using the staging capability. -First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication. -See other authentication alternatives in details in the provider documentation. +Configurations are managed through separate Terraform configuration files (e.g. examplesite.tf and examplesite2.tf), and the SVTA configurations are managed through the corresponding JSON files (e.g. examplesite.json, examplesite2.json). Both the Terraform and JSON configuration are templated to allow variable substitution based on the type of site being managed. Each site and instance has its own associated certificate and private key. -To get started, you must create your workspaces. For example: -``` -$ terraform workspace new prod -Created and switched to workspace "prod"! +To use this example: -You're now on a new, empty workspace. Workspaces isolate their state, -so if you run "terraform plan" Terraform will not see any existing state -for this configuration. +1. Make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.) -$ terraform workspace new dev -Created and switched to workspace "dev"! + For more information on authentication, see the provider documentation, which also covers alternative methods. -You're now on a new, empty workspace. Workspaces isolate their state, -so if you run "terraform plan" Terraform will not see any existing state -for this configuration. +2. Create your workspaces. -$ terraform workspace list - default -* dev - prod -``` + For example, to create workspaces for production and development, run the following commands: -Terraform will now track separate states for each of these environments. You may now switch to an environment to operate within it. This will switch to the production workspace so that you can apply the production configuration: -``` -$ terraform workspace select prod -Switched to workspace "prod". -``` + ``` + $ terraform workspace new prod + Created and switched to workspace "prod"! -Now, you may apply the configuration as follows: -``` -$ terraform apply -``` + You're now in a new, empty workspace. Workspaces isolate their state, so when you run Terraform plan, Terraform will not detect any existing state for this configuration. -The same may be done within the "dev" workspace. Managing more than 2 workspaces (prod and non-prod) will require further changes to the configuration. \ No newline at end of file + $ terraform workspace new dev + Created and switched to workspace "dev"! + + You're now in a new, empty workspace. Workspaces isolate their state, so when you run terraform plan, Terraform will not detect any existing state for this configuration. + + $ terraform workspace list + default + * dev + prod + ``` + + Terraform will now track separate states for each environment. You must switch to an environment to operate within it. For example, to apply the production configuration, switch to the production workspace: + + ``` + $ terraform workspace select prod + Switched to workspace "prod". + ``` + +3. Switch to the desired workspace and apply the configuration: + + ``` + $ terraform apply + ``` + + Repeat for the "dev" workspace if needed. + + Managing more than two workspaces (e.g. additional non-production environments) requires further changes to the configuration. \ No newline at end of file diff --git a/examples/playground/qwilt-config-multi/README.md b/examples/playground/qwilt-config-multi/README.md index d65e5c5..93f00a6 100644 --- a/examples/playground/qwilt-config-multi/README.md +++ b/examples/playground/qwilt-config-multi/README.md @@ -1,13 +1,19 @@ # Qwilt Multi-Config Resource Example -This is a more complex example demonstrating how to manage 2 sites, site configurations, certificates, and activation resources in a single configuration. +This is a more complex example demonstrating how to manage two sites, site configurations, certificates, and activation resources in a single configuration. -Configurations are managed through separate Terraform configuration files (e.g. examplesite.tf and examplesite2.tf), and SVTA configurations are managed through corresponding JSON files that are included in the configuration. Each site has its own associated certificate and private key. +Configurations are managed through separate Terraform configuration files (e.g. examplesite.tf and examplesite2.tf), and the SVTA configurations are managed through the corresponding JSON files (e.g. examplesite.json, examplesite2.json) that are included in the configuration. Each site has its own associated certificate and private key. -First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication. -See other authentication alternatives in details in the provider documentation. +To use this example: -To use it, run 'apply': -``` -$ terraform apply -``` \ No newline at end of file +1. Make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.) + + For more information on authentication, see the provider documentation, which also covers alternative methods. + +2. Replace the placeholder values with your own specific configuration details. Replace the example certificate and key values with your own. + +3. Apply the configuration: + + ``` + $ terraform apply + ``` \ No newline at end of file diff --git a/examples/playground/qwilt-datasource/README.md b/examples/playground/qwilt-datasource/README.md index 3056993..936df7b 100644 --- a/examples/playground/qwilt-datasource/README.md +++ b/examples/playground/qwilt-datasource/README.md @@ -1,9 +1,9 @@ # Qwilt Data Source Example -This is a practical demonstration of how to use the sites and certificates data sources to query for various resources within your configuration. +This is a practical example demonstrating how to use the *sites* and *certificates* data sources to query various resources within your configuration. -First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication. -See other authentication alternatives in details in the provider documentation. +First, make sure the QCDN_API_KEY env variable is set. (This is the recommended authentication method.) +For more information on authentication, see the provider documentation, which also covers alternative methods. By default, checking the plan will return an empty result: ``` @@ -12,22 +12,28 @@ $ terraform plan ## Site Lookup -A common use case for using the data source is to find your site information so that you can import it into a Terraform configuration. To search sites by name, you may do this: -``` -$ terraform plan -var="site_name=example.com" -``` -The command above will perform a substring match of the site_name attribute of each defined site and output matching site_id's. +A common use case for using the data source is to find your site information so that you can import it into a Terraform configuration. + +To search for a site by name, do this: + ``` + $ terraform plan -var="site_name=example.com" + ``` + The above command launches a substring match of the site_name attribute of each defined site and outputs the matching site_ids. -If you prefer searching through a giant list of all sites, you may output all sites as follows: -``` -$ terraform plan -var="site_id=all" -``` + +To retrieve a list of all sites, do this: + + ``` + $ terraform plan -var="site_id=all" + ``` Once you have identified the site_id that you are targeting, you may search for it directly: -``` -$ terraform plan -var="site_id=" -``` -This will provide details about a specific site_id, and a list of associated site configurations (i.e. revisions) and publishing operations (i.e. site activations). + + ``` + $ terraform plan -var="site_id=" + ``` + + The output includes details about the specified site_id, and a list of associated site configurations (i.e. revisions) and publishing operations (i.e. site activations). ## Site Configuration and Activation Lookup @@ -35,28 +41,32 @@ To get details about a specific site configuration and/or publishing operation, ``` $ terraform plan -var="site_id=" -var="revision_id=" -var="publish_id=" ``` -You may specific either revision_id, publish_id, or both. +You may specify revision_id, publish_id, or both. ## Certificate Lookup The same logic can be applied to certificates. Certificates can be queried by domain name and certificate ID. -To search for certificates by domain name, you may do this: -``` -$ terraform plan -var="cert_domain=example.com" -``` -This command will perform a substring match of the cert_domain attribute for each defined certificate and output the matching cert_id's. +To search for certificates by domain name: + + ``` + $ terraform plan -var="cert_domain=example.com" + ``` + The above command launches a substring match of the cert_domain attribute for each defined certificate and outputs the matching cert_ids. -If you prefer searching through a giant list of all certificates, you may output all certificates as follows: -``` -$ terraform plan -var="cert_id=all" -``` + +To retrieve a list of all certificates, do this: + + ``` + $ terraform plan -var="cert_id=all" + ``` Once you have identified the cert_id that you are targeting, you may search for it directly: -``` -$ terraform plan -var="cert_id=" -``` -This will provide details about a specific cert_id. + + ``` + $ terraform plan -var="cert_id=" + ``` + The output provides details about the specified cert_id. ## About This Example diff --git a/examples/playground/qwilt-datasource/outputs-certificates.tf b/examples/playground/qwilt-datasource/outputs-certificates.tf index ea76617..8a2891d 100644 --- a/examples/playground/qwilt-datasource/outputs-certificates.tf +++ b/examples/playground/qwilt-datasource/outputs-certificates.tf @@ -8,12 +8,12 @@ output "cert_list_by_cert_domain" { value = var.cert_domain != null ? [for cert in data.qwilt_cdn_certificates.detail.certificate : { cert_domain = cert.domain, cert_id = cert.cert_id } if strcontains(cert.domain, var.cert_domain)] : null } -# Output the detail of a matching cert if cert_id is set to an explicit value +# Output the details of a matching cert if cert_id is set to an explicit value output "cert_detail" { value = var.cert_id == "all" || var.cert_id == null || data.qwilt_cdn_certificates.detail.certificate == null ? null : data.qwilt_cdn_certificates.detail.certificate[0] } -# Output to dump every attribute of every cert in the account (probably not what you want) +# Output to dump every attribute of every certificate available to users in your org (probably not what you want) #output "all_certs" { # value = data.qwilt_cdn_certificates.detail #} diff --git a/examples/playground/qwilt-datasource/outputs-publishops.tf b/examples/playground/qwilt-datasource/outputs-publishops.tf index b8f8b07..8bf2f29 100644 --- a/examples/playground/qwilt-datasource/outputs-publishops.tf +++ b/examples/playground/qwilt-datasource/outputs-publishops.tf @@ -3,7 +3,7 @@ output "publish_ops_list" { value = var.site_id != "all" && data.qwilt_cdn_sites.detail.publish_op != null && var.publish_id == "all" && var.revision_id == "all" ? [for publish_op in data.qwilt_cdn_sites.detail.publish_op : publish_op] : null } -# Output the publish_ops belonging to revision_id if list of a site if site_id and revision_id are defined, and publish_id is not defined +# Output the publish_ops belonging to revision_id of a site if site_id and revision_id are defined, and publish_id is not defined output "publish_ops_list_by_revision_id" { value = data.qwilt_cdn_sites.detail.publish_op != null && var.site_id != "all" && var.revision_id != "all" && var.publish_id == "all" ? [for publish_op in data.qwilt_cdn_sites.detail.publish_op : publish_op if publish_op.revision_id == var.revision_id] : null } @@ -13,7 +13,7 @@ output "publish_ops_list_by_revision_id_active" { value = data.qwilt_cdn_sites.detail.publish_op != null && var.site_id != "all" && var.revision_id != "all" && var.publish_id == "all" ? [for publish_op in data.qwilt_cdn_sites.detail.publish_op : publish_op if publish_op.revision_id == var.revision_id && publish_op.is_active == true] : null } -# Output the publish_ops detail of a matching operation if site_id and publish_id are set to an explicit value +# Output the publish_ops detail of a matching operation if site_id and publish_id are set to explicit values output "publish_op_detail" { value = var.site_id == "all" || var.publish_id == "all" || data.qwilt_cdn_sites.detail.publish_op == null ? null : data.qwilt_cdn_sites.detail.publish_op[0] } diff --git a/examples/playground/qwilt-datasource/outputs-revisions.tf b/examples/playground/qwilt-datasource/outputs-revisions.tf index fcd94cf..beb90f6 100644 --- a/examples/playground/qwilt-datasource/outputs-revisions.tf +++ b/examples/playground/qwilt-datasource/outputs-revisions.tf @@ -3,7 +3,7 @@ output "revisions_list" { value = var.site_id != "all" && data.qwilt_cdn_sites.detail.revision != null && var.revision_id == "all" ? [for revision in data.qwilt_cdn_sites.detail.revision : { revision_id = revision.revision_id, revision_num = revision.revision_num, change_description = revision.change_description }] : null } -# Output the revision detail of a matching revision if site_id and revision_id are set to an explicit value +# Output the revision detail of a matching revision if site_id and revision_id are set to explicit values output "revision_detail" { value = var.site_id == "all" || var.revision_id == "all" || data.qwilt_cdn_sites.detail.revision == null ? null : data.qwilt_cdn_sites.detail.revision[0] } diff --git a/examples/playground/qwilt-datasource/outputs-sites.tf b/examples/playground/qwilt-datasource/outputs-sites.tf index 1be4b58..7f1610f 100644 --- a/examples/playground/qwilt-datasource/outputs-sites.tf +++ b/examples/playground/qwilt-datasource/outputs-sites.tf @@ -13,7 +13,7 @@ output "site_detail" { value = var.site_id == "all" || var.site_id == null || data.qwilt_cdn_sites.detail.site == null ? null : data.qwilt_cdn_sites.detail.site[0] } -# Output to dump every attribute of every site in the account (probably not what you want) +# Output to dump every attribute of every site available to your user (probably not what you want) #output "all_sites" { # value = data.qwilt_cdn_sites.detail #} diff --git a/examples/playground/qwilt-import/README.md b/examples/playground/qwilt-import/README.md index e33b5bd..17794a2 100644 --- a/examples/playground/qwilt-import/README.md +++ b/examples/playground/qwilt-import/README.md @@ -1,28 +1,31 @@ # Qwilt Import Resource Example -This is a simple example demonstrating how to import 1 site, site configuration, certificate, and activation resource. +This is a simple example demonstrating how to import a single site, site configuration, certificate, and activation resource. -First, make sure your QCDN_API_KEY env variable is set (this is the recommended method for authentication. -See other authentication alternatives in details in the provider documentation. +First, make sure your QCDN_API_KEY env variable is set. (This is the recommended authentication method.) +For more information on authentication, see the provider documentation, which also covers alternative methods. ## Basic Import -Basic import uses site_id to detect revison_id and publish_id automatically and spare the user the hussle of more complex commands. -The logic for qwilt_cdn_site_configuration is: -1. use published active revision_id (if available) -2. use published last revision_id (if available) -3. use latest revision_id (max revision_number) - -The import is a rather manual operation. To complete the import process the following steps should be done for each resource: -1. perform terraform import -2. verify import completed successfully -3. use attributes from terraform state to generate the configurable attributes in the .tf file for this resource -4. change the id's to reference to allow implicit dependencies: - 1. site_id in site_configuration - 2. site_id, revision_id and cert_id in site_activation -5. run terraform plan - expect no changes - -To use it for step (1), define your API token and run: +Basic import uses the site_id to automatically detect the revison_id and publish_id. + +The logic for determining which qwilt_cdn_site_configuration to import is: +1. If there is an active published version, it is imported. +2. If there is no active published version, the most recently published version is imported. +3. If the site has never been published, the most recently saved configuration version is imported. (The version with the highest revision_Id value - max revision_number.) + +To complete the import process, implement the following steps for each resource: +1. Make sure your QCDN_API_KEY env variable is set. +2. Perform terraform import. (See below.) +2. Verify the import was completed successfully. +3. Use the attribute values from the terraform state to generate the configurable attributes in the .tf file for the particular resource. +4. Change the following id's to references to allow for implicit dependencies: + - *site_id* in the *site_configuration* resource. + - *site_id*, *revision_id*, and *certificate_id* in the *site_activation* resource. +5. Run ```terraform plan``` - expect no changes. + + +The Terraform import command for each of the resources: ``` $ terraform import qwilt_cdn_certificate.example -var="token=" $ terraform import qwilt_cdn_site.example -var="token=" @@ -32,18 +35,21 @@ $ terraform import qwilt_cdn_site_activation.example -var="token= -var="token=" $ terraform import qwilt_cdn_site.example -var="token=" diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf index a1227e1..427b0eb 100644 --- a/examples/provider/provider.tf +++ b/examples/provider/provider.tf @@ -1,18 +1,33 @@ -# authentication is supported by methods: login and xapi token +# Both API key-based and token-based authentication is supported. # 1. api_key is always the preferred method -# 2. user/password are supported but not recommended and might be deprecated in the near future. +# 2. user/password (token-based) are supported but not recommended and might be deprecated in the near future. # 3. each of these variables can be replaced with a corresponding env variable: # - username --> QCDN_USERNAME # - password --> QCDN_PASSWORD # - api_key --> QCDN_API_KEY provider "qwilt" { - # Specify username, or set env variable QCDN_USERNAME - username = "me@mycompany.com" - # Specify password or set env variable QCDN_PASSWORD - password = "me123456" - # Specify token or set env variable QCDN_API_KEY + # Specify username and password, or set env variables QCDN_USERNAME and QCDN_PASSWORD. + # username = "me@mycompany.com" + # password = "me123456" + # Or, specify key or set env variable QCDN_API_KEY. api_key = "eyJhbGciOiJSUzI1NiIsIn..." } +#Provider configuration: If you set the authentication parameters in the Terraform provider configuration, +#you can define either the username and password *or* the api_key. + +# Environment variables: If the QCDN_API_KEY env variable is defined, then the QCDN_USERNAME and QCDN_PASSWORD env variables are ignored. + +# When the username and password parameters are set, any Terraform command (apply, refresh, plan, etc.) triggers the Qwilt Login API to +# generate the required cqloud access token. A token is valid for one hour. + +# When the api_key parameter is set, the key is passed in the header of each API call to authenticate the request. A key is valid for one year. +# To obtain an API key, please contact [support@qwilt.com](mailto:support@qwilt.com). + +# When the authentication parameters are set by the shell environment variables, the provider config looks like this: +# ``` +# provider "qwilt" {} +# ``` + diff --git a/examples/resources/qwilt_cdn_certificate/import.sh b/examples/resources/qwilt_cdn_certificate/import.sh index 17360a2..425f731 100644 --- a/examples/resources/qwilt_cdn_certificate/import.sh +++ b/examples/resources/qwilt_cdn_certificate/import.sh @@ -1,15 +1,18 @@ -#keep an empty resource to import into -#after import is completed the user should manually set the required attributes in the resource from the imported state file +#Create an empty resource to import into. +#After the import is complete, manually set the required attributes in the resource based on the imported state. + resource "qwilt_cdn_certificate" "example" { - #after import, the private_key will remain empty in the state. - #to avoid plan keep detecting this as a change, add this lifecycle section to the imported resource + #After import, the private_key remains empty in the state. + #To prevent this from being detected as a change every time you run ```terraform plan```, add this lifecycle section to the imported resource: + lifecycle { - ignore_changes = [ - private_key - ] - } + ignore_changes = [ + private_key + ] + } + } terraform import qwilt_cdn_certificate.example \ No newline at end of file diff --git a/examples/resources/qwilt_cdn_site/import.sh b/examples/resources/qwilt_cdn_site/import.sh index ca8b439..d0b08f6 100644 --- a/examples/resources/qwilt_cdn_site/import.sh +++ b/examples/resources/qwilt_cdn_site/import.sh @@ -1,5 +1,6 @@ -#keep an empty resource to import into -#after import is completed the user should manually set the required attributes in the resource from the imported state file +#Create an empty resource to import into. +#After the import is complete, manually set the required attributes in the resource based on the imported state. + resource "qwilt_cdn_site" "example" { } diff --git a/examples/resources/qwilt_cdn_site_activation/import.sh b/examples/resources/qwilt_cdn_site_activation/import.sh index 1efaf74..3fa5144 100644 --- a/examples/resources/qwilt_cdn_site_activation/import.sh +++ b/examples/resources/qwilt_cdn_site_activation/import.sh @@ -1,14 +1,18 @@ -#keep an empty resource to import into -#after import is completed the user manually sets the required attributes in the resource from the imported state file -#it is advised to change site_id and site_id and revision_id attributes with references to qwilt_cdn_site_configuration resource to achieve implicit dependency +#Create an empty resource to import into. +#After the import is complete, manually set the required attributes in the resource based on the imported state. +#We recommend changing the site_id and revision_id attributes to references to the qwilt_cdn_site_configuration resource to achieve implicit dependency. resource "qwilt_cdn_site_activation" "example" { } -# qwilt_cdn_site_activation can be imported using their site ID, e.g. -terraform import qwilt_cdn_site_activation.example + # You can import the qwilt_cdn_site_activation resource by specifying the site_id. + # For example: terraform import qwilt_cdn_site_activation.example + + # The process determines which configuration to import based on the following conditions: + # - If there is an active published site configuration, it is imported. + # - If there is not, the most recently saved configuration version is imported. + + # Alternatively, you can specify a particular publish_id by appending to the site_id : followed by the publish_id. + # For example: */terraform import qwilt_cdn_site_activation.example xxxxxxxxxxxxxxxxxxxx:yyyyyyyyyyyyyyyyyyy + +terraform import qwilt_cdn_site_activation.example : -# By default, either: -# 1. the active publish operation will be imported -# 2. the latest published operation if no publish is active -# Alternatively, a specific publish_id of the site configuration can be selected by appending an : followed by the publish_id to the site ID, e.g. */terraform import qwilt_cdn_site_activation.example xxxxxxxxxxxxxxxxxxxx:yyyyyyyyyyyyyyyyyyy -terraform import qwilt_cdn_site_activation.example : \ No newline at end of file diff --git a/examples/resources/qwilt_cdn_site_activation/resource.tf b/examples/resources/qwilt_cdn_site_activation/resource.tf index f25ce0a..f69b994 100644 --- a/examples/resources/qwilt_cdn_site_activation/resource.tf +++ b/examples/resources/qwilt_cdn_site_activation/resource.tf @@ -1,8 +1,8 @@ # -#Notes -#this resource take a long time to fully apply. -#any attempt to apply site_activation with the same site_id might encounter a failure due to another publish operation in-progress -#the user can run terraform refresh to sync the state of this resource explicitly +#Notes: +#- This resource takes a long time to fully apply. +#- Any attempt to apply site_activation with the same site_id might encounter a failure due to another publish operation in-progress. +#- Run terraform refresh to sync the state of this resource explicitly. resource "qwilt_cdn_site_activation" "example" { diff --git a/examples/resources/qwilt_cdn_site_activation_staging/import.sh b/examples/resources/qwilt_cdn_site_activation_staging/import.sh index a7c04da..64d10eb 100644 --- a/examples/resources/qwilt_cdn_site_activation_staging/import.sh +++ b/examples/resources/qwilt_cdn_site_activation_staging/import.sh @@ -1,16 +1,20 @@ -> ⚠️ **Disclaimer**: this resource is experimental and should not be used! +> ⚠️ **Disclaimer**: This is a limited availability feature. -#keep an empty resource to import into -#after import is completed the user should manually set the required attributes in the resource from the imported state file -#it is advised to change site_id and site_id and revision_id attributes with references to qwilt_cdn_site_configuration resource to achieve implicit dependency + +#Create an empty resource to import into. +#After the import is complete, manually set the required attributes in the resource based on the imported state. +#We recommend changing the site_id and revision_id attributes with references to the qwilt_cdn_site_configuration resource to achieve implicit dependency. resource "qwilt_cdn_site_activation" "example" { } -# site_activation_staging can be imported using their site ID, e.g. -terraform import qwilt_cdn_site_activation_staging.example +# You can import the qwilt_cdn_site_activation_staging resource by specifying the site ID. +# For example: terraform import qwilt_cdn_site_activation_staging.example + + # The process determines which configuration to import based on the following conditions: + # - If there is an active published site configuration, it is imported. + # - If there is not, the most recently saved configuration version is imported. + +# Alternatively, you can specify a particular publish_id by appending to the site_id : followed by the publish_id. +# For example: */terraform import qwilt_cdn_site_activation_staging.example xxxxxxxxxxxxxxxxxxxx:yyyyyyyyyyyyyyyyyyy -# By default, either: -# 1. the active publish operation will be imported -# 2. the latest published operation if no publish is active -# Alternatively, a specific publish_id of the site configuration can be selected by appending an : followed by the publish_id to the site ID, e.g. */ terraform import qwilt_cdn_site_activation_staging.example : \ No newline at end of file diff --git a/examples/resources/qwilt_cdn_site_activation_staging/resource.tf b/examples/resources/qwilt_cdn_site_activation_staging/resource.tf index 3566bff..8f2b28c 100644 --- a/examples/resources/qwilt_cdn_site_activation_staging/resource.tf +++ b/examples/resources/qwilt_cdn_site_activation_staging/resource.tf @@ -1,12 +1,15 @@ -#> ⚠️ **Disclaimer**: this resource is experimental and should not be used! +#> ⚠️ **Disclaimer**: This is a limited availability feature. -#Notes -#this resource is similar to site_activation resource but activates the selected configuration to staging segment only. -#Note that activation cannot be performed if a previous activation is still in-progress +#Notes: +#- This resource is similar to the qwilt_cdn_site_activation resource but activates the selected configuration to the staging environment only. +#- Activation cannot be initiated while a previous activation is still in-progress. resource "qwilt_cdn_site_activation_staging" "example" { site_id = qwilt_cdn_site_configuration.example.site_id revision_id = qwilt_cdn_site_configuration.example.revision_id #certificate_id = qwilt_cdn_certificate.example.cert_id -} \ No newline at end of file +} + + + diff --git a/examples/resources/qwilt_cdn_site_configuration/import.sh b/examples/resources/qwilt_cdn_site_configuration/import.sh index c15b2c2..84b4d62 100755 --- a/examples/resources/qwilt_cdn_site_configuration/import.sh +++ b/examples/resources/qwilt_cdn_site_configuration/import.sh @@ -1,17 +1,19 @@ -#keep an empty resource to import into -#after import is completed the user should manually set the required attributes in the resource from the imported state file -#it is advised to change site_id attribute with references to qwilt_cdn_site resource to achieve implicit dependency +#Create an empty resource to import into. +#After the import is complete, manually set the required attributes in the resource based on the imported state. +#We recommend changing the site_id attribute to a reference to the qwilt_cdn_site resource to achieve implicit dependency/ resource "qwilt_cdn_site_configuration" "example" { } -# site_configurations can be imported using their site ID, e.g. -terraform import qwilt_cdn_site_configuration.example +# You can import the qwilt_cdn_site_configuration resource by specifying just the site_id. -# By default, either: -# 1. the active revision will be imported -# 2. the latest published revision if no version is active -# 3. the latest configured revision, if no published revision -# Alternatively, a specific revision_id of the site configuration can be selected by appending an : followed by the revision_id to the site ID, e.g. */ + #For example: terraform import qwilt_cdn_site_configuration.example + + # The process determines which saved site version (represented by the revisionId) to import based on the following conditions: + # - If there is an active published version, it is imported. + # - If there is no active published version, the most recently published version is imported. + # - If the site has never been published, the most recently saved configuration version is imported. -terraform import qwilt_cdn_site_configuration.example : \ No newline at end of file +# Alternatively, you can specify a particular revision_id of the site configuration by appending an : followed by the revision_id to the site ID. + +terraform import qwilt_cdn_site_configuration.example : diff --git a/goreleaser.yml b/goreleaser.yml index 4b6b3aa..857871e 100644 --- a/goreleaser.yml +++ b/goreleaser.yml @@ -35,7 +35,7 @@ checksum: signs: - artifacts: checksum args: - # We must pass the --batch flag to indicate to GitHub Actions that its + # We must pass the --batch flag to indicate to GitHub Actions that it's # not interactive. - "--batch" - "--local-user" diff --git a/qwilt/cdn/cdn_certificate_resource.go b/qwilt/cdn/cdn_certificate_resource.go index 29a07be..523d018 100644 --- a/qwilt/cdn/cdn_certificate_resource.go +++ b/qwilt/cdn/cdn_certificate_resource.go @@ -47,7 +47,7 @@ func (r *certificateResource) Schema(_ context.Context, _ resource.SchemaRequest Description: "Manages a Qwilt CDN Certificate.", Attributes: map[string]schema.Attribute{ "id": schema.Int64Attribute{ - Description: "The unique identifier of the site. Equals cert_id. Required for testing infra", + Description: "For internal use only, for testing. Equals cert_id.", Computed: true, }, "cert_id": schema.Int64Attribute{ @@ -208,7 +208,7 @@ func (r *certificateResource) Read(ctx context.Context, req resource.ReadRequest } } -// Update updates the resource and sets the updated Terraform state on success. +// Update the resource and sets the updated Terraform state on success. func (r *certificateResource) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) { // Retrieve values from plan var plan cdnmodel.Certificate @@ -267,7 +267,7 @@ func (r *certificateResource) Update(ctx context.Context, req resource.UpdateReq } } -// Delete deletes the resource and removes the Terraform state on success. +// Deletes the resource and removes the Terraform state on success. func (r *certificateResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) { // Retrieve values from state var state cdnmodel.Certificate diff --git a/qwilt/cdn/cdn_certificates_data_source.go b/qwilt/cdn/cdn_certificates_data_source.go index 0c7e5fc..23ac396 100644 --- a/qwilt/cdn/cdn_certificates_data_source.go +++ b/qwilt/cdn/cdn_certificates_data_source.go @@ -54,7 +54,7 @@ func (d *qwiltCertificatesDataSource) Metadata(_ context.Context, req datasource // Schema defines the schema for the data source. func (d *qwiltCertificatesDataSource) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) { resp.Schema = schema.Schema{ - Description: "Fetches Qwilt Certificates configuration.", + Description: "Retrieve the certificates uploaded by your organization to Qwilt CDN, and associated metadata.", Attributes: map[string]schema.Attribute{ "certificate": schema.ListNestedAttribute{ Description: "List of certificates.", @@ -76,7 +76,7 @@ func (d *qwiltCertificatesDataSource) Schema(_ context.Context, _ datasource.Sch Required: true, }, "description": schema.StringAttribute{ - Description: "The certificate's description.", + Description: "The certificate description.", Computed: false, Optional: true, }, @@ -108,7 +108,7 @@ func (d *qwiltCertificatesDataSource) Schema(_ context.Context, _ datasource.Sch Optional: true, Attributes: map[string]schema.Attribute{ "cert_id": schema.Int64Attribute{ - Description: "Filter certificates based on a specific certificate ID.", + Description: "The ID of the specific certificate you want to retrieve.", Optional: true, }, }, diff --git a/qwilt/cdn/cdn_site_resource.go b/qwilt/cdn/cdn_site_resource.go index b04d3d7..d2f0016 100644 --- a/qwilt/cdn/cdn_site_resource.go +++ b/qwilt/cdn/cdn_site_resource.go @@ -49,7 +49,7 @@ func (r *siteResource) Schema(_ context.Context, _ resource.SchemaRequest, resp Description: "Manages a Qwilt CDN site.", Attributes: map[string]schema.Attribute{ "id": schema.StringAttribute{ - Description: "The unique identifier of the site. Equals site_id. Required for testing infra", + Description: "For internal use only, for testing. Equals site_id.", Computed: true, }, "site_id": schema.StringAttribute{ @@ -60,7 +60,7 @@ func (r *siteResource) Schema(_ context.Context, _ resource.SchemaRequest, resp }, }, "site_dns_cname_delegation_target": schema.StringAttribute{ - Description: "The CNAME you'll use direct traffic from your website to the cdnclient.", + Description: "The CNAME you'll use to direct traffic from your website to the cdnclient.", Computed: true, }, "site_name": schema.StringAttribute{ @@ -68,7 +68,7 @@ func (r *siteResource) Schema(_ context.Context, _ resource.SchemaRequest, resp Required: true, }, "routing_method": schema.StringAttribute{ - Description: "The routing method used for the site. It is defaulted to 'DNS'.", + Description: "The routing method used for the site. The default is 'DNS.', Computed: true, }, "owner_org_id": schema.StringAttribute{ diff --git a/qwilt/cdn/cdn_siteactivation_resource.go b/qwilt/cdn/cdn_siteactivation_resource.go index 90386e2..8edbd49 100644 --- a/qwilt/cdn/cdn_siteactivation_resource.go +++ b/qwilt/cdn/cdn_siteactivation_resource.go @@ -54,7 +54,7 @@ func (r *siteActivationResource) Schema(_ context.Context, _ resource.SchemaRequ Description: "Manages a Qwilt CDN site activation and certificate assignment.", Attributes: map[string]schema.Attribute{ "id": schema.StringAttribute{ - Description: "The unique identifier of the publish operation of this site. Equals site_id:publish_id. Required for testing infra", + Description: "For internal use only, for testing. Equals site_id:publish_id.", Computed: true, }, "site_id": schema.StringAttribute{ @@ -101,7 +101,11 @@ func (r *siteActivationResource) Schema(_ context.Context, _ resource.SchemaRequ Computed: true, }, "publish_status": schema.StringAttribute{ - Description: "The publishing operation status.\\n\\nThe \\\"publishStatus\\\" values aggregate the \\\"publishState\\\" values into broader categories. \\n\\t\\n- Success - The operation succeeded.\\n- Failed - The operation failed.\\n- Aborted - The operation was canceled.\\n- InProgress - The operation is in progress.", + Description: "The publishing operation status. The 'publishStatus' values aggregate the 'publishState' values into broader categories. \n\n" + + " - Success - The operation succeeded.\n" + + " - Failed - The operation failed.\n" + + " - Aborted - The operation was canceled.\n" + + " - InProgress - The operation is in progress.", Computed: true, }, "publish_acceptance_status": schema.StringAttribute{ diff --git a/qwilt/cdn/cdn_siteconfig_resource.go b/qwilt/cdn/cdn_siteconfig_resource.go index 172cbd9..79cbf4e 100644 --- a/qwilt/cdn/cdn_siteconfig_resource.go +++ b/qwilt/cdn/cdn_siteconfig_resource.go @@ -49,7 +49,7 @@ func (r *siteConfigResource) Schema(_ context.Context, _ resource.SchemaRequest, Description: "Manages a Qwilt CDN site Configuration.", Attributes: map[string]schema.Attribute{ "id": schema.StringAttribute{ - Description: "The unique identifier of the site configuration. Equals site_id:revision_id. Required for testing infra", + Description: "For internal use only, for testing. Equals site_id:revision_id.", Computed: true, }, "site_id": schema.StringAttribute{ diff --git a/qwilt/cdn/cdn_sites_data_source.go b/qwilt/cdn/cdn_sites_data_source.go index 1925f05..b2b28e2 100644 --- a/qwilt/cdn/cdn_sites_data_source.go +++ b/qwilt/cdn/cdn_sites_data_source.go @@ -44,10 +44,10 @@ func (d *qwiltSitesDataSource) Metadata(_ context.Context, req datasource.Metada // Schema defines the schema for the data source. func (d *qwiltSitesDataSource) Schema(_ context.Context, _ datasource.SchemaRequest, resp *datasource.SchemaResponse) { resp.Schema = schema.Schema{ - Description: "Fetches Qwilt Sites configuration.", + Description: "Retrieves the sites available to your user. By default, the output includes site metadata, details about the associated site configuration versions, and details about the associated publishing operations. You can apply filters to the data source.", Attributes: map[string]schema.Attribute{ "site": schema.ListNestedAttribute{ - Description: "List of site configurations.", + Description: "Site metadata.", Computed: true, NestedObject: schema.NestedAttributeObject{ Attributes: map[string]schema.Attribute{ @@ -148,7 +148,7 @@ func (d *qwiltSitesDataSource) Schema(_ context.Context, _ datasource.SchemaRequ Computed: true, }, "host_index": schema.StringAttribute{ - Description: "The SVTA metadata objects that define the delivery service configuration, in application/json format.", + Description: "The SVTA metadata objects that define the delivery service configuration, in application/json format.", Computed: true, }, "change_description": schema.StringAttribute{ diff --git a/qwilt/cdn/client/client_test.go b/qwilt/cdn/client/client_test.go index adbaa55..79ef45b 100644 --- a/qwilt/cdn/client/client_test.go +++ b/qwilt/cdn/client/client_test.go @@ -20,9 +20,9 @@ import ( cdnclient "github.com/Qwilt/terraform-provider-qwilt/qwilt/cdn/client" ) -// Run "go generate" to format example terraform files and generate the docs for the registry/website +// Run "go generate" to format example terraform files and generate the docs for the registry/website. -// If you do not have terraform installed, you can remove the formatting command, but its suggested to +// If you do not have terraform installed, you can remove the formatting command, but it is suggested to // ensure the documentation is formatted properly. // these will be set by the goreleaser configuration diff --git a/qwilt/cdn/client/publishops.go b/qwilt/cdn/client/publishops.go index d6ebcbf..ef738ca 100644 --- a/qwilt/cdn/client/publishops.go +++ b/qwilt/cdn/client/publishops.go @@ -170,7 +170,7 @@ func (c *PublishOpsClient) GetPubOp(siteId string, publishId string) (*api.PubOp return &pubOp, nil } -// GetAndWaitForPubOpAcceptance - Returns details on a publishing operation after waitingfor it to completevalidation step +// GetAndWaitForPubOpAcceptance - Returns details about a publishing operation after waiting for it to complete validation step. func (c *PublishOpsClient) GetAndWaitForPubOpAcceptance(siteId string, publishId string, timeout time.Duration) (*api.PubOp, error) { if siteId == "" || publishId == "" { return nil, fmt.Errorf("Invalid input, siteId=%s publishId=%s", siteId, publishId) diff --git a/qwilt/provider/schema.go b/qwilt/provider/schema.go index 71230a7..0604a91 100644 --- a/qwilt/provider/schema.go +++ b/qwilt/provider/schema.go @@ -30,13 +30,13 @@ func AddResponseSchema(resp *provider.SchemaResponse) { }, "password": schema.StringAttribute{ Description: "Password for Qwilt CDN Sites API. May also be provided via QCDN_PASSWORD environment variable.", - MarkdownDescription: "XApiToken from the Login API. May also be provided via QCDN_PASSWORD environment variable.", + MarkdownDescription: "QC services password. May also be provided via QCDN_PASSWORD environment variable.", Optional: true, Sensitive: true, }, "api_key": schema.StringAttribute{ - Description: "X-API Token for Qwilt CDN Sites API. May also be provided via QCDN_API_KEY environment variable.", - MarkdownDescription: "X-API Token generated by Qwilt CDN. May also be provided via QCDN_API_KEY environment variable.", + Description: "API key for Qwilt CDN Sites API. May also be provided via QCDN_API_KEY environment variable.", + MarkdownDescription: "API key for Qwilt CDN Sites API. May also be provided via QCDN_API_KEY environment variable.", Optional: true, Sensitive: true, },