vmproxy

Documentation

Overview

Package vmproxy provides tools to proxy App Engine requests to on-demand Compute Engine instances.

Google App Engine is a PaaS cloud infrastructure that scales automatically, and is very cost-effective. One nice features of App Engine is the ability to scale apps to 0 instances. This is a perfect fit for low-traffic websites, or to run sporadic background tasks, so you only pay for the time you are serving requests.

However, App Engine runs your apps on a sandboxed environment. This limits what you can do with your application instances, to a confined subset of supported languages and features.

To remove this limitation, you have to either move to Compute Engine virtual machines (IaaS) or use a Docker Container cluster (Google Container Engine) to host your applications. Both are ideal to improve your DevOps experiences and you can pick the best fit for you use case. There is a new option available, that boils down to running Docker containers and VMs, but leaveraging most other App Engine features, called Managed VMs.

The problem with the previous alternatives is that you can't scale to zero. You need at least one VM aways on. For some use cases, this is a deal breaker.

This package attempts to solve this by allowing you to easily launch VMs on-demand, and proxy requests from App Engine to yor VM.

How it works

The requests handled by a vmproxy.VM, are routed to a configured Compute Engine instance. If the instance is not up, a new instance is created. You must specify the instance name, so we don't create multiple instances.

The thadeoff you do by using this package is that the very first request will launch a new virtual machine, and this may take several seconds depending on your VM initialization.

It is not the scope of this tool to provide any scalability features, such as load-balacing multiple VMs. This is a simple proxy, that routes requests to VMs, bringing them up on demmand. It is intended to serve very small, backend, and non-user-facing traffic, as loading requests here take several tens of seconds.

ATTENTION! The default behavior of the vmproxy.VM is to launch *PREEMPTIBLE* VMs, and you must explicity disable this with the NotPreemptible flag set to `true`.

Compute Engine instances are terminated by the App Engine instance /_ah/stop handler (must be mapped by the user), or by the Compute Engine when it preempts your instance.

Running as a backend module

This package is designed to handle requests as a backend module, configured with Basic Scaling [1].

Here is a basic usage of this script.

startupScript = `
apt-get update && apt-get upgrade --yes;
apt-get install nginx --yes`

nginx = &vmproxy.VM{
	Path: "/",
	Instance: vmproxy.Instance{
		Name:          "backend",
		Zone:          "us-central1-a",
		MachineType:   "f1-micro",
		StartupScript: startupScript,
		// NotPreemptible: true // Uncomment to use non-preemptible VMs.
	},
}
http.Handle("/", nginx)

References

[1] https://cloud.google.com/appengine/docs/managed-vms/
[2] https://cloud.google.com/appengine/docs/go/modules/

Index

• Constants
• Variables
• type Instance
• type VM
  • func (vm *VM) Delete(c context.Context) (err error)
  • func (vm *VM) IsRunning(c context.Context) bool
  • func (vm *VM) PublicIP(c context.Context) string
  • func (vm *VM) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (vm *VM) Start(c context.Context) (err error)
  • func (vm *VM) Stop(c context.Context) (err error)

Constants

const (
	// DefaultImageName, currently points to Debian Jessie.
	// TODO(ronoaldo): discover latest debian-8 VM name when launching.
	DefaultImageName = "debian-8-jessie-v20150818"
	// DefaultMachineType used to launch an instance.
	DefaultMachineType = "n1-standard-1"
	// ResourcePrefix is the prefix URL to build resource URIs,
	// such as image, disks and instance URIs.
	ResourcePrefix = "https://www.googleapis.com/compute/v1/projects"
)

Variables

var (
	ErrStartupTimeout = errors.New("vmproxy: startup timeout")
)

Types

type Instance

type Instance struct {
	// Name is the VM unique Name.
	// Mandatory, and must be unique to the project.
	Name string

	// Compute Engine Zone, where the VM will launch.
	// Mandatory.
	Zone string

	// Image to use to boot the instance.
	// Defaults to debian-8-backports if empty.
	Image string

	// Machine type to use. Defaults to n1-standard-1.
	MachineType string

	// Optional instance tags. Defaults to http-server.
	// Use this to setup firewall rules.
	Tags []string

	// Metadata to add to the instance description.
	Metadata map[string]string

	// Optional startup script URL to be added to the VM.
	StartupScript    string
	StartupScriptURL string

	// BootDiskSize in base-2 GB
	BootDiskSize int64

	// Marks the instance as a preemptible VM.
	NotPreemptible bool

	// Scopes to be used when creating the instance.
	// No scopes by default.
	Scopes []string
}

Instance represents basic information about a single Compute Engine VM.

type VM

type VM struct {
	// VM instance configuration.
	Instance Instance

	// Path to forward requests to. Mandatory.
	Path string
	// Path used to check if the VM is ready to serve traffic.
	// Defaults to Path.
	HealthPath string
	// Hostname is sent as a Host: header, if specified,
	// for both health-check and proxy forwarding.
	Hostname string
	// Port to forward requests to. Defaults to 80 if 0.
	Port int
	// contains filtered or unexported fields
}

VM manages and proxies requests from App Engine to the configured Compute Engine VM.

func (*VM) Delete

func (vm *VM) Delete(c context.Context) (err error)

Delete put's the instance in TERMINATED state and remove it. All attached disks marked for deletion are also removed.

func (*VM) IsRunning

func (vm *VM) IsRunning(c context.Context) bool

IsRunning returns true if the instance is running

func (*VM) PublicIP

func (vm *VM) PublicIP(c context.Context) string

PublicIP returns the current instance IP. The value is cached in-memory, so it may return stale results.

func (*VM) ServeHTTP

func (vm *VM) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles the HTTP request, by forwarding it to the target VM. If the VM is not up, it will be launched.

func (*VM) Start

func (vm *VM) Start(c context.Context) (err error)

Start launches a new Compute Engine VM and wait until the health path is ready.

References:

https://github.com/google/google-api-go-client/blob/master/examples/compute.go
https://godoc.org/golang.org/x/oauth2/google#example-AppEngineTokenSource

func (*VM) Stop

func (vm *VM) Stop(c context.Context) (err error)

Stop puts the instance in the TERMINATED state, but does not delete it.