Set defaults for observability buckets

This document describes how to configure an organization, folder, or project so that your observability buckets satisfy your compliance or regulatory requirements.

  • For organizations, folders, and projects, default settings for observability buckets let you configure the following:

    • A default storage location.
    • For each location, a default Cloud Key Management Service key.

    Descendants in the resource hierarchy automatically use these settings, except for those descendants where you've configured default settings.

    The default settings for observability buckets apply only to new resources, not to existing resources.

The default settings for observability buckets settings don't apply to log buckets, which store log data. To learn how to set the default location or require CMEK for log buckets, see Configure default resource settings for Cloud Logging.

View default settings for observability buckets

This section describes how you can view the default settings for observability buckets for a resource, which is an organization, folder, or project.

To retrieve the default settings for observability buckets, you must issue multiple API commands. The first command returns the default storage location. The second command returns the Cloud KMS key for that location. These instructions are for the APIs Explorer, which lets you issue API commands from a documentation page. However, you can also issue a curl command.

The commands described in this section are for a specific resource. The responses of these commands are limited to user-configured values for that resource. These commands don't return settings that the resource might use but that are configured for an ancestor.

Before you begin

To get the permission that you need to view the default settings for observability buckets for an organization, folder, or project, ask your administrator to grant you the Observability Viewer (roles/observability.viewer) IAM role on the organization, folder, or project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the observability.settings.get permission, which is required to view the default settings for observability buckets for an organization, folder, or project.

You might also be able to get this permission with custom roles or other predefined roles.

Get the default storage location for a resource

To get the default storage location for a resource, you send a command to a resource-specific endpoint, and set the location of that command to global. The response data includes the default storage location and the name of a service account. If you require CMEK for the resource, then this service account is used to retrieve Cloud KMS keys.

REST

  1. For the resource whose default settings you want to display, select the appropriate endpoint and then in the APIs Explorer, specify the path parameter:

    Organization:

    Folder:

    Project:

    The variables in the previous expressions have the following meaning:

    • ORGANIZATION_ID: The unique numeric identifier of the organization. For information about getting this identifier, see Getting your organization ID.
    • FOLDER_ID: The unique numeric identifier of the folder. For information about using folders, see Creating and managing folders.
    • PROJECT_ID: The identifier of the project.

  2. Click Execute.

    When successful, the response is a Settings object. If the default_storage_location field is empty, then a default storage location isn't set.

    For example, if you issue a getSettings command and set the path parameter to an organization, the response is similar to one of the following:

    • Default storage location set to "us":

      default_storage_location: "us"
service_account_id: service-org-ORGANIZATION_ID@gcp-sa-observability.iam.gserviceaccount.com

    • No default storage location set:

      service_account_id: service-org-ORGANIZATION_ID@gcp-sa-observability.iam.gserviceaccount.com

Get the default Cloud KMS key for a resource and location

Cloud KMS keys are regional resources. They can only be used to encrypt or decrypt data that is stored in the same location as the key. For each location supported by observability buckets, and for each organization, folder, or project, you can configure the default settings for observability buckets with a Cloud KMS key.

This section describes how to get the default Cloud KMS key for resource and location.

REST

  1. For the resource whose default settings you want to display, select the appropriate endpoint and then in the APIs Explorer, specify the path parameter:

    Organization:

    Folder:

    Project:

    The variables in the previous expressions have the following meaning:

    • ORGANIZATION_ID: The unique numeric identifier of the organization. For information about getting this identifier, see Getting your organization ID.
    • FOLDER_ID: The unique numeric identifier of the folder. For information about using folders, see Creating and managing folders.
    • PROJECT_ID: The identifier of the project.
    • LOCATION_ID: The location whose CMEK configuration you want to view.

  2. Click Execute.

    When successful, the response is a Settings object.

    For example, suppose that you issue the getSettings command and set the path parameter to organizations/ORGANIZATION_ID/locations/LOCATION_ID/settings, then the response is similar to one of the following:

    • When a Cloud KMS key isn't set for the organization and location, the response lists only a service account:

      service_account_id: service-org-ORGANIZATION_ID@gcp-sa-observability.iam.gserviceaccount.com

    • When the Cloud KMS key is set for the organization and location, the response includes a service account and the Cloud KMS key name:

      name: "organizations/ORGANIZATION_ID/locations/LOCATION_ID/settings"
