mmv1/docs: move write-only arguments into arguments section (#15385)

Co-authored-by: Ramon Vermeulen <[email protected]>
Co-authored-by: Stephen Lewis (Burrows) <[email protected]>

Author: 3 people

mmv1/api/resource.go

@@ -850,7 +850,6 @@ func (r *Resource) attachConstraintGroup(groupType string, source []string) *[]s
 }
 
 func buildWriteOnlyField(name string, versionFieldName string, originalField *Type) *Type {
-	description := fmt.Sprintf("%s Note: This property is write-only and will not be read from the API. For more info see [updating write-only attributes](/docs/providers/google/guides/using_write_only_attributes.html#updating-write-only-attributes)", originalField.Description)
 	originalFieldLineage := originalField.TerraformLineage()
 	newFieldLineage := strings.ReplaceAll(originalFieldLineage, google.Underscore(originalField.Name), google.Underscore(name))
 	requiredWith := strings.ReplaceAll(originalFieldLineage, google.Underscore(originalField.Name), google.Underscore(versionFieldName))
@@ -863,7 +862,7 @@ func buildWriteOnlyField(name string, versionFieldName string, originalField *Ty
 	options := []func(*Type){
 		propertyWithType("String"),
 		propertyWithRequired(false),
-		propertyWithDescription(description),
+		propertyWithDescription(originalField.Description),
 		propertyWithWriteOnly(true),
 		propertyWithApiName(apiName),
 		propertyWithIgnoreRead(true),
@@ -898,7 +897,7 @@ func buildWriteOnlyField(name string, versionFieldName string, originalField *Ty
 }
 
 func buildWriteOnlyVersionField(name string, originalField *Type, writeOnlyField *Type) *Type {
-	description := fmt.Sprintf("Triggers update of %s write-only. For more info see [updating write-only attributes](/docs/providers/google/guides/using_write_only_attributes.html#updating-write-only-attributes)", google.Underscore(writeOnlyField.Name))
+	description := fmt.Sprintf("Triggers update of `%s` write-only. Increment this value when an update to `%s` is needed. For more info see [updating write-only arguments](/docs/providers/google/guides/using_write_only_arguments.html#updating-write-only-arguments)", google.Underscore(writeOnlyField.Name), google.Underscore(writeOnlyField.Name))
 	requiredWith := strings.ReplaceAll(originalField.TerraformLineage(), google.Underscore(originalField.Name), google.Underscore(writeOnlyField.Name))
 
 	options := []func(*Type){

mmv1/products/bigquerydatatransfer/Config.yaml

@@ -228,7 +228,7 @@ properties:
         required_with:
           - 'sensitive_params.0.secretAccessKeyWo'
         description: |
-          The version of the sensitive params - used to trigger updates of the write-only params. For more info see [updating write-only attributes](/docs/providers/google/guides/using_write_only_attributes.html#updating-write-only-attributes)
+          The version of the sensitive params - used to trigger updates of the write-only params. For more info see [updating write-only arguments](/docs/providers/google/guides/using_write_only_arguments.html#updating-write-only-arguments)
       - name: 'secretAccessKey'
         type: String
         description: |

mmv1/products/secretmanager/SecretVersion.yaml

@@ -189,7 +189,7 @@ properties:
         is_missing_in_cai: true
       - name: 'secretDataWo'
         type: String
-        description: The secret data. Must be no larger than 64KiB. For more info see [updating write-only attributes](/docs/providers/google/guides/using_write_only_attributes.html#updating-write-only-attributes)
+        description: The secret data. Must be no larger than 64KiB. For more info see [updating write-only arguments](/docs/providers/google/guides/using_write_only_arguments.html#updating-write-only-arguments)
         api_name: data
         required_with:
           - 'SecretDataWoVersion'
@@ -200,5 +200,5 @@ properties:
         type: Integer
         default_value: 0
         url_param_only: true
-        description: Triggers update of secret data write-only. For more info see [updating write-only attributes](/docs/providers/google/guides/using_write_only_attributes.html#updating-write-only-attributes)
+        description: Triggers update of secret data write-only. For more info see [updating write-only arguments](/docs/providers/google/guides/using_write_only_arguments.html#updating-write-only-arguments)
         immutable: true

mmv1/templates/terraform/property_documentation.html.markdown.tmpl

@@ -20,10 +20,13 @@
   {{- end }}
   {{- if or $.WriteOnlyLegacy $.WriteOnly }}
   **Note**: This property is write-only and will not be read from the API.
+
+  ~> **Note:** One of `{{ slice (underscore $.Name) 0 (sub (len (underscore $.Name)) 3) }}` or `{{ underscore $.Name }}` can only be set.
   {{- end }}
   {{- if and (not $.FlattenObject) $.NestedProperties }}
   Structure is [documented below](#nested_{{ $.LineageAsSnakeCase}}).
   {{- end }}
+
   {{- if $.DeprecationMessage }}
 
   ~> **Warning:** {{ $.DeprecationMessage }}

mmv1/templates/terraform/resource.html.markdown.tmpl

@@ -60,7 +60,7 @@ values will be stored in the raw state as plain text: {{ $.SensitivePropsToStrin
 {{ end }}
 {{- if $.WriteOnlyProps }}
 ~> **Note:**  All arguments marked as write-only values will not be stored in the state: {{ $.WriteOnlyPropsToString }}.
-[Read more about Write-only Attributes](https://developer.hashicorp.com/terraform/plugin/sdkv2/resources/write-only-arguments).
+[Read more about Write-only Arguments](https://developer.hashicorp.com/terraform/plugin/sdkv2/resources/write-only-arguments).
 {{ end }}
 {{- if $.Examples }}
 	{{- range $e := $.Examples }}
@@ -110,13 +110,13 @@ The following arguments are supported:
 {{ "" }}
 {{ "" }}
 {{- range $p := $.RootProperties }}
-	{{- if and $p.Required (not $p.WriteOnlyLegacy) (not $p.WriteOnly) }}
+	{{- if $p.Required }}
 {{- trimTemplate "property_documentation.html.markdown.tmpl" $p -}}
 	{{- end }}
 {{- end }}
 {{ "" }}
 {{- range $p := $.RootProperties }}
-	{{- if and (not $p.Required) (not $p.Output) (not $p.WriteOnlyLegacy) (not $p.WriteOnly) }}
+	{{- if and (not $p.Required) (not $p.Output) }}
 {{- trimTemplate "property_documentation.html.markdown.tmpl" $p -}}
 	{{- end }}
 {{- end }}
@@ -146,19 +146,6 @@ The following arguments are supported:
 	{{- end}}
 {{- end }}
 {{- "" }}
-{{- if $.WriteOnlyProps }}
-## Ephemeral Attributes Reference
-
-The following write-only attributes are supported:
-{{ range $p := $.RootProperties }}
-    {{- if or $p.WriteOnlyLegacy $p.WriteOnly }}
-{{- trimTemplate "property_documentation.html.markdown.tmpl" $p }}
-    {{- end}}
-{{- end }}
-{{ range $p := $.AllUserProperties }}
-{{- trimTemplate "nested_property_write_only_documentation.html.markdown.tmpl" $p }}
-{{- end }}
-{{- end }}
 ## Attributes Reference
 
 In addition to the arguments listed above, the following computed attributes are exported:

mmv1/third_party/terraform/website/docs/ephemeral-resources/service_account_id_token.html.markdown

@@ -13,7 +13,7 @@ For more information see
 
 ## Example Usage - ServiceAccount JSON credential file.
 
--> **Note:** If you run this example configuration you will be able to see ephemeral.google_service_account_id_token.oidc in terraform plan and apply terminal output but you will not see it in state, as ephemeral resources are excluded from state. In future, when write-only attributes are added to resources in the Google provider, ephemeral resources such as google_service_account_id_token could be used to set field values when creating managed resources.
+-> **Note:** If you run this example configuration you will be able to see ephemeral.google_service_account_id_token.oidc in terraform plan and apply terminal output but you will not see it in state, as ephemeral resources are excluded from state. In future, when write-only arguments are added to resources in the Google provider, ephemeral resources such as google_service_account_id_token could be used to set field values when creating managed resources.
 
   `google_service_account_id_token` will use the configured [provider credentials](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#credentials-1)
 
@@ -25,7 +25,7 @@ For more information see
 
 ## Example Usage - Service Account Impersonation.
 
--> **Note:** If you run this example configuration you will be able to see ephemeral.google_service_account_id_token.oidc in terraform plan and apply terminal output but you will not see it in state, as ephemeral resources are excluded from state. In future, when write-only attributes are added to resources in the Google provider, ephemeral resources such as google_service_account_id_token could be used to set field values when creating managed resources.
+-> **Note:** If you run this example configuration you will be able to see ephemeral.google_service_account_id_token.oidc in terraform plan and apply terminal output but you will not see it in state, as ephemeral resources are excluded from state. In future, when write-only arguments are added to resources in the Google provider, ephemeral resources such as google_service_account_id_token could be used to set field values when creating managed resources.
 
   Ephemeral resource `google_service_account_id_token` will use background impersonated credentials provided by [google_service_account_access_token](https://registry.terraform.io/providers/hashicorp/google/latest/docs/data-sources/service_account_access_token).
 

mmv1/third_party/terraform/website/docs/ephemeral-resources/service_account_jwt.html.markdown

@@ -10,7 +10,7 @@ This ephemeral resource provides a [self-signed JWT](https://cloud.google.com/ia
 
 ## Example Usage
 
--> **Note:** If you run this example configuration you will be able to see ephemeral.google_service_account_jwt.foo in terraform plan and apply terminal output but you will not see it in state, as ephemeral resources are excluded from state. In future, when write-only attributes are added to resources in the Google provider, ephemeral resources such as google_service_account_jwt could be used to set field values when creating managed resources.
+-> **Note:** If you run this example configuration you will be able to see ephemeral.google_service_account_jwt.foo in terraform plan and apply terminal output but you will not see it in state, as ephemeral resources are excluded from state. In future, when write-only arguments are added to resources in the Google provider, ephemeral resources such as google_service_account_jwt could be used to set field values when creating managed resources.
 
 Note: in order to use the following, the caller must have _at least_ `roles/iam.serviceAccountTokenCreator` on the `target_service_account`.
 

mmv1/third_party/terraform/website/docs/ephemeral-resources/service_account_key.html.markdown

@@ -10,7 +10,7 @@ Get an ephemeral service account public key. For more information, see [the offi
 
 ## Example Usage
 
--> **Note:** If you run this example configuration you will be able to see ephemeral.google_service_account_key.mykey in terraform plan and apply terminal output but you will not see it in state, as ephemeral resources are excluded from state. In future, when write-only attributes are added to resources in the Google provider, ephemeral resources such as google_service_account_key could be used to set field values when creating managed resources.
+-> **Note:** If you run this example configuration you will be able to see ephemeral.google_service_account_key.mykey in terraform plan and apply terminal output but you will not see it in state, as ephemeral resources are excluded from state. In future, when write-only arguments are added to resources in the Google provider, ephemeral resources such as google_service_account_key could be used to set field values when creating managed resources.
 
 
 ```hcl

mmv1/third_party/terraform/website/docs/guides/using_ephemeral_resources.html.markdown

@@ -22,7 +22,7 @@ These are based on existing data sources already in the provider. In future you
 
 ## Use the Google Cloud provider's new ephemeral resources
 
-Ephemeral resources are a source of ephemeral data, and they can be referenced in your configuration just like the attributes of resources and data sources. However, a field that references an ephemeral resource must be capable of handling ephemeral data. Due to this, resources in the Google Cloud provider will need to be updated so they include write-only attributes that are capable of using ephemeral data while not storing those values in the resource's state.
+Ephemeral resources are a source of ephemeral data, and they can be referenced in your configuration just like the attributes of resources and data sources. However, a field that references an ephemeral resource must be capable of handling ephemeral data. Due to this, resources in the Google Cloud provider will need to be updated so they include write-only arguments that are capable of using ephemeral data while not storing those values in the resource's state. 
 
 Until then, ephemeral resources can only be used to pass values into the provider block, which is already capable of receiving ephemeral values.
 

…sing_write_only_attributes.html.markdown …using_write_only_arguments.html.markdownmmv1/third_party/terraform/website/docs/guides/using_write_only_attributes.html.markdown renamed to mmv1/third_party/terraform/website/docs/guides/using_write_only_arguments.html.markdown mmv1/third_party/terraform/website/docs/guides/using_write_only_attributes.html.markdown renamed to mmv1/third_party/terraform/website/docs/guides/using_write_only_arguments.html.markdown

@@ -1,29 +1,29 @@
 ---
-page_title: "Use write-only attributes in the Google Cloud provider"
+page_title: "Use write-only arguments in the Google Cloud provider"
 description: |-
-  How to use write-only attributes in the Google Cloud provider
+  How to use write-only arguments in the Google Cloud provider
 ---
 
-# Write-only attributes in the Google Cloud provider
+# Write-only arguments in the Google Cloud provider
 
-The Google Cloud provider has introduced new write-only attributes for a more secure way to manage data. The new `WriteOnly` attribute accepts values from configuration and will not be stored in plan or state providing an additional layer of security and control over data access.
+The Google Cloud provider has introduced new write-only arguments for a more secure way to manage data. These arguments accept values from configuration and will not be stored in plan or state providing an additional layer of security and control over data access.
 
-For more information, see the [official HashiCorp documentation for Write-only Attributes](https://developer.hashicorp.com/terraform/plugin/sdkv2/resources/write-only-arguments).
+For more information, see the [official HashiCorp documentation for Write-only Arguments](https://developer.hashicorp.com/terraform/plugin/sdkv2/resources/write-only-arguments).
 
-The Google Cloud provider has added the following write-only attributes:
+The Google Cloud provider has added the following write-only arguments:
 - [`google_sql_user: password_wo`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/sql_user#password-1)
 - [`google_secret_manager_secret_version: secret_data_wo`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/secret_manager_secret_version#secret_data_wo)
 - [`google_bigquery_data_transfer_config: sensitive_params.secret_access_key_wo`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_data_transfer_config#secret_access_key_wo)
 
-These were chosen due to them being marked as sensitive already in the provider. Although sensitive attributes do not appear in `terraform plan`, they are still stored in the Terraform state. Write-only attributes allow users to access and use data in their configurations without that data being stored in Terraform state.
+These were chosen due to them being marked as sensitive already in the provider. Although sensitive arguments do not appear in `terraform plan`, they are still stored in the Terraform state. Write-only arguments allow users to access and use data in their configurations without that data being stored in Terraform state.
 
-## Use the Google Cloud provider's new write-only attributes
+## Use the Google Cloud provider's new write-only arguments
 
-The following sections show how to use the new write-only attributes in the Google Cloud provider.
+The following sections show how to use the new write-only argument in the Google Cloud provider.
 
-### Applying a write-only attribute
+### Applying a write-only argument
 
-The following example shows how to apply a write-only attribute. All write-only attributes are marked with the `wo` suffix and can not be used with the attribute that it's mirroring. For example, `secret_data_wo` can not be used with `secret_data`.
+The following example shows how to apply a write-only argument. All write-only arguments are marked with the `wo` suffix and can't be used with the argument that it's mirroring. For example, `secret_data_wo` can not be used with `secret_data`.
 
 ```hcl
 resource "google_sql_database_instance" "instance" {
@@ -44,7 +44,7 @@ resource "google_sql_user" "user1" {
 }
 ```
 
-During `terraform plan` you will see that the write-only attribute is marked appropriately:
+During `terraform plan` you will see that the write-only argument is marked appropriately:
 
 ```
   # google_sql_user.user1 will be created
@@ -88,11 +88,11 @@ Upon `terrform apply` you will see in `terraform.tfstate` that the write-only at
           },
 ```
 
-Any value that is set for a write-only attribute is nulled out before the RPC response is sent to Terraform.
+Any value that is set for a write-only argument is nulled out before the RPC response is sent to Terraform.
 
-### Updating write-only attributes
+### Updating write-only arguments
 
-Since write-only attributes are not stored in the Terraform state, they cannot be updated by just changing the value in the configuration due to the attribute being nulled out.
+Since write-only arguments are not stored in the Terraform state, they cannot be updated by just changing the value in the configuration due to the attribute being nulled out.
 
 In order to update a write-only attribute we must change the write-only attribute's version.
 
@@ -106,7 +106,7 @@ resource "google_sql_user" "user1" {
 }
 ```
 
-A `terraform apply` of this configuration will allow you to update the write-only attribute despite the new value not being shown in the plan.
+A `terraform apply` of this configuration will allow you to update the write-only argument despite the new value not being shown in the plan.
 
 ```hcl
 Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: