Create a bucket with IP filtering rules

This page describes how to create a bucket with IP filtering rules. By creatinga bucket with IP filtering, you can control access to your buckets by examiningincoming requests against the IP addresses specified in the bucket IP filteringrules. For details, seeBucket IP filtering.

Caution: It's crucial to set up your IP filtering rules accurately. Incorrectlyconfigured rules can prevent legitimate users from reaching your bucket or evenlock you out completely. If you find yourself locked out of your bucket, you canbypass the bucket IP filtering rules to regain access. For details, see Bypassbucket IP filtering rules.

For information about how to create or update the IP filtering rules on anexisting bucket, seeUpdate bucket IP filtering rules.

Required roles

To get the required permissions for creating a bucket with 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 abucket with IP filtering rules.

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

Required permissions

storage.buckets.create
storage.buckets.setIpFilter

You can also get these permissions withcustom roles. You might be able toget these permissions with other predefined roles as well. To see which rolesare associated with which permissions, refer toIAM roles forCloud Storage.

For instructions on granting roles on buckets, seeSet and manage IAM policies on buckets.

Create bucket with IP filtering rules

Note: When you use IP filtering with gRPC direct path, you mustenable IPv6 support on the VPC network.Caution: When configuring IP-based access controls for Cloud Storagebuckets, evaluate your Google Cloud architecture. Google Cloudservices, such as Cloud Composer, might operate within separate,Google-managed projects that have their own VPCnetworks. To experience uninterrupted service, you must identify and allowlistthe IP ranges from the associated VPC networks in your bucket'sfilter configuration. Failure to do so might result in the services beingblocked from accessing your bucket. For complex Google Cloudarchitectures, we recommend consulting your account team for assistance inmapping all necessary IP address ranges.

gcloud

Verify that you have the Google Cloud CLI version 526.0.0 or later installed:
```
gcloud version | head -n1
```
If you have an earlier gcloud CLI version installed, update the version:
```
gcloud components update --version=526.0.0
```
Create a JSON file that defines the rules for incoming requests. Forexamples and information about how to structure the bucket IP filteringrules, seeBucket IP filtering configurations.
```
{"mode":"MODE","publicNetworkSource":{"allowedIpCidrRanges":["RANGE_CIDR","..."]},"vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["RANGE_CIDR","..."]},"..."],"allowCrossOrgVpcs":ALLOW_CROSS_ORG_VPCS,"allowAllServiceAgentAccess":ALLOW_ALL_SERVICE_AGENT_ACCESS}
```
Where:
- MODE is the mode of the bucket IP filteringconfiguration. Valid values areEnabled andDisabled. When set toEnabled, IP filtering rules are applied to a bucket. Any incoming request to the bucket is evaluated against these rules. When set toDisabled, all incoming requests are allowed to access the bucket.
  Note: To safely enable bucket IP filtering rules, start by configuring yourrules with themode field set toDisabled so that you can add and adjust ruleswithout immediately blocking requests. After you've verified that your rulesare correctly defined, update themode field toEnabled to activate bucket IPfiltering.
- RANGE_CIDR is a public network IPv4 or IPv6address range that's allowed to access the bucket. You canenter one or multiple address ranges as a list.
- PROJECT_ID is the project ID wherethe Virtual Private Cloud (VPC) network exists. To configuremultiple VPC networks, you need to specifythe project where each network is located.
- NETWORK_NAME is the name of theVPC network that is allowed to access thebucket. To configure multiple VPC networks,you need to specify a name for each network.
- ALLOW_CROSS_ORG_VPCS is a boolean valuethat indicates whether to allow VPC networksthat are defined invpcNetworkSources to originatefrom a different organization. This field is optional. If set totrue, therequest allows cross-organizational VPCnetworks. If set tofalse, the request restrictsthe VPC networks to the same organization as thebucket. If not specified, the default value isfalse. This field applies only ifvpcNetworkSources is not empty.
- ALLOW_ALL_SERVICE_AGENT_ACCESS is aboolean value that indicates whether to allow serviceagents to access the bucket,regardless of the IP filter configuration. If the value istrue, other Google Cloud services can useservice agents to access the bucket without IP-based validation.
To create a bucket with IP filtering rules, run thegcloudstorage buckets create command in your developmentenvironment:
```
gcloud 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 tonaming requirements. For example,my-bucket.
- IP_FILTER_CONFIG_FILE is the JSON file that defines the rules for incoming requests.

JSON API

Have gcloud CLIinstalled and initialized , which lets you generate an access token for theAuthorization header.
Create a JSON file that contains the settings for the bucket, which mustinclude thename andipFilter configuration fields for the bucket. Forexamples and information about how to structure the bucket IPfiltering rules, see Bucket IP filtering configurations.
```
{"name":"BUCKET_NAME","ipFilter":{"mode":"MODE","publicNetworkSource":{"allowedIpCidrRanges":[RANGE_CIDR,...]},"vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":[RANGE_CIDR,...]},...],"allowCrossOrgVpcs":ALLOW_CROSS_ORG_VPCS,"allowAllServiceAgentAccess":ALLOW_ALL_SERVICE_AGENT_ACCESS},}
```
Where:
- MODE is the state of the IP filter configuration. Valid values areEnabled andDisabled. When set toEnabled, IP filtering rules are applied to a bucket and all incoming requests to the bucket are evaluated against these rules. When set toDisabled, all incoming requests can access the bucket and its data without any evaluation if you have the required IAM permissions.
  Note: To safely enable bucket IP filtering rules, start by configuring your rules with themode field set toDisabled so that you can add and adjust rules without immediately blocking requests. After you've verified that your rules are correctly defined, update themode field toEnabled 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.
- ALLOW_ALL_SERVICE_AGENT_ACCESS is a boolean value that indicates whether to allow service agents to access the bucket, regardless of the IP filter configuration. If the value istrue, other Google Cloud services can use service agents to access the bucket without IP-based validation.
- ALLOW_CROSS_ORG_VPCS is a boolean value that indicates whether to allow VPC networks that are defined invpcNetworkSources to originate from a different organization. This field is optional. If set totrue, the request allows cross-organizational VPC networks. If set tofalse, the request restricts the VPC networks to the same organization as the bucket. If not specified, the default value isfalse. This field applies only ifvpcNetworkSources is not empty.
UsecURL to call theJSON API with aPOST 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_ID"
```
Where:
- JSON_FILE_NAME is name of the JSON filethat contains the settings for the bucket.
- PROJECT_ID is the ID ofthe project with which your bucket is associated. Forexample,my-project.

