Create bucket IP filtering rules

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes how to create bucket IP filtering rules. By enabling bucket IP filtering, you can control access to your buckets by examining incoming requests against the IP addresses specified in the bucket IP filtering rules. For details, see Bucket IP filtering.

Caution: It's crucial to set up your IP filtering rules accurately. Incorrectly configured rules can prevent legitimate users from reaching your bucket or even lock you out completely. If you find yourself locked out of your bucket, you can bypass the bucket IP filtering rules to regain access. For details, see Bypass bucket IP filtering rules.

Required roles

To get the required permissions for creating bucket IP filtering rules, ask your administrator to grant you the Storage Admin (roles/storage.admin) role on the bucket. This role contains the permissions required to create bucket IP filtering rules.

To see the exact permissions that are required, expand the Required permissions section:

Required permissions

• storage.buckets.create
• storage.buckets.setIpFilter

You can also get these permissions with custom roles. You might be able to get these permissions with other predefined roles as well. To see which roles are associated with which permissions, refer to IAM roles for Cloud Storage.

For instructions on granting roles on buckets, see Use IAM with buckets.

Create bucket IP filtering rules

Command line

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Create a JSON file that defines the rules for incoming requests. For examples and information about how to structure the bucket IP filtering rules, see Bucket IP filtering configurations.

   {
     "mode": "Enabled",
     "publicNetworkSource":
       {
       "allowedIpCidrRanges":
         [RANGE_CIDR,
         ...
         ]
       },
     "vpcNetworkSources":
         [
          {"network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
           "allowedIpCidrRanges":
             [RANGE_CIDR,
             ...
             ]
          },
         ...
         ]
      }
   

   Where:

   • mode is the mode of the bucket IP filtering configuration. Valid values are Enabled and Disabled. When set to Enabled, IP filtering rules are applied to a bucket. Any incoming request to the bucket is evaluated against these rules. When set to Disabled, all incoming requests are allowed to access the bucket.

     Note: To safely enable bucket IP filtering rules, start by configuring your rules with the mode set to Disabled so that you can add and adjust rules without immediately blocking requests. After you've verified that your rules are correctly defined, update the mode to Enabled to activate bucket IP filtering.

   • RANGE_CIDR is a public network IPv4 or IPv6 address range that's allowed to access the bucket. You can enter one or multiple address ranges as a list.

   • PROJECT_ID is the project ID where the Virtual Private Cloud (VPC) network exists. To configure multiple VPC networks, you need to specify the project where each network is located.

   • NETWORK_NAME is the name of the VPC network that is allowed to access the bucket. To configure multiple VPC networks, you need to specify a name for each network.

3. To create a bucket with IP filtering rules, run the gcloud alpha storage buckets create command in your development environment:

   gcloud alpha storage buckets create gs://BUCKET_NAME --ip-filter-file=IP_FILTER_CONFIG_FILE

   Where:

   • BUCKET_NAME is the name you want to give your bucket, subject to naming requirements. For example, my-bucket.
   • IP_FILTER_CONFIG_FILE is the JSON file that defines the rules for incoming requests.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

2. Create a JSON file that contains the settings for the bucket, which must include the name and ipFilter configuration fields for the bucket. For examples and information about how to structure the bucket IP filtering rules, see Bucket IP filtering configurations.

   {
     "name": "BUCKET_NAME"
     "ipFilter": {
       "mode": "Enabled",
       "publicNetworkSource":
         {
           "allowedIpCidrRanges":
             [RANGE_CIDR,
               ...
             ]
             },
             "vpcNetworkSources":
             [
             {"network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
               "allowedIpCidrRanges":
               [RANGE_CIDR,
                 ...
               ]
             },
             ...
             ]
           }
          }
         

   Where:

   • mode is the state of the IP filter configuration. Valid values are Enabled and Disabled. When set to Enabled, IP filtering rules are applied to a bucket and all incoming requests to the bucket are evaluated against these rules. When set to Disabled, all incoming requests can access the bucket and its data without any evaluation if you have the required IAM permissions. To safely enable bucket IP filtering rules, start by configuring your rules with the mode set to Disabled so that you can add and adjust rules without immediately blocking requests. After you've verified that your rules are correctly defined, update the mode to Enabled to activate bucket IP filtering.

   • RANGE_CIDR is a public network IPv4 or IPv6 address range that's allowed to access the bucket. You can enter one or multiple address ranges as a list.

   • PROJECT_ID is the project ID where the VPC network exists. To configure multiple VPC networks, you need to specify the project where each network is located.

   • NETWORK_NAME is the name of the VPC network that is allowed to access the bucket. To configure multiple VPC networks, you need to specify a name for each network.

