> [!WARNING]
>
> **Preview**
>
>
> This feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the
> [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

Select a documentation version: <button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">18.1.0</button>

- [Current (18.4.0)](https://docs.cloud.google.com/alloydb/omni/kubernetes/current/docs/create-tde-cluster.md.txt)
- [18.4.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.4.0/docs/create-tde-cluster.md.txt)
- [18.3.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.3.0/docs/create-tde-cluster.md.txt)
- [18.1.0](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.1.0/docs/create-tde-cluster.md.txt)

<br />

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](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) to ensure that the Key Encryption Key (KEK) path and [JSON Web Token (JWT)](https://developer.hashicorp.com/vault/docs/auth/jwt#jwt-authentication) is 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 <var translate="no">DBCLUSTER_NAME</var> with the name of the `DBCluster` and <var translate="no">DBCLUSTER_NAMESPACE</var> 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.

```yaml
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:

```bash
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 `TdeConfig` resource.

```yaml
  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](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.1.0/docs/deploy-kubernetes.md.txt#create).

   ```yaml
   apiVersion: alloydbomni.dbadmin.goog/v1
   kind: DBCluster
   metadata:
     name: "DBCLUSTER_NAME"
   spec:
     databaseVersion: "18.1.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.

   ```bash
   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.

## View TDE metrics

After the cluster is initialized, complete the following steps to verify that
TDE is enabled and view related TDE metrics.

1. Connect to your database using `psql` or your preferred client. For detailed instructions on connecting to your instances, see [Run and connect to AlloyDB Omni](https://docs.cloud.google.com/alloydb/omni/kubernetes/18.1.0/docs/run-connect.md.txt).
2. Run the following command:

   ```sql
   select * FROM pgsnap.g$tde_stats;
   ```

   If TDE is enabled successfully, the output shows TDE metrics such as whether TDE is enabled, the KEK URL, KEK version, and KEK creation timestamp.

   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 |