Add the environment context to evaluated templates + doc updates

.tool-versions

@@ -1 +1 @@
-golang 1.21.0
+golang 1.21.5

cloudtruth/data_template.go

@@ -15,7 +15,8 @@ import (
 
 func dataCloudTruthTemplate() *schema.Resource {
 	return &schema.Resource{
-		Description: "A CloudTruth template data source",
+		Description: `A CloudTruth template data source. Use this to reference the rendered values from CloudTruth
+Templates in the context of a project and environment.`,
 		ReadContext: dataCloudTruthTemplateRead,
 		Schema: map[string]*schema.Schema{
 			"project": {
@@ -97,7 +98,7 @@ func dataCloudTruthTemplateRead(ctx context.Context, d *schema.ResourceData, met
 	body := template.GetBody()
 	tflog.Debug(ctx, fmt.Sprintf("dataCloudTruthTemplateRead: template body - %s", body))
 
-	previewBody, err := renderTemplateBody(ctx, name, body, *projID, meta)
+	previewBody, err := renderTemplateBody(ctx, name, body, *projID, *envID, meta)
 	if err != nil {
 		return diag.FromErr(err)
 	}
@@ -110,7 +111,7 @@ func dataCloudTruthTemplateRead(ctx context.Context, d *schema.ResourceData, met
 	return nil
 }
 
-func renderTemplateBody(ctx context.Context, name, body, projectID string, meta any) (*string, error) {
+func renderTemplateBody(ctx context.Context, name, body, projectID, envID string, meta any) (*string, error) {
 	tflog.Debug(ctx, "entering renderTemplateBody")
 	defer tflog.Debug(ctx, "exiting renderTemplateBody")
 	c := meta.(*cloudTruthClient)
@@ -121,7 +122,7 @@ func renderTemplateBody(ctx context.Context, name, body, projectID string, meta
 	// We cannot use the TF Provider SDK's retry functionality because it only works with state change events
 	// so we employ a simple retry loop instead
 	for retryCount < loadCacheRetries {
-		previewCreate, r, err := c.openAPIClient.ProjectsAPI.ProjectsTemplatePreviewCreate(ctx, projectID).
+		previewCreate, r, err := c.openAPIClient.ProjectsAPI.ProjectsTemplatePreviewCreate(ctx, projectID).Environment(envID).
 			TemplatePreviewCreateRequest(*templatePrevReq).Execute()
 		if r.StatusCode >= 500 {
 			apiError = err
@@ -218,7 +219,7 @@ func dataCloudTruthTemplatesRead(ctx context.Context, d *schema.ResourceData, me
 		for _, res := range results {
 			templateName := res.GetName()
 			templateBody := res.GetBody()
-			previewBody, err := renderTemplateBody(ctx, templateName, templateBody, *projID, meta)
+			previewBody, err := renderTemplateBody(ctx, templateName, templateBody, *projID, *envID, meta)
 			if err != nil {
 				return diag.FromErr(fmt.Errorf("dataCloudTruthTemplatesRead: %w", err))
 			} else {

cloudtruth/resource_template.go

@@ -13,7 +13,10 @@ import (
 
 func resourceTemplate() *schema.Resource {
 	return &schema.Resource{
-		Description:   "A CloudTruth Template.",
+		Description: `A CloudTruth Template. Use this to manage Templates in your CloudTruth project
+If you want to render a template in the context of a project and environment, use a cloudtruth_template
+data source instead. The value for a cloudtruth_template resource is the raw unevaluated template string.
+`,
 		CreateContext: resourceTemplateCreate,
 		ReadContext:   resourceTemplateRead,
 		UpdateContext: resourceTemplateUpdate,

docs/data-sources/template.md

@@ -3,12 +3,14 @@
 page_title: "cloudtruth_template Data Source - terraform-provider-cloudtruth"
 subcategory: ""
 description: |-
-  A CloudTruth template data source
+  A CloudTruth template data source. Use this to reference the rendered values from CloudTruth
+  Templates in the context of a project and environment.
 ---
 
 # cloudtruth_template (Data Source)
 
-A CloudTruth template data source
+A CloudTruth template data source. Use this to reference the rendered values from CloudTruth
+Templates in the context of a project and environment.
 
 
 

docs/index.md

@@ -1,16 +1,66 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "cloudtruth Provider"
-subcategory: ""
+page_title: "CloudTruth Provider"
 description: |-
-  
+  The CloudTruth Terraform provider is used to interact with CloudTruth application resources.
 ---
 
-# cloudtruth Provider
+# CloudTruth Provider
 
+The [CloudTruth](https://cloudtruth.com) Terraform provider is used to interact with CloudTruth application resources.
 
+## Example Usage
 
+```hcl
+# You can specify the CloudTruth API explicitly like this and inject it into
+# the environment where your Terraform commands run by running
+# export TF_VAR_cloudtruth_api_key=<YOUR_API_KEY>
+# or you can omit this provider block entirely and
+# use the CloudTruth CLI environment variable format by
+# running export CLOUDTRUTH_API_KEY=<YOUR_API_KEY>
+provider "cloudtruth" {
+  api_key = var.cloudtruth_api_key
+}
 
+// Projects
+resource "cloudtruth_project" "parent_project" {
+  name        = "ParentProject"
+  description = "A top level project."
+}
+
+resource "cloudtruth_project" "project_a" {
+  name        = "ProjectA"
+  description = "A subproject"
+  parent      = cloudtruth_project.parent_project.name
+}
+
+resource "cloudtruth_parameter" "some_parameter" {
+  name    = "my_parameter_name"
+  project = cloudtruth_project.parent_project.name
+}
+
+# When the environment is not specified, the "default" environment is used
+resource "cloudtruth_parameter_value" "some_parameter_value" {
+  parameter_name = cloudtruth_parameter.some_parameter.name
+  project        = cloudtruth_project.parent_project.name
+  value          = "A_REGULAR_STRING_VALUE_NOT_A_SECRET"
+}
+
+# Here's another value for the same parameter in the "development" environment
+resource "cloudtruth_parameter_value" "some_parameter_value_in_dev" {
+  parameter_name = cloudtruth_parameter.some_parameter.name
+  environment    = "development"
+  project        = cloudtruth_project.parent_project.name
+  value          = "A_REGULAR_STRING_OVERRIDE_FOR_THE_DEV_ENV"
+}
+
+# Here we specify a value for the parameter in the default environment only
+# in the child project ProjectA
+resource "cloudtruth_parameter_value" "some_parameter_value" {
+  parameter_name = cloudtruth_parameter.some_parameter.name
+  project        = cloudtruth_project.project_a.name
+  value          = "A_REGULAR_STRING_VALUE_IN_PROJECT_A_DEFAULT_ENV"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/resources/template.md

@@ -3,12 +3,16 @@
 page_title: "cloudtruth_template Resource - terraform-provider-cloudtruth"
 subcategory: ""
 description: |-
-  A CloudTruth Template.
+  A CloudTruth Template. Use this to manage Templates in your CloudTruth project
+  If you want to render a template in the context of a project and environment, use a cloudtruthtemplate
+  data source instead. The value for a cloudtruthtemplate resource is the raw unevaluated template string.
 ---
 
 # cloudtruth_template (Resource)
 
-A CloudTruth Template.
+A CloudTruth Template. Use this to manage Templates in your CloudTruth project
+If you want to render a template in the context of a project and environment, use a cloudtruth_template
+data source instead. The value for a cloudtruth_template resource is the raw unevaluated template string.
 
 
 

templates/index.md.tmpl

@@ -0,0 +1,65 @@
+---
+page_title: "CloudTruth Provider"
+description: |-
+  The CloudTruth Terraform provider is used to interact with CloudTruth application resources.
+---
+
+# CloudTruth Provider
+
+The [CloudTruth](https://cloudtruth.com) Terraform provider is used to interact with CloudTruth application resources.
+
+## Example Usage
+
+```hcl
+# You can specify the CloudTruth API explicitly like this and inject it into
+# the environment where your Terraform commands run by running
+# export TF_VAR_cloudtruth_api_key=<YOUR_API_KEY>
+# or you can omit this provider block entirely and
+# use the CloudTruth CLI environment variable format by
+# running export CLOUDTRUTH_API_KEY=<YOUR_API_KEY>
+provider "cloudtruth" {
+  api_key = var.cloudtruth_api_key
+}
+
+// Projects
+resource "cloudtruth_project" "parent_project" {
+  name        = "ParentProject"
+  description = "A top level project."
+}
+
+resource "cloudtruth_project" "project_a" {
+  name        = "ProjectA"
+  description = "A subproject"
+  parent      = cloudtruth_project.parent_project.name
+}
+
+resource "cloudtruth_parameter" "some_parameter" {
+  name    = "my_parameter_name"
+  project = cloudtruth_project.parent_project.name
+}
+
+# When the environment is not specified, the "default" environment is used
+resource "cloudtruth_parameter_value" "some_parameter_value" {
+  parameter_name = cloudtruth_parameter.some_parameter.name
+  project        = cloudtruth_project.parent_project.name
+  value          = "A_REGULAR_STRING_VALUE_NOT_A_SECRET"
+}
+
+# Here's another value for the same parameter in the "development" environment
+resource "cloudtruth_parameter_value" "some_parameter_value_in_dev" {
+  parameter_name = cloudtruth_parameter.some_parameter.name
+  environment    = "development"
+  project        = cloudtruth_project.parent_project.name
+  value          = "A_REGULAR_STRING_OVERRIDE_FOR_THE_DEV_ENV"
+}
+
+# Here we specify a value for the parameter in the default environment only
+# in the child project ProjectA
+resource "cloudtruth_parameter_value" "some_parameter_value" {
+  parameter_name = cloudtruth_parameter.some_parameter.name
+  project        = cloudtruth_project.project_a.name
+  value          = "A_REGULAR_STRING_VALUE_IN_PROJECT_A_DEFAULT_ENV"
+}
+```
+
+{{ .SchemaMarkdown | trimspace }}