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)



Replica Pools

Limited Preview

This is a Limited Preview release of Replica Pools. As a result, it might be changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA or deprecation policy. Request to be whitelisted to use this feature .


Google Compute Engine Replica Pools provides the ability to create and manage homogeneous "pools" of Compute Engine virtual machine instances ("replicas") from a common template. For example, you can create a pool with 50 homogeneous replicas and you can use the Replica Pool API to resize, update, or delete replicas from your pool. A Replica Pool template can define attributes of an instance such as its base image, the details of any attached disks, attached networking objects and a startup script to be executed after the instance has booted. The Replica Pool service can perform regular health checking on replicas within a pool, and can restart or re-build replicas that fail to respond appropriately. Replica Pools can be used as target pools for the purposes of Load Balancing .

The Replica Pool API is recommended for users who need a service to create and manage a large number of homogeneous resources, that occasionally require simple tasks such as resizing the number of resources, or updating the attributes of the specified resources.

Replica Pools may also be created via the Google Cloud Deployment Manager service. If you would like a more full-featured service with more control over your Cloud resources, such as the ability to provision multiple Replica Pools simultaneously, or to provision them in concert with other resource types at the same time, you should consider using this service to manage your Replica Pools.

Contents

Sign up

Before you can sign up for the Replica Pool service, you must first sign up and enable the correct APIs. Follow the instructions below to sign up for the service.

Enable the Compute Engine API

The Replica Pool service requires access to Compute Engine resources. You must first enable the Compute Engine API before enabling Replica Pools.

To sign up and enable Compute Engine, see the Compute Engine signup instructions .

Request access to the service

The Replica Pool API is currently in Limited Preview and requires that you request access to the service before you can use it.

Request access

Enable the Replica Pool API

Once you have given access to the API, you must enable it for your Google Developers Console project.

Enable the API and select your Google Compute Engine project.

Overview

Compute Engine Replica Pool makes it easy to create and manage a large number of homogeneous resources, providing the ability to resize pools, update replicas, and set up health checking when necessary.

There are two types of available resources in the Replica Pool service: the Replica resource, which represents a single virtual machine instance, and the Pool resource, which can contain any number of replicas. Replicas are not directly created by you. Instead, you must create a pool, which in turn provisions replicas based on the attributes you define. For more information, see Creating your first replica pool

Pool resource

A Pool resource can contain any number of Replica resources. Rather than interacting with individual replicas, you manage all your replicas through the pool itself. For example, to create any replicas, you must define a Pool resource with a template of your desired replicas, along with the number of replicas you want in the pool. The creation of your pool automatically creates your replicas as well.

Similarly, when you want resize your pool, you can make a request to your replica pool, rather than manually interact with your replicas. Replica pools and their replicas live in zones . Zones are independent of each other and you can decide which zone your replica pools should live in during initial creation of the replica pool.

For more information, see the Pools reference documentation .

Replica resource

Replicas represent the instantiation of a certain resource. Currently, replicas can only be used to create Compute Engine virtual machine instances.

A single replica represents a single virtual machine instance. Each replica must live within a pool and users must manage their replicas through the pool rather than dealing with the replica directly. To create replicas, you must provide a template for your replicas when you create your pool. Your replicas will automatically be created at the same as your pool.

For more information, see the Replicas reference documentation .

Quotas

The Replica Pool API imposes the following quota limits, in addition to the Compute Engine quota and API rate limits

Resource quotas:

  • 5 Pools per project
  • 500 Replicas per pool

API rate limits

  • 50,000 requests/day
  • 20 requests/second

Create a replica pool

Creating your first replica pool is a straightforward process. This guide describes how to set up and start a replica pool through the API using the Google APIs Python client library . This guide also assumes basic Python knowledge.

This guide is intended for users who are new to the Replica Pool API and would like a step-by-step guide that explains how to start a replica pool. If you are comfortable using the Replica Pool service, you might consider reviewing more advanced documentation, such as how to define replica pool templates .

Setup

Before you can start this exercise:

Create your script

To start, create a file named hello-world.py in a folder of your choosing. There a couple of packages you must import into your script, such as the client library, authorization packages, and so on. Add the following import lines to the top of your file: 

#!/usr/bin/python

import logging
import sys
import argparse
import httplib2
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from oauth2client import tools
from oauth2client.tools import run_flow
from apiclient.discovery import build
import json

