Create a TDE-enabled cluster

Select a documentation version:

The AlloyDB Omni Kubernetes operator automates the lifecycle of Transparent Data Encryption (TDE) clusters using the TdeConfig custom resource. This resource stores Key Management Service (KMS) connection details, enabling the operator to securely inject required credentials into database pods.

Before you begin

  • Configure HashiCorp Vault's KV-V2 secrets engine to ensure that the Key Encryption Key (KEK) path and JSON Web Token (JWT) are available.
  • Ensure that AlloyDB Omni has permission to read the JWT token file.

  • Optional: To deploy a TDE-enabled cluster on OpenShift, grant the hostmount-anyuid Security Context Constraint (SCC) to the DBCluster service account running the database cluster.

    oc adm policy add-scc-to-user hostmount-anyuid -z DBCLUSTER_NAME-sa -n DBCLUSTER_NAMESPACE

    Replace DBCLUSTER_NAME with the name of the DBCluster and DBCLUSTER_NAMESPACE with the namespace where you want to create the DBCluster resource.

Configure vault access

Create a secret resource that contains your KEK path and authentication credentials.

apiVersion: v1
kind: ConfigMap
metadata:
  name: CONFIG_MAP_NAME
data:
  kek_url: "KEK_URL"
  token_path: "JWT_TOKEN_PATH"

Replace the following:

  • CONFIG_MAP_NAME: name of the config map. The values defined in kek_url and token_path are used in the TdeConfig resource definition.
  • KEK_URL: The fully qualified URL to the KEK in HashiCorp Vault. Use vault as the protocol to specify HashiCorp Vault as the KMS provider—for example, vault://vault.default.svc:8200/v1/secrets/data/alloydb_kek.
  • JWT_TOKEN_PATH: path to the JWT token on the node. For example, /tmp/token. The JWT token access path must be consistent across all nodes in the cluster.

Create a TLS secret

To create a TLS secret to store your certificates, run the following commands:

kubectl create secret tls VAULT_SECRET_NAME \
    --cert=vault.crt \
    --key=vault.key

kubectl patch secret VAULT_SECRET_NAME \
    -p '{"data":{"ca.crt":"'$(base64 -w 0 vault.crt)'"}}' \
    --type=merge

Replace VAULT_SECRET_NAME with a name for the TLS secret. You use this secret name when you create the TdeConfig custom resource.

Create the TdeConfig CRD

Create a TdeConfig resource that defines how AlloyDB Omni communicates with the vault to retrieve the KEK. The only supported authentication type is jwt. Make sure that you create the TdeConfig resource in the same namespace as the DbCluster resource.

Ensure that the path to your JWT token is accessible to the postgres user and that your vault instance is reachable over the network.

To create the TdeConfig resource, follow these steps:

Create and apply a manifest for the TdeConfig resource.

  apiVersion: alloydbomni.dbadmin.goog/v1
  kind: TdeConfig
  metadata:
    name: TDE_CONFIG_NAME
  spec:
    kekUrlRef:
      name: CONFIG_MAP_NAME
      key: kek_url
    kmsProvider:
      vault:
        authType: "jwt"
        authMount: "JWT_AUTH_MOUNT_PATH"
        jwt:
          pathRef:
            name: "CONFIG_MAP_NAME"
            key: "token_path"
          role: "VAULT_ROLE"
    tls:
      certSecret:
        name: "VAULT_SECRET_NAME"

Replace the following:

  • TDE_CONFIG_NAME: name of the TdeConfig resource.
  • JWT_AUTH_MOUNT_PATH: path where the authentication engine is mounted within HashiCorp Vault, as defined by your configuration. For example, auth/kms.
  • (Optional) VAULT_ROLE: the client role defined in your vault setup. The client role validates the JWT and reflects the specific access rights and identity the role is granted within HashiCorp Vault.
  • VAULT_SECRET_NAME: name of the secret that contains the certificates for the vault connection. For example, vault-secret.

Deploy the DBCluster

  1. Create and apply a manifest to create a DBCluster resource that references your TdeConfig resource. For more information about creating a database cluster, see Create a database cluster.

    apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: "DBCLUSTER_NAME"
