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

  1. 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.
  2. In the Google Cloud console, on the project selector page, click Create project to begin creating a new Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.
  5. To initialize the gcloud CLI, run the following command:

    gcloud init
  6. In the Google Cloud console, on the project selector page, click Create project to begin creating a new Google Cloud project.

    Go to project selector

  7. Make sure that billing is enabled for your Google Cloud project.

  8. Install the Google Cloud CLI.
  9. 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:

  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

    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

The image of a kitten to upload into the 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: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.

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

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

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

  1. Open a terminal window (if not already open).
  2. 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