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 ¶
Functions ¶
This section is empty.
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 ¶
Delete put's the instance in TERMINATED state and remove it. All attached disks marked for deletion are also removed.
func (*VM) IsRunning ¶
IsRunning returns true if the instance is running
func (*VM) PublicIP ¶
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 ¶
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
Source Files
Directories