spec:
  databaseVersion: "18.3.0"
  features:
    transparentDataEncryption:
      tdeConfigRef:
        name: "TDE_CONFIG_NAME"

[...]

    Replace TDE_CONFIG_NAME with the name of your TdeConfig resource and DBCLUSTER_NAME with the name of the DBCluster you want to create.

  2. Optional: If you're deploying DBCluster in an OpenShift environment, you need to annotate the DBCluster resource with the hostmount-anyuid annotation.

    kubectl annotate dbclusters.alloydbomni.dbadmin.goog `DBCLUSTER_NAME` -n `DBCLUSTER_NAMESPACE` openshift.io/scc=anyuid

    Replace DBCLUSTER_NAME with the name of your DBCluster resource and DBCLUSTER_NAMESPACE with the namespace where you want to create the DBCluster resource.

To enable TDE for columnar cache spilled to SSD, patch your DBCluster as follows:

kubectl patch dbcluster `DBCLUSTER_NAME` \
  -n `DBCLUSTER_NAMESPACE` \
  -p '{"spec":{"primarySpec":{"parameters": {"google_columnar_engine.enable_tde_for_storage_cache": "on"}}}}' \
  --type=merge

TDE metrics references

You can view all TDE metrics in AlloyDB Omni's monitoring agent. The following table explains what each metric means.

Name Description Label Unit Type
alloydb_omni_database_tde_data_blocks_decrypted_count_total Number of data blocks decrypted. Not applicable counter
alloydb_omni_database_tde_data_blocks_encrypted_count_total Number of data blocks encrypted. Not applicable counter
alloydb_omni_database_tde_data_decryption_time_us_total Total time spent in data block decryption. Not applicable microseconds counter
alloydb_omni_database_tde_data_encryption_time_us_total Total time spent in data block encryption. Not applicable microseconds counter
alloydb_omni_database_tde_enabled TDE enabled status. Not applicable gauge
alloydb_omni_database_tde_kek_info TDE KEK information.
  • kek_version: Version of the KEK
    in use for key wrapping.
  • kek_url: Fully qualified path
    to KEK in KMS
  • kek_creation_timestamp:
    Creation time of the KEK version in use.
 gauge
alloydb_omni_database_tde_temp_blocks_decrypted_count_total Number of temporary blocks decrypted. Not applicable counter
alloydb_omni_database_tde_temp_blocks_encrypted_count_total Number of temporary blocks encrypted. Not applicable counter
alloydb_omni_database_tde_temp_decryption_time_us_total Total time spent in temporary block decryption. Not applicable microseconds counter
alloydb_omni_database_tde_temp_encryption_time_us_total Total time spent in temporary block encryption. Not applicable microseconds counter
alloydb_omni_database_tde_wal_blocks_decrypted_count_total Number of WAL blocks decrypted. Not applicable counter
alloydb_omni_database_tde_wal_blocks_encrypted_count_total Number of WAL blocks encrypted. Not applicable counter
alloydb_omni_database_tde_wal_decryption_time_us_total Total time spent in WAL block decryption. Not applicable microseconds counter
alloydb_omni_database_tde_wal_encryption_time_us_total Total time spent in WAL block encryption. Not applicable microseconds counter
tde_chill_cache_blocks_encrypted Number of chill cache blocks encrypted. Not applicable counter
tde_chill_cache_blocks_decrypted Number of chill cache blocks decrypted. Not applicable counter
tde_chill_cache_blocks_total_encryption_time_us Total time spent in chill cache block encryption. Not applicable microseconds counter
tde_chill_cache_blocks_total_decryption_time_us Total time spent in chill cache block decryption. Not applicable microseconds counter
tde_ce_cache_ssd_blocks_encrypted Number of columnar cache blocks spilled to SSD storage that were encrypted. Not applicable counter
tde_ce_cache_ssd_blocks_decrypted Number of columnar cache blocks spilled to SSD storage that were decrypted. Not applicable counter
tde_ce_cache_ssd_blocks_total_encryption_time_us Total time spent encrypting columnar cache blocks spilled to SSD storage. Not applicable microseconds counter
tde_ce_cache_ssd_blocks_total_decryption_time_us Total time spent decrypting columnar cache blocks spilled to SSD storage. Not applicable microseconds counter