Discover object storage with the gcloud tool

Create a bucket

Buckets are the basic containers that hold your data in Cloud Storage.

To create a bucket:

1. Open a terminal window.

2. 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 --location=LOCATION_NAME

   This uses a bucket named "my-awesome-bucket." You must choose your own, globally-unique, bucket name.

   See bucket naming requirements.

   • Bucket names can only contain lowercase letters, numeric characters, dashes (-), and underscores (_). Spaces are not allowed.
   • Bucket names must start and end with a number or letter.
   • Bucket names must contain 3-63 characters. Names containing dots can contain up to 222 characters, but each dot-separated component can be no longer than 63 characters.
   • Bucket names cannot be represented as an IP address in dotted-decimal notation (for example, 192.168.5.4).
   • Bucket names cannot begin with the "goog" prefix.
   • Bucket names cannot contain "google" or close misspellings, such as "g00gle".

   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

1. Right-click the image above and save it somewhere on your computer, such as on the desktop.

2. 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

1. 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

1. 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

1. 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

1. 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

1. 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.

2. 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

1. 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:example-service-account@example-project.s3ns.iam.gserviceaccount.com --role=roles/storage.objectCreator

   The command is successful if your response contains the following:

   bindings:
     - members:
       - user:example-service-account@example-project.s3ns.iam.gserviceaccount.com
       role: roles/storage.objectCreator
   

   Now someone else can add items to your bucket.

2. To remove this permission, use the command:

   gcloud storage buckets remove-iam-policy-binding gs://my-awesome-bucket --member=user:example-service-account@example-project.s3ns.iam.gserviceaccount.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

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