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

## 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/application/ao-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/application/ao-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/application/ao-user/iam/sign-in.md.txt#global-resources-kubeconfig) for the global API server.

## Storage bucket naming guidelines

Bucket names must adhere to the following naming conventions:

- Be unique within the project. The management API server prepends a unique prefix to the bucket's fully qualified name, ensuring there aren't clashes within the organization. In the unlikely event of a prefix and bucket name clash across organizations, the bucket creation fails with a "bucket name in use" error.
- Refrain from including any personally identifiable information (PII).
- Be DNS-compliant.
- Have at least 1 and no more than 55 characters.
- Start with a letter and use only letters, numbers, and hyphens.

## Create a bucket

> [!NOTE]
> **Note:** The bucket that is created will be automatically encrypted with either version `v1` or `v2`. `v2` will be the default if the `encryption-version` label is not specified since `v2` bucket is strongly recommended as it has better encryption and security. `v1` is only recommended if you need higher performance for many small objects.

By default, buckets use the `Standard` storage class. If Nearline storage has been enabled by your Infrastructure Operator (IO), you can also select the `Nearline` storage class for data that is accessed less frequently. Nearline storage is supported for both single-zone and dual-zone buckets.

### Console

1. In the navigation menu, click **Object Storage**.
2. In the project selector, select the project where you want to create the bucket.
3. Click **Create Bucket**.
4. In the bucket creation flow, assign a name unique across all buckets within the project.
5. Enter a description.
6. Under **Storage class** , select **Standard** or **Nearline** . The **Nearline** option is visible only if Nearline storage is enabled.
7. Optional: Click the toggle_off toggle to set a retention policy and enter your preferred number of days. Contact your IO if you need to exceed retention policy limits.
8. Click **Create** . A success message appears and you are directed back to the **Buckets** page.

To verify that you have successfully created a new bucket, refresh the **Buckets** page after a few minutes and check that the bucket state updates from `Not ready` to `Ready`.

### gdcloud

To create a single-zone bucket with `gdcloud` using the `Nearline` storage class:

```bash
gdcloud storage buckets create BUCKET_NAME \
    --location=ZONE_NAME \
    --location-type=SingleZone \
    --storage-class=Nearline
```

To create a dual-zone bucket with `gdcloud` using the global location:

```bash
gdcloud storage buckets create BUCKET_NAME \
    --location=ZONE_1,ZONE_2 \
    --location-type=AsyncDualZone \
    --storage-class=Nearline
```

If `--storage-class` is omitted, `Standard` is used by default.

For more details, see [gdcloud storage buckets create](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-reference/gdcloud-storage-buckets-create.md.txt).

### API

To create a zonal bucket, apply a bucket specification to your project namespace:

```bash
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG apply -f bucket.yaml
```

The following is an example of a bucket specification using the `Standard` storage class:

```yaml
apiVersion: object.gdc.goog/v1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
spec:
  description: DESCRIPTION
  storageClass: Standard
  bucketPolicy:
    lockingPolicy:
      defaultObjectRetentionDays: RETENTION_DAY_COUNT
```

The following is an example of a bucket specification using the `Nearline` storage class:

```yaml
apiVersion: object.gdc.goog/v1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
spec:
  description: DESCRIPTION
  storageClass: Nearline
  bucketPolicy:
    lockingPolicy:
      defaultObjectRetentionDays: RETENTION_DAY_COUNT
```

The following is an example of a bucket specification with encryption version as `v1`:

```yaml
apiVersion: object.gdc.goog/v1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: NAMESPACE_NAME
  labels:
    object.gdc.goog/encryption-version: v1
spec:
  description: DESCRIPTION
  storageClass: Standard
  bucketPolicy:
    lockingPolicy:
      defaultObjectRetentionDays: RETENTION_DAY_COUNT
```

For more details, see the [Bucket API reference](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/service/storage/storage-api-overview.md.txt).

The following is an example of a dual-zone bucket specification for the global API server:

```yaml
apiVersion: object.global.gdc.goog/v1
kind: Bucket
metadata:
  name: BUCKET_NAME
  namespace: PROJECT_NAME
spec:
  location: LOCATION_NAME
  description: Sample DZ Bucket
  storageClass: Standard
```

To create a dual-zone bucket using Nearline storage, set `storageClass: Nearline`.

Note that only V2 encryption is supported for dual-zone buckets and all operations for creating, updating, or deleting a dual-zone bucket resource must be performed against the global API server.

To create a dual-zone bucket, apply the specification against the global API server:

```bash
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f bucket.yaml
```

## Verify bucket and related resource creation

After creating the bucket, run the following command to confirm and check the
details of the bucket:

```bash
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG describe buckets BUCKET_NAME -n PROJECT_NAMESPACE
```

The **Status** section has two important fields: **Encryption** (for encryption details) and **Fully Qualified Name** (which contains the <var translate="no">FULLY_QUALIFIED_BUCKET_NAME</var>).

### Encryption v1

The information is about the AEADKey named as `obj-FULLY_QUALIFIED_BUCKET_NAME`, which serves as a reference to the encryption key employed for encrypting objects stored within the bucket. Here is an example:

```yaml
Status:
  Encryption:
    Key Ref:
      Kind: AEADKey
      Name: obj-FULLY_QUALIFIED_BUCKET_NAME
      Namespace: PROJECT_NAMESPACE
    Type: CMEK
```

### Encryption v2

The information pertains to the Secret named as `kek-ref-FULLY_QUALIFIED_BUCKET_NAME`, which acts as a reference for active default AEADKeys. Active default AEADKeys are randomly selected from to encrypt objects uploaded to the bucket when specific AEADKey is not specified.

> [!NOTE]
> **Note:** Inactive default AEADKeys are those that are no longer referenced in the Secret. See the Manage Encryption Resources section for more info.

Here is an example:

```yaml
Status:
  Encryption:
    Key Ref:
      Kind: Secret
      Name: kek-ref-FULLY_QUALIFIED_BUCKET_NAME
      Namespace: PROJECT_NAMESPACE
    Type: CMEK
```

You can also run the following command to verify needed AEADKeys are created:

```bash
kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG get aeadkeys -n PROJECT_NAMESPACE -l  cmek.security.gdc.goog/resource-name=FULLY_QUALIFIED_BUCKET_NAME
```