Merge pull request #629 from hmlanigan/doc-improvements

#629

## Description

Various documentation updates
- add text to attributes where changing them will replace the resource
- add warning requested in an issue #393 
- reword note on offer_url in integration resources

## Type of change

- Other: documentation updates

docs/resources/application.md

@@ -1,5 +1,5 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
+# generated using template templates/resources/application.md.tmpl
 page_title: "juju_application Resource - terraform-provider-juju"
 subcategory: ""
 description: |-
@@ -11,7 +11,6 @@ description: |-
 A resource that represents a single Juju application deployment from a charm. Deployment of bundles is not supported.
 
 ## Example Usage
-
 ```terraform
 resource "juju_application" "this" {
   name = "my-application"
@@ -48,17 +47,17 @@ resource "juju_application" "this" {
 
 ### Required
 
-- `model` (String) The name of the model where the application is to be deployed.
+- `model` (String) The name of the model where the application is to be deployed. Changing this value will cause the application to be destroyed and recreated by terraform.
 
 ### Optional
 
-- `charm` (Block List) The name of the charm to be installed from Charmhub. (see [below for nested schema](#nestedblock--charm))
+- `charm` (Block List) The charm installed from Charmhub. (see [below for nested schema](#nestedblock--charm))
 - `config` (Map of String) Application specific configuration. Must evaluate to a string, integer or boolean.
-- `constraints` (String) Constraints imposed on this application.
+- `constraints` (String) Constraints imposed on this application. Changing this value will cause the application to be destroyed and recreated by terraform.
 - `endpoint_bindings` (Attributes Set) Configure endpoint bindings (see [below for nested schema](#nestedatt--endpoint_bindings))
 - `expose` (Block List) Makes an application publicly available over the network (see [below for nested schema](#nestedblock--expose))
-- `name` (String) A custom name for the application deployment. If empty, uses the charm's name.
-- `placement` (String) Specify the target location for the application's units
+- `name` (String) A custom name for the application deployment. If empty, uses the charm's name.Changing this value will cause the application to be destroyed and recreated by terraform.
+- `placement` (String) Specify the target location for the application's units. Changing this value will cause the application to be destroyed and recreated by terraform.
 - `resources` (Map of String) Charm resources. Must evaluate to a string. A resource could be a resource revision number from CharmHub or a custom OCI image resource.
 Specify a resource other than the default for a charm. Note that not all charms have resources.
 
@@ -82,7 +81,7 @@ Notes:
 
 Required:
 
-- `name` (String) The name of the charm
+- `name` (String) The name of the charm to be deployed.  Changing this value will cause the application to be destroyed and recreated by terraform.
 
 Optional:
 
@@ -124,6 +123,12 @@ Read-Only:
 - `pool` (String) Name of the storage pool.
 - `size` (String) The size of each volume.
 
+
+### Notes
+
+Removing the config map will not reset the charm config to defaults per [GH issue #393](https://github.com/juju/terraform-provider-juju/issues/393)
+
+
 ## Import
 
 Import is supported using the following syntax:

docs/resources/credential.md

@@ -35,15 +35,15 @@ resource "juju_credential" "this" {
 
 ### Required
 
-- `auth_type` (String) Credential authorization type
-- `name` (String) The name to be assigned to the credential
+- `auth_type` (String) Credential authorization type.
+- `name` (String) The name to be assigned to the credential. Changing this value will cause the credential to be destroyed and recreated by terraform.
 
 ### Optional
 
 - `attributes` (Map of String, Sensitive) Credential attributes accordingly to the cloud
-- `client_credential` (Boolean) Add credentials to the client
-- `cloud` (Block List) JuJu Cloud where the credentials will be used to access (see [below for nested schema](#nestedblock--cloud))
-- `controller_credential` (Boolean) Add credentials to the controller
+- `client_credential` (Boolean) Add credentials to the client.
+- `cloud` (Block List) Juju Cloud where the credentials will be used to access. (see [below for nested schema](#nestedblock--cloud))
+- `controller_credential` (Boolean) Add credentials to the controller.
 
 ### Read-Only
 

docs/resources/integration.md

@@ -68,13 +68,14 @@ resource "juju_integration" "this" {
 
 Optional:
 
-- `endpoint` (String) The endpoint name.
-- `name` (String) The name of the application.
-- `offer_url` (String) The URL of a remote application.
+- `endpoint` (String) The endpoint name. This attribute may not be used at the same time as the offer_url.
+- `name` (String) The name of the application. This attribute may not be used at the same time as the offer_url.
+- `offer_url` (String) The URL of a remote application. This attribute may not be used at the same time as name and endpoint.
 
 
 ### Notes
-When creating this resource the `offer_url` property will show `(known after apply)` as below:
+When creating this resource the `offer_url` property will show `(known after apply)` if a `name` or
+ `name` and `endpoint` are supplied as below:
 ```
   + resource "juju_integration" "this" {
       + id    = (known after apply)
@@ -88,7 +89,8 @@ When creating this resource the `offer_url` property will show `(known after app
         }
     }
 ```
-This is due to a bug in the sdk this provider uses - this property will never be computed and can only be provided by the user.
+This is due to an integration requiring a name/endpoint combination or an offer_url, but not both
+bits of data together.
 
 ## Import
 

docs/resources/machine.md

@@ -26,19 +26,19 @@ resource "juju_machine" "this_machine" {
 
 ### Required
 
-- `model` (String) The Juju model in which to add a new machine.
+- `model` (String) The Juju model in which to add a new machine. Changing this value will cause the machine to be destroyed and recreated by terraform.
 
 ### Optional
 
-- `base` (String) The operating system to install on the new machine(s). E.g. [email protected].
-- `constraints` (String) Machine constraints that overwrite those available from 'juju get-model-constraints' and provider's defaults.
-- `disks` (String) Storage constraints for disks to attach to the machine(s).
+- `base` (String) The operating system to install on the new machine(s). E.g. [email protected]. Changing this value will cause the machine to be destroyed and recreated by terraform.
+- `constraints` (String) Machine constraints that overwrite those available from 'juju get-model-constraints' and provider's defaults. Changing this value will cause the application to be destroyed and recreated by terraform.
+- `disks` (String) Storage constraints for disks to attach to the machine(s). Changing this value will cause the machine to be destroyed and recreated by terraform.
 - `name` (String) A name for the machine resource in Terraform.
-- `placement` (String) Additional information about how to allocate the machine in the cloud.
+- `placement` (String) Additional information about how to allocate the machine in the cloud. Changing this value will cause the application to be destroyed and recreated by terraform.
 - `private_key_file` (String) The file path to read the private key from.
 - `public_key_file` (String) The file path to read the public key from.
-- `series` (String, Deprecated) The operating system series to install on the new machine(s).
-- `ssh_address` (String) The user@host directive for manual provisioning an existing machine via ssh. Requires public_key_file & private_key_file arguments.
+- `series` (String, Deprecated) The operating system series to install on the new machine(s). Changing this value will cause the machine to be destroyed and recreated by terraform.
+- `ssh_address` (String) The user@host directive for manual provisioning an existing machine via ssh. Requires public_key_file & private_key_file arguments. Changing this value will cause the machine to be destroyed and recreated by terraform.
 
 ### Read-Only
 

docs/resources/model.md

@@ -38,7 +38,7 @@ resource "juju_model" "this" {
 
 ### Optional
 
-- `cloud` (Block List) JuJu Cloud where the model will operate (see [below for nested schema](#nestedblock--cloud))
+- `cloud` (Block List) Juju Cloud where the model will operate. Changing this value will cause the model to be destroyed and recreated by terraform. (see [below for nested schema](#nestedblock--cloud))
 - `config` (Map of String) Override default model configuration
 - `constraints` (String) Constraints imposed to this model
 - `credential` (String) Credential used to add the model

docs/resources/offer.md

@@ -13,23 +13,22 @@ A resource that represent a Juju Offer.
 ## Example Usage
 
 ```terraform
-resource "juju_offer" "this" {
+resource "juju_offer" "myoffer" {
   model            = juju_model.development.name
   application_name = juju_application.percona-cluster.name
   endpoint         = server
 }
 
-// an offer can then be used in an integration as below:
-resource "juju_integration" "this" {
+// an offer can then be used in an cross model integration as below:
+resource "juju_integration" "myintegration" {
   model = juju_model.development-destination.name
 
   application {
     name     = juju_application.wordpress.name
     endpoint = "db"
   }
-
   application {
-    offer_url = juju_offer.this.url
+    offer_url = juju_offer.myoffer.url
   }
 }
 ```
@@ -39,13 +38,13 @@ resource "juju_integration" "this" {
 
 ### Required
 
-- `application_name` (String) The name of the application.
-- `endpoint` (String) The endpoint name.
-- `model` (String) The name of the model to operate in.
+- `application_name` (String) The name of the application. Changing this value will cause the offer to be destroyed and recreated by terraform.
+- `endpoint` (String) The endpoint name. Changing this value will cause the offer to be destroyed and recreated by terraform.
+- `model` (String) The name of the model to operate in. Changing this value will cause the offer to be destroyed and recreated by terraform.
 
 ### Optional
 
-- `name` (String) The name of the offer.
+- `name` (String) The name of the offer. Changing this value will cause the offer to be destroyed and recreated by terraform.
 
 ### Read-Only
 

docs/resources/secret.md

@@ -38,7 +38,7 @@ resource "juju_application" "my-application" {
 
 ### Required
 
-- `model` (String) The model in which the secret belongs.
+- `model` (String) The model in which the secret belongs. Changing this value will cause the secret to be destroyed and recreated by terraform.
 - `value` (Map of String, Sensitive) The value map of the secret. There can be more than one key-value pair.
 
 ### Optional

docs/resources/user.md

@@ -17,12 +17,12 @@ A resource that represents a Juju User.
 
 ### Required
 
-- `name` (String) The name to be assigned to the user
-- `password` (String, Sensitive) The password to be assigned to the user
+- `name` (String) The username to be assigned to the user. Changing this value will cause the user to be destroyed and recreated by terraform.
+- `password` (String, Sensitive) The password to be assigned to the user.
 
 ### Optional
 
-- `display_name` (String) The display name to be assigned to the user (optional)
+- `display_name` (String) The display name to be assigned to the user (optional).
 
 ### Read-Only
 

examples/resources/juju_offer/resource.tf

@@ -1,19 +1,18 @@
-resource "juju_offer" "this" {
+resource "juju_offer" "myoffer" {
   model            = juju_model.development.name
   application_name = juju_application.percona-cluster.name
   endpoint         = server
 }
 
-// an offer can then be used in an integration as below:
-resource "juju_integration" "this" {
+// an offer can then be used in an cross model integration as below:
+resource "juju_integration" "myintegration" {
   model = juju_model.development-destination.name
 
   application {
     name     = juju_application.wordpress.name
     endpoint = "db"
   }
-
   application {
-    offer_url = juju_offer.this.url
+    offer_url = juju_offer.myoffer.url
   }
 }

internal/provider/resource_application.go

@@ -130,17 +130,19 @@ func (r *applicationResource) Schema(_ context.Context, _ resource.SchemaRequest
 			" is not supported.",
 		Attributes: map[string]schema.Attribute{
 			"name": schema.StringAttribute{
-				Description: "A custom name for the application deployment. If empty, uses the charm's name.",
-				Optional:    true,
-				Computed:    true,
+				Description: "A custom name for the application deployment. If empty, uses the charm's name." +
+					"Changing this value will cause the application to be destroyed and recreated by terraform.",
+				Optional: true,
+				Computed: true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplaceIfConfigured(),
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"model": schema.StringAttribute{
-				Description: "The name of the model where the application is to be deployed.",
-				Required:    true,
+				Description: "The name of the model where the application is to be deployed. Changing this value" +
+					" will cause the application to be destroyed and recreated by terraform.",
+				Required: true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplaceIfConfigured(),
 				},
@@ -157,8 +159,9 @@ func (r *applicationResource) Schema(_ context.Context, _ resource.SchemaRequest
 				ElementType: types.StringType,
 			},
 			"constraints": schema.StringAttribute{
-				Description: "Constraints imposed on this application.",
-				Optional:    true,
+				Description: "Constraints imposed on this application. Changing this value will cause the" +
+					" application to be destroyed and recreated by terraform.",
+				Optional: true,
 				// Set as "computed" to pre-populate and preserve any implicit constraints
 				Computed: true,
 				PlanModifiers: []planmodifier.String{
@@ -213,9 +216,10 @@ func (r *applicationResource) Schema(_ context.Context, _ resource.SchemaRequest
 				Default:     booldefault.StaticBool(false),
 			},
 			"placement": schema.StringAttribute{
-				Description: "Specify the target location for the application's units",
-				Optional:    true,
-				Computed:    true,
+				Description: "Specify the target location for the application's units. Changing this value" +
+					" will cause the application to be destroyed and recreated by terraform.",
+				Optional: true,
+				Computed: true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplaceIfConfigured(),
 					stringplanmodifier.UseStateForUnknown(),
@@ -267,12 +271,13 @@ func (r *applicationResource) Schema(_ context.Context, _ resource.SchemaRequest
 		},
 		Blocks: map[string]schema.Block{
 			CharmKey: schema.ListNestedBlock{
-				Description: "The name of the charm to be installed from Charmhub.",
+				Description: "The charm installed from Charmhub.",
 				NestedObject: schema.NestedBlockObject{
 					Attributes: map[string]schema.Attribute{
 						"name": schema.StringAttribute{
-							Required:    true,
-							Description: "The name of the charm",
+							Required: true,
+							Description: "The name of the charm to be deployed.  Changing this value will cause" +
+								" the application to be destroyed and recreated by terraform.",
 							PlanModifiers: []planmodifier.String{
 								stringplanmodifier.RequiresReplaceIfConfigured(),
 							},

internal/provider/resource_credential.go

@@ -71,7 +71,7 @@ func (c *credentialResource) Schema(_ context.Context, _ resource.SchemaRequest,
 						},
 					},
 				},
-				Description: "JuJu Cloud where the credentials will be used to access",
+				Description: "Juju Cloud where the credentials will be used to access.",
 				PlanModifiers: []planmodifier.List{
 					listplanmodifier.RequiresReplace(),
 				},
@@ -88,24 +88,25 @@ func (c *credentialResource) Schema(_ context.Context, _ resource.SchemaRequest,
 				Sensitive:   true,
 			},
 			"auth_type": schema.StringAttribute{
-				Description: "Credential authorization type",
+				Description: "Credential authorization type.",
 				Required:    true,
 			},
 			"client_credential": schema.BoolAttribute{
-				Description: "Add credentials to the client",
+				Description: "Add credentials to the client.",
 				Optional:    true,
 				Computed:    true,
 				Default:     booldefault.StaticBool(false),
 			},
 			"controller_credential": schema.BoolAttribute{
-				Description: "Add credentials to the controller",
+				Description: "Add credentials to the controller.",
 				Optional:    true,
 				Computed:    true,
 				Default:     booldefault.StaticBool(true),
 			},
 			"name": schema.StringAttribute{
-				Description: "The name to be assigned to the credential",
-				Required:    true,
+				Description: "The name to be assigned to the credential. Changing this value will cause the" +
+					" credential to be destroyed and recreated by terraform.",
+				Required: true,
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},