Functions

Functions are serverless code that runs on AWS Lambda. You write the code, deploy it to Volcano, and invoke it via HTTP. Volcano handles provisioning, scaling, and execution.

How functions work

┌─────────────────────────────────────────────────────────────┐
│ 1. Write your code (Node.js, Python, or Ruby)               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Package a source ZIP or tar.gz and upload via API          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Volcano builds and deploys the function                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Invoke via DNS endpoint or API endpoint                   │
└─────────────────────────────────────────────────────────────┘

Functions:

• Scale automatically based on demand
• Run only when invoked (no idle costs)
• Can access databases with user context
• Receive authenticated user identity when invoked with user tokens
• Can be invoked automatically on a cron schedule with scheduled invocations

CLI folder layout

When using the Volcano CLI, place functions under:

volcano/functions/

Supported layouts:

• single-file functions such as volcano/functions/hello.js
• directory-based functions such as volcano/functions/api/index.js

The CLI derives the function name from:

• the filename for single-file functions
• the directory name for directory-based functions

The CLI packages cloud function sources as tar.gz archives and also automatically packages:

• shared files/directories whose names start with _
• dependency manifests such as package.json, requirements.txt, and Gemfile

Cloud deploys install dependencies during the function compile build. Do not upload node_modules, python_deps, or vendor to the cloud API. Local mode does not run CodeBuild, so it still expects dependencies to be installed locally.

Function and frontend source archives are limited by SOURCE_ARCHIVE_SIZE_LIMIT_MB, which is enforced by the API. The CLI does not apply its own source archive size limit. Final Lambda container images are limited by LAMBDA_TARGET_CONTAINER_SIZE_LIMIT_MB, which is enforced in the cloud publish build before images are pushed.

See Creating functions for concrete layout examples.

Deployment regions

Functions deploy according to the owning project's region policy:

• Project all_regions=true: function deploys to all configured regions.
• Project all_regions=false: function deploys only to selected_regions.

Function API responses include deployed_regions so you can see where the function is active.

Deployment lifecycle

Deploying a new function or updating an existing function's code starts an asynchronous workflow. Function reads return status: "provisioning" while the workflow is running, then transition to active when deployment succeeds or failed if deployment fails. Deleting a function returns status: "deleting" while cleanup runs, then the function disappears from get and list results.

Supported runtimes

The handler is the function that Lambda calls when your code runs. For Node.js, index.handler means the handler export in index.js. You can customize this when deploying.

Quick example

1. Write your function

// index.js
exports.handler = async (event) => {
  const name = event.payload?.name || 'World';

  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      message: `Hello, ${name}!`
    })
  };
};

2. Package and deploy

# Create source ZIP or tar.gz file
zip function.zip index.js

# Deploy to Volcano
curl -X POST "https://api.volcano.dev/projects/$PROJECT_ID/functions" \
  -H "Authorization: Bearer $PLATFORM_TOKEN" \
  -F "name=hello" \
  -F "runtime=nodejs24.x" \
  -F "handler=handler" \
  -F "code=@function.zip"

3. Invoke

# Option A (recommended): DNS endpoint with geo routing
curl -X POST "https://$FUNCTION_ID.functions.volcano.dev/" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"name": "Volcano"}}'

# Option B: Invoke endpoint on API host (direct invocation)
curl -X POST "http://api.volcano.dev/functions/$FUNCTION_ID/invoke" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"name": "Volcano"}}'

Response:

{
  "message": "Hello, Volcano!"
}

The invocation HTTP status code and headers come directly from your function response, and Volcano adds X-Volcano-Version to invoked function responses (production: VERSION, non-production: ENV-VERSION).

Environment variables

Functions automatically receive these environment variables:

You can add custom environment variables through the API. See Environment variables.

// Access environment variables in your function
const apiKey = process.env.MY_API_KEY;
const dbUrl = process.env.DATABASE_URL;

User context

When a function is invoked with a user's access token, it receives the user's identity in event.__volcano_auth:

exports.handler = async (event) => {
  // Check if user is authenticated
  if (!event.__volcano_auth) {
    return {
      statusCode: 401,
      body: JSON.stringify({ error: 'Unauthorized' })
    };
  }

  const { user_id, email, role, project_id } = event.__volcano_auth;

  return {
    statusCode: 200,
    body: JSON.stringify({
      message: `Hello, ${email}!`,
      userId: user_id,
      role: role  // 'authenticated' or 'anonymous'
    })
  };
};

Note: When invoked with a service key instead of a user token, event.__volcano_auth is not present. Service key invocations are for admin operations that don't have a user context.

See User context for details.

Resource limits

Functions have configurable resource limits based on your plan:

What's next