Manage Encryption Resources

This page shows you how to manage encrypted Google Distributed Cloud (GDC) air-gapped storage buckets.

Before you begin

A project namespace manages bucket resources in the management API server. You must have a project to work with buckets and objects.

Required IAM roles

Contact your IAM Project Admin to request the following roles in your project namespace:

  • Project Bucket Admin (project-bucket-admin): create, update, and delete storage buckets.
  • Project Bucket Object Viewer (project-bucket-object-viewer): view and check details of storage buckets and objects.

For more information, see Grant bucket access.

Prepare your environment

To run commands against the management API server or the global API server, do the following:

  1. Sign in and generate the kubeconfig file for the zonal management API server if you don't have one.
  2. For dual-zone buckets, do the following:
    • Verify with your Infrastructure Operator (IO) that the BucketLocationConfig custom resource has been created for your paired zones.
    • Generate the kubeconfig file for the global API server.

Manage encryption resources

Buckets with v2 encryption would have a secret kekRef and several AEADKeys created, in which kekRef is used to reference active default AEADKeys being used and AEADKeys include active and archive ones belong to the bucket.

Refresh active default AEADKeys for a bucket

As a best practice, refresh your bucket's default AEADKeys after approximately 42 billion object writes. This proactive step enhances security and prevents key exhaustion. The refresh process will create a new kekRef and deactivates the previous AEADKeys. To start the refresh process, delete the kekRef secret associated with the bucket.

The previous kekRef can be retrieved by running the following command to retrieve:

kubectl get secrets -n NAMESPACE_NAME -l  object.gdc.goog/bucket-name=BUCKET_NAME

Then you can run the following to delete the existing kekRef:

kubectl delete secrets OLD_KEKREF_NAME -n  NAMESPACE_NAME

After the successful deletion, you can run the following to confirm a new kekRef has been created based on AGE:

kubectl get secrets -n NAMESPACE_NAME -l  object.gdc.goog/bucket-name=BUCKET_NAME

Verify new default AEADKeys have been created based on AGE:

kubectl get aeadkeys -n NAMESPACE_NAME -l  cmek.security.gdc.goog/resource-name=BUCKET_NAME

Rotate default AEADKeys for a bucket

If an AEADKey for your bucket becomes compromised, you must manually rotate the key encryption keys associated with the bucket.

To start the process, you must first refresh the active default keys. This creates new active default AEADKeys, and marks the previous key encryption keys as deactivated. After the default keys refresh, the subsequent object uploads use the new AEADKeys as the key encryption keys. The previous AEADKeys are not destroyed, so you can still decrypt existing objects that were previously encrypted using those keys.

Next, follow the steps to download and re-upload the objects in your bucket and delete the old objects.

After you re-upload all the objects in your bucket, you can clean up the inactive AEADKeys and old objects. Identify the deactivated AEADKeys based on AGE:

kubectl get aeadkeys -n NAMESPACE_NAME -l  cmek.security.gdc.goog/resource-name=BUCKET_NAME

Lastly, follow the steps to delete the AEADKeys.