stitch

package
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 12, 2017 License: MIT Imports: 17 Imported by: 0

README

Quilt.js

Documentation for quilt.js

Container

The Container object represents a container to be deployed.

Specifying the Image

The first argument of the Container constructor is the image that container should run.

If a string is supplied, the image at that repository is used.

Dockerfile

Instead of supplying a link to a pre-built image, Quilt also support building images in the cluster. When specifying a Dockerfile to be built, an Image object must be passed to the Container constructor.

For example,

new Container(new Image("my-image-name",
  "FROM nginx\n" +
  "RUN cd /web_root && git clone github.com/my/web_repo"
))

would deploy an image called my-image-name built on top of the nginx image, with the github.com/my/web_repo repository cloned into /web_root.

If the Dockerfile is saved as a file, it can simply be read in:

new Container(new Image("my-image-name", read("./Dockerfile")))

If a user runs a spec that uses a custom image, then runs another spec that changes the contents of that image's Dockerfile, the image is re-built and all containers referencing that Dockerfile are restarted with the new image.

If multiple containers specify the same Dockerfile, the same image is reused for all containers.

If two images with the same name but different Dockerfiles are referenced, an error is thrown.

Container.filepathToContent

Container.filepathToContent defines text files to be installed on the container before the container starts. Both the key and value are strings.

For example,

{
  "/etc/myconf": "foo"
}

would create a file at /etc/myconf containing the text foo.

new Container("haproxy").withFiles({
  "/etc/myconf": "foo"
});

would create a haproxy instance with a text file /etc/myconf containing foo.

If the files change after the container boots, Quilt does not restart the container. However, if the file content specified by filepathToContent changes, Quilt will destroy the old container and boot a new one with the proper files.

The files are installed with permissions 0644. Parent directories are automatically created.

Container.hostname()

Container.hostname gets the container's hostname. If the container has no hostname, an error is thrown.

Container.setHostname()

Container.setHostname gives the container a hostname at which the container can be reached.

If multiple containers have the same hostname, an error is thrown during the vetting process.

Machine

The Machine object represents a machine to be deployed.

Its attributes are:

  • role string: The Quilt role the machine will run as. required
    • Master
    • Worker
  • provider string: The machine provider. required
    • Amazon
    • DigitalOcean
    • Google
  • region string: The region the machine will run in. optional
    • Provider-specific
  • size string: The instance type. optional
    • Provider-specific
  • cpu Range or int: The desired number of CPUs. optional
  • ram Range or int: The desired amount of RAM in Gib. optional
  • diskSize int: The desired amount of disk space in GB. optional
  • floatingIp string: A reserved IP to associate with the machine. optional
  • sshKeys []string: Public keys to allow login into the machine. optional
  • preemptible bool: Whether the machine should be preemptible. optional
    • Defaults to false
    • Preemptible instances are only supported on the Amazon provider.

Files

Quilt.js has some basic support for reading files from the local filesystem which can be used either as Dockerfiles for container images, or imported directly into a container at boot. These utilities should be considered experimental and are likely subject to change.

read()

read() reads the contents of a file into a string. The file path is passed in as an argument to the function. For example, in the below example, contents will contain a string representing the contents of the file located at /path/to/file.txt.

var contents = read("/path/to/file.txt")
readDir()

readDir() lists the contents of a directory. It takes the file path of a directory as its only argument, and returns a list of objects representing files in that directory. Each object contains the fields name (the name of the file), and isDir (true if the path is a directory instead of a file). For example, in the walk() function below, readDir() is used to recursively execute a callback on every file in a directory.

function walk(path, fn) {
        var files = readDir(path);
        for (var i = 0; i < files.length; i++) {
                var filePath = path + "/" + files[i].name;
                if (files[i].isDir) {
                        walk(filePath, fn);
                } else {
                        fn(filePath)
                }
        }
}

Documentation

Index

Constants

View Source 
const PublicInternetLabel = "public"

PublicInternetLabel is a magic label that allows connections to or from the public network.

View Source 
const QuiltPathKey = "QUILT_PATH"

QuiltPathKey is the environment variable key we use to lookup the Quilt path.

Variables

View Source 
var DefaultImportGetter = NewImportGetter(GetQuiltPath())

DefaultImportGetter uses the default QUILT_PATH, and doesn't automatically download imports.

View Source 
var HTTPGet = http.Get

HTTPGet is the function used to make the HTTP GET request for the GitHub keys. Exported so that we can run specs in tests without actually interacting with the network.

Functions

func GetQuiltPath 

func GetQuiltPath() string

GetQuiltPath returns the user-defined QUILT_PATH, or the default absolute QUILT_PATH, which is ~/.quilt if the user did not specify a QUILT_PATH.

Types

type AvailabilitySet 

type AvailabilitySet map[string]struct{}

AvailabilitySet represents a set of containers which can be placed together on a VM.

func (AvailabilitySet) Check 

func (avSet AvailabilitySet) Check(label string) bool

Check checks set membership.

func (AvailabilitySet) CopyAvSet 

func (avSet AvailabilitySet) CopyAvSet() AvailabilitySet

CopyAvSet returns a copy of the set.

func (AvailabilitySet) Insert 

func (avSet AvailabilitySet) Insert(labels ...string)

Insert inserts labels into the set.

func (AvailabilitySet) Nodes 

func (avSet AvailabilitySet) Nodes() []string

Nodes returns the membership of the set.

func (AvailabilitySet) Remove 

func (avSet AvailabilitySet) Remove(labels ...string)

Remove removes labels from the set.

func (AvailabilitySet) Str 

func (avSet AvailabilitySet) Str() string

Str returns the string representation of the set.

