Google Cloud Storage Bucket Architect

gcloud Command Generation Guide

[!IMPORTANT]

DO NOT EXECUTE THESE COMMANDS AUTOMATICALLY. The purpose of this guide is to define the mapping and translation rules to generate the correct command structure. These generated commands must be presented to the user for confirmation and are only executed in a subsequent phase if explicit confirmation is granted by the user.

This guide describes how to translate a Draft Bucket Creation Plan (from Phase 2) into the corresponding gcloud storage commands.

Official Documentation References

• gcloud storage buckets create

• gcloud storage buckets update

• gcloud storage buckets add-iam-policy-binding

• gcloud storage objects update

• gcloud storage cp

• gcloud storage buckets notifications create

• gcloud storage buckets anywhere-caches create

• Create zonal buckets

• Domain-named bucket verification

• Host a static website

[!CAUTION]

DO NOT HALLUCINATE GCLOUD FLAGS. The gcloud storage CLI syntax and flags evolve. The agent MUST strictly ground all flags, settings, and argument formats in the provided reference and anything unclear should come from the --help flag. If it is still unclear, reference the official Google Cloud SDK documentation (linked above) before presenting them in the commands. Do not assume a flag exists or guess its name (e.g. do not guess --enable-versioning if it is --versioning). If unsure about a flag or its compatibility with other settings, the agent must perform a search or verify with official documentation first.

Translation Mapping Table

Use this mapping table to translate draft configurations into gcloud flags or secondary commands. Where possible, prefer adding configurations directly in a single gcloud storage buckets create command rather than splitting them into multiple update commands. For settings that must be applied via update (such as labels, versioning, CORS, website configuration, or usage logging), prefer combining them into a single gcloud storage buckets update command (sticking to create or create + one update where possible) rather than a long chain of separate update commands.

Helper Configuration Templates

When the plan requires complex configurations (CORS, Lifecycles, Encryption Enforcement, IP Filters), you must write them to temporary JSON files in the workspace before running gcloud.

1. Encryption Enforcement (encryption_enforcement.json)

Used to restrict CSEK:

{
  "gmekEnforcement": {"restrictionMode": "NotRestricted"},
  "cmekEnforcement": {"restrictionMode": "NotRestricted"},
  "csekEnforcement": {"restrictionMode": "FullyRestricted"}
}

You must allow at least one encryption type. If you omit the enforcement configuration for a specific encryption type, then that encryption type is allowed by default on create.

2. CORS Template (cors.json)

Configure allowed domains and methods:

[
  {
    "origin": ["https://my-website.appspot.com"],
    "method": ["GET", "POST", "PUT"],
    "responseHeader": ["Content-Type", "x-goog-resumable"],
    "maxAgeSeconds": 3600
  }
]

3. Lifecycle OLM Template (lifecycle.json)

Configure object deletion or transitions. e.g. aborting incomplete uploads and deleting files after 365 days:

{
  "rule": [
    {
      "action": {"type": "AbortIncompleteMultipartUpload"},
      "condition": {"age": 7}
    },
    {
      "action": {"type": "Delete"},
      "condition": {"age": 365}
    }
  ]
}

[!WARNING] Autoclass Restrictions: If Autoclass is enabled on the bucket, the Object Lifecycle Management (OLM) configuration MUST NOT contain rules that use the SetStorageClass action or the matchesStorageClass condition. Combining Autoclass with these rules will cause the bucket creation or update to fail.

4. IP Filtering Template (ip_filter.json)

Configure allowed IP ranges and VPC networks:

{
  "mode": "Enabled",
  "allowAllServiceAgentAccess": true,
  "allowCrossOrgVpcs": false,
  "publicNetworkSource": {
    "allowedIpCidrRanges": ["192.0.2.0/24", "198.51.100.0/32"]
  },
  "vpcNetworkSources": [
    {
      "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
      "allowedIpCidrRanges": ["10.0.0.0/16"]
    }
  ]
}

Conversion Examples

Example 1: Standard Secure Bucket (Baseline)

Input Draft Plan

*   **Bucket Name**: `my-company-secure-bucket`
*   **Project**: `my-security-project`
*   **Location**: `us-east1`
*   **Storage Class**: `STANDARD`
*   **UBLA**: Enabled
*   **Public Access Prevention (PAP)**: Enforced
*   **Soft Delete**: Enabled (7 days)
*   **Encryption Enforcement**: CSEK Restricted

Output Commands

Create encryption_enforcement.json with CSEK restricted:

{
  "gmekEnforcement": {"restrictionMode": "NotRestricted"},
  "cmekEnforcement": {"restrictionMode": "NotRestricted"},
  "csekEnforcement": {"restrictionMode": "FullyRestricted"}
}

gcloud Command:

CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
gcloud storage buckets create gs://my-company-secure-bucket \
    --project=my-security-project \
    --location=us-east1 \
    --default-storage-class=STANDARD \
    --uniform-bucket-level-access \
    --public-access-prevention \
    --soft-delete-duration=7d \
    --encryption-enforcement-file=encryption_enforcement.json

Example 2: Sensitive Data / Compliance

Input Draft Plan

*   **Bucket Name**: `my-compliance-pii-bucket`
*   **Project**: `my-compliance-project`
*   **Location**: `us-central1`
*   **Storage Class**: `STANDARD` (Autoclass will handle transitions)
*   **UBLA**: Enabled
*   **Public Access Prevention (PAP)**: Enforced
*   **Encryption Enforcement**: Restrict CSEK
*   **Encryption**: Customer-Managed Key (CMEK)
*   **Soft Delete**: Enabled (7 days)
*   **Bucket Lock (Retention Policy)**: Enabled (90 days, Unlocked)
*   **Use-case specific settings**:
    *   Autoclass: Enabled
    *   CMEK Key ID: `projects/my-kms-project/locations/us-central1/keyRings/my-keyring/cryptoKeys/my-key`
    *   Labels: `data-class=pii`, `owner=security-team`
    *   Lifecycle: Abort incomplete multipart uploads after 7 days
    *   IP Filtering: Restrict access to `192.0.2.0/24` (Corporate Range)

Output Commands

1. Create encryption_enforcement.json (CSEK restricted):

   Copy

   {
     "gmekEnforcement": {"restrictionMode": "NotRestricted"},
     "cmekEnforcement": {"restrictionMode": "NotRestricted"},
     "csekEnforcement": {"restrictionMode": "FullyRestricted"}
   }

2. Create lifecycle_abort.json:

   Copy

   {
     "rule": [
       {
         "action": {"type": "AbortIncompleteMultipartUpload"},
         "condition": {"age": 7}
       }
     ]
   }

3. Create ip_filter.json (allowing corporate IP range):

   Copy

   {
     "mode": "Enabled",
     "allowAllServiceAgentAccess": true,
     "publicNetworkSource": {
       "allowedIpCidrRanges": ["192.0.2.0/24"]
     },
   }

4. Run:

   Copy

   # 1. Create the bucket
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage buckets create gs://my-compliance-pii-bucket \
       --project=my-compliance-project \
       --location=us-central1 \
       --uniform-bucket-level-access \
       --public-access-prevention \
       --soft-delete-duration=7d \
       --retention-period=90d \
       --encryption-enforcement-file=encryption_enforcement.json \
       --enable-autoclass \
       --default-encryption-key=projects/my-kms-project/locations/us-central1/keyRings/my-keyring/cryptoKeys/my-key \
       --lifecycle-file=lifecycle_abort.json \
       --ip-filter-file=ip_filter.json
   
   # 2. Add labels (cannot be set during create)
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage buckets update gs://my-compliance-pii-bucket \
       --project=my-compliance-project \
       --update-labels=data-class=pii,owner=security-team

   Note: The retention policy is created unlocked. To lock it (making it permanent and irreversible), run:

   Copy

   # WARNING: Locking is irreversible. Neither an administrator nor Cloud
   # Support can reduce or remove the retention period on a locked bucket.
   # CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   # gcloud storage buckets update gs://my-compliance-pii-bucket --lock-retention-period

Example 3: Static Website Hosting

Input Draft Plan

*   **Bucket Name**: `www.my-company-site.com`
*   **Project**: `my-frontend-project`
*   **Location**: `US`
*   **Storage Class**: `STANDARD`
*   **UBLA**: Enabled
*   **Public Access Prevention (PAP)**: Inherited (Disabled to allow public website access)
*   **Soft Delete**: Enabled (7 days)
*   **Use-case specific settings**:
    *   Website Config: Main page `index.html`, Error page `404.html`
    *   Public Access: Required (allUsers -> storage.objectViewer)
    *   CORS: Allowed GET/HEAD from any domain

Output Commands

1. Create cors_web.json (allowing GET/HEAD from *).

2. Run:

   Copy

   # 1. Create the bucket with PAP inherited (allowing public access)
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage buckets create gs://www.my-company-site.com \
       --project=my-frontend-project \
       --location=US \
       --default-storage-class=STANDARD \
       --uniform-bucket-level-access \
       --no-public-access-prevention \
       --soft-delete-duration=7d
   
   # 2. Configure Website settings and CORS in a single update (cannot be set during create)
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage buckets update gs://www.my-company-site.com \
       --web-main-page-suffix=index.html \
       --web-error-page=404.html \
       --cors-file=cors_web.json
   
   # 3. Grant public read access to website files
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage buckets add-iam-policy-binding gs://www.my-company-site.com \
       --member=allUsers \
       --role=roles/storage.objectViewer

Example 4: AI/ML Checkpointing (Zonal Buckets)

Input Draft Plan

