function

package module
v0.16.0 Latest Latest
Warning

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

 Go to latest Published: Jun 23, 2021 License: Apache-2.0 Imports: 15 Imported by: 0

README

Boson Function CLI

Main Build Status Develop Build Status Client API Documentation GitHub Issues License Release

func is a Client Library and CLI for enabling the development of implicitly deployed, platform agnostic code.

Read the Documentation

Contributing

We are always looking for contributions from the Function Developer community. For more information on how to participate, see the Contributor's Guide

Documentation

Index

Constants

View Source 
const (
	DefaultRegistry = "docker.io"
	DefaultRuntime  = "node"

	// DefautlTemplate is the default Function signature / environmental context
	// of the resultant function.  All runtimes are expected to have at least
	// one implementation of each supported funciton sinagure.  Currently that
	// includes an HTTP Handler ("http") and Cloud Events handler ("events")
	DefaultTemplate = "http"
)
View Source 
const ConfigFile = "func.yaml"

ConfigFile is the name of the config's serialized form.

Variables

View Source 
var (
	ErrRepositoryNotFound        = errors.New("repository not found")
	ErrRepositoriesNotDefined    = errors.New("custom template repositories location not specified")
	ErrRuntimeNotFound           = errors.New("runtime not found")
	ErrTemplateNotFound          = errors.New("template not found")
	ErrTemplateMissingRepository = errors.New("template name missing repository prefix")
)
View Source 
var ErrNotBuilt = errors.New("not built")

ErrNotBuilt indicates the Function has not yet been built.

Functions

func DerivedImage 

func DerivedImage(root, registry string) (image string, err error)

DerivedImage returns the derived image name (OCI container tag) of the Function whose source is at root, with the default registry for when the image has to be calculated (derived). The following are eqivalent due to the use of DefaultRegistry: registry: docker.io/myname 

myname

A full image name consists of registry, image name and tag. in form [registry]/[image-name]:[tag] example docker.io/alice/my.example.func:latest Default if not provided is --registry (a required global setting) followed by the provided (or derived) image name.

func ValidateEnvs added in v0.16.0 

func ValidateEnvs(envs Envs) (errors []string)

ValidateEnvs checks that input Envs are correct and contain all necessary fields. Returns array of error messages, empty if no errors are found

Allowed settings:

  • name: EXAMPLE1 # ENV directly from a value value: value1
  • name: EXAMPLE2 # ENV from the local ENV var value: {{ env:MY_ENV }}
  • name: EXAMPLE3 value: {{ secret:secretName:key }} # ENV from a key in secret
  • value: {{ secret:secretName }} # all key-pair values from secret are set as ENV
  • name: EXAMPLE4 value: {{ configMap:configMapName:key }} # ENV from a key in configMap
  • value: {{ configMap:configMapName }} # all key-pair values from configMap are set as ENV

Types

type Builder 

type Builder interface {
	// Build a Function project with source located at path.
	Build(context.Context, Function) error
}

Builder of Function source to runnable image.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client for managing Function instances.

func New 

func New(options ...Option) *Client

New client for Function management.

func (*Client) Build 

func (c *Client) Build(ctx context.Context, path string) (err error)

Build the Function at path. Errors if the Function is either unloadable or does not contain a populated Image.

func (*Client) Create 

func (c *Client) Create(cfg Function) (err error)

Create a new Function project locally using the settings provided on a Function object.

func (*Client) Deploy 

func (c *Client) Deploy(ctx context.Context, path string) (err error)

Deploy the Function at path. Errors if the Function has not been initialized with an image tag.

func (*Client) Describe 

func (c *Client) Describe(ctx context.Context, name, root string) (d Description, err error)

Describe a Function. Name takes precidence. If no name is provided, the Function defined at root is used.

func (*Client) Emit added in v0.15.0 

func (c *Client) Emit(ctx context.Context, endpoint string) error

Emit a CloudEvent to a function endpoint

func (*Client) List 

func (c *Client) List(ctx context.Context) ([]ListItem, error)

List currently deployed Functions.

func (*Client) New 

func (c *Client) New(ctx context.Context, cfg Function) (err error)

New Function. Use Create, Build and Deploy independently for lower level control.

func (*Client) Remove 

func (c *Client) Remove(ctx context.Context, cfg Function) error

Remove a Function. Name takes precidence. If no name is provided, the Function defined at root is used if it exists.

func (*Client) Route 

func (c *Client) Route(path string) (err error)

func (*Client) Run 

func (c *Client) Run(ctx context.Context, root string) error

Run the Function whose code resides at root.

type DNSProvider 

type DNSProvider interface {
	// Provide the given name by routing requests to address.
	Provide(Function) error
}

DNSProvider exposes DNS services necessary for serving the Function.

type Deployer 

type Deployer interface {
	// Deploy a Function of given name, using given backing image.
	Deploy(context.Context, Function) (DeploymentResult, error)
}

Deployer of Function source to running status.

type DeploymentResult added in v0.13.0 

type DeploymentResult struct {
	Status Status
	URL    string
}

type Describer 

type Describer interface {
	// Describe the running state of the service as reported by the underlyng platform.
	Describe(ctx context.Context, name string) (description Description, err error)
}

Describer of Functions' remote deployed aspect.

type Description 

type Description struct {
	Name          string         `json:"name" yaml:"name"`
	Image         string         `json:"image" yaml:"image"`
	Namespace     string         `json:"namespace" yaml:"namespace"`
	Routes        []string       `json:"routes" yaml:"routes"`
	Subscriptions []Subscription `json:"subscriptions" yaml:"subscriptions"`
}

type Emitter added in v0.15.0 

type Emitter interface {
	Emit(ctx context.Context, endpoint string) error
}

Emit CloudEvents to functions

type Env added in v0.16.0 

type Env struct {
	Name  *string `yaml:"name,omitempty"`
	Value *string `yaml:"value"`
}

func (Env) String added in v0.16.0 

func (e Env) String() string

type Envs added in v0.16.0 

type Envs []Env

type Function 

type Function struct {
	// Root on disk at which to find/create source and config files.
	Root string

	// Name of the Function.  If not provided, path derivation is attempted when
	// requried (such as for initialization).
	Name string

	// Namespace into which the Function is deployed on supported platforms.
	Namespace string

	// Runtime is the language plus context.  nodejs|go|quarkus|rust etc.
	Runtime string

	// Template for the Function.
	Template string

	// Registry at which to store interstitial containers, in the form
	// [registry]/[user]. If omitted, "Image" must be provided.
	Registry string

	// Optional full OCI image tag in form:
	//   [registry]/[namespace]/[name]:[tag]
	// example:
	//   quay.io/alice/my.function.name
	// Registry is optional and is defaulted to DefaultRegistry
	// example:
	//   alice/my.function.name
	// If Image is provided, it overrides the default of concatenating
	// "Registry+Name:latest" to derive the Image.
	Image string

	// SHA256 hash of the latest image that has been built
	ImageDigest string

	// Builder represents the CNCF Buildpack builder image for a function,
	// or it might be reference to `BuilderMap`.
	Builder string

	// Map containing known builders.
	// e.g. { "jvm": "docker.io/example/quarkus-jvm-builder" }
	BuilderMap map[string]string

	// List of volumes to be mounted to the function
	Volumes Volumes

	// Env variables to be set
	Envs Envs

	// Map containing user-supplied annotations
	// Example: { "division": "finance" }
	Annotations map[string]string

	// Options to be set on deployed function (scaling, etc.)
	Options Options
}

func NewFunction 

func NewFunction(root string) (f Function, err error)

NewFunction loads a Function from a path on disk. use .Initialized() to determine if the path contained an initialized Function. NewFunction creates a Function struct whose attributes are loaded from the configuraiton located at path.

func (Function) Built added in v0.12.0 

func (f Function) Built() bool

Built indicates the Function has been built. Does not guarantee the image indicated actually exists, just that it _should_ exist based off the current state of the Funciton object, in particular the value of the Image and ImageDiget fields.

func (Function) ImageWithDigest 

func (f Function) ImageWithDigest() string

ImageWithDigest returns the full reference to the image including SHA256 Digest. If Digest is empty, image:tag is returned.

func (Function) Initialized 

func (f Function) Initialized() bool

Initialized returns if the Function has been initialized. Any errors are considered failure (invalid or inaccessible root, config file, etc).

func (Function) WriteConfig 

func (f Function) WriteConfig() (err error)

WriteConfig writes this Function's configuration to disk.

type ListItem 

type ListItem struct {
	Name      string `json:"name" yaml:"name"`
	Namespace string `json:"namespace" yaml:"namespace"`
	Runtime   string `json:"runtime" yaml:"runtime"`
	URL       string `json:"url" yaml:"url"`
	Ready     string `json:"ready" yaml:"ready"`
}

type Lister 

type Lister interface {
	// List the Functions currently deployed.
	List(ctx context.Context) ([]ListItem, error)
}

Lister of deployed services.

type Option 

type Option func(*Client)

Option defines a Function which when passed to the Client constructor optionally mutates private members at time of instantiation.

func WithBuilder 

func WithBuilder(d Builder) Option

WithBuilder provides the concrete implementation of a builder.

func WithDNSProvider 

func WithDNSProvider(provider DNSProvider) Option

WithDNSProvider proivdes a DNS provider implementation for registering the effective DNS name which is either explicitly set via WithName or is derived from the root path.