service_account_id: service-org-ORGANIZATION_ID@gcp-sa-observability.iam.gserviceaccount.com
kms_key_name: "projects/my-kms-project/locations/LOCATION_ID/keyRings/my-key-ring/cryptoKeys/my-key"

Set the default settings for observability buckets

This section describes how you can configure default settings for observability buckets for a resource, which is an organization, folder, or project.

If you plan to require CMEK for a resource and location, then configure the default settings for observability buckets for that pair before you set the default storage location. When you configure default settings for a resource and location, you specify the Cloud KMS key to use.

These instructions are for the APIs Explorer, which lets you issue API commands from a documentation page. However, you can also issue a curl command.

Example configurations

This section lists common use cases.

Require new buckets to be in a specific location

To require that new system-created observability buckets in your organization be in the us location, set the default storage location for your organization to us.

To override the organization-level settings and to require that new system-created observability buckets in the child folder named my-eu-projects to be in the eu region, set the default storage location for the my-eu-projects folder to eu.

Require new buckets to be in a specific location and to use CMEK

To require that all new system-created observability buckets in your organization be in the us location and use CMEK, do the following:

  1. Configure the default settings for observability buckets for your organization and the us location to specify a Cloud KMS key.

  2. Set the default storage location for your organization to be us.

Before you begin

If you are only planning to set the default storage location, then you can skip the Google Cloud CLI setup and you don't need any Cloud KMS roles.

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To get the permissions that you need to set the default settings for observability buckets for an organization, folder, or project, ask your administrator to grant you the following IAM roles on the organization, folder, or project:

    For more information about granting roles, see Manage access to projects, folders, and organizations.

    These predefined roles contain the permissions required to set the default settings for observability buckets for an organization, folder, or project. To see the exact permissions that are required, expand the Required permissions section:

    Required permissions

    The following permissions are required to set the default settings for observability buckets for an organization, folder, or project:

    • observability.settings.get
    • observability.settings.update
    • cloudkms.cryptoKeys.getIamPolicy
    • cloudkms.cryptoKeys.setIamPolicy

    You might also be able to get these permissions with custom roles or other predefined roles.

  3. If you plan to require use of CMEK, then make sure that you have a Cloud KMS key in the required location. If necessary, create a Cloud KMS key ring and a Cloud KMS key.

  4. Determine the resource whose default settings for observability buckets you plan to update. This resource can be an organization, folder, or project.

    If you configure default settings for an organization or a folder, then they apply to all descendants of that organization or folder. If you configure default settings for observability buckets for a project, then they apply only to that project.

Grant resource's service account access to a key

