Create storage buckets for projects

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

Before you begin

A project namespace manages bucket resources in the org admin cluster. 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 57 characters.
• Start with a letter and use only letters, numbers, and hyphens.

Create a bucket

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.

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.

Verify bucket and related resource creation

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 bucketFullyQualifiedName).

Encryption v1

The information is about the AEADKey named as obj-bucketFullyQualifiedName, 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-bucketFullyQualifiedName
      Namespace: NAMESPACE_NAME
    Type: CMEK

Encryption v2

The information pertains to the Secret named as kek-ref-bucketFullyQualifiedName, 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: 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:

Status:
  Encryption:
    Key Ref:
      Kind: Secret
      Name: kek-ref-bucketFullyQualifiedName
      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=BUCKET_NAME