func WithDeployer 

func WithDeployer(d Deployer) Option

WithDeployer provides the concrete implementation of a deployer.

func WithDescriber 

func WithDescriber(describer Describer) Option

WithDescriber provides a concrete implementation of a Function describer.

func WithEmitter added in v0.15.0 

func WithEmitter(e Emitter) Option

WithEmitter sets a CloudEvent emitter on the client which is capable of sending a CloudEvent to an arbitrary function endpoint

func WithLister 

func WithLister(l Lister) Option

WithLister provides the concrete implementation of a lister.

func WithProgressListener 

func WithProgressListener(p ProgressListener) Option

WithProgressListener provides a concrete implementation of a listener to be notified of progress updates.

func WithPusher 

func WithPusher(d Pusher) Option

WithPusher provides the concrete implementation of a pusher.

func WithRegistry 

func WithRegistry(registry string) Option

WithRegistry sets the default registry which is consulted when an image name/tag is not explocitly provided. Can be fully qualified, including the registry (ex: 'quay.io/myname') or simply the namespace 'myname' which indicates the the use of the default registry.

func WithRemover 

func WithRemover(r Remover) Option

WithRemover provides the concrete implementation of a remover.

func WithRepositories added in v0.16.0 

func WithRepositories(repositories string) Option

WithRepositories sets the location to use for extensible template repositories. Extensible template repositories are additional templates that exist on disk and are not built into the binary.

func WithRunner 

func WithRunner(r Runner) Option

WithRunner provides the concrete implementation of a deployer.

func WithVerbose 

func WithVerbose(v bool) Option

WithVerbose toggles verbose logging.

type Options added in v0.16.0 

type Options struct {
	Scale     *ScaleOptions     `yaml:"scale,omitempty"`
	Resources *ResourcesOptions `yaml:"resources,omitempty"`
}

type ProgressListener 

type ProgressListener interface {
	// SetTotal steps of the given task.
	SetTotal(int)

	// Increment to the next step with the given message.
	Increment(message string)

	// Complete signals completion, which is expected to be somewhat different than a step increment.
	Complete(message string)

	// Done signals a cessation of progress updates.  Should be called in a defer statement to ensure
	// the progress listener can stop any outstanding tasks such as synchronous user updates.
	Done()
}

ProgressListener is notified of task progress.

type Pusher 

type Pusher interface {
	// Push the image of the Function.
	// Returns Image Digest - SHA256 hash of the produced image
	Push(ctx context.Context, f Function) (string, error)
}

Pusher of Function image to a registry.

type Remover 

type Remover interface {
	// Remove the Function from remote.
	Remove(ctx context.Context, name string) error
}

Remover of deployed services.

type ResourcesLimitsOptions added in v0.16.0 

type ResourcesLimitsOptions struct {
	CPU         *string `yaml:"cpu,omitempty"`
	Memory      *string `yaml:"memory,omitempty"`
	Concurrency *int64  `yaml:"concurrency,omitempty"`
}

type ResourcesOptions added in v0.16.0 

type ResourcesOptions struct {
	Requests *ResourcesRequestsOptions `yaml:"requests,omitempty"`
	Limits   *ResourcesLimitsOptions   `yaml:"limits,omitempty"`
}

type ResourcesRequestsOptions added in v0.16.0 

type ResourcesRequestsOptions struct {
	CPU    *string `yaml:"cpu,omitempty"`
	Memory *string `yaml:"memory,omitempty"`
}

type Runner 

type Runner interface {
	// Run the Function locally.
	Run(context.Context, Function) error
}

Runner runs the Function locally.

type ScaleOptions added in v0.16.0 

type ScaleOptions struct {
	Min         *int64   `yaml:"min,omitempty"`
	Max         *int64   `yaml:"max,omitempty"`
	Metric      *string  `yaml:"metric,omitempty"`
	Target      *float64 `yaml:"target,omitempty"`
	Utilization *float64 `yaml:"utilization,omitempty"`
}

type Status added in v0.13.0 

type Status int
const (
	Failed Status = iota
	Deployed
	Updated
)

type Subscription 

type Subscription struct {
	Source string `json:"source" yaml:"source"`
	Type   string `json:"type" yaml:"type"`
	Broker string `json:"broker" yaml:"broker"`
}

type Volume added in v0.16.0 

type Volume struct {
	Secret    *string `yaml:"secret,omitempty"`
	ConfigMap *string `yaml:"configMap,omitempty"`
	Path      *string `yaml:"path"`
}

func (Volume) String added in v0.16.0 

func (v Volume) String() string

type Volumes added in v0.16.0 

type Volumes []Volume

Source Files

View all Source files

Directories

Path Synopsis
cmd
func
test
_e2e

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.