Authorize access

This sample uses OAuth 2.0 authorization. You will need to create a client ID and client secret, and use both with the oauth2client library. By default, the oauth2 library is included in the google-api-python-client library, which you should have downloaded in the Setup section.

To find your project's client ID and client secret, do the following:

  1. Go to the Google Developers Console .
  2. Select a project, or create a new one.
  3. In the sidebar on the left, expand APIs & auth . Next, click APIs . In the list of APIs, make sure the status is ON for the Google Compute Engine API.
  4. In the sidebar on the left, select Credentials .
  5. If you haven't done so already, create your project's OAuth 2.0 credentials by clicking Create new Client ID , and providing the information needed to create the credentials.
  6. Look for the Client ID and Client secret in the table associated with each of your credentials.

Note that not all types of credentials use both a client ID and client secret and won't be listed in the table if they are not used.

When prompted:

  1. Select Installed application .
  2. Select Other under the Installed application type .
  3. Once you have created your client ID and secret, save it locally by clicking Download JSON and naming the file client_secrets.json in the same directory as hello-world.py.

Next, add the following authorization code, shown in boldface, to your file: 

#!/usr/bin/python

import logging
import sys
import argparse
import httplib2
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from oauth2client import tools
from oauth2client.tools import run_flow
from apiclient.discovery import build
import json

CLIENT_SECRETS = "client_secrets.json"
MANAGE_SCOPE = "https://www.googleapis.com/auth/ndev.cloudman https://www.googleapis.com/auth/devstorage.full_control"
OAUTH2_STORAGE = "oauth.dat"

def main(argv):
  logging.basicConfig(level=logging.INFO)

  parser = argparse.ArgumentParser(
    description=__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter,
    parents=[tools.argparser])

  # Parse the command-line flags.
  flags = parser.parse_args(argv[1:])

  # Perform OAuth 2.0 authorization.
  flow = flow_from_clientsecrets(CLIENT_SECRETS, scope=MANAGE_SCOPE)
  storage = Storage(OAUTH2_STORAGE)
  credentials = storage.get()

  if credentials is None or credentials.invalid:
    credentials = run_flow(flow, storage, flags)
  http = httplib2.Http()
  auth_http = credentials.authorize(http=http)

if __name__ == "__main__":
    main(sys.argv)

If you run the program at this point, you should be prompted to grant access to your Developers Console project. Once you've run through that process in your browser, your application should be authorized to access the Replica Pool API.

Building and initializing the API

To build and initialize the service, add the lines shown in boldface: 

#!/usr/bin/python

import logging
import sys
import argparse
import httplib2
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from oauth2client import tools
from oauth2client.tools import run_flow
from apiclient.discovery import build
import json

CLIENT_SECRETS = "client_secrets.json"
MANAGE_SCOPE = "https://www.googleapis.com/auth/ndev.cloudman https://www.googleapis.com/auth/devstorage.full_control"
OAUTH2_STORAGE = "oauth.dat"

def main(argv):
  logging.basicConfig(level=logging.INFO)

  parser = argparse.ArgumentParser(
    description=__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter,
    parents=[tools.argparser])

  # Parse the command-line flags.
  flags = parser.parse_args(argv[1:])

  # Perform OAuth 2.0 authorization.
  flow = flow_from_clientsecrets(CLIENT_SECRETS, scope=MANAGE_SCOPE)
  storage = Storage(OAUTH2_STORAGE)
  credentials = storage.get()

  if credentials is None or credentials.invalid:
    credentials = run_flow(flow, storage, flags)
  http = httplib2.Http()
  auth_http = credentials.authorize(http=http)

  # Build the service
  replicapool_service = build("replicapool", "v1beta1")

if __name__ == "__main__":
    main(sys.argv)

Great, now you can start making requests to the API! If you run your script now, nothing will happen, but once you start making requests to the API, your script will start displaying more relevant output.

Define your template

To start a replica pool, you must decide how many replicas you want in the pool and the qualities of the replicas. For example, you can decide you need four replicas that use a specific image and are a specific machine type. Replicas are homogeneous, so each replica is exactly the same as the others.

The number of replicas your pool and the specific settings of the replicas are defined in the replica pool template. You can learn more about templates by reading the Defining templates documentation. For the purposes of this quickstart, you will use a fairly simple template that creates four replicas.

