func/docs/reference/commands.txt

686 lines
26 KiB
Plaintext

CLI Command Reference
------------------------------------------------------------------------------
CREATE
NAME
func create - Create a function project.
SYNOPSIS
func create [-l|--language] [-t|--template] [-r|--repository]
[-c|--confirm] [-v|--verbose] [path]
DESCRIPTION
Creates a new function project.
$ func create -l node -t http
Creates a function in the current directory '.' which is written in the
language/runtime 'node' and handles HTTP events.
If [path] is provided, the function is initialized at that path, creating
the path if necessary.
To complete this command interactively, use --confirm (-c):
$ func create -c
Available Language Runtimes and Templates:
Language Template
-------- --------
go cloudevents
go http
go lkingland/e2e
node cloudevents
node http
python cloudevents
python http
quarkus cloudevents
quarkus http
runtime lkingland/template
rust cloudevents
rust http
springboot cloudevents
springboot http
typescript cloudevents
typescript http
To install more language runtimes and their templates see 'func repository'.
EXAMPLES
o Create a Node.js function (the default language runtime) in the current
directory (the default path) which handles http events (the default
template).
$ func create
o Create a Node.js function in the directory 'myfunc'.
$ func create myfunc
o Create a Go function which handles CloudEvents in ./myfunc.
$ func create -l go -t cloudevents myfunc
Usage:
func create [flags]
Flags:
-c, --confirm Prompt to confirm all options interactively (Env: $FUNC_CONFIRM)
-h, --help help for create
-l, --language string Language Runtime (see help text for list) (Env: $FUNC_LANGUAGE)
-r, --repository string URI to a Git repository containing the specified template (Env: $FUNC_REPOSITORY)
-t, --template string Function template. (see help text for list) (Env: $FUNC_TEMPLATE) (default "http")
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------
BUILD
Build a function project as a container image
This command builds the function project in the current directory or in the directory
specified by --path. The result will be a container image that is pushed to a registry.
The func.yaml file is read to determine the image name and registry.
If the project has not already been built, either --registry or --image must be provided
and the image name is stored in the configuration file.
Usage:
func build [flags]
Examples:
# Build from the local directory, using the given registry as target.
# The full image name will be determined automatically based on the
# project directory name
func build --registry quay.io/myuser
# Build from the local directory, specifying the full image name
func build --image quay.io/myuser/myfunc
# Re-build, picking up a previously supplied image name from a local func.yml
func build
# Build using s2i instead of Buildpacks
func build --builder=s2i
# Build with a custom buildpack builder
func build --builder=pack --builder-image cnbs/sample-builder:bionic
Flags:
-b, --builder string build strategy to use when creating the underlying image. Currently supported build strategies are "pack" and "s2i". (default "pack")
--builder-image string builder image, either an as a an image name or a mapping name.
Specified value is stored in func.yaml (as 'builder' field) for subsequent builds. ($FUNC_BUILDER_IMAGE)
-c, --confirm Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)
-h, --help help for build
-i, --image string Full image name in the form [registry]/[namespace]/[name]:[tag] (optional). This option takes precedence over --registry (Env: $FUNC_IMAGE)
-p, --path string Path to the project directory (Env: $FUNC_PATH) (default ".")
--platform string Target platform to build (e.g. linux/amd64).
-u, --push Attempt to push the function image after being successfully built
-r, --registry string Registry + namespace part of the image to build, ex 'quay.io/myuser'. The full image name is automatically determined based on the local directory name. If not provided the registry will be taken from func.yaml (Env: $FUNC_REGISTRY)
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------
CONFIG
Configure a function
Interactive prompt that allows configuration of Volume mounts, Environment
variables, and Labels for a function project present in the current directory
or from the directory specified with --path.
Usage:
func config [flags]
func config [command]
Available Commands:
envs List and manage configured environment variable for a function
labels List and manage configured labels for a function
volumes List and manage configured volumes for a function
Flags:
-h, --help help for config
-p, --path string Path to the project directory (Env: $FUNC_PATH) (default ".")
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
Use "func config [command] --help" for more information about a command.
------------------------------------------------------------------------------
CREATE
NAME
func create - Create a function project.
SYNOPSIS
func create [-l|--language] [-t|--template] [-r|--repository]
[-c|--confirm] [-v|--verbose] [path]
DESCRIPTION
Creates a new function project.
$ func create -l node -t http
Creates a function in the current directory '.' which is written in the
language/runtime 'node' and handles HTTP events.
If [path] is provided, the function is initialized at that path, creating
the path if necessary.
To complete this command interactively, use --confirm (-c):
$ func create -c
Available Language Runtimes and Templates:
Language Template
-------- --------
go cloudevents
go http
go lkingland/e2e
node cloudevents
node http
python cloudevents
python http
quarkus cloudevents
quarkus http
runtime lkingland/template
rust cloudevents
rust http
springboot cloudevents
springboot http
typescript cloudevents
typescript http
To install more language runtimes and their templates see 'func repository'.
EXAMPLES
o Create a Node.js function (the default language runtime) in the current
directory (the default path) which handles http events (the default
template).
$ func create
o Create a Node.js function in the directory 'myfunc'.
$ func create myfunc
o Create a Go function which handles CloudEvents in ./myfunc.
$ func create -l go -t cloudevents myfunc
Usage:
func create [flags]
Flags:
-c, --confirm Prompt to confirm all options interactively (Env: $FUNC_CONFIRM)
-h, --help help for create
-l, --language string Language Runtime (see help text for list) (Env: $FUNC_LANGUAGE)
-r, --repository string URI to a Git repository containing the specified template (Env: $FUNC_REPOSITORY)
-t, --template string Function template. (see help text for list) (Env: $FUNC_TEMPLATE) (default "http")
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------
DELETE
Undeploy a function
This command undeploys a function from the cluster. By default the function from
the project in the current directory is undeployed. Alternatively either the name
of the function can be given as argument or the project path provided with --path.
No local files are deleted.
Usage:
func delete [NAME] [flags]
Examples:
# Undeploy the function defined in the local directory
func delete
# Undeploy the function 'myfunc' in namespace 'apps'
func delete -n apps myfunc
Flags:
-a, --all string Delete all resources created for a function, eg. Pipelines, Secrets, etc. (Env: $FUNC_ALL) (allowed values: "true", "false") (default "true")
-c, --confirm Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)
-h, --help help for delete
-p, --path string Path to the project directory (Env: $FUNC_PATH) (default ".")
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------
DEPLOY
Deploy a function
Builds a container image for the function and deploys it to the connected Knative enabled cluster.
The function is picked up from the project in the current directory or from the path provided
with --path.
If not already configured, either --registry or --image has to be provided and is then stored
in the configuration file.
If the function is already deployed, it is updated with a new container image
that is pushed to an image registry, and finally the function's Knative service is updated.
Usage:
func deploy [flags]
Examples:
# Build and deploy the function from the current directory's project. The image will be
# pushed to "quay.io/myuser/<function name>" and deployed as Knative service with the
# same name as the function to the currently connected cluster.
func deploy --registry quay.io/myuser
# Same as above but using a full image name, that will create a Knative service "myfunc" in
# the namespace "myns"
func deploy --image quay.io/myuser/myfunc -n myns
Flags:
-b, --build string Build specifies the way the function should be built. Supported types are "disabled", "local" or "git" (Env: $FUNC_BUILD) (default "local")
--builder string build strategy to use when creating the underlying image. Currently supported build strategies are "pack" and "s2i". (default "pack")
--builder-image string builder image, either an as a an image name or a mapping name.
Specified value is stored in func.yaml (as 'builder' field) for subsequent builds. ($FUNC_BUILDER_IMAGE)
-c, --confirm Prompt to confirm all configuration options (Env: $FUNC_CONFIRM)
-e, --env stringArray Environment variable to set in the form NAME=VALUE. You may provide this flag multiple times for setting multiple environment variables. To unset, specify the environment variable name followed by a "-" (e.g., NAME-).
-t, --git-branch string Git branch to be used for remote builds (Env: $FUNC_GIT_BRANCH)
-d, --git-dir string Directory in the repo where the function is located (Env: $FUNC_GIT_DIR)
-g, --git-url string Repo url to push the code to be built (Env: $FUNC_GIT_URL)
-h, --help help for deploy
-i, --image string Full image name in the form [registry]/[namespace]/[name]:[tag]@[digest]. This option takes precedence over --registry. Specifying digest is optional, but if it is given, 'build' and 'push' phases are disabled. (Env: $FUNC_IMAGE)
-p, --path string Path to the project directory (Env: $FUNC_PATH) (default ".")
--platform string Target platform to build (e.g. linux/amd64).
-u, --push Attempt to push the function image to registry before deploying (Env: $FUNC_PUSH) (default true)
-r, --registry string Registry + namespace part of the image to build, ex 'quay.io/myuser'. The full image name is automatically determined based on the local directory name. If not provided the registry will be taken from func.yaml (Env: $FUNC_REGISTRY)
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------
INFO
Show details of a function
Prints the name, route and any event subscriptions for a deployed function in
the current directory or from the directory specified with --path.
Usage:
func info <name> [flags]
Examples:
# Show the details of a function as declared in the local func.yaml
func info
# Show the details of the function in the myotherfunc directory with yaml output
func info --output yaml --path myotherfunc
Flags:
-h, --help help for info
-o, --output string Output format (human|plain|json|xml|yaml|url) (Env: $FUNC_OUTPUT) (default "human")
-p, --path string Path to the project directory (Env: $FUNC_PATH) (default ".")
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------
INVOKE
NAME
func invoke - test a function by invoking it with test data
SYNOPSIS
func invoke [-t|--target] [-f|--format]
[--id] [--source] [--type] [--data] [--file] [--content-type]
[-s|--save] [-p|--path] [-c|--confirm] [-v|--verbose]
DESCRIPTION
Invokes the function by sending a test request to the currently running
function instance, either locally or remote. If the function is running
both locally and remote, the local instance will be invoked. This behavior
can be manually overridden using the --target flag.
Functions are invoked with a test data structure consisting of five values:
id: A unique identifier for the request.
source: A sender name for the request (sender).
type: A type for the request.
data: Data (content) for this request.
content-type: The MIME type of the value contained in 'data'.
The values of these parameters can be individually altered from their defaults
using their associated flags. Data can also be provided from a file using the
--file flag.
Invocation Target
The function instance to invoke can be specified using the --target flag
which accepts the values "local", "remote", or <URL>. By default the
local function instance is chosen if running (see func run).
To explicitly target the remote (deployed) function:
func invoke --target=remote
To target an arbitrary endpoint, provide a URL:
func invoke --target=https://myfunction.example.com
Invocation Data
Providing a filename in the --file flag will base64 encode its contents
as the "data" parameter sent to the function. The value of --content-type
should be set to the type from the source file. For example, the following
would send a JPEG base64 encoded in the "data" POST parameter:
func invoke --file=example.jpeg --content-type=image/jpeg
Message Format
By default functions are sent messages which match the invocation format
of the template they were created using; for example "http" or "cloudevent".
To override this behavior, use the --format (-f) flag.
func invoke -f=cloudevent -t=http://my-sink.my-cluster
EXAMPLES
o Invoke the default (local or remote) running function with default values
$ func invoke
o Run the function locally and then invoke it with a test request:
(run in two terminals or by running the first in the background)
$ func run
$ func invoke
o Deploy and then invoke the remote function:
$ func deploy
$ func invoke
o Invoke a remote (deployed) function when it is already running locally:
(overrides the default behavior of preferring locally running instances)
$ func invoke --target=remote
o Specify the data to send to the function as a flag
$ func invoke --data="Hello World!"
o Send a JPEG to the function
$ func invoke --file=example.jpeg --content-type=image/jpeg
o Invoke an arbitrary endpoint (HTTP POST)
$ func invoke --target="https://my-http-handler.example.com"
o Invoke an arbitrary endpoint (CloudEvent)
$ func invoke -f=cloudevent -t="https://my-event-broker.example.com"
Usage:
func invoke [flags]
Flags:
-c, --confirm Prompt to confirm all options interactively. (Env: $FUNC_CONFIRM)
--content-type string Content Type of the data. (Env: $FUNC_CONTENT_TYPE) (default "application/json")
--data string Data to send in the request. (Env: $FUNC_DATA) (default "{\"message\":\"Hello World\"}")
--file string Path to a file to use as data. Overrides --data flag and should be sent with a correct --content-type. (Env: $FUNC_FILE)
-f, --format string Format of message to send, 'http' or 'cloudevent'. Default is to choose automatically. (Env: $FUNC_FORMAT)
-h, --help help for invoke
--id string ID for the request data. (Env: $FUNC_ID)
-p, --path string Path to the project directory (Env: $FUNC_PATH) (default ".")
--source string Source value for the request data. (Env: $FUNC_SOURCE) (default "/boson/fn")
-t, --target string Function instance to invoke. Can be 'local', 'remote' or a URL. Defaults to auto-discovery if not provided. (Env: $FUNC_TARGET)
--type string Type value for the request data. (Env: $FUNC_TYPE) (default "boson.fn")
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------
LIST
List functions
Lists all deployed functions in a given namespace.
Usage:
func list [flags]
Examples:
# List all functions in the current namespace with human readable output
func list
# List all functions in the 'test' namespace with yaml output
func list --namespace test --output yaml
# List all functions in all namespaces with JSON output
func list --all-namespaces --output json
Flags:
-A, --all-namespaces List functions in all namespaces. If set, the --namespace flag is ignored.
-h, --help help for list
-o, --output string Output format (human|plain|json|xml|yaml) (Env: $FUNC_OUTPUT) (default "human")
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------
REPOSITORY
NAME
func - Manage set of installed repositories.
SYNOPSIS
func repo [-c|--confirm] [-v|--verbose]
func repo list [-r|--repositories] [-c|--confirm] [-v|--verbose]
func repo add <name> <url>[-r|--repositories] [-c|--confirm] [-v|--verbose]
func repo rename <old> <new> [-r|--repositories] [-c|--confirm] [-v|--verbose]
func repo remove <name> [-r|--repositories] [-c|--confirm] [-v|--verbose]
DESCRIPTION
Manage template repositories installed on disk at either the default location
(~/.config/func/repositories) or the location specified by the --repository
flag. Once added, a template from the repository can be used when creating
a new function.
Interactive Prompts:
To complete these commands interactively, pass the --confirm (-c) flag to
the 'repository' command, or any of the inidivual subcommands.
The Default Repository:
The default repository is not stored on disk, but embedded in the binary and
can be used without explicitly specifying the name. The default repository
is always listed first, and is assumed when creating a new function without
specifying a repository name prefix.
For example, to create a new Go function using the 'http' template from the
default repository.
$ func create -l go -t http
The Repository Flag:
Installing repositories locally is optional. To use a template from a remote
repository directly, it is possible to use the --repository flag on create.
This leaves the local disk untouched. For example, To create a function using
the Boson Project Hello-World template without installing the template
repository locally, use the --repository (-r) flag on create:
$ func create -l go \
--template hello-world \
--repository https://github.com/boson-project/templates
Alternative Repositories Location:
Repositories are stored on disk in ~/.config/func/repositories by default.
This location can be altered by setting the FUNC_REPOSITORIES_PATH
environment variable.
COMMANDS
With no arguments, this help text is shown. To manage repositories with
an interactive prompt, use the use the --confirm (-c) flag.
$ func repository -c
add
Add a new repository to the installed set.
$ func repository add <name> <URL>
For Example, to add the Boson Project repository:
$ func repository add boson https://github.com/boson-project/templates
Once added, a function can be created with templates from the new repository
by prefixing the template name with the repository. For example, to create
a new function using the Go Hello World template:
$ func create -l go -t boson/hello-world
list
List all available repositories, including the installed default
repository. Repositories available are listed by name. To see the URL
which was used to install remotes, use --verbose (-v).
rename
Rename a previously installed repository from <old> to <new>. Only installed
repositories can be renamed.
$ func repository rename <name> <new name>
remove
Remove a repository by name. Removes the repository from local storage
entirely. When in confirm mode (--confirm) it will confirm before
deletion, but in regular mode this is done immediately, so please use
caution, especially when using an altered repositories location
(via the FUNC_REPOSITORIES_PATH environment variable).
$ func repository remove <name>
EXAMPLES
o Run in confirmation mode (interactive prompts) using the --confirm flag
$ func repository -c
o Add a repository and create a new function using a template from it:
$ func repository add boson https://github.com/boson-project/templates
$ func repository list
default
boson
$ func create -l go -t boson/hello-world
...
o List all repositories including the URL from which remotes were installed
$ func repository list -v
default
boson https://github.com/boson-project/templates
o Rename an installed repository
$ func repository list
default
boson
$ func repository rename boson boson-examples
$ func repository list
default
boson-examples
o Remove an installed repository
$ func repository list
default
boson-examples
$ func repository remove boson-examples
$ func repository list
default
Usage:
func repository [flags]
func repository [command]
Aliases:
repository, repo, repositories
Available Commands:
add Add a repository
list List repositories
remove Remove a repository
rename Rename a repository
Flags:
-c, --confirm Prompt to confirm all options interactively (Env: $FUNC_CONFIRM)
-h, --help help for repository
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
Use "func repository [command] --help" for more information about a command.
------------------------------------------------------------------------------
RUN
Run the function locally
Runs the function locally in the current directory or in the directory
specified by --path flag.
Building
By default the function will be built if never built, or if changes are detected
to the function's source. Use --build to override this behavior.
Usage:
func run [flags]
Examples:
# Run the function locally, building if necessary
func run
# Run the function, forcing a rebuild of the image.
# This is useful when the function's image was manually deleted, necessitating
# A rebuild even when no changes have been made the function's source.
func run --build
# Run the function's existing image, disabling auto-build.
# This is useful when filesystem changes have been made, but one wishes to
# run the previously built image without rebuilding.
func run --build=false
Flags:
-b, --build string[="true"] Build the function. [auto|true|false]. (default "auto")
-e, --env stringArray Environment variable to set in the form NAME=VALUE. You may provide this flag multiple times for setting multiple environment variables. To unset, specify the environment variable name followed by a "-" (e.g., NAME-).
-h, --help help for run
-p, --path string Path to the project directory (Env: $FUNC_PATH) (default ".")
-r, --registry string Registry + namespace part of the image if building, ex 'quay.io/myuser' (Env: $FUNC_REGISTRY)
Global Flags:
-n, --namespace string The namespace on the cluster used for remote commands. By default, the namespace func.yaml is used or the currently active namespace if not set in the configuration. (Env: $FUNC_NAMESPACE)
-v, --verbose Print verbose logs ($FUNC_VERBOSE)
------------------------------------------------------------------------------