fission

README

Fission: Serverless Functions for Kubernetes

fission.io @fissionio

Fission is a fast serverless framework for Kubernetes with a focus on developer productivity and high performance.

Fission operates on just the code: Docker and Kubernetes are abstracted away under normal operation, though you can use both to extend Fission if you want to.

Fission is extensible to any language; the core is written in Go, and language-specific parts are isolated in something called environments (more below). Fission currently supports NodeJS, Python, Ruby, Go, PHP, Bash, and any Linux executable, with more languages coming soon.

Performance: 100msec cold start

Fission maintains a pool of "warm" containers that each contain a small dynamic loader. When a function is first called, i.e. "cold-started", a running container is chosen and the function is loaded. This pool is what makes Fission fast: cold-start latencies are typically about 100msec.

Kubernetes is the right place for Serverless

We're built on Kubernetes because we think any non-trivial app will use a combination of serverless functions and more conventional microservices, and Kubernetes is a great framework to bring these together seamlessly.

Building on Kubernetes also means that anything you do for operations on your Kubernetes cluster — such as monitoring or log aggregation — also helps with ops on your Fission deployment.

Fission Concepts

A function is a piece of code that follows the fission function interface.

An environment contains the language- and runtime-specific parts of running a function. Fission comes with NodeJS and Python environments; you can also extend environments or create entirely new ones if you want. (An environment is essentially just a container with a webserver and dynamic loader.)

A trigger is something that maps an event to a function; Fission supports HTTP routes as triggers today, with upcoming support for other types of event triggers, such as timers and Kubernetes events.

Usage

  # Add the stock NodeJS env to your Fission deployment
  $ fission env create --name nodejs --image fission/node-env

  # A javascript one-liner that prints "hello world"
  $ curl https://raw.githubusercontent.com/fission/fission/master/examples/nodejs/hello.js > hello.js

  # Upload your function code to fission
  $ fission function create --name hello --env nodejs --code hello.js

  # Map GET /hello to your new function
  $ fission route create --method GET --url /hello --function hello

  # Run the function.  This takes about 100msec the first time.
  $ curl http://$FISSION_ROUTER/hello
  Hello, world!

See the examples directory for more.

Running Fission on your Cluster

See the installation guide.

Compiling Fission

See the compilation guide.

Status

Fission is in early alpha. It's not suitable for production use just yet.

Reach us on slack or twitter.

Fission is a project by Platform9 Systems and many contributors.

Documentation

Index

• Constants
• func GetHTTPError(err error) (int, string)
• func MakeErrorFromHTTP(resp *http.Response) error
• func UrlForFunction(name string) string
• type Archive
• type ArchiveType
• type BuildStatus
• type Builder
• type Checksum
• type ChecksumType
• type EnvironmentReference
• type EnvironmentSpec
• type Error
  • func MakeError(code int, msg string) Error
  • func (err Error) Description() string
  • func (err Error) Error() string
  • func (err Error) HTTPStatus() int
• type FunctionLoadRequest
• type FunctionPackageRef
• type FunctionReference
• type FunctionReferenceType
• type FunctionSpec
• type HTTPTriggerSpec
• type KubernetesWatchTriggerSpec
• type MessageQueueTriggerSpec
• type PackageRef
• type PackageSpec
• type PackageStatus
• type Runtime
• type TimeTriggerSpec

Constants

const (
	BuildStatusPending   = "pending"
	BuildStatusRunning   = "running"
	BuildStatusSucceeded = "succeeded"
	BuildStatusFailed    = "failed"
)

const (
	ErrorInternal = iota

	ErrorNotAuthorized
	ErrorNotFound
	ErrorNameExists
	ErrorInvalidArgument
	ErrorNoSpace
	ErrorNotImplmented
	ErrorChecksumFail
	ErrorSizeLimitExceeded
)

const (
	ArchiveLiteralSizeLimit int64 = 256 * 1024
)

const (
	// FunctionReferenceFunctionName means that the function
	// reference is simply by function name.
	FunctionReferenceTypeFunctionName = "name"
)

Functions

func GetHTTPError

func GetHTTPError(err error) (int, string)

func MakeErrorFromHTTP

func MakeErrorFromHTTP(resp *http.Response) error

func UrlForFunction

func UrlForFunction(name string) string

Types

type Archive

type Archive struct {
	// Type defines how the package is specified: literal or URL.
	Type ArchiveType `json:"type"`

	// Literal contents of the package. Can be used for
	// encoding packages below TODO (256KB?) size.
	Literal []byte `json:"literal"`

	// URL references a package.
	URL string `json:"url"`

	// Checksum ensures the integrity of packages
	// refereced by URL. Ignored for literals.
	Checksum Checksum `json:"checksum"`
}

Package contains or references a collection of source or binary files.

type ArchiveType

type ArchiveType string

ArchiveType is either literal or URL, indicating whether the package is specified in the Archive struct or externally.

const (
	// ArchiveTypeLiteral means the package contents are specified in the Literal field of
	// resource itself.
	ArchiveTypeLiteral ArchiveType = "literal"

	// ArchiveTypeUrl means the package contents are at the specified URL.
	ArchiveTypeUrl ArchiveType = "url"
)

type BuildStatus

type BuildStatus string

type Builder

type Builder struct {
	Image   string `json:"image"`
	Command string `json:"command"`
}

type Checksum

type Checksum struct {
	Type ChecksumType `json:"type"`
	Sum  string       `json:"sum"`
}

Checksum of package contents when the contents are stored outside the Package struct. Type is the checksum algorithm; "sha256" is the only currently supported one. Sum is hex encoded.

type ChecksumType

type ChecksumType string

ChecksumType specifies the checksum algorithm, such as sha256, used for a checksum.

const (
	ChecksumTypeSHA256 ChecksumType = "sha256"
)

type EnvironmentReference

type EnvironmentReference struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
}

type EnvironmentSpec

type EnvironmentSpec struct {
	// Environment API version
	Version int `json:"version"`

	// Runtime container image etc.; required
	Runtime Runtime `json:"runtime"`

	// Optional
	Builder Builder `json:"builder"`

	// Optional, but strongly encouraged. Used to populate
	// links from UI, CLI, etc.
	DocumentationURL string `json:"documentationurl"`
}

type Error

type Error struct {
	Code    errorCode `json:"code"`
	Message string    `json:"message"`
}

Errors returned by the Fission API.

func MakeError

func MakeError(code int, msg string) Error

func (Error) Description

func (err Error) Description() string

func (Error) Error

func (err Error) Error() string

func (Error) HTTPStatus

func (err Error) HTTPStatus() int

type FunctionLoadRequest

type FunctionLoadRequest struct {
	// FilePath is an absolute filesystem path to the
	// function. What exactly is stored here is
	// env-specific. Optional.
	FilePath string `json:"filepath"`

	// Entrypoint has an environment-specific meaning;
	// usually, it defines a function within a module
	// containing multiple functions. Optional; default is
	// environment-specific.
	EntryPoint string `json:"entrypoint"`

	// URL to expose this function at. Optional; defaults
	// to "/".
	URL string `json:"url"`
}

Fission-Environment interface. The following types are not exposed in the Fission API, but rather used by Fission to talk to environments.

type FunctionPackageRef

type FunctionPackageRef struct {
	PackageRef PackageRef `json:"packageref"`

	// FunctionName specifies a specific function within the package. This allows
	// functions to share packages, by having different functions within the same
	// package.
	//
	// Fission itself does not interpret this path. It is passed verbatim to
	// build and runtime environments.
	//
	// This is optional: if unspecified, the environment has a default name.
	FunctionName string `json:"functionName"`
}

type FunctionReference

type FunctionReference struct {
	// Type indicates whether this function reference is by name or selector. For now,
	// the only supported reference type is by name.  Future reference types:
	//   * Function by label or annotation
	//   * Branch or tag of a versioned function
	//   * A "rolling upgrade" from one version of a function to another
	Type FunctionReferenceType `json:"type"`

	// Name of the function.
	Name string `json:"name"`
}

type FunctionReferenceType

type FunctionReferenceType string

type FunctionSpec

type FunctionSpec struct {
	// Environment is the build and runtime environment that this function is
	// associated with. An Environment with this name should exist, otherwise the
	// function cannot be invoked.
	Environment EnvironmentReference `json:"environment"`

	// Reference to a package containing deployment and optionally the source
	Package FunctionPackageRef `json:"package"`
}

FunctionSpec describes the contents of the function.

type HTTPTriggerSpec

type HTTPTriggerSpec struct {
	Host              string            `json:"host"`
	RelativeURL       string            `json:"relativeurl"`
	Method            string            `json:"method"`
	FunctionReference FunctionReference `json:"functionref"`
}

type KubernetesWatchTriggerSpec

type KubernetesWatchTriggerSpec struct {
	Namespace         string            `json:"namespace"`
	Type              string            `json:"type"`
	LabelSelector     map[string]string `json:"labelselector"`
	FunctionReference FunctionReference `json:"functionref"`
}

type MessageQueueTriggerSpec

type MessageQueueTriggerSpec struct {
	FunctionReference FunctionReference `json:"functionref"`
	MessageQueueType  string            `json:"messageQueueType"`
	Topic             string            `json:"topic"`
	ResponseTopic     string            `json:"respTopic,omitempty"`
	ContentType       string            `json:"contentType"`
}

MessageQueueTriggerSpec defines a binding from a topic in a message queue to a function.

type PackageRef

type PackageRef struct {
	Namespace string `json:"namespace"`
	Name      string `json:"name"`

	// Including resource version in the reference forces the function to be updated on
	// package update, making it possible to cache the function based on its metadata.
	ResourceVersion string `json:"resourceversion"`
}

type PackageSpec

type PackageSpec struct {
	Environment EnvironmentReference `json:"environment"`
	Source      Archive              `json:"source"`
	Deployment  Archive              `json:"deployment"`
}

type PackageStatus

type PackageStatus struct {
	BuildStatus BuildStatus `json:"buildstatus"`
	BuildLog    string      `json:"buildlog"` // output of the build (errors etc)
}

type Runtime

type Runtime struct {
	// Image for containing the language runtime.
	Image string `json:"image"`

	// LoadEndpointPort defines the port on which the
	// server listens for function load
	// requests. Optional; default 8888.
	LoadEndpointPort int32 `json:"loadendpointport"`

	// LoadEndpointPath defines the relative URL on which
	// the server listens for function load
	// requests. Optional; default "/specialize".
	LoadEndpointPath string `json:"loadendpointpath"`

	// FunctionEndpointPort defines the port on which the
	// server listens for function requests. Optional;
	// default 8888.
	FunctionEndpointPort int32 `json:"functionendpointport"`
}

type TimeTriggerSpec

type TimeTriggerSpec struct {
	Cron              string `json:"cron"`
	FunctionReference `json:"functionref"`
}

TimeTrigger invokes the specific function at a time or times specified by a cron string.