In your script, add the lines shown in boldface. This portion of the script defines the template that you will use to use but doesn't actually make the API request yet. 

#!/usr/bin/python

import logging
import sys
import argparse
import httplib2
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from oauth2client import tools
from oauth2client.tools import run_flow
from apiclient.discovery import build
import json

CLIENT_SECRETS = "client_secrets.json"
MANAGE_SCOPE = "https://www.googleapis.com/auth/ndev.cloudman https://www.googleapis.com/auth/devstorage.full_control"
OAUTH2_STORAGE = "oauth.dat"
PROJECT_ID = "your-project-id"
ZONE = "us-central1-a"
POOLNAME = "my-new-pool"
IMAGE_URI = "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20131120"

def main(argv):
  logging.basicConfig(level=logging.INFO)

  parser = argparse.ArgumentParser(
    description=__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter,
    parents=[tools.argparser])

  # Parse the command-line flags.
  flags = parser.parse_args(argv[1:])

  # Perform OAuth 2.0 authorization.
  flow = flow_from_clientsecrets(CLIENT_SECRETS, scope=MANAGE_SCOPE)
  storage = Storage(OAUTH2_STORAGE)
  credentials = storage.get()

  if credentials is None or credentials.invalid:
    credentials = run_flow(flow, storage, flags)
  http = httplib2.Http()
  auth_http = credentials.authorize(http=http)

  # Build the service
  replicapool_service = build("replicapool", "v1beta1")

  # Add replica pool
  addReplicaPool(auth_http, replicapool_service)