3. Use cURL to call the JSON API with a POST bucket request:

   curl -X POST --data-binary @JSON_FILE_NAME \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b?project=PROJECT_IDENTIFIER&projection=full"

   Where:

   • JSON_FILE_NAME is name of the JSON file that contains the settings for the bucket.
   • PROJECT_IDENTIFIER is the ID or number of the project with which your bucket is associated. For example, my-project.

Bucket IP filtering configurations

This section provides examples of bucket IP filtering JSON file configurations to control access to your Cloud Storage buckets. You can grant access to incoming requests using any of the following examples:

• Any public IP address (IPv4 or IPv6):

  The following configuration grants access to any public IPv4 address, but blocks traffic originating from any VPC:

  {
  "ipFilterConfig": {
    "mode": "Enabled"
    "publicNetworkSource": ["0.0.0.0/0", "::/0"]
  }
  }
  

• Specific public IP ranges:

  • The following example configuration grants access to 192.0.2.0/24 public IPv4 address range, but blocks traffic originating from any VPC:

    {
    "ipFilterConfig": {
      "mode": "Enabled"
      "publicNetworkSource": ["192.0.2.0/24"]
    }
    }
    

  • The following example configuration grants access to 2001:db8::/32 public IPv6 address range, but blocks traffic originating from any VPC:

    {
    "ipFilterConfig": {
      "mode": "Enabled"
      "publicNetworkSource": ["2001:db8::/32"]
    }
    }
    

• VPC networks: Using the following configurations, you can grant access to resources within your VPC network. You can grant access to all IP addresses within the VPC or specific IP ranges within the VPC. In each of these examples, PROJECT_ID is the project ID where the VPC network exists and NETWORK_NAME is the name of the VPC network that is allowed to access the bucket.

  • The following example configuration grants access to a request from any IPv4 or IPv6 address coming from a specific VPC and blocks traffic originating from a public IP address:

    {
    "ipFilterConfig": {
      "mode": "Enabled"
      "vpcNetworkSources": [
          {
              "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
              "allowedIpCidrRanges": ["0.0.0.0/0", "::/0"]
          },
      ]
    }
    }
    

  • The following example configuration only grants access to a request from a VPC associated to a VM with an external IPv4 address as 192.0.2.0/24 and blocks traffic originating from a public IP address:

    {
    "ipFilterConfig": {
      "mode": "Enabled"
    "vpcNetworkSources": [
          {
              "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
              "allowedIpCidrRanges": ["192.0.2.0/24"]
          },
      ]
    }
    }
    

  • The following example configuration only grants access to a request coming from a VPC with an internal IPv4 subnet range as 192.0.2.0/24 associated to a VM with no external IP address and blocks traffic originating from a public IP address:

    {
    "ipFilterConfig": {
      "mode": "Enabled"
    "vpcNetworkSources": [
          {
              "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
              "allowedIpCidrRanges": ["192.0.2.0/24"]
          },
      ]
    }
    }
    

  • The following example configuration only grants access to a request coming from a VPC with dual-stack IPv4 and IPv6 subnet range associated to a VM with an external IPv6 address range as 2001:db8::/32 and blocks traffic originating from a public IP address:

    {
    "ipFilterConfig": {
      "mode": "Enabled"
    "vpcNetworkSources": [
          {
              "network": "projects/PROJECT_ID/global/networks/NETWORK_NAME",
              "allowedIpCidrRanges": ["2001:db8::/32"]
          },
      ]
    }
    }
    

What's next

• Update bucket IP filtering rules.
• Get bucket IP filtering rules.
• List bucket IP filtering rules.
• Disable bucket IP filtering.

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try Cloud Storage free