Discover object storage with the gcloud tool
This page shows you how to perform basic tasks in Cloud Storage using the gcloud command-line tool.
Costs that you incur in Cloud Storage are based on the resources you use. This quickstart typically uses less than $0.01 USD worth of Cloud Storage resources.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, click Create project to begin creating a new Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project .
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, click Create project to begin creating a new Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project .
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
Create a bucket
Buckets are the basic containers that hold your data in Cloud Storage.
To create a bucket:
- Open a terminal window.
-
Use the
gcloud storage buckets create
command and a unique name to create a bucket:gcloud storage buckets create gs://my-awesome-bucket/ --uniform-bucket-level-access
This uses a bucket named "my-awesome-bucket." You must choose your own, globally-unique, bucket name.
If successful, the command returns:
Creating gs://my-awesome-bucket/...
You've just created a bucket where you can store your data!
Creating gs://my-awesome-bucket/... ServiceException: 409 Bucket my-awesome-bucket already exists.
Try again with a different bucket name.
Upload an object into your bucket
-
Right-click the image above and save it somewhere on your computer, such as on the desktop.
-
Use the
gcloud storage cp
command to copy the image from the location where you saved it to the bucket you created:gcloud storage cp Desktop/kitten.png gs://my-awesome-bucket
If successful, the command returns:
Copying file://Desktop/kitten.png [Content-Type=image/png]... Uploading gs://my-awesome-bucket/kitten.png: 0 B/164.3 KiB Uploading gs://my-awesome-bucket/kitten.png: 164.3 KiB/164.3 KiB
You've just stored an object in your bucket.
Download the object from your bucket
-
Use the
gcloud storage cp
command to download the image you stored in your bucket to somewhere on your computer, such as the desktop:gcloud storage cp gs://my-awesome-bucket/kitten.png Desktop/kitten2.png
If successful, the command returns:
Copying gs://my-awesome-bucket/kitten.png... Downloading file://Desktop/kitten2.png: 0 B/164.3 KiB Downloading file://Desktop/kitten2.png: 164.3 KiB/164.3 KiB
You've just downloaded something from your bucket.
Copy the object to a folder in the bucket
-
Use the
gcloud storage cp
command to create a folder and copy the image into it:gcloud storage cp gs://my-awesome-bucket/kitten.png gs://my-awesome-bucket/just-a-folder/kitten3.png
If successful, the command returns:
Copying gs://my-awesome-bucket/kitten.png [Content-Type=image/png]... Copying ...my-awesome-bucket/just-a-folder/kitten3.png: 164.3 KiB/164.3 KiB
You've just copied your image into a new folder in your bucket.
List contents of a bucket or folder
-
Use the
gcloud storage ls
command to list the contents at the top level of your bucket:gcloud storage ls gs://my-awesome-bucket
If successful, the command returns a message similar to:
gs://my-awesome-bucket/kitten.png gs://my-awesome-bucket/just-a-folder/
You've just seen the contents at the top level of your bucket.
List details for an object
-
Use the
gcloud storage ls
command, with the--long
flag to get some details about a one of your images:gcloud storage ls gs://my-awesome-bucket/kitten.png --long
If successful, the command returns a message similar to:
2638 2016-02-26T23:05:14Z gs://my-awesome-bucket/kitten.png TOTAL: 1 objects, 168243.2 bytes (164.3 KiB)
You've just obtained information about the image's size and date of creation.
Make the objects publicly accessible
-
Use the
gcloud storage buckets add-iam-policy-binding
command to grant all users permission to read the images stored in your bucket:gcloud storage buckets add-iam-policy-binding gs://my-awesome-bucket --member=allUsers --role=roles/storage.objectViewer
The command is successful if your response contains the following:
bindings: - members: - allUsers role: roles/storage.objectViewer
Now anyone can get your images.
-
To remove this access, use the command:
gcloud storage buckets remove-iam-policy-binding gs://my-awesome-bucket --member=allUsers --role=roles/storage.objectViewer
The command is successful if no error is returned.
You have removed public access to the images in your bucket.
Give someone access to your bucket
-
Use the
gcloud storage buckets add-iam-policy-binding
command to give a specific email address permission to add objects to your bucket:gcloud storage buckets add-iam-policy-binding gs://my-awesome-bucket --member=user:jane@gmail.com --role=roles/storage.objectCreator
The command is successful if your response contains the following:
bindings: - members: - user:jane@gmail.com role: roles/storage.objectCreator
Now someone else can add items to your bucket.
-
To remove this permission, use the command:
gcloud storage buckets remove-iam-policy-binding gs://my-awesome-bucket --member=user:jane@gmail.com --role=roles/storage.objectCreator
The command is successful if no error is returned.
You have removed the user's access to this bucket.
Delete an object
-
Use the
gcloud storage rm
command to delete one of your images:gcloud storage rm gs://my-awesome-bucket/kitten.png
If successful, the command returns:
Removing gs://my-awesome-bucket/kitten.png...
This copy of the image is no longer stored on Cloud Storage (though the copy you made in the folder
just-a-folder/
still exists).
Clean up
To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.
- Open a terminal window (if not already open).
-
Use the
gcloud storage rm
command with the--recursive
flag to delete the bucket and anything inside of it:gcloud storage rm gs://my-awesome-bucket --recursive
If successful, the command returns a message similar to:
Removing gs://my-awesome-bucket/just-a-folder/cloud-storage.logo.png#1456530077282000... Removing gs://my-awesome-bucket/...
Your bucket and its contents are deleted.
What's next
- Work through Cloud Storage Quickstart using the Google Cloud console .
- Read the Cloud Storage product overview .
- Learn about Cloud Storage pricing .
- See the reference pages for Google Cloud CLI commands, such as make bucket (
buckets create
) , copy (cp
) , list (ls
) , add access (buckets add-iam-policy-binding
, and remove (rm
) .