Resource Settings overview

You can use Resource Settings to centrally configure settings for your Google Cloud projects, folders, and organization. These settings are inherited by their descendants in the resource hierarchy. Each setting is created and managed by Google.

Resource Settings

Resource Settings represent a dimension of a Google Cloud resource or service that you can configure. For example, a Cloud Storage bucket creation location setting could determine the default location at which new bucket resources is created.

Each resource setting has the following key properties:

  • Name: a globally unique identifier for the setting that is used when configuring values for a setting.

  • Metadata: the Google-managed information about the resource setting. Metadata for a resource setting includes the following fields:

    • Data type: the type of values that can be configured for this setting. The possible data types include booleans, strings, sets of strings, and enums.

    • Default value: the Google-managed default value of the setting if no other value is set within your organization.

    • Read only: a flag that indicates whether Google has made this setting read only. If a resource setting is read only, values for this setting can't be modified. A setting is only made read only for migrations and deprecations. Google provides a warning before making a change to this flag.

  • Local value: the specific value of a setting associated with a resource.

  • Effective value: the value of a setting after evaluating inherited resource settings from the resource hierarchy.

You need the Resource Settings Viewer or Resource Settings Administrator Identity and Access Management role to see the list of settings available for use on a given organization, folder, or project. For more details about these roles, see Required permissions.

Resource setting availability can differ between organizations, depending on the release status of the resource setting.

Example resource setting

The following is an example of how a resource setting appears:

# Setting
{
  "name": "net-preferredDnsServers",
  "metadata": {
    "displayName": "Preferred DNS Servers",
    "description": "The DNS servers to be used by VMs associated with this resource.",
    "read_only": false,
    "data_type" : "STRING_SET",
    "default_value" : {
      "string_set_value" : {
        "values" : [ "8.8.8.8" ],
      }
    }
  }
}

Naming

A resource setting has a globally unique short name, in the format settings/SETTING_ID. For example, the short name of a resource setting to control the initial startup image for a virtual machine might be settings/compute-vmStartupImage.

The relative resource name of a setting adds the numeric resource ID to the setting short name. For example, the relative resource name of the above settings/compute-vmStartupImage setting for organizations/12345678901 is organizations/12345678901/settings/compute-vmStartupImage.

Settings that have the same short name are considered identical by Google Cloud, even if they have different relative resource names. The resource included in a relative resource name only denotes availability of that setting to the named resource.

Local setting values

The setting value that is directly applied to a particular resource setting is called the local setting value. You can directly modify the local value of a resource setting using the Resource Settings API.

The following is an example resource setting that includes a local setting value:

# Setting
{
  "name" : "folders/123/settings/net-preferredDnsServers"
  "localValue": {
    "stringSetValue": {
      "values": ["8.8.8.8", "8.8.4.4"]
    }
  }
}

Effective setting values

The local setting value for a resource is inherited by all of that resource's descendants in the resource hierarchy. If one of these descendants has a local setting value, that overrides the inherited setting value. If you have not set a local setting value on a resource or any of its descendants, then the Google-defined default for that setting is used.

Resource settings are evaluated, and the result is the effective setting value. This value shows the result the final result of all inheritance and local value settings on a given resource. The rules for determining the effective setting value are evaluated as follows:

  1. If a resource has a value for a given resource setting, then that is the effective value, overriding any inherited value.

  2. If the resource does not have a value for this resource setting, if any of the resource's ancestors has a value for that setting, then the value associated with the nearest ancestor is the effective value.

  3. If neither this resource nor its ancestors have a value for this resource setting, and the setting has a Google-managed default, then that is the effective value.

  4. If neither the resource nor its ancestors have a value for this resource setting, and the value does not have a Google-managed default, then there is no effective value for this setting on this resource.

Resource settings with no effective value

If a resource setting does not have a Google-managed default, then it is possible to have a resource that does not have an effective value for that setting. New resource settings don't have Google-managed defaults if it is possible to do so in a backwards-compatible manner. New settings therefore don't interrupt existing services.

Empty values and unset values

A resource setting value is considered empty if it has a resource setting value that is empty. For example, "" is an empty string. Empty values are still considered values according to the evaluation of effective setting values, and override inheritance.

If no local value is set, the resource setting remains unset; this resource inherits the resource setting value.

What's next