Google Compute Engine

gcutil Tool

This document describes installation and usage of the gcutil tool. gcutil is a command-line tool that is used to manage your Google Compute Engine resources.

Note: Looking for reference pages for gcutil commands? See the reference documentation instead!

If you haven't already activated Google Compute Engine, you must follow the Sign Up steps.

Contents

  1. System Requirements
  2. Installing gcutil
  3. Authenticating to Google Compute Engine
  4. Upgrading gcutil on Google Compute Engine instancesDeprecated
  5. Next Steps

System Requirements

gcutil runs on UNIX-based operating systems such as Linux and Mac OS X. To use gcutil, you must have Python 2.6.x or 2.7.x installed on your computer. gcutil does not support Python 3.x. Python is installed by default on most Linux distributions and Mac OS X.

You can also run gcutil on the Microsoft Windows family of operating systems by using Cygwin. Cygwin is not installed on Windows by default. The instructions below describe how to install Cygwin.

Installing gcutil

This section discusses how to install gcutil on your computer.

gcutil is distributed as part of the Cloud SDK, which contains tools and libraries for managing resources on Google Cloud Platform.

Installing on Linux or Mac OS X


  1. Download and install the Cloud SDK.

    You can download and install the Cloud SDK using the following command:

    $ curl https://dl.google.com/dl/cloudsdk/release/install_google_cloud_sdk.bash | bash

    Alternatively, if you don't want to use curl, you can always download and unzip the package manually:

    1. Download google-cloud-sdk.zip
    2. Unzip the file:
      $ unzip google-cloud-sdk.zip
    3. Run the installation script:
      $ ./google-cloud-sdk/install.sh

    Follow the prompts to complete the setup. When prompted if you would like to update your system path, select y.

  2. Restart your terminal to allow changes to your PATH to take affect.

    You can also run source ~/.<bash-profile-file> if you want to avoid restarting your terminal.

  3. Authenticate to the Google Cloud platform by running:
    $ gcloud auth login

Installing on Windows with Cygwin


  1. Download and install Cygwin.

    Cygwin's website contains installation instructions. While installing Cygwin, be sure to select openssh, curl, and the latest 2.6.x or 2.7.x version of python from the package selection screen.

  2. Start Cygwin.

    By default, you can launch Cygwin by going to Start -> All Programs -> Cygwin -> Cygwin Terminal.

  3. Download the Cloud SDK and install it.

    You can download and install the Cloud SDK by issuing the following commands from Cygwin:

    $ curl https://dl.google.com/dl/cloudsdk/release/install_google_cloud_sdk.bash | bash

    Alternatively, if you don't want to use curl, you can always download and unzip the package manually:

    1. Download google-cloud-sdk.zip.
    2. Unzip the file by right-clicking on it and selecting Extract all.
    3. Run the installation script by clicking on the install.bat file.

    Follow the prompts to complete the setup. When prompted if you would like to update your system path, select y.

  4. Restart Cygwin (or cmd).
  5. Authenticate to the Google Cloud platform by running:
    $ gcloud auth login

Authenticating to Google Compute Engine

Google Compute Engine uses OAuth2 to authenticate and authorize access. Before you can use gcutil, you must first authorize the Cloud SDK on your behalf to access your project and acquire an auth token. You won't need to repeat these steps unless you delete your stored credentials file or remove Google Compute Engine access to your Google account.

  1. Run gcloud auth login to request a token. This command prints a URL and opens a browser window to request access to your project.
    $ gcloud auth login
    Your browser has been opened to visit:
    
    https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
    Fauth%2Fappengine.admin+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery+https
    %3A%2F%2Fwww.googleapis.com%2Fauth%2Fcompute+https%3A%2F%2Fwww.googleapis.com%
    Fauth%2Fdevstorage.full_control+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuser...
    
    Created new window in existing browser session.

    You can also provide the --no-launch-browser flag if your browser doesn't automatically load the URL. If you provide this flag, the tool will print out a verification code that you can copy and paste into a browser, instead of opening a new browser window.

    $ gcloud auth login --no-launch-browser
    Go to the following link in your browser:
    
    https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
    Fauth%2Fappengine.admin+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery+https
    %3A%2F%2Fwww.googleapis.com%2Fauth%2Fcompute+https%3A%2F%2Fwww.googleapis.com%
    Fauth%2Fdevstorage.full_control+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuser...
    
    Enter verification code:
  2. Grant access.

    In the browser window, review the application permissions and click Accept when you are ready. If you used the --no-launch-browser flag, copy and paste the printed code on the next page onto the command line. Otherwise, the code will automatically be sent to the command line without any additional action on your part.

  3. (Optional) Next, the tool will prompt you for a project ID to use as your default project. Enter the ID of the project you want to use for Google Compute Engine:
    You can list your projects and create new ones in the Google Cloud
    console at https://cloud.google.com/console. If you have a project
    ready, you can enter it now.
    Enter a cloud project id (or leave blank
    to not set): myproject

    If you do not want to select a default project at this time, you can leave the prompt blank. To set your project ID later, run the following command at any time:

    $ gcloud config set project <new-project-id>

    Similarly, to unset your project ID, run:

    $ gcloud config unset project

    You can also view your settings, including your project ID:

    $ gcloud config list
  4. Try a quick example, such as a gcutil listinstances command:
    $ gcutil listinstances

Back to top

Upgrading gcutil on Compute Engine instances

Warning: The stand-alone version of gcutil is deprecated and we encourage users to transition to using the Cloud SDK.

Currently, Compute Engine instances do not come preinstalled with the Cloud SDK and instead, provides a stand-alone version of gcutil. We encourage users to transition to the Cloud SDK using the installation instructions above, but if you need to keep the stand-alone gcutil version, use the following instructions to keep the tool to updated to the latest version.

  1. Download the latest gcutil-1.14.2.tar.gz file.
    wget https://dl.google.com/dl/cloudsdk/release/artifacts/gcutil-1.14.2.tar.gz
  2. Extract the files.

    Run the following command to extract the tar file. This unpacks a directory named gcutil-1.14.2 in /usr/local/share.

    sudo tar xzvpf gcutil-1.14.2.tar.gz -C /usr/local/share
  3. Create a symbolic link to the gcutil binary.
    sudo ln -sf /usr/local/share/gcutil-1.14.2/gcutil /usr/local/bin/gcutil
  4. Start using gcutil.

    If you modified your system path, restart your shell before continuing so the changes can take effect. To see a list of available gcutil commands, run:

    gcutil help

Back to top

Next Steps

That's it, you can now start using gcutil! Here are some ideas to get you started:

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.