For the resource whose default settings you plan to configure, grant its service account a role:

  1. Identify the Cloud KMS key that you want to use for encryption and decryption.

    Cloud KMS key are regional. For example, if you plan to require new system-created observability buckets to be in the us location, then you need a Cloud KMS key in the us location.

  2. Identify the service account for your resource.

    For example, if you want all new system-created observability buckets in your organization to be in the us location and to use CMEK, then issue a getSettings call to the global location and set the path parameter to an organization. The response data lists the organization's service account:

    service_account_id: service-org-ORGANIZATION_ID@gcp-sa-observability.iam.gserviceaccount.com

  3. Grant the service account you identified in the previous step the Cloud KMS CryptoKey Encrypter/Decrypter (roles.cloudkms.cryptoKeyEncrypterDecrypter role for the Cloud KMS key that you want to use to encrypt and decrypt data.

    This role binding is for a specific Cloud KMS key.

    gcloud CLI

    Run the gcloud kms keys add-iam-policy-binding command:

    gcloud kms keys add-iam-policy-binding KMS_KEY_NAME \
--project=KMS_PROJECT_ID \
--member=serviceAccount:SERVICE_ACCT_NAME@gcp-sa-observability.iam.gserviceaccount.com \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=LOCATION_ID \
--keyring=KMS_KEY_RING

    Before running the previous command, make the following replacements:

    • KMS_KEY_NAME: The name of the key.
    • KMS_PROJECT_ID: The unique alphanumeric identifier, composed of your Google Cloud project name and a randomly assigned number, of the Google Cloud project running Cloud KMS. For information about getting this identifier, see Identifying projects.
    • SERVICE_ACCT_NAME: The name of your resource's service account, which you identified in the previous step.
    • LOCATION_ID: The location of your Cloud KMS key.
    • KMS_KEY_RING: The Cloud KMS key ring's name.

    Google Cloud console

    1. In the Google Cloud console, go to the Key management page.

      Go to Key management

    2. Select the name of the key ring that contains the key.

    3. Select the checkbox for the key.

      The Permissions tab becomes available.

    4. In the Add members dialog, specify the email address of the Google Cloud Observability service account you are granting access.

    5. In the Select a role menu, select Cloud KMS CryptoKey Encrypter/Decrypter.

    6. Click Add.

Set the default Cloud KMS key for a resource and location

In the previous step, you granted a resource's service account the permissions to encrypt and decrypt data for a specific Cloud KMS key. For example, you might have granted an organization's service account an IAM role that lets it access a Cloud KMS key that is in the us location.

In this step, for that resource and for the location of the Cloud KMS key, you update the default settings for observability buckets with the key information. For example, in this step, you might configure the default settings for observability buckets for your organization and for the us location, to the Cloud KMS key that is also in the us location.

REST

  1. For the resource whose default settings you want to set, select the appropriate endpoint and then in the APIs Explorer, specify the path parameter:

    Organization:

    Folder:

    Project:

    The variables in the previous expressions have the following meaning:

    • ORGANIZATION_ID: The unique numeric identifier of the organization. For information about getting this identifier, see Getting your organization ID.
    • FOLDER_ID: The unique numeric identifier of the folder. For information about using folders, see Creating and managing folders.
    • PROJECT_ID: The identifier of the project.
    • LOCATION_ID: The location of your Cloud KMS key.

  2. Set the updateMask field as follows:

    updateMask=kmsKeyName

  3. Configure the Request body as follows:

    {
  "kmsKeyName"="projects/KMS_PROJECT_ID/locations/LOCATION_ID/keyRings/KMS_KEY_RING/cryptoKeys/KMS_KEY_NAME"
}

    Before entering the values, make the following replacements:

    • KMS_PROJECT_ID: The unique alphanumeric identifier, composed of your Google Cloud project name and a randomly assigned number, of the Google Cloud project running Cloud KMS. For information about getting this identifier, see Identifying projects.
    • LOCATION_ID: The location of your Cloud KMS key.
    • KMS_KEY_RING: The Cloud KMS key ring's name.
    • KMS_KEY_NAME: The name of the key.

    The value of the "kmsKeyName" is the fully-qualified name of your key.

  4. Click Execute.

    When successful, the response is a Settings object.

    For example, suppose that you issue the updateSettings command to set a Cloud KMS key and that you set the path parameter to organizations/ORGANIZATION_ID/locations/LOCATION_ID/settings, then response is similar to the following:

    name: "organizations/ORGANIZATION_ID/locations/LOCATION_ID/settings"
service_account_id: service-org-ORGANIZATION_ID@gcp-sa-observability.iam.gserviceaccount.com
kms_key_name: "projects/KMS_PROJECT_ID/locations/LOCATION_ID/keyRings/KMS_KEY_RING/cryptoKeys/KMS_KEY_NAME"

Set the default storage location for a resource

This step describes how to set a default storage location for a resource, which is an organization, folder, or project. All descendants in the resource hierarchy automatically use the default storage location, except for those descendants where you've configured a default storage location.

For example, if you set the default storage location for an organization to the us location, then new system-created observability buckets in that organization are in the us location. If you want a folder or project to have a different default storage location, then configure default settings for observability buckets for the folder or project.

If you want the system-created observability buckets in a resource to use CMEK, then you complete the following steps before you set the default storage location for the resource:

  1. Grant the resource's service account the IAM role that lets the service account encrypt and decrypt data. This role is for a specific Cloud KMS key, and that key is in a specific location.
  2. Configure the default settings for observability buckets for the resource and key location with the Cloud KMS key information.

REST

To set the default storage location for your organization, folder, or project, do the following:

  1. For the resource whose default settings you want to set, select the appropriate endpoint and then in the APIs Explorer, specify the path parameter:

    Organization:

    Folder:

    Project:

    The variables in the previous expressions have the following meaning:

    • ORGANIZATION_ID: The unique numeric identifier of the organization. For information about getting this identifier, see Getting your organization ID.
    • FOLDER_ID: The unique numeric identifier of the folder. For information about using folders, see Creating and managing folders.
    • PROJECT_ID: The identifier of the project.

  2. Set the updateMask field as follows:

    updateMask=defaultStorageLocation

  3. Configure the Request body as follows:

    {
  "defaultStorageLocation"="DEFAULT_STORAGE_LOCATION"
}

    Replace DEFAULT_STORAGE_LOCATION with a supported observability bucket location.

    For example, suppose you want all new system-created observability buckets in your organization to be in the us location and to use CMEK. In previous steps, you granted the organization's service account an IAM role that lets it encrypt and decrypt data by using a Cloud KMS key that is in the us location. You complete the configuration by setting DEFAULT_STORAGE_LOCATION to us.

  4. Click Execute.

    When successful, the response is a Settings object.

    For example, if you issue am updateSettings command and set the path parameter to an organization and set the default storage location to us, then the response is similar to the following:

    default_storage_location: "us"
service_account_id: service-org-ORGANIZATION_ID@gcp-sa-observability.iam.gserviceaccount.com

Update the default storage location for a resource

To update the default storage location for an organization, folder, or project, follow the same procedure as when you set the default storage location.

Manage your Cloud KMS keys

The following sections describe how to change, disable, or revoke access to a Cloud KMS key.

Update the default Cloud KMS key for a resource and location

To update the Cloud KMS key for a specific resource and location, follow the same procedure as when you set the Cloud KMS key.

Unset the default Cloud KMS key for a resource and location

To unset or clear the Cloud KMS key for a specific resource and location, follow the same procedure as described in Set the default Cloud KMS key for a location. However, when you configure the request body, set the value of the key to an empty string.

{
  "kmsKeyName"=""
}

If the resource doesn't have a default Cloud KMS key, then the system searches the ancestors of the resource for a default Cloud KMS key:

  • If a Cloud KMS key is found, then that key is used to encrypt the data stored in the new observability bucket.

  • If a Cloud KMS key isn't found, then the new observability bucket doesn't use CMEK.

Revoke key access for a resource and location

When you configure the default settings for observability buckets for a resource and location with a Cloud KMS key, you must grant the resource's service account the Cloud KMS CryptoKey Encrypter/Decrypter (roles.cloudkms.cryptoKeyEncrypterDecrypter role for the key.

If you don't want a resource to have access to a key, then remove the IAM binding for that key. You can remove this binding by running the gcloud kms keys remove-iam-policy-binding command.

It might take several hours for the role change to fully propagate.

Key-rotation behavior

Google Cloud Observability doesn't automatically rotate the encryption key for temporary disaster-recovery files when the Cloud KMS key associated with the Google Cloud organization or folder rotates. Existing recovery files continue to use the key version with which they were created. New recovery files use the current primary key version.

To learn more, see Key rotation.

Limitations

The following are known limitations when you configure your default settings for observability buckets to have a CMEK setting.

Degradation due to key unavailability

Google Cloud Observability uses the Cloud KMS API to access both Cloud KMS keys and Cloud EKM keys. Both types of keys might become unavailable.

If a key becomes unavailable, then the following occur:

  • You can't query stored data.
  • Google Cloud Observability buffers the most recent three hours of data. Data older than this sliding three-hour window might be discarded.
  • For permanent data storage, a Cloud KMS key must be available and accessible for at least 24 consecutive hours in the 48 hour period after data has been written. If the Cloud KMS key isn't available and accessible for this period, then data might not be fully persisted to storage and might be discarded.

What's next