Getting Started With Google Compute Engine¶

Initial Profile¶

Set up an initial profile at /etc/salt/cloud.profiles or /etc/salt/cloud.profiles.d/gce.conf:

my-gce-profile:
  image: centos-6
  size: n1-standard-1
  location: europe-west1-b
  network: default
  subnetwork: default
  labels: '{"name": "myinstance"}'
  tags: '["one", "two", "three"]'
  metadata: '{"one": "1", "2": "two"}'
  use_persistent_disk: True
  delete_boot_pd: False
  ssh_interface: public_ips
  external_ip: "ephemeral"

image¶

Image is used to define what Operating System image should be used to for the instance. Examples are Debian 7 (wheezy) and CentOS 6. Required.

size¶

A 'size', in GCE terms, refers to the instance's 'machine type'. See the on-line documentation for a complete list of GCE machine types. Required.

location¶

A 'location', in GCE terms, refers to the instance's 'zone'. GCE has the notion of both Regions (e.g. us-central1, europe-west1, etc) and Zones (e.g. us-central1-a, us-central1-b, etc). Required.

network¶

Use this setting to define the network resource for the instance. All GCE projects contain a network named 'default' but it's possible to use this setting to create instances belonging to a different network resource.

subnetwork¶

Use this setting to define the subnetwork an instance will be created in. This requires that the network your instance is created under has a mode of 'custom' or 'auto'. Additionally, the subnetwork your instance is created under is associated with the location you provide.

labels¶

This setting allows you to set labels on your GCE instances. It should be a dictionary and must be parse-able by the python ast.literal_eval() function to convert it to a python dictionary.

tags¶

GCE supports instance/network tags and this setting allows you to set custom tags. It should be a list of strings and must be parse-able by the python ast.literal_eval() function to convert it to a python list.

metadata¶

GCE supports instance metadata and this setting allows you to set custom metadata. It should be a hash of key/value strings and parse-able by the python ast.literal_eval() function to convert it to a python dictionary.

use_persistent_disk¶

Use this setting to ensure that when new instances are created, they will use a persistent disk to preserve data between instance terminations and re-creations.

delete_boot_pd¶

In the event that you wish the boot persistent disk to be permanently deleted when you destroy an instance, set delete_boot_pd to True.

ssh_interface¶

Specify whether to use public or private IP for deploy script.

Valid options are:

• private_ips: The salt-master is also hosted with GCE

• public_ips: The salt-master is hosted outside of GCE

external_ip¶

Per instance setting: Used a named fixed IP address to this host.

Valid options are:

• ephemeral: The host will use a GCE ephemeral IP

• None: No external IP will be configured on this host.

Optionally, pass the name of a GCE address to use a fixed IP address. If the address does not already exist, it will be created.

ex_disk_type¶

GCE supports two different disk types, pd-standard and pd-ssd. The default disk type setting is pd-standard. To specify using an SSD disk, set pd-ssd as the value.

ip_forwarding¶

GCE instances can be enabled to use IP Forwarding. When set to True, this options allows the instance to send/receive non-matching src/dst packets. Default is False.

Profile with scopes¶

Scopes can be specified by setting the optional ex_service_accounts key in your cloud profile. The following example enables the bigquery scope.

my-gce-profile:
 image: centos-6
  ssh_username: salt
  size: f1-micro
  location: us-central1-a
  network: default
  subnetwork: default
  labels: '{"name": "myinstance"}'
  tags: '["one", "two", "three"]'
  metadata: '{"one": "1", "2": "two",
              "sshKeys": ""}'
  use_persistent_disk: True
  delete_boot_pd: False
  deploy: False
  make_master: False
  provider: gce-config
  ex_service_accounts:
    - scopes:
      - bigquery

Email can also be specified as an (optional) parameter.

my-gce-profile:
...snip
  ex_service_accounts:
    - scopes:
      - bigquery
      email: default

There can be multiple entries for scopes since ex-service_accounts accepts a list of dictionaries. For more information refer to the libcloud documentation on specifying service account scopes.

Create¶

When creating a disk, you can create an empty disk and specify its size (in GB), or specify either an 'image' or 'snapshot'.

salt-cloud -f create_disk gce disk_name=pd location=us-central1-b size=200

Delete¶

Deleting a disk only requires the name of the disk to delete

salt-cloud -f delete_disk gce disk_name=old-backup

Attach¶

Attaching a disk to an existing instance is really an 'action' and requires both an instance name and disk name. It's possible to use this ation to create bootable persistent disks if necessary. Compute Engine also supports attaching a persistent disk in READ_ONLY mode to multiple instances at the same time (but then cannot be attached in READ_WRITE to any instance).

salt-cloud -a attach_disk myinstance disk_name=pd mode=READ_WRITE boot=yes

Detach¶

Detaching a disk is also an action against an instance and only requires the name of the disk. Note that this does not safely sync and umount the disk from the instance. To ensure no data loss, you must first make sure the disk is unmounted from the instance.

salt-cloud -a detach_disk myinstance disk_name=pd

Show disk¶

It's also possible to look up the details for an existing disk with either a function or an action.