type Connection 

type Connection struct {
	From    string `json:",omitempty"`
	To      string `json:",omitempty"`
	MinPort int    `json:",omitempty"`
	MaxPort int    `json:",omitempty"`
}

A Connection allows containers implementing the From label to speak to containers implementing the To label in ports in the range [MinPort, MaxPort]

type ConnectionSlice 

type ConnectionSlice []Connection

A ConnectionSlice allows for slices of Collections to be used in joins

func (ConnectionSlice) Get 

func (cs ConnectionSlice) Get(ii int) interface{}

Get returns the value contained at the given index

func (ConnectionSlice) Len 

func (cs ConnectionSlice) Len() int

Len returns the number of items in the slice

type Container 

type Container struct {
	ID                string            `json:",omitempty"`
	Image             Image             `json:",omitempty"`
	Command           []string          `json:",omitempty"`
	Env               map[string]string `json:",omitempty"`
	FilepathToContent map[string]string `json:",omitempty"`
	Hostname          string            `json:",omitempty"`
}

A Container may be instantiated in the stitch and queried by users.

type Edge 

type Edge struct {
	From string
	To   string
}

An Edge in the communication Graph.

type Graph 

type Graph struct {
	Nodes map[string]Node
	// A set of containers which can be placed together on a VM.
	Availability []AvailabilitySet
	// Constraints on which containers can be placed together.
	Placement map[string][]string
	Machines  []Machine
}

A Graph represents permission to communicate across a series of Nodes. Each Node is a container and each edge is permissions to initiate a connection.

func InitializeGraph 

func InitializeGraph(spec Stitch) (Graph, error)

InitializeGraph queries the Stitch to fill in the Graph structure.

func (Graph) GetConnections 

func (g Graph) GetConnections() []Edge

GetConnections returns a list of the edges in the Graph.

type Image 

type Image struct {
	Name       string `json:",omitempty"`
	Dockerfile string `json:",omitempty"`
}

An Image represents a Docker image that can be run. If the Dockerfile is non-empty, the image should be built and hosted by Quilt.

type ImportGetter 

type ImportGetter struct {
	Path         string
	AutoDownload bool
	// contains filtered or unexported fields
}

ImportGetter provides functions for working with imports.

func NewImportGetter 

func NewImportGetter(path string) ImportGetter

NewImportGetter returns an ImporGetter with the given path and without automatic downloads.

func (ImportGetter) Get 

func (getter ImportGetter) Get(repoName string) error

Get takes in an import path `repoName`, and attempts to download the repository associated with that repoName.

type Label 

type Label struct {
	Name        string   `json:",omitempty"`
	IDs         []string `json:",omitempty"`
	Annotations []string `json:",omitempty"`
}

A Label represents a logical group of containers.

type Machine 

type Machine struct {
	ID          string   `json:",omitempty"`
	Provider    string   `json:",omitempty"`
	Role        string   `json:",omitempty"`
	Size        string   `json:",omitempty"`
	CPU         Range    `json:",omitempty"`
	RAM         Range    `json:",omitempty"`
	DiskSize    int      `json:",omitempty"`
	Region      string   `json:",omitempty"`
	SSHKeys     []string `json:",omitempty"`
	FloatingIP  string   `json:",omitempty"`
	Preemptible bool     `json:",omitempty"`
}

A Machine specifies the type of VM that should be booted.

type Node 

type Node struct {
	Name        string
	Label       string
	Annotations map[string]struct{}
	Connections map[string]Node
}

A Node in the communiction Graph.

type Placement 

type Placement struct {
	TargetLabel string `json:",omitempty"`

	Exclusive bool `json:",omitempty"`

	// Label Constraint
	OtherLabel string `json:",omitempty"`

	// Machine Constraints
	Provider   string `json:",omitempty"`
	Size       string `json:",omitempty"`
	Region     string `json:",omitempty"`
	FloatingIP string `json:",omitempty"`
}

A Placement constraint guides where containers may be scheduled, either relative to the labels of other containers, or the machine the container will run on.

type Range 

type Range struct {
	Min float64 `json:",omitempty"`
	Max float64 `json:",omitempty"`
}

A Range defines a range of acceptable values for a Machine attribute

func (Range) Accepts 

func (stitchr Range) Accepts(x float64) bool

Accepts returns true if `x` is within the range specified by `stitchr` (include), or if no max is specified and `x` is larger than `stitchr.min`.

type Stitch 

type Stitch struct {
	Containers  []Container  `json:",omitempty"`
	Labels      []Label      `json:",omitempty"`
	Connections []Connection `json:",omitempty"`
	Placements  []Placement  `json:",omitempty"`
	Machines    []Machine    `json:",omitempty"`

	AdminACL  []string `json:",omitempty"`
	MaxPrice  float64  `json:",omitempty"`
	Namespace string   `json:",omitempty"`

	Invariants []invariant `json:",omitempty"`
}

A Stitch is an abstract representation of the policy language.

func FromFile 

func FromFile(filename string, getter ImportGetter) (Stitch, error)

FromFile gets a Stitch handle from a file on disk.

func FromJSON 

func FromJSON(jsonStr string) (stc Stitch, err error)

FromJSON gets a Stitch handle from the deployment representation.

func FromJavascript 

func FromJavascript(specStr string, getter ImportGetter) (Stitch, error)

FromJavascript gets a Stitch handle from a string containing Javascript code.

func New 

func New(filename string, specStr string, getter ImportGetter) (Stitch, error)

New parses and executes a stitch (in text form), and returns an abstract Dsl handle.

func (Stitch) String 

func (stitch Stitch) String() string

String returns the Stitch in its deployment representation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.