def addReplicaPool(auth_http, replicapool_service):
  body = {
    "name": POOLNAME,
    "type": "SMART_VM",
    "initialNumReplicas": "3",
    "template": {
      "vmParams": {
        "machineType": "n1-standard-1",
        "baseInstanceName": "my-replica",
        "disksToCreate": [{
          "boot": "true",
          "initializeParams": {
            "sourceImage": IMAGE_URI,
            "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }]
      }
    }
  }

if __name__ == "__main__":
    main(sys.argv)

The template for the request is always defined in JSON and provided as part of the request body: 

  body = {
    "name": POOLNAME,
    "type": "SMART_VM",
    "initialNumReplicas": "3",
    "template": {
      "vmParams": {
        "machineType": "n1-standard-1",
        "baseInstanceName": "my-replica",
        "disksToCreate": [{
          "boot": "true",
          "initializeParams": {
            "sourceImage": IMAGE_URI,
            "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }]
      }
    }
  }

Next, you will add code to actually make the request.

Add a replica pool

To actually insert a replica pool, make a request to the pools().insert method: 

#!/usr/bin/python

import logging
import sys
import argparse
import httplib2
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from oauth2client import tools
from oauth2client.tools import run_flow
from apiclient.discovery import build
import json

CLIENT_SECRETS = "client_secrets.json"
MANAGE_SCOPE = "https://www.googleapis.com/auth/ndev.cloudman https://www.googleapis.com/auth/devstorage.full_control"
OAUTH2_STORAGE = "oauth.dat"
PROJECT_ID = "your-project-id"
ZONE = "us-central1-a"
POOLNAME = "my-new-pool"
IMAGE_URI = "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20131120"

def main(argv):
  logging.basicConfig(level=logging.INFO)

  parser = argparse.ArgumentParser(
    description=__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter,
    parents=[tools.argparser])

  # Parse the command-line flags.
  flags = parser.parse_args(argv[1:])

  # Perform OAuth 2.0 authorization.
  flow = flow_from_clientsecrets(CLIENT_SECRETS, scope=MANAGE_SCOPE)
  storage = Storage(OAUTH2_STORAGE)
  credentials = storage.get()

  if credentials is None or credentials.invalid:
    credentials = run_flow(flow, storage, flags)
  http = httplib2.Http()
  auth_http = credentials.authorize(http=http)

  # Build the service
  replicapool_service = build("replicapool", "v1beta1")

  # Add replica pool
  addReplicaPool(auth_http, replicapool_service)

def addReplicaPool(auth_http, replicapool_service):
  body = {
    "name": POOLNAME,
    "type": "SMART_VM",
    "initialNumReplicas": "3",
    "template": {
      "vmParams": {
        "machineType": "n1-standard-1",
        "baseInstanceName": "my-replica",
        "disksToCreate": [{
          "boot": "true",
          "initializeParams": {
            "sourceImage": IMAGE_URI,
            "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }]
      }
    }
  }

  request = replicapool_service.pools().insert(projectName=PROJECT_ID, zone=ZONE, body=body)
  response = request.execute(auth_http)

  _printResults(response)

def _printResults(response):

  print json.dumps(response, sort_keys=True, indent=4, separators=(',', ': '))

if __name__ == "__main__":
    main(sys.argv)

Run your script again to add your replica pool! You can check for your new replicas by visiting Google Developers Console and watching for the associated virtual machine instances to be created.

List your replicas

You can also get a list of your replicas as they are being created using the replicas().list method: 

#!/usr/bin/python

import logging
import sys
import argparse
import httplib2
from oauth2client.client import flow_from_clientsecrets
from oauth2client.file import Storage
from oauth2client import tools
from oauth2client.tools import run_flow
from apiclient.discovery import build
import json
CLIENT_SECRETS = "client_secrets.json"
MANAGE_SCOPE = "https://www.googleapis.com/auth/ndev.cloudman https://www.googleapis.com/auth/devstorage.full_control"
OAUTH2_STORAGE = "oauth.dat"
PROJECT_ID = "your-project-id"
ZONE = "us-central1-a"
POOLNAME = "my-new-pool"
IMAGE_URI = "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20131120"

def main(argv):
  logging.basicConfig(level=logging.INFO)

  parser = argparse.ArgumentParser(
    description=__doc__,
    formatter_class=argparse.RawDescriptionHelpFormatter,
    parents=[tools.argparser])

  # Parse the command-line flags.
  flags = parser.parse_args(argv[1:])

  # Perform OAuth 2.0 authorization.
  flow = flow_from_clientsecrets(CLIENT_SECRETS, scope=MANAGE_SCOPE)
  storage = Storage(OAUTH2_STORAGE)
  credentials = storage.get()

  if credentials is None or credentials.invalid:
    credentials = run_flow(flow, storage, flags)
  http = httplib2.Http()
  auth_http = credentials.authorize(http=http)

  # Build the service
  replicapool_service = build("replicapool", "v1beta1")

  '''  # Add replica pool
  addReplicaPool(auth_http, replicapool_service)'''

  # List replicas
  listReplicas(auth_http, replicapool_service)

def addReplicaPool(auth_http, replicapool_service):
  body = {
    "name": POOLNAME,
    "type": "SMART_VM",
    "initialNumReplicas": "3",
    "template": {
      "vmParams": {
        "machineType": "n1-standard-1",
        "baseInstanceName": "my-replica",
        "disksToCreate": [{
          "boot": "true",
          "initializeParams": {
            "sourceImage": IMAGE_URI,
            "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }]
      }
    }
  }

  request = replicapool_service.pools().insert(projectName=PROJECT_ID, zone=ZONE, body=body)
  response = request.execute(auth_http)

  _printResults(response)

def listReplicas(auth_http, replicapool_service):

  request = replicapool_service.replicas().list(projectName=PROJECT_ID, zone=ZONE, poolName=POOLNAME)
  response = request.execute(auth_http)

  _printResults(response)

def _printResults(response):

  print json.dumps(response, sort_keys=True, indent=4, separators=(',', ': '))

if __name__ == "__main__":
    main(sys.argv)

Run your script and it should return something similar to: 

{ "resources": [{
    "name": "my-replica-2o95",
    "selfLink": "https://www.googleapis.com/replicapool/v1beta1/projects/myproject/zones/us-central1-a/pools/my-new-pool/replicas/my-replica-2o95",
    "currentNumReplicas": 4,
    "status": {
      "state": "RUNNING",
      "templateVersion": "",
      "vmLink": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/my-replica-2o95"
    },
    {
    "name": "my-replica-ssuw",
    "selfLink": "https://www.googleapis.com/replicapool/v1beta1/projects/myproject/zones/us-central1-a/pools/my-new-pool/replicas/my-replica-ssuw",
    "currentNumReplicas": 3,
    "status": {
      "state": "RUNNING",
      "templateVersion": "",
      "vmLink": "https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/my-replica-ssuw"
     }
    },
    ...
   }]
 }

That's it! You've started your own replica pool.

Summary

In this quickstart, you were able to:

  1. Authorize to the Replica Pool API
  2. Define a valid template for your replicas
  3. Create a Replica Pool
  4. List your replicas!

You can continue building on this example, or take some time to review other tasks you can do with the Replica Pool service.

How to create a replica pool template

A replica pool takes a template that defines the settings of your individual replicas. The template acts as a blueprint for Replica Pool to create replicas to your specifications. This template must be provided during the creation of the replica pool, which is then used to automatically create your replicas. You can define as many settings for your replicas as you would like, but there are some basic, required settings you must define in your template in order to successfully create replicas.

All replica pool template settings described here are also discussed in detail in the reference documentation .

Defining a template

To create a replica pool template, define the template as part of the body of your request. For example, the follow example uses Google Python Client library to create a new replica pool with the provided template: 

def addReplicaPool(auth_http, replicapool_service):
  body = {
    "name": "my-pool",
    "type": "SMART_VM",
    "initialNumReplicas": "3",
    "template": {
      "vmParams": {
        "machineType": "n1-standard-1",
        "baseInstanceName": "my-vm-rp",
        "disksToCreate": [{
          "boot": true,
          "initializeParams": {
            "sourceImage": "<full-image-uri>",
            "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }]
      }
    }
  }

  request = replicapool_service.pools().insert(projectName=PROJECT_ID, zone=ZONE, body=body)
  response = request.execute(auth_http)

  _printResults(response)

In this example, the template for your replicas is explicitly defined in the vmParams section, which indicates that the replicas should use machine type n1-standard-1, a Debian 7 image, and should start with base instance name of my-vm-rp.

Required template settings

Replica Pool uses the Compute Engine v1 API to create your replicas. The same required configuration options for inserting a single virtual machine instance are also the same required options in your replica pool template. You can still provide any number of the available template settings beyond the required settings but you must provide, at a minimum, the following template fields. 

 body = {
    "name": "my-pool",
    "type": "SMART_VM",
    "initialNumReplicas": "3",
    "template": {
      "vmParams": {
        "machineType": "n1-standard-1",
        "disksToCreate": [{
          "boot": true,
          "initializeParams": {
            "sourceImage": "<full-image-uri>",
            "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }]
      }
    }
  }
"name": string
Sets the replica pool name. You will always refer to this replica pool using this name. Must follow the regex [a-zA-Z0-9-_]{1,28} . For example: 
"name": "my-new-replica-pool"
"type": string
Specifies the type of replicas to create. Currently, only SMART_VM is available. For example: 
"type": "SMART_VM"
"initialNumReplicas": integer
Defines how many replicas you want to create for this replica pool. You must provide at least one replica; it is invalid to provide "0." For example: 
"initialNumReplicas": "3"
"template": nested object
Indicates the beginning of the template. You must provide at least the vmParams field. 
"template": {
  ...
}
"template.vmParams": nested object
Indicates that the next set of template values are parameters for virtual machine instances. 
"template": {
  "vmParams": { ... }
}
"template.vmParams.machineType": string
Sets the machine type for your replicas. For a list of machine types, see the machine types documentation on Compute Engine. Must be a name for the machine type (and not the full URI): 
"machineType": "n1-standard-1"
"template.vmParams.disksToCreate": list
Creates a root persistent disk for each of your replicas. You can also specify the size of the root persistent disk. Provide the following required configuration options. 
"disksToCreate": [{
  "boot": true,
  "initializeParams": {
    "sourceImage": "<full-image-uri>"
  }
}]
Must be the fully-qualified URI to the image when using a public image: 
https://www.googleapis.com/compute/v1/projects/my-project/global/images/debian-7-wheezy-vYYYYMMDD
If using a private image in your project, you can also provide just the image name instead.
"template.vmParams.networkInterfaces": list
Sets the access configs for these replicas. Also creates an ephemeral IP address for each replica. You must provide the following configuration options: "networkInterfaces": [{ network": "network-name", "accessConfigs": [{ "type": "ONE_TO_ONE_NAT", "name": "External NAT" }] }]
network must be the name of a network (rather than the full URI). The accessConfigs settings can be provided as-is. For example: 
"networkInterfaces": [{
  "network": "default",
  "accessConfigs": [{
    "type": "ONE_TO_ONE_NAT",
    "name": "External NAT"
  }]
}]

Caution: Although you can also explicitly set reserved IP address for an instance using the access configs, this will fail if you are creating more than one instance. The Replica Pool API applies the same settings to each replica, but a reserved IP address can only be used for one instance at a time, causing the rest of the replicas to fail during creation.

Useful template settings

There are several useful template settings that are not required for creating a template but provide extra functionality that can be helpful for managing your replicas. For a full list of these settings, see the reference documentation .

"template.action": nested object
The actions parameter is an optional field that allows you to specify Linux commands that will run on your instances after they have been deployed. For example, some actions might install software, run updates, or run specialized bash commands. Actions also allow you to define environment variables. 
"action": {
  "name": "install-apache",
  "commands": [
    "sudo apt-get update"
    "sudo apt-get install apache"
    ...
  ],
  "envVariables: [
    ...
  ]
}
"autoRestart": boolean
Defines whether replicas should be restarted if they experience a failure. Does not apply for user-initiated failures (such as an instance shutdown). By default, this is set to true . 
"autoRestart": "false"
"template.vmParams.baseInstanceName": string
The base instance name to use for these replicas. This must match the regex [a-z]([-a-z0-9]*[a-z0-9])? . If specified, the instances in this replica pool will be named in the format <base-instance-name>-<ID> . The <ID> postfix will be a four character alphanumeric identifier generated by the service. If this is not specified by the user, a random base instance name is generated by the service. 
"baseInstanceName": "my-vm-replicas"
"template.vmParams.version": string
A free-form string to mark the version of the template. This is optional but can be useful to keep track of your template versions as you make updates. 
"version": "v2beta1"
"template.vmParams.disksToAttach[]": list
Attaches persistent disks to your replicas. All disks specified in this field will be attached to all replicas in read-only mode. 
"disksToAttach": [{
  "source": "full-uri-to-disk",
  "type": "PERSISTENT",
  }
]

Updating a replica pool template

After creating your replica pool, you may occasionally need to update the template of your replicas. The Replica Pool API provides the custom pools().updatetemplate method that lets you update the template of a running replica pool.

Updating a replica pool template will apply the new template to all new replicas that are created after the new template has been uploaded (for example, if a resize request is made), and to any replicas that are restarted using the restart() method. Any existing replicas that were there before the new template will not have any new changes from the updated template. You must delete or restart these replicas individually in order for them to pick up the new template properties.

In an update request, you must provide at a minimum all the required fields necessary for defining a template, even if the value of the field remains the same. For example, every template request, whether an update and an initial insert request, must have a machine type defined.

An update request requires a slightly different structure for the template. You do not need to define the template name, type, or number of replicas, and can simply provide the settings of the vmParams field. For example, the following code provides the bare minimum for an update template request: 

def updateTemplate(auth_http, replicapool_service):
  body = {
      "vmParams": {
        "version": "v2" # Not required but useful
        "machineType": "n1-standard-2",
        "disksToCreate": [{
          "boot": true,
          "initializeParams": {
            "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-vYYYYMMDD",
             "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }]
      }
   }

  request = replicapool_service.pools().updatetemplate(projectName=PROJECT_ID, zone=ZONE, body=body, poolName=POOLNAME)
  response = request.execute(auth_http)

  _printResults(response)

Notice that you only need to provide fields within the vmParams field. The same required parameters described above are still required for the new template. Also notice that there is now an optional, but useful new field called version . The version field lets you define a free-form string that distinguishes this template from other template versions. Although you don't need to provide this, it can be useful to keep track of the version of a template you are using.

Resizing a replica pool

At any point after you have created your replica pool, you can resize the pool to a different number of replicas. You may want to do this if the original number of replicas is no longer necessary and deleting some replicas will result in a lower monthly charge from Compute Engine, or you may want to resize the replica pool to a larger number of replicas than initially intended.

When you resize a replica pool to add more replicas, the new replicas will use the latest template that was provided to the pool. If you need to update your template, you should use the pools().updatetemplate method before resizing your replica pool.

When resizing to a smaller number of replicas, the Replica Pool service chooses which replicas to delete, until your replica pool contains the desired number of replicas. There is no way to explicitly tell the Replica Pool service which replicas to delete.

Using the resize method

To use the resize method, make a call to the resize() method, providing the project ID, the pool name, the zone for the request, and the desired number of replicas you want. For example, in the Google Python Client library, a request might look like the following: 

def resizeReplicaPool(auth_http, replicapool_service):
   request = replicapool_service.pools().resize(projectName=PROJECT_ID, poolName=POOLNAME, zone=ZONE, initialNumReplicas=2)
   response = request.execute(auth_http)

   _printResults(response)

Using the command-line tool to resize

To resize your pool using the command-line tool , run: 

$ gcloud preview replica-pools --zone ZONE resize --new-size NEW-SIZE POOL-NAME

Setting up health checking

The Replica Pool API lets you set up application-level health checking to check the state of applications or services that are running on each replica, using health check parameters that you define. For example, you can set up a health check to send requests to a local host path on each replica to determine if your application is healthy.

Replica Pool application health checks are designed to be used for checking the health of applications or services running on your replicas. While you can check on the state of a replica fairly easily, it is more difficult to check on the actual state of running applications on your replicas. For example, consider a setup where you have multiple replicas that serve multiple copies of a website. If your webserver dies on any of these replicas, it won't actually affect the replica state, which would still be running. However, there is no way for you to know that your application or webserver has failed. By providing health checking, you can check the state of your application using a path that you provide, within the parameters you define (such as how many failures would be considered unhealthy, how long it should takes for a health check to complete before it times out, and other options).

After a replica is marked as unhealthy, the Replica Pool service will shut down the instance, causing the replica state to change to FAILING . If the replica has been set to auto restart, the Replica Pool service deletes and recreates the virtual machine instance with the same original settings. If the instance has not been set to auto restart, the replica remains in the FAILING state.

If an instance cannot be recreated after a certain number of tries, Replica Pool marks the replica as PERMANENTLY FAILING .

Set up health checking

When you initiate health checking with the default settings, you must provide two required settings:

"name": string
The name of the health check object.
"path": string
The local host path that should be used for health requests.

There are other options that are not required, but do provide default settings:

"checkIntervalSec": integer
Determines how often, in seconds, to make HTTP requests for the health check. The default is every 5 seconds.
"healthyThreshold": integer
Sets the number of consecutive health check requests that must succeed before the replica is considered healthy. The default is 2 successful consecutive health checks. Only a HTTP 2xx response is considered successful.
"timeoutSec": integer
How long to wait in seconds before claiming failures for a health check. The default is 5 seconds.
"unhealthyThreshold": string
The number of consecutive health check requests that need to fail to consider the replica unhealthy. The default value is 2. An unhealthy request is anything other than a HTTP 2xx response.

To set up health checking, include a health check object in your replica pool template. For example, the following template creates a replica pool with a health check object that uses the localhost/healthCheck path: 

def addReplicaPoolWithHealthChecks(auth_http, replicapool_service):
  body = {
    "name": "my-replica-pool",
    "type": "SMART_VM",
    "initialNumReplicas": "3",
    "template": {
      "vmParams": {
        "machineType": "n1-standard-1",
        "baseInstanceName": "instance-rp2",
        "disksToCreate": [{
          "boot": true,
          "initializeParams": {
            "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20131120",
            "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }],
        "healthChecks": [{
          "name": "testhealth",
          "path": "localhost/healthCheck"
        }]
      }
    }
  }

  request = replicapool_service.pools().insert(projectName="myproject", zone="us-central1-a", body=body)
  response = request.execute(auth_http)

  _printResults(response)

Remove or change health checks

To add or remove a health check, update your template with the desired changes and perform an updateTemplate() request: 

def updateTemplate(auth_http, replicapool_service):
  body = {
      "vmParams": {
        "machineType": "n1-standard-1",
        "baseInstanceName": "instance-rp2",
        "disksToCreate": [{
          "boot": true,
          "initializeParams": {
            "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20131120",
            "diskSizeGb": "100"
          }
        }],
        "networkInterfaces": [{
          "network": "default",
          "accessConfigs": [{
            "type": "ONE_TO_ONE_NAT",
            "name": "External NAT"
          }]
        }],
        "healthChecks": [{
          "name": "test2",
          "path": "localhost/new-healthcheck"
        }]
      }
   }

  request = replicapool_service.pools().updatetemplate(projectName="myproject", zone="us-central1-a", body=body, poolName=POOLNAME)
  response = request.execute(auth_http)

  _printResults(response)

Using the command-line tool

Replica Pool offers a command-line tool that allows you to manage your Pool and Replicas. To use the tool, you must download and install the Cloud SDK tool if you do not already have it installed.

Authentication

If this is your first time running the Cloud SDK tool, authenticate to it by running: 

$ gcloud auth login

If prompted for a project ID, you can provide one so you can omit the project in future requests, or you can leave it blank and provide the project on a case-by-case basis. You can also reset the project ID later by running: 

$ gcloud config set project PROJECT

Invoking the command-line tool

To use the Replica Pool service in the command-line, you must enable preview features by running: 

$ gcloud components update preview

Once you have run the above command, you can invoke the command-line tool for Replica Pool like so: 

$ gcloud preview replica-pools COMMAND

Use the following commands to help manage your pools and replicas.

Note: When managing pools and replicas, you must always provide the --zone flag, which must appear before the desired command (e.g. --zone ZONE list ).

List pools 

$ gcloud preview replica-pools --zone ZONE list

To list pools using the API, see the pools.list() method .

Create a pool

To create a pool, use the create command: 

$ gcloud preview replica-pools --zone ZONE  create --size NUM-REPLICAS --template TEMPLATE-FILE POOL-NAME

Your TEMPLATE-FILE file must be a JSON formatted template file and contain the settings of your replicas starting from the template field. For example, a sample template file might look like the following: 

{ "template": {
    "vmParams": {
      "machineType": "n1-standard-1",
      "baseInstanceName": "my-replica",
      "disksToCreate": [{
        "boot": "true",
        "initializeParams": {
          "sourceImage": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-7-wheezy-v20131120",
          "diskSizeGb": "100"
         }
       }],
     "networkInterfaces": [{
       "network": "default",
       "accessConfigs": [{
         "type": "ONE_TO_ONE_NAT",
         "name": "External NAT"
       }]
     }]
   }
  }
}

To create a pool using the API, see the pools.insert() method .

Get information about a pool 

$ gcloud preview replica-pools --zone ZONE get POOL-NAME

To get information about your replica pool using the API, see the pools.get() method .

Resize a pool 

$ gcloud preview replica-pools --zone ZONE resize --new-size NEW-SIZE POOL-NAME

For details about the resize behavior, see Resizing a replica pool .

Delete a replica pool

Deleting a replica pool deletes all replicas in the pool and their associated virtual machine instances. Optionally, you can provide a list of virtual machine instances that you would like to keep and the Replica Pool service won't delete those instances. You can also delete a single replica . 

$ gcloud preview replica-pools --zone ZONE delete POOL-NAME --abandon-instance INSTANCE-1 INSTANCE-2 .. INSTANCE-N

To delete your replica pool using the API, see the pools.delete() method .

Update a replica pool template 

$ gcloud preview replica-pools --zone ZONE update-template --template TEMPLATE-FILE POOL-NAME

The new template is applied to all new replicas added to the pool and to all replicas that are restarted after the template file is updated. Existing replicas that aren't restarted retain their original template.

To update your template using the API, see the pools.updatetemplate() method .

List all replicas 

$ gcloud preview replica-pools --zone ZONE replicas --pool POOL-NAME list

To list your replicas using the API, see the replicas.list() method .

Get a replica

To get information about a single replica, run this command: 

$ gcloud preview replica-pools --zone ZONE replicas --pool POOL-NAME get REPLICA-NAME

To get information about a replica using the API, see the replicas.get() method .

Restart a replica 

$ gcloud preview replica-pools --zone ZONE replicas --pool POOL-NAME restart REPLICA-NAME

Currently, it is only possible to restart a single replica at a time.

To restart a replica using the API, see the replicas.restart() method .

Delete a replica

In some cases, you may want to delete a single replica. 

$ gcloud preview replica-pools --zone ZONE replicas --pool POOL-NAME delete REPLICA-NAME [--abandon-instance]

By default, this command deletes the underlying virtual machine instance along with the specified replica. If you want to keep the virtual machine instance, but delete the replica, include the --abandon-instance flag.

To delete a replica using the API, see the replicas.delete() method .

Getting help and providing feedback

For feedback and questions, please email the Limited Preview discussion group .

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.