This page guides you through how to set retention periods for storage buckets within Google Distributed Cloud (GDC) air-gapped environments. It covers the prerequisites and the steps for defining the length of time that data must be retained within a storage bucket using both the GDC console and command line interface (CLI). This information helps you meet your regulatory and data management requirements.

This page is for audiences such as IT administrators within the infrastructure operator group or developers within the application operator group who are responsible for configuring and managing storage bucket settings in GDC air-gapped environments. For more information, see [Audiences for GDC air-gapped documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Before you begin

Storage buckets are resources scoped to a specific [project](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/project-management.md.txt). The project acts as a container, grouping your buckets and enabling their management through the Management API server. Before you can perform the operations on this page, you must either create a new project or select an existing one where you have sufficient permissions.

### Required IAM roles

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

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

For more information, see [Grant bucket access](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/grant-obtain-storage-access.md.txt#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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/iam/sign-in.md.txt#zonal-resources-kubeconfig) 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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/iam/sign-in.md.txt#global-resources-kubeconfig) for the global API server.

## Set a bucket retention period

### Console

1. In the navigation menu, click **Object Storage**.
2. Click the name of the bucket that you want to update.
3. Click the **Configuration** tab.
4. In the Security section, next to the **Retention policy** field, click **Edit**.
5. Edit the number of days with a value higher than the existing number of days and click **Save**.

### API

By default, you can delete objects at any time. You can enable object locking
with a retention period to prevent all objects in the bucket from deletion for
the specified number of days. You cannot delete a bucket until you
delete all objects after the retention period.

You must enable object locking when creating the bucket. You cannot enable or
disable object locking after you create a bucket. However, you can modify the
default object retention period.

You can create a bucket with or without enabling object locking. If you've
enabled object locking, specifying a default retention period is optional.

To modify the retention period, update the
`Bucket.spec.bucketPolicy.lockingPolicy.defaultObjectRetentionDays` field in the
[Bucket resource](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/storage-krm-api).

The following is an example of updating the field in the Bucket resource:

```yaml
apiVersion: object.gdc.goog/v1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
spec:
  description: "This bucket has a default retention period specified."
  storageClass: Standard
  bucketPolicy:
    lockingPolicy:
      defaultObjectRetentionDays: RETENTION_DAY_COUNT
---
apiVersion: object.gdc.goog/v1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
spec:
  description: "This would enable object locking but not specify a default retention period."
  storageClass: Standard
  bucketPolicy:
    lockingPolicy:
---
apiVersion: object.gdc.goog/v1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
spec:
  description: "This bucket does not have locking or retention enabled."
  storageClass: Standard
```

Any updates to the retention period apply to objects created in the bucket after
the update. For pre-existing objects, the retention period does not change.

When you've enabled object locking, if you attempt to overwrite an object, you add a new
version of the object. You can retrieve both object versions. To retrieve object versions, see [List storage objects](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/list-storage-objects.md.txt).

To create a write-once, read-many (WORM) bucket, refer to the
[WORM Bucket](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/create-storage-worm-buckets.md.txt) section.