Go Shell Other
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github Add faas-cli version information into Your Environment section Apr 7, 2018
builder Add build folder to dockerfile when shrinkwrap Aug 17, 2018
ci Move hash generator script into /ci folder Jun 30, 2018
commands Move deploy function params into a specification Aug 17, 2018
config Refactor file names Nov 11, 2017
contrib/bash Migrate CLI to Cobra and add experimental bash completion Aug 31, 2017
guide Make dockerfile a language with a file in the repo Jan 24, 2018
proxy Move deploy function params into a specification Aug 17, 2018
sample Move from localhost to 127.0.0.1 as a default for IPv6 clashes, add e… Mar 12, 2018
schema Add annotation flag support to the deploy and store-deploy Aug 9, 2018
stack Rename r/o FS flag in schema Aug 1, 2018
test PR feedback for version info command update Jul 17, 2018
vendor Adds annotation support to stack.yml schema Jul 24, 2018
version Version relocation works Nov 8, 2017
versioncontrol Make dockerfile a language with a file in the repo Jan 24, 2018
.DEREK.yml Redirect Derek file to openfaas/faas file May 18, 2018
.gitignore Add cloud command for sealing secrets Jun 5, 2018
.travis.yml Push image to both Quay.io and Docker Hub Jul 17, 2018
CHANGELOG.md Add generated changelog Nov 11, 2017
CONTRIBUTING.md Update deprecated / unmaintained community packages Mar 13, 2018
Dockerfile Install CLI to /usr/bin Aug 9, 2018
Dockerfile.redist Update license-check to allow "Author(s)" term Aug 9, 2018
Gopkg.lock Adds annotation support to stack.yml schema Jul 24, 2018
Gopkg.toml Adds annotation support to stack.yml schema Jul 24, 2018
LICENSE Add contributions guide May 4, 2017
MANUAL_CLI.md Move from localhost to 127.0.0.1 as a default for IPv6 clashes, add e… Mar 12, 2018
Makefile Move deploy function params into a specification Aug 17, 2018
README.md Move YAML reference to docs Aug 2, 2018
app.go Migrate all imports/references to OpenFaaS org Sep 25, 2017
build.sh Update path for build Aug 9, 2018
build_redist.sh Move hash generator script into /ci folder Jun 30, 2018
build_samples.sh Move samples.yml to stack.yml (default) and update references in shel… Feb 6, 2018
deploy_samples.sh Move from localhost to 127.0.0.1 as a default for IPv6 clashes, add e… Mar 12, 2018
get.sh Repoint version command to non-API URI Jul 31, 2018
legacy_cli.go error string starts with lowercase and do not contain trailing '.' Jan 17, 2018
legacy_cli_test.go Spaces between header and code Oct 23, 2017
stack.yml Comment out limits/requests Apr 6, 2018

README.md

faas-cli

Go Report Card Build Status License: MIT OpenFaaS

This is a CLI for use with OpenFaaS - a serverless functions framework for Docker & Kubernetes.

Before using this tool please setup OpenFaaS by following instructions over on the main repo.

The CLI can be used to build and deploy functions to OpenFaaS. You can build OpenFaaS functions from a set of supported language templates (such as Node.js, Python, CSharp and Ruby). That means you just write a handler file such as (handler.py/handler.js) and the CLI does the rest to create a Docker image.

Demo: ASCII cinema

TL;DR - Introductory tutorial

Blog: Coffee with the FaaS-CLI

FAQ

  • Does the CLI hang while deploying faas deploy?

Checkout the troubleshooting guide

  • Can you not push your image via faas push?

Make sure you have specified your Docker Hub user account in your YAML file - so if your account is alexellis2 and your image name is demo, then put:

    image: alexellis2/demo
  • Need other help with troubleshooting?

Checkout the troubleshooting guide

Get started: Install the CLI

You can install the CLI with a curl utility script, brew or by downloading the binary from the releases page. Once installed you'll get the faas-cli command and faas alias.

Utility script with curl:

$ curl -sSL https://cli.openfaas.com | sudo sh

Non-root with curl (requires further actions as advised after downloading):

$ curl -sSL https://cli.openfaas.com | sh

Via brew:

$ brew install faas-cli

Note: The brew release may not run the latest minor release but is updated regularly.

In PowerShell:

$version = (Invoke-WebRequest "https://api.github.com/repos/openfaas/faas-cli/releases/latest" | ConvertFrom-Json)[0].tag_name
(New-Object System.Net.WebClient).DownloadFile("https://github.com/openfaas/faas-cli/releases/download/$version/faas-cli.exe", "faas-cli.exe")

Windows

The easiest way to install the faas-cli is through scoop:

scoop install faas-cli

Note: The scoop release may not run the latest minor release but is updated regularly.

Build from source

the contributing guide has instructions for building from source and for configuring a Golang development environment.

Run the CLI

The main commands supported by the CLI are:

  • faas-cli new - creates a new function via a template in the current directory
  • faas-cli build - builds Docker images from the supported language types
  • faas-cli push - pushes Docker images into a registry
  • faas-cli deploy - deploys the functions into a local or remote OpenFaaS gateway
  • faas-cli remove - removes the functions from a local or remote OpenFaaS gateway
  • faas-cli invoke - invokes the functions and reads from STDIN for the body of the request
  • faas-cli login - stores basic auth credentials for OpenFaaS gateway (supports multiple gateways)
  • faas-cli logout - removes basic auth credentials for a given gateway
  • faas-cli store - allows browsing and deploying OpenFaaS store functions