Bucket IP filtering configurations

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

Any public IP address (IPv4 or IPv6):

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

gcloud

{"mode":"Enabled","publicNetworkSource":{"allowedIpCidrRanges":["0.0.0.0/0","::/0"]},"allowAllServiceAgentAccess":false}

JSON API

{"name":"my-bucket","ipFilter":{"mode":"Enabled","publicNetworkSource":{"allowedIpCidrRanges":["0.0.0.0/0","::/0"]},"allowAllServiceAgentAccess":false}}

Specific public IP ranges:

The following example configuration grants access to192.0.2.0/24 public IPv4 address range, but blocks traffic originating from any VPC:
gcloud
```
{"mode":"Enabled","publicNetworkSource":{"allowedIpCidrRanges":["192.0.2.0/24"]},"allowAllServiceAgentAccess":false}
```

JSON API

{"name":"my-bucket","ipFilter":{"mode":"Enabled","publicNetworkSource":{"allowedIpCidrRanges":["192.0.2.0/24"]},"allowAllServiceAgentAccess":false}}

The following example configuration grants access to2001:db8::/32 public IPv6 address range, but blocks traffic originating from any VPC:
gcloud
```
{"mode":"Enabled","publicNetworkSource":{"allowedIpCidrRanges":["2001:db8::/32"]},"allowAllServiceAgentAccess":false}
```

JSON API

{"name":"my-bucket","ipFilter":{"mode":"Enabled","publicNetworkSource":{"allowedIpCidrRanges":["2001:db8::/32"]},"allowAllServiceAgentAccess":false}}

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 andNETWORK_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:
gcloud
```
{"mode":"Enabled","vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["0.0.0.0/0","::/0"]},],"allowAllServiceAgentAccess":false}
```

JSON API

{"name":"my-bucket","ipFilter":{"mode":"Enabled","vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["0.0.0.0/0","::/0"]},],"allowAllServiceAgentAccess":false}}

The following example configuration only grants access to a request from a VPC associated to a VM with an external IPv4 address as192.0.2.0/24 and blocks traffic originating from a public IP address:
gcloud
```
{"mode":"Enabled","vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["192.0.2.0/24"]},],"allowAllServiceAgentAccess":false}
```

JSON API

{"name":"my-bucket","ipFilter":{"mode":"Enabled","vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["192.0.2.0/24"]},],"allowAllServiceAgentAccess":false}}

The following example configuration only grants access to a request coming from a VPC with an internal IPv4 subnet range associated to a VM with no external IP address and blocks traffic originating from a public IP address:
gcloud
```
{"mode":"Enabled","vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["IP_ADDRESS"]},],"allowAllServiceAgentAccess":false}
```
Where:
IP_ADDRESS is aninternal IPv4 subnet range.

JSON API

{"name":"my-bucket","ipFilter":{"mode":"Enabled","vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["IP_ADDRESS"]},],"allowAllServiceAgentAccess":false}}

Where:

IP_ADDRESS is aninternal IPv4 subnet range.

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 as2001:db8::/32 and blocks traffic originating from a public IP address:
gcloud
```
{"mode":"Enabled","vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["2001:db8::/32"]},],"allowAllServiceAgentAccess":false}
```

JSON API

{"name":"my-bucket","ipFilter":{"mode":"Enabled","vpcNetworkSources":[{"network":"projects/PROJECT_ID/global/networks/NETWORK_NAME","allowedIpCidrRanges":["2001:db8::/32"]},],"allowAllServiceAgentAccess":false}}

What's next

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.

Movatterモバイル変換

Create a bucket with IP filtering rules Stay organized with collections Save and categorize content based on your preferences.

Required roles

Required permissions

Create bucket with IP filtering rules

gcloud

JSON API

Bucket IP filtering configurations

gcloud

JSON API

gcloud

JSON API

gcloud

JSON API

gcloud

JSON API

gcloud

JSON API

gcloud

JSON API

gcloud

JSON API

What's next

Try it for yourself

Create a bucket with IP filtering rules