MMv1 field reference #

This page documents commonly-used properties for fields. For a full list of available properties, see type.go ↗.

Shared properties #

`min_version: beta` #

Marks the field (and any subfields) as beta-only. Ensure a beta version block is present in provider.yaml. Do not use if an ancestor field (or the overall resource) is already marked as beta-only.

`immutable` #

If true, the field (and any subfields) are considered immutable - that is, only settable on create. If unset or false, the field is still considered immutable if any ancestor field (or the overall resource) is immutable, unless update_url is set.

Example:

immutable: true

`update_url` #

If set, changes to the field’s value trigger a separate call to a specific API method for updating the field’s value. The field is not considered immutable even if an ancestor field (or the overall resource) is immutable. Terraform field names enclosed in double curly braces are replaced with the field values from the resource at runtime.

Example:

update_url: 'projects/{{project}}/locations/{{location}}/resourcenames/{{name}}/setFieldName'

`update_verb` #

If update_url is also set, overrides the verb used to update this specific field. Allowed values: ‘POST’, ‘PUT’, ‘PATCH’. Default: Resource’s update_verb (which defaults to ‘PUT’ if unset).

Example:

update_verb: 'POST'

`required` #

If true, the field is required. If unset or false, the field is optional.

Example:

required: true

`output` #

If true, the field is output-only - that is, it cannot be configured by the user. If unset or false, the field is configurable.

Example:

output: true

`sensitive` #

If true, the field is considered “sensitive”, which means that its value will be obscured in Terraform output such as plans. If false, the value will not be obscured. Either way, the value will still be stored in plaintext in Terraform state. See Handling Sensitive Values in State for more information.

Sensitive fields are often not returned by the API (because they are sensitive). In this case, the field will also need to use ignore_read or a custom_flatten function.

Example:

sensitive: true

`ignore_read` #

If true, the provider sets the field’s value in the resource state based only on the user’s configuration. If false or unset, the provider sets the field’s value in the resource state based on the API response. Only use this attribute if the field cannot be read from GCP due to either API or provider constraints.

Nested fields currently do not support ignore_read but can replicate the behavior by implementing a custom_flatten that always ignores the value returned by the API. Example. Any fields using a custom flatten also need to be added to ignore_read_extra for any examples where the field is set.

Example: YAML

ignore_read: true

Example: Custom flatten

func flatten{{$.GetPrefix}}{{$.TitlelizeProperty}}(v interface{}, d *schema.ResourceData, config *transport_tpg.Config) interface{} {
  return d.Get("password")
}

`default_value` #

Sets a client-side default value for the field. This should be used if the API has a default value that applies in all cases and is stable. Removing or changing a default value is a breaking change. If unset, the field defaults to an “empty” value (such as zero, false, or an empty string).

Example:

default_value: DEFAULT_VALUE

`default_from_api` #

If true, and the field is either not set or set to an “empty” value (such as zero, false, or empty strings), the provider accepts any value returned from the API as the value for the field. If false, and the field is either not set or set to an “empty” value, the provider treats the field’s default_value as the value for the field and shows a diff if the API returns any other value for the field. This attribute is useful for complex or frequently-changed API-side defaults, but provides less useful information at plan time than default_value and causes the provider to ignore user configurations that explicitly set the field to an “empty” value. default_from_api and send_empty_value cannot both be true on the same field.

Example:

default_from_api: true

`send_empty_value` #

If true, the provider sends “empty” values (such as zero, false, or empty strings) to the API if set explicitly in the user’s configuration. If false, “empty” values cause the field to be omitted entirely from the API request. This attribute is useful for fields where the API would behave differently for an “empty” value vs no value for a particular field - for example, boolean fields that have an API-side default of true. send_empty_value and default_from_api cannot both be true on the same field.

Due to a bug, NestedObject fields will currently be sent as null if unset (rather than being omitted.)

Example:

send_empty_value: true

`conflicts` #

Specifies a list of fields (excluding the current field) that cannot be specified at the same time as the current field. Must be set separately on all listed fields. Not supported within lists of nested objects.

Example:

- name: 'fieldOne'
  type: String
  conflicts:
    - field_two
    - nested_object.0.nested_field

`required_with` #

Specifies a list of fields (excluding the current field) that must all be specified if at least one is specified. Must be set separately on all listed fields. Not supported within lists of nested objects.

Example:

- name: 'fieldOne'
  type: String
  required_with:
    - field_two
    - nested_object.0.nested_field

`exactly_one_of` #

Specifies a list of fields (including the current field) of which exactly one must be set. Must be set separately on all listed fields. Not supported within lists of nested objects.

Example:

- name: 'fieldOne'
  type: String
  exactly_one_of:
    - field_one
    - field_two
    - nested_object.0.nested_field

`at_least_one_of` #

Specifies a list of fields (including the current field) that cannot be specified at the same time (but at least one of which must be set). Must be set separately on all listed fields. Not supported within lists of nested objects.

Example:

- name: 'fieldOne'
  type: String
  at_least_one_of:
    - field_one
    - field_two
    - nested_object.0.nested_field

`diff_suppress_func` #

Specifies the name of a diff suppress function to use for this field. In many cases, a custom flattener is preferred because it will allow the user to see a clearer diff when the field actually is being changed. See Fix diffs for more information and best practices.

The function specified can be a provider-specific function (for example, tgpresource.CaseDiffSuppress) or a function defined in resource-specific custom code.

Example:

- name: 'fieldOne'
  type: String
  diff_suppress_func: 'tpgresource.CaseDiffSuppress'

`validation` #

Controls the value set for the field’s ValidateFunc.

For Enum fields, this will override the default validation (that the provided value is one of the enum values). If you need additional validation on top of an enum, ensure that the supplied validation func also verifies the enum values are correct.

This property has two mutually exclusive child properties:

function: The name of a validation function to use for validation. The function can be a Terraform-provided function (for example, validation.IntAtLeast(0)), a provider-specific function (for example, verify.ValidateBase64String), or a function defined in resource-specific custom code.
regex: A regex string to check values against. This can only be used on simple String fields. It is equivalent to function: verify.ValidateRegexp(REGEX_STRING).

validation is not supported for Array fields (including sets); however, individual elements in the array can be validated using item_validation.

Example: Provider-specific function

- name: 'fieldOne'
  type: String
  validation:
    function: 'verify.ValidateBase64String'

Example: Regex

- name: 'fieldOne'
  type: String
  validation:
    regex: '^[a-zA-Z][a-zA-Z0-9_]*$'

`api_name` #

Specifies a name to use for communication with the API that is different than the name of the field in Terraform. In general, setting an api_name is not recommended, because it makes it more difficult for users and maintainers to understand how the resource maps to the underlying API.

- name: 'fieldOne'
  type: String
  api_name: otherFieldName

`url_param_only` #

If true, the field is not sent in the resource body, and the provider does not read the field value from the API response. If unset or false, the field is sent in the resource body, and the provider reads the field value from the API response.

url_param_only: true

`Enum` properties #

`enum_values` #

Enum only. If the allowed values change frequently, use a String field instead to allow better forwards-compatibility, and link to API documentation stating the current allowed values in the String field’s description. Do not include UNSPECIFIED values in this list.

Enums will validate that the provided field is in the allowed list unless a custom validation is provided.

Example:

enum_values:
  - 'VALUE_ONE'
  - 'VALUE_TWO'

`Array` properties #

`item_type` #

Array only. Sets the expected type of the items in the array. Primitives should use the name of the primitive class as a string; other types should define the attributes of the nested type.

Example: Primitive value

item_type:
  type: String

Example: Enum value

item_type:
  type: Enum
  description: 'required but unused'
  values:
    - 'VALUE_ONE'
    - 'VALUE_TWO'

Example: Nested object

item_type:
  type: NestedObject
  properties:
    - name: 'FIELD_NAME'
      type: String
      description: |
        MULTI_LINE_FIELD_DESCRIPTION

`item_validation` #

Array only. Controls the ValidateFunc used to validate individual items in the array. Behaves like validation.

For arrays of enums, this will override the default validation (that the provided value is one of the enum values). If you need additional validation on top of an enum, ensure that the supplied validation func also verifies the enum values are correct.

Example: Provider-specific function

- name: 'fieldOne'
  type: Array
  item_type:
    type: String
  item_validation:
    function: 'verify.ValidateBase64String'

Example: Regex

- name: 'fieldOne'
  type: Array
  item_type:
    type: String
  item_validation:
    regex: '^[a-zA-Z][a-zA-Z0-9_]*$'

Example: Enum

- name: 'fieldOne'
  type: Array
  item_type:
    type: Enum
    description: 'required but unused'
    values:
      - 'VALUE_ONE'
      - 'VALUE_TWO'
  item_validation: 
    function: 'customFunction'

`NestedObject` properties #

`properties` #

NestedObject only. Defines fields nested inside the current field.

Example:

properties:
  - name: 'FIELD_NAME'
    type: String
    description: |
      MULTI_LINE_FIELD_DESCRIPTION

MMv1 field reference #

Shared properties #

min_version: beta #

immutable #

update_url #

update_verb #

required #

output #

sensitive #

ignore_read #

default_value #

default_from_api #

send_empty_value #

conflicts #

required_with #

exactly_one_of #

at_least_one_of #

diff_suppress_func #

validation #

api_name #

url_param_only #

Enum properties #

enum_values #

Array properties #

item_type #

item_validation #

NestedObject properties #

properties #

`min_version: beta` #

`immutable` #

`update_url` #

`update_verb` #

`required` #

`output` #

`sensitive` #

`ignore_read` #

`default_value` #

`default_from_api` #

`send_empty_value` #

`conflicts` #

`required_with` #

`exactly_one_of` #

`at_least_one_of` #

`diff_suppress_func` #

`validation` #

`api_name` #

`url_param_only` #

`Enum` properties #

`enum_values` #

`Array` properties #

`item_type` #

`item_validation` #

`NestedObject` properties #

`properties` #