The default gateway URL of 127.0.0.1:8080 can be overriden in three places including an environmental variable.

  • 1st priority --gateway flag
  • 2nd priority --yaml / -f flag or stack.yml if in current directory
  • 3rd priority OPENFAAS_URL environmental variable

For Kubernetes users you may want to set this in your .bash_rc file:

export OPENFAAS_URL=127.0.0.1:31112

Advanced commands:

Help for all of the commands supported by the CLI can be found by running:

  • faas-cli help or faas-cli [command] --help

You can chose between using a programming language template where you only need to provide a handler file, or a Docker that you can build yourself.

Templates

Command: faas-cli new FUNCTION_NAME --lang python/node/go/ruby/Dockerfile/etc

In your YAML you can also specify lang: node/python/go/csharp/ruby

  • Supports common languages

  • Quick and easy - just write one file

  • Specify depenencies on Gemfile / requirements.txt or package.json etc

  • Customise the provided templates

Perhaps you need to have gcc or another dependency in your Python template? That's not a problem.

You can customise the Dockerfile or code for any of the templates. Just create a new directory and copy in the templates folder from this repository. The templates in your current working directory are always used for builds.

See also: faas-cli new --help

Third-party community templates

Templates created and maintained by a third-party can be added to your local system using the faas-cli template pull command.

Curated language templates:

Language Author URL
PHP @itscaro https://github.com/itscaro/openfaas-template-php/
PHP5 @itscaro https://github.com/itscaro/openfaas-template-php/
F# @hayer https://github.com/hayer/faas-fsharp-template/

Read more on community templates here.

Docker image as a function

Specify lang: Dockerfile if you want the faas-cli to execute a build or skip_build: true for pre-built images.

  • Ultimate versatility and control
  • Package anything
  • If you are using a stack file add the skip_build: true attribute
  • Use one of the samples as a basis

Read the blog post/tutorial: Turn Any CLI into a Function with OpenFaaS

Private registries

  • For Kubernetes

Create a named image pull secret and add the secret name to the secrets section of your YAML file or your deployment arguments with --secret.

Alternatively you can assign a secret to the node to allow it to pull from your private registry. In this case you do not need to assign the secret to your function.

  • For Docker Swarm

For Docker Swarm use the --send-registry-auth flag or its shorthand -a which will look up your registry credentials in your local credentials store and then transmit them over the wire to the deploy command on the API Gateway. Make sure HTTPS/TLS is enabled before attempting this.

Use a YAML stack file

Read the YAML reference guide in the OpenFaaS docs.

Quick guide

A YAML stack file groups functions together and also saves on typing.

You can define individual functions or a set of of them within a YAML file. This makes the CLI easier to use and means you can use this file to deploy to your OpenFaaS instance. By default the faas-cli will attempt to load stack.yaml from the current directory.

Here is an example file using the stack.yml file included in the repository.

provider:
  name: faas
  gateway: http://127.0.0.1:8080

functions:
  url-ping:
    lang: python
    handler: ./sample/url-ping
    image: alexellis2/faas-urlping

This url-ping function is defined in the sample/url-ping folder makes use of Python. All we had to do was to write a handler.py file and then to list off any Python modules in requirements.txt.

  • Build the files in the .yml file:
$ faas-cli build -f ./stack.yml

-f specifies the file or URL to download your YAML file from. The long version of the -f flag is: --yaml.

You can also download over HTTP/s:

$ faas-cli build -f https://raw.githubusercontent.com/openfaas/faas-cli/master/stack.yml

Docker along with a Python template will be used to build an image named alexellis2/faas-urlping.

  • Deploy your function

Now you can use the following command to deploy your function(s):

$ faas-cli deploy -f ./stack.yml

Access functions with curl

You can initiate a HTTP POST via curl:

  • with the -d flag i.e. -d "my data here"
  • or with --data-binary @filename.txt to send a whole file including newlines
  • if you want to pass input from STDIN then use --data-binary @-
$ curl -d '{"hello": "world"}' http://127.0.0.1:8080/function/nodejs-echo
{ nodeVersion: 'v6.9.1', input: '{"hello": "world"}' }

$ curl --data-binary @README.md http://127.0.0.1:8080/function/nodejs-echo

$ uname -a | curl http://127.0.0.1:8080/function/nodejs-echo--data-binary @-

For further instructions on the manual CLI flags (without using a YAML file) read manual_cli.md

OpenFaaS Cloud (extensions)

OpenFaaS Cloud provides a GitOps experience for functions on Kubernetes.

Commands:

  • seal

You can use the CLI to seal a secret for usage on public Git repo. The pre-requisite is that you have installed SealedSecrets and exported your public key from your cluster as pub-cert.pem.

Install kubeseal:

release=$(curl --silent "https://api.github.com/repos/bitnami-labs/sealed-secrets/releases/latest" | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')
GOOS=$(go env GOOS)
GOARCH=$(go env GOARCH)
wget https://github.com/bitnami/sealed-secrets/releases/download/$release/kubeseal-$GOOS-$GOARCH
sudo install -m 755 kubeseal-$GOOS-$GOARCH /usr/local/bin/kubeseal

Now grab your pub-cert.pem file from your cluster, or use the official OpenFaaS Cloud certificate.

$ kubeseal --fetch-cert > pub-cert.pem

Then seal a secret using the OpenFaaS CLI:

$ faas-cli cloud seal --name alexellis-github --literal hmac-secret=1234 --cert=pub-cert.pem

You can then place the secrets.yml file in any public Git repo without others being able to read the contents.

FaaS-CLI Developers / Contributors

See contributing guide.

License

This project is part of the OpenFaaS project licensed under the MIT License.