*   **Bucket Name**: `my-training-checkpoints-us-east1-b`
*   **Project**: `my-ai-project`
*   **Location**: `us-east1-b` (Zone-level co-location for high performance)
*   **Storage Class**: `RAPID` (Must be explicitly specified for zonal buckets)
*   **UBLA**: Enabled (Required for Hierarchical Namespace)
*   **Public Access Prevention (PAP)**: Enforced
*   **Encryption**: Google-managed key
*   **Soft Delete**: Disabled (0 days) (Soft delete is not supported for zonal buckets)
*   **Use-case specific settings**:
    *   Hierarchical Namespace: Enabled (Required for Zonal buckets)
    *   Lifecycle: Delete checkpoint files older than 14 days

Output Commands

1. Create lifecycle_checkpoint.json:

   Copy

   {
     "rule": [
       {
         "action": {"type": "Delete"},
         "condition": {"age": 14}
       }
     ]
   }

2. Run:

   Copy

   # Specifying a zone (e.g. us-east1-b) and RAPID storage class sets up a zonal bucket.
   # Zonal buckets require enabling Hierarchical Namespace and UBLA.
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage buckets create gs://my-training-checkpoints-us-east1-b \
       --project=my-ai-project \
       --location=us-east1 \
       --placement=us-east1-b \
       --default-storage-class=RAPID \
       --uniform-bucket-level-access \
       --enable-hierarchical-namespace \
       --public-access-prevention \
       --soft-delete-duration=0 \
       --lifecycle-file=lifecycle_checkpoint.json

Example 5: WORM Archive with Object Lock (Per-Object Retention)

Input Draft Plan

*   **Bucket Name**: `my-legal-archive-bucket`
*   **Project**: `my-legal-project`
*   **Location**: `us-east1`
*   **UBLA**: Enabled
*   **Public Access Prevention (PAP)**: Enforced
*   **Soft Delete**: Enabled (7 days)
*   **Encryption**: Customer-Managed Key (CMEK) (Highly Recommended)
*   **Use-case specific settings**:
    *   Storage Class: `ARCHIVE`
    *   Object Lock (Per-Object Retention): Enabled
    *   CMEK Key ID: `projects/my-kms-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key`
    *   Labels: `compliance-type=regulatory`, `retention-period=7y` (Highly Recommended tags)
    *   Lifecycle: Delete objects older than 7 years (2555 days) (Highly Recommended OLM)

Output Commands

1. Create lifecycle_archive.json to purge objects after 7 years:

   Copy

   {
     "rule": [
       {
         "action": {"type": "Delete"},
         "condition": {"age": 2555}
       }
     ]
   }

2. Create the bucket and apply labels:

   Copy

   # 1. Create the bucket (object retention must be enabled at bucket creation time)
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage buckets create gs://my-legal-archive-bucket \
       --project=my-legal-project \
       --location=us-east1 \
       --default-storage-class=ARCHIVE \
       --uniform-bucket-level-access \
       --public-access-prevention \
       --soft-delete-duration=7d \
       --enable-per-object-retention \
       --default-encryption-key=projects/my-kms-project/locations/us-east1/keyRings/my-keyring/cryptoKeys/my-key \
       --lifecycle-file=lifecycle_archive.json
   
   # 2. Add labels (cannot be set during create)
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage buckets update gs://my-legal-archive-bucket \
       --project=my-legal-project \
       --update-labels=compliance-type=regulatory,retention-period=7y

3. Upload an object with a specific retention period (e.g., retain until December 31, 2030, in Locked mode):

   Copy

   # Uploading and setting retention in one command:
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage cp case_file_abc.pdf gs://my-legal-archive-bucket/case_file_abc.pdf \
       --retain-until=2030-12-31T23:59:59Z \
       --retention-mode=Locked

4. Alternatively, set or update retention on an existing object in the bucket:

   Copy

   # Update retention on an existing object:
   CLOUDSDK_METRICS_ENVIRONMENT="${CLOUDSDK_METRICS_ENVIRONMENT:+$CLOUDSDK_METRICS_ENVIRONMENT }gcs-skills gcs-skills/1.0 (skill:google-cloud-storage-bucket-architect)" \
   gcloud storage objects update gs://my-legal-archive-bucket/case_file_abc.pdf \
       --retain-until=2030-12-31T23:59:59Z \
       --retention-mode=Locked \
       --override-unlocked-retention

   Note: Setting the retention mode to Locked is permanent and irreversible. Once locked, the retention period cannot be shortened or removed, and the object cannot be deleted or overwritten by anyone (including administrators) until the retention period expires.

   [!IMPORTANT] If you are modifying an existing Unlocked retention configuration on an object, you must include the --override-unlocked-retention flag if you want to:

   • Change the mode to Locked (--retention-mode=Locked).

   • Reduce the retention time (--retain-until).

   • Clear the retention settings (--clear-retention).

   Failing to include this flag when performing these actions on an object with existing Unlocked retention will cause the command to fail.