Create storage buckets

This page guides you through how to create a storage bucket for your Google Distributed Cloud (GDC) air-gapped projects. It covers prerequisites, creation and verification steps, and naming guidelines. This helps you establish compliant and well-configured object storage that meets the needs of your isolated deployments.

This page is for audiences such as IT admins within the infrastructure operator group or developers within the application operator group who are looking to provision and manage object storage buckets for projects within GDC air-gapped environments. For more information, see Audiences for GDC air-gapped documentation.

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.

You must also have the appropriate bucket permissions to perform the following operation. See Grant bucket access.

Storage bucket naming guidelines

Bucket names must adhere to the following naming conventions:

  • Be unique within the project. A project appends a unique prefix to the bucket 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

Console

  1. In the navigation menu, click Object Storage.
  2. Click Create Bucket.
  3. In the bucket creation flow, assign a name unique across all buckets within the project.
  4. Enter a description.
  5. 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.
  6. 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.

CLI

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

kubectl apply -f bucket.yaml

The following is an example of a bucket specification:

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 with encryption version as v1:

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.

The following is an example of a dual-zone bucket in org-admin global API:

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

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.

gdcloud

To create a bucket with gdcloud, follow gdcloud storage buckets create.

Once the bucket is created, you can run the following command to confirm and check the details of the bucket:

kubectl describe buckets BUCKET_NAME -n NAMESPACE_NAME

The Status section has two important fields: Encryption (for encryption details) and Fully Qualified Name (which contains the FULLY_QUALIFIED_BUCKET_NAME).

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:

Status:
  Encryption:
    Key Ref:
      Kind: AEADKey
      Name: obj-FULLY_QUALIFIED_BUCKET_NAME
      Namespace: NAMESPACE_NAME
    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.

Here is an example:

Status:
  Encryption:
    Key Ref:
      Kind: Secret
      Name: kek-ref-FULLY_QUALIFIED_BUCKET_NAME
      Namespace: NAMESPACE_NAME
    Type: CMEK

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

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

After creating a bucket, you can manage it on behalf of Application Operators (AOs) by creating a policy file when granting bucket access and assign the policy to a bucket.