salt-cloud -a show_disk myinstance disk_name=pd
salt-cloud -f show_disk gce disk_name=pd

Create snapshot¶

You can take a snapshot of an existing disk's content. The snapshot can then in turn be used to create other persistent disks. Note that to prevent data corruption, it is strongly suggested that you unmount the disk prior to taking a snapshot. You must name the snapshot and provide the name of the disk.

salt-cloud -f create_snapshot gce name=backup-20140226 disk_name=pd

Delete snapshot¶

You can delete a snapshot when it's no longer needed by specifying the name of the snapshot.

salt-cloud -f delete_snapshot gce name=backup-20140226

Show snapshot¶

Use this function to look up information about the snapshot.

salt-cloud -f show_snapshot gce name=backup-20140226

Create network¶

New networks require a name and CIDR range if they don't have a 'mode'. Optionally, 'mode' can be provided. Supported modes are 'auto', 'custom', 'legacy'. Optionally, 'description' can be provided to add an extra note to your network. New instances can be created and added to this network by setting the network name during create. It is not possible to add/remove existing instances to a network.

salt-cloud -f create_network gce name=mynet cidr=10.10.10.0/24
salt-cloud -f create_network gce name=mynet mode=auto description=some optional info.

Destroy network¶

Destroy a network by specifying the name. If a resource is currently using the target network an exception will be raised.

salt-cloud -f delete_network gce name=mynet

Show network¶

Specify the network name to view information about the network.

salt-cloud -f show_network gce name=mynet

Create subnetwork¶

New subnetworks require a name, region, and CIDR range. Optionally, 'description' can be provided to add an extra note to your subnetwork. New instances can be created and added to this subnetwork by setting the subnetwork name during create. It is not possible to add/remove existing instances to a subnetwork.

salt-cloud -f create_subnetwork gce name=mynet network=mynet region=us-central1 cidr=10.0.10.0/24
salt-cloud -f create_subnetwork gce name=mynet network=mynet region=us-central1 cidr=10.10.10.0/24 description=some info about my subnet.

Destroy subnetwork¶

Destroy a subnetwork by specifying the name and region. If a resource is currently using the target subnetwork an exception will be raised.

salt-cloud -f delete_subnetwork gce name=mynet region=us-central1

Show subnetwork¶

Specify the subnetwork name to view information about the subnetwork.

salt-cloud -f show_subnetwork gce name=mynet

Create address¶

Create a new named static IP address in a region.

salt-cloud -f create_address gce name=my-fixed-ip region=us-central1

Delete address¶

Delete an existing named fixed IP address.

salt-cloud -f delete_address gce name=my-fixed-ip region=us-central1

Show address¶

View details on a named address.

salt-cloud -f show_address gce name=my-fixed-ip region=us-central1

Create firewall¶

You'll need to create custom firewall rules if you want to allow other traffic than what is described above. For instance, if you run a web service on your instances, you'll need to explicitly allow HTTP and/or SSL traffic. The firewall rule must have a name and it will use the 'default' network unless otherwise specified with a 'network' attribute. Firewalls also support instance tags for source/destination

salt-cloud -f create_fwrule gce name=web allow=tcp:80,tcp:443,icmp

Delete firewall¶

Deleting a firewall rule will prevent any previously allowed traffic for the named firewall rule.

salt-cloud -f delete_fwrule gce name=web

Show firewall¶

Use this function to review an existing firewall rule's information.

salt-cloud -f show_fwrule gce name=web

HTTP Health Check¶

HTTP Health Checks can be used as a means to toggle load-balancing across instance members, or to detect if an HTTP site is functioning. A common use-case is to set up a health check URL and if you want to toggle traffic on/off to an instance, you can temporarily have it return a non-200 response. A non-200 response to the load-balancer's health check will keep the LB from sending any new traffic to the "down" instance. Once the instance's health check URL beings returning 200-responses, the LB will again start to send traffic to it. Review Compute Engine's documentation for allowable parameters. You can use the following salt-cloud functions to manage your HTTP health checks.

salt-cloud -f create_hc gce name=myhc path=/ port=80
salt-cloud -f delete_hc gce name=myhc
salt-cloud -f show_hc gce name=myhc

Load-balancer¶

When creating a new load-balancer, it requires a name, region, port range, and list of members. There are other optional parameters for protocol, and list of health checks. Deleting or showing details about the LB only requires the name.

salt-cloud -f create_lb gce name=lb region=... ports=80 members=w1,w2,w3
salt-cloud -f delete_lb gce name=lb
salt-cloud -f show_lb gce name=lb

You can also create a load balancer using a named fixed IP addressby specifying the name of the address. If the address does not exist yet it will be created.

salt-cloud -f create_lb gce name=my-lb region=us-central1 ports=234 members=s1,s2,s3 address=my-lb-ip

Attach and Detach LB¶

It is possible to attach or detach an instance from an existing load-balancer. Both the instance and load-balancer must exist before using these functions.

salt-cloud -f attach_lb gce name=lb member=w4
salt-cloud -f detach_lb gce name=lb member=oops