Functions

What it is

A function is a unit of deployed backend logic (JavaScript/TypeScript, Python, or Ruby) that Volcano builds, packages, and runs on a managed runtime. It is invoked over HTTP, by name/alias, or on a schedule.

How it relates

• Belongs to a project.
• Reads configuration and secrets from variables. By default it receives every project variable; declare a narrower variable scope to give it only the ones it needs.
• Connects to databases and storage in the same project.
• Its visibility (private, authenticated, or public) and schedulers can be declared in the declarative config or managed with the CLI.
• A frontend route can serve a public function under a path of a frontend.
• Can be given an alias so you can invoke it by a friendly name.
• Work that has to run for hours belongs in a durable function instead, which is a separate collection with its own commands.

The CLI discovers functions in the volcano/functions directory, detects the runtime from source file extensions, and uploads a packaged archive.

If a volcano-config.yaml is present, functions deploy also sends the variable_scope and variables declared there for each function it uploads. Functions the manifest does not mention keep their existing scope. The manifest is only read — deploying never writes it back. See variable scope.

Because those declarations come from the manifest, a manifest that is present but cannot be read stops the deploy before anything is uploaded, and the error says what to fix. That includes a ${VAR} reference anywhere in the file whose environment variable is not set in the deploying shell, even in a section unrelated to functions. Deploying past it would upload a function without the scope it declared, giving it every project variable. With no volcano-config.yaml at all there is nothing to declare and deploy runs normally.

CLI operations

Prefix with cloud (e.g. volcano cloud functions deploy) to target cloud. Without the prefix, function commands always target local development.

Cloud deploys use latest-wins queueing. If the function is already deploying, the new source replaces any older queued deploy and runs next. Delete supersedes queued deploys; later deploys are rejected until deletion finishes.

Visibility

Visibility decides who can invoke a function:

A refused caller gets:

If your app gets 404 for a function you deployed, check its visibility with volcano cloud functions get <name>.

New functions start private. functions deploy says so for each function it creates and prints the command that lets signed-in users in:

  Deployed notes-summary (new, visibility private)

New functions are private: only service keys and schedulers can invoke them.
To let your project's signed-in users call one, run:
  volcano functions update notes-summary --visibility authenticated
Or declare its visibility in volcano-config.yaml and run volcano config deploy

A deploy does not apply the visibility in volcano-config.yaml. When the manifest already declares a level for a new function, the hint points at volcano config deploy instead.

--public is the same as --visibility public. --private is no longer accepted: it used to let signed-in users in, which is authenticated now, so pick the level you mean. A function that a frontend route forwards to has to stay public; functions update lists the routes to delete first.

functions update sets the level of standard functions. For a durable function, declare visibility in volcano-config.yaml and run volcano cloud config deploy.

functions get shows the level, and under "Routed from" every frontend path that forwards to the function:

Visibility: public
Routed from: web /api/session

Examples

volcano deploy deploys the functions together with the project's variables, durable functions, frontends, and configuration. Use functions deploy to deploy only functions.

# Deploy everything, or a single function by name or path
volcano functions deploy --all
volcano functions deploy -f get-notes
volcano functions deploy -f volcano/functions/get-notes.js

# Invoke with a JSON payload; --json prints compact machine output
volcano functions invoke hello --payload '{"name":"Ada"}'
volcano functions invoke hello --json
volcano functions invoke --id 33333333-3333-4333-8333-333333333333

# Let signed-in users invoke a function
volcano functions update notes-summary --visibility authenticated

# Tail build/runtime logs
volcano functions logs hello

# Schedule a function (cron), then disable it
volcano functions schedulers create hello --name refresh-cache --cron "*/5 * * * *"
volcano functions schedulers disable hello --name refresh-cache

# Invoke-by-alias
volcano functions alias set hello 44444444-4444-4444-8444-444444444444
volcano functions invoke hello

schedulers list shows each scheduler's health, how many runs in a row have failed, and the last error of a failing one. A run fails when Volcano cannot invoke the function; an error the function itself returns does not count. To be alerted when a scheduler keeps failing, see notifications.md.