Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



Resource Overview

At the core of Google Compute Engine are virtual machine instances that run on Google's infrastructure. Each virtual machine instance is considered an Instance resource and part of the Instance collection. When you create a virtual machine instance, you are creating an Instance resource that uses other resources, such as Disk resources, Network resources, Image resources, and so on. Each resource performs a different function. For example, a Disk resource functions as data storage for your virtual machine, similar to a physical hard drive, and a Network resource helps regulate traffic to and from your instances.

All resources belong to the global, regional, or zonal plane. For example, images are a global resource so they can be accessed from all other resources. Static IPs are a regional resource, and only resources that are part of the same region can use the static IPs in that region. Google Cloud Platform resources are hosted in multiple locations world-wide. These locations are composed of regions and zones within those regions. Putting resources in different zones in a region provides isolation for many types of infrastructure, hardware, and software failures. Putting resources in different regions provides an even higher degree of failure independence. This allows you to design robust systems with resources spread across different control planes.

Contents

Google Developers Console projects

Before you can start using Google Compute Engine, you must enable the service from the Google Developers Console. The Developers Console is designed to be a one-stop shop for you to create and manage multiple API "projects" at once. Each project is a totally compartmentalized world. Projects do not share resources, can have different owners and users, are billed separately, and are managed separately.

After Google Compute Engine is enabled, any resources you create or use in Google Compute Engine belong to the project. It is possible to have many projects with Google Compute Engine enabled. To differentiate between them, Google Compute Engine requires that you always identify the project you're working in when interacting with the Google Compute Engine service.

Identifying projects

In order to interact with Google Compute Engine resources, you must provide identifying project information for every request. If you are using gcloud compute , you can save your project ID so it is automatically provided for each request, but in the API, you must always specify the project ID.

A project can be identified two ways: using a project ID , or a project number . A project ID is the customized name you chose when you created the project, or when you activated an API that required you to create a project ID. It can be found in the Dashboard of the project, and looks similar to the following:

When you specify your project ID, you need to include the full project ID, including any domain if one is shown in your project ID. For example, when using gcloud compute , you can specify your project ID like so: 

$ gcloud --project example.com:my-project compute instances create example-instance

gcloud lets you save your project ID so that it is automatically provided for each request. To set a default project, use the gcloud config set command: 

$ gcloud config set project example.com:my-project

When you choose your project ID (or any resource names), avoid providing sensitive information in your names.

Alternatively, you can also use the project number to identify your project to Google Compute Engine. Your project number is unique to the project and can be found in the URL of the project:

Generally, we recommend using the project ID to identify your projects because it is easier to remember than the numeric ID.

Project team members

Projects have team members that can collaborate on and access the project to varying degrees. Team members can be added as an owner, editor, or viewer. Every project can have one or more owners, editors, and viewers. Depending on their role, team members can access Google Compute Engine resources for that project accordingly:

  • To add or modify Google Compute Engine resources in a project, you need to be an owner or editor of that project.
  • To list information about certain resources within a project, you need to be a viewer, owner, or editor of that project.

To add team members to a project, see managing project members .

For more information, see Projects .

Global resources

Global resources are accessible by any resource in any zone within the same project. When you create a global resource, you do not need to provide a scope specification. Global resources include:

Images
Images can be used by any instance or disk resource in the same project as the image. Google also provides preconfigured images that you can use to boot your instance, or you can customize an image to use instead.
Snapshots
Persistent disk snapshots are available to all disks within the same project as the snapshot.
Network
A network can be used by any instance in the same project.
Firewalls
Firewalls apply to a single network, but are considered a global resource because they can be used by any network in the same project.
Routes
Routes allow you to create complicated networking scenarios by letting you manage how traffic destined for a certain IP range should be routed, similar to how a router directs traffic within a local area network. Routes apply to networks within a Google Compute Engine project and are considered a global resource.
Global operations

Operations are both a per-zone resource and a global resource. If you are performing an operation on a global resource, the operation is considered a global operation. For example, inserting an image would be considered a global operation, because images are a global resource.

Most of the global resources are briefly described below.

Image resources

When you start an instance, you must select an image to use. An image resource contains an operating system and root file system necessary for starting your instance. Google maintains and provides images that are ready-to-use or you can customize an image and use that as your image of choice for creating instances. Depending on your needs, you can also apply an image to a persistent disk and use the persistent disk as your root file system.

Images are a global resource, so you can use any image with an instance or disk. All your custom images are also global. For more information, see Images .

Snapshot resources

Persistent disk snapshots lets you copy data from an existing persistent disk and apply them to new persistent disks. This is especially useful for creating backups of your persistent disk data in cases of unexpected failures and zone maintenance events. Since snapshots are a global resource, you can apply a snapshot to any disk in any zone. If a persistent disk in a zone is taken offline, you can use snapshots to recreate the same disk in another zone of your choice.

For more information, see Persistent Disk Snapshots .

Network resources

A project has one or more Network resources that define how instances communicate with each other, with other networks, and with the outside world. Each instance belongs to a single network and any communication between instances in different networks must be through a public IP address.

A network defines the address range and gateway address of all instances connected to it, which you can configure to suit your needs. Networks are associated with Firewall resources, which allow you to specify the types of connections that are permitted into an instance. For example, you can configure the network and firewall resources of a specific instance so that the instance can have an externally visible IP address that lets it act as an HTTP server, or handle SSH, UDP, or other requests as defined by the network and firewall settings.

Networks belong to a single project but are a global resource; any instance within the same project as the network may use the network.

The default network

Every project comes preconfigured with a single Network resource named default . The default network includes two firewalls: a firewall that allows all instances in the network to communicate over TCP/UDP/ICMP, and a firewall that supports ssh into the network from outside. No other connections are supported by default. You can modify or delete the default firewalls or add new firewalls to your project's default network to customize how your instances communicate with each other and the world.

Most users will not need to create any Networks above and beyond the default network.

For more information, see Networking and Firewalls .

Firewall resources

A Firewall resource contains one or more rules that permit connections into instances. Every firewall resource is associated with one and only one network. It is not possible to associate one firewall with multiple networks.

No communication is allowed into an instance unless a Firewall resource permits the network traffic, even between instances on the same network. However, an instance is always allowed to communicate out, unless it is trying to communicate through one of the blocked traffic sources . In other words, firewalls only apply to incoming connections. A firewall resource consists of:

  • A set of allowed sources. This can either be explicit IP address ranges or a set of instances defined by a tag on the instance.
  • A set of target VMs, defined by tags on the instances.
  • A set of protocols and ports.

With these primitives, Google Compute Engine provides a flexible configuration to allow connections from any source or to any target. To get started, here are some firewall examples:

  • A firewall that allows incoming TCP connections to port 80 and 443 on instances tagged 'frontend' from anywhere.
  • A firewall that allows SSH requests into any instance from just your workstation's IP.
  • A firewall that allows all TCP or UDP requests from instances labeled "frontend" to any instances labeled "backend" over port 118.

    • For more information, see Networking and Firewalls .

    Route resources

    Google Compute Engine offers a routing table that lets you manage how traffic destined for a certain IP range should be routed. Similar to a physical router in your local area network, all outbound traffic is compared to your routes table and appropriately forwarded if the outbound packet matches any rules in the routes table. For example, you can route traffic destined for the Internet through the nearest VPN gateway. Routes apply to networks inside your Google Compute Engine project and are considered a global resource.

    Regional resources

    Regional resources are accessible by any resources within the same region. For example, if you reserve a static IP in a specific region, only instances within that region can use that static IP. Each region also has one or more zones and you can find out which zone belongs to which region by performing a gcloud compute regions describe request.

    You can see a list of available region using gcloud compute](/compute/docs/gcloud-compute) with the [ regions list` command: 

    $ gcloud compute regions list

    Regional resources include:

    Addresses
    Reserved addresses are static external IP addresses that you reserve and manage for your instances. Addresses are a regional resource and can only be used by instances that are in the same region as the address.
    Regional operations

    Operations are a per-zone resource, a per-region resource, and a global resource. If you are performing an operation on a resource that lives within a region, the operation is considered a per-region operation. For example, reserving an address is considered regional operation, because the operation is being performed on a region-specific resource, an address.

    Address resources are discussed in detail below.

    Address resources

    When you create an instance, an ephemeral external IP address is automatically assigned to your instance by default. This address is attached to your instance for the life of the instance and is released once the instance has been terminated. If you want to reserve a static IP address instead, you can use the Addresses collection, a self-service API that allows you to reserve, release, and manage static IPs for your project. Using the Addresses collection, you can also promote an ephemeral IP address to a static IP address. For more information, review the Reserved IP Addresses documentation.

    As a regional resource, an Address resource is only available to instances that are in a zone that is hosted in the same region as the Address resource.

    Traffic to and from that instance to Internet requires that an instance has an external IP address assigned to the instance. If an instance doesn't have an external IP address, it can only access other instances and will not be able to reach the Internet.

    Zone resources

    A zone is an independent entity in a specific geographical location where you can run your resources. For example, a zone named us-central1-a indicates a location in the central United States. Choosing a zone is important for several reasons:

    Handling failures
    It is important to distribute your resources across multiple zones to plan for scheduled or unscheduled zone outages. Since each zone is an independent entity, zone failures should not affect other zones. If a zone becomes unavailable, you can transfer traffic to another zone, allowing your services to remain running in the face of failures. For more information about distributing your resources and designing a robust system, see Designing Robust Systems .
    Decreased latency
    To decrease latency, you may want to choose a zone that is close to your point of service. For example, if you mostly have customers on the West Coast of the US, then you may want to choose a zone that is close to that area, in order to decrease latency between your virtual machine instances and your customers.

    Resources that are hosted in a zone are called per-zone resources. Zone-specific resources, or per-zone resources, are unique to that zone and are only usable by other resources in the same zone. For example, an instance is a per-zone resource. When you create an instance, you must provide the zone where the instance should live. The instance can access other resources within the same zone, and can access global resources, but it cannot access other per-zone resources in a different zone, such as a Disk resource.

    You can see a list of available zones using gcloud compute with the zones list command: 

    $ gcloud compute zones list

    Per-zone resources include:

    Instances
    A virtual machine instance must reside within a zone and can access global resources or resources within the same zone.
    Disks
    A Disk resource can only be accessed by other instances within the same zone. For example, you can only attach a disk in the same zone as the instance; you cannot attach a disk to an instance in another zone.
    Machine types
    Machine types are per-zone resources. Instances and disks can only uses machine types that are in the same zone.
    Per-zone operations

    Operations are both a per-zone resource and a global resource. If you are performing an operation on a resource that lives within a zone, the operation is considered a per-zone operation. For example, inserting an instance is considered a per-zone operation, because the operation is being performed on a zone-specific resource, an instance.

    Most zonal resources are described briefly below.

    Instance resource

    Instances (virtual machine instances) are the heart of Google Compute Engine. A Google Compute Engine instance is a virtual machine running on a Linux configuration. You can choose to customize as little or as much of your instances as you would like, including customizing the hardware, OS, disk, and other configuration options. You can start and customize instances individually with very few restrictions and you have root privileges on any instance that you start. An instance is a member of a single project and a single zone. Instances cannot be shared across zones or projects.

    Instances are a per-zone resource, so all requests to an instance require a zone specification.

    For more information, see Instances .

    Machine type resources

    An instance's machine type determines the number of cores, the amount of memory, and the number of persistent disks allowed your virtual machine instance. Machine types are a zonal resource, so you can only use machine types that are in the same zone as your instances. Some machine types are not available in all zones.

    For more information, see Machine types .

    Disk Resources

    A persistent disk is persistent network storage that you can attach and detach between instances. Persistent disks live as long as you need them to and can be tied to the life of the instance or can live beyond the life of the instance. Instances must store their data on a persistent disk and you can create both root persistent disk and data persistent disks.

    All instances must use a root persistent disk which contains an operating system and root filesystem from which the instance boots. Data persistent disks do not contain a root filesystem but act as additional storage for an instance. You can attach multiple persistent disks to an instance or attach a single persistent disk to multiple instances in read- only mode.

    Disk Encryption

    All information stored on persistent disks is encrypted before being written to physical media, and the keys are tightly controlled by Google.

    For more information, see Disks .

    Aggregate Lists

    By default, list requests to resource collections return a list of resources in a particular control plane. For example, when you query the API for a list of Instance resources, you must provide the zone for which you want to list instances. To list resources across all zones or regions, you can perform an aggregate list query. Each per-region and per-zone resource has an aggregate list URI that can be queried to list all resources of that type. For example, to list all instances across all zones, you can make a request to the following URI: 

    https://www.googleapis.com/compute/v1/project/<project-id>/aggregated/instances

    Similarly, to list all addresses across all regions, make a request to the following URI: 

    https://www.googleapis.com/compute/v1/project/<project-id>/aggregated/addresses

    For more information, review the aggregateList method for that resource.

    Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

    Authentication required

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

    Signing you in...

    Google Developers needs your permission to do that.