MMv1 field reference #

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

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<%= prefix -%><%= titlelize_property(property) -%>(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.

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:

- !ruby/object:Api::Type::String
  name: 'fieldOne'
  conflicts:
    - 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:

- !ruby/object:Api::Type::String
  name: 'fieldOne'
  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:

- !ruby/object:Api::Type::String
  name: 'fieldOne'
  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 a permadiff 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:

- !ruby/object:Api::Type::String
  name: 'fieldOne'
  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

- !ruby/object:Api::Type::String
  name: 'fieldOne'
  validation: !ruby/object:Provider::Terraform::Validation
    function: 'verify.ValidateBase64String'

Example: Regex

- !ruby/object:Api::Type::String
  name: 'fieldOne'
  validation: !ruby/object:Provider::Terraform::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.

- !ruby/object:Api::Type::String
  name: 'fieldOne'
  api_name: 'otherFieldName'

`Enum` properties #

`values` #

Enum only. Sets allowed values as ruby “literal constants” (prefixed with a colon). 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:

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: Api::Type::String

Example: Enum value

item_type: !ruby/object:Api::Type::Enum
  name: 'required but unused'
  description: 'required but unused'
  values:
    - :VALUE_ONE
    - :VALUE_TWO

Example: Nested object

item_type: !ruby/object:Api::Type::NestedObject
  properties:
    - !ruby/object:Api::Type::String
      name: 'FIELD_NAME'
      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

- !ruby/object:Api::Type::Array
  name: 'fieldOne'
  item_type: Api::Type::String
  item_validation: !ruby/object:Provider::Terraform::Validation
    function: 'verify.ValidateBase64String'

Example: Regex

- !ruby/object:Api::Type::Array
  name: 'fieldOne'
  item_type: Api::Type::String
  item_validation: !ruby/object:Provider::Terraform::Validation
    regex: '^[a-zA-Z][a-zA-Z0-9_]*$'

Example: Enum

- !ruby/object:Api::Type::Array
  name: 'fieldOne'
  item_type: !ruby/object:Api::Type::Enum
    name: 'required but unused'
    description: 'required but unused'
    values:
      - :VALUE_ONE
      - :VALUE_TWO
  item_validation: 'customFunction'

`NestedObject` properties #

`properties` #

NestedObject only. Defines fields nested inside the current field.

Example:

properties:
  - !ruby/object:Api::Type::String
    name: 'FIELD_NAME'
    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 #

exactly_one_of #

at_least_one_of #

diff_suppress_func #

validation #

api_name #

Enum properties #

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` #

`exactly_one_of` #

`at_least_one_of` #

`diff_suppress_func` #

`validation` #

`api_name` #

`Enum` properties #

`values` #

`Array` properties #

`item_type` #

`item_validation` #

`NestedObject` properties #

`properties` #