← Back to dashboard

Cloud Functions

Audience: operator · Profile: demo · Read this when: you need a stable HTTPS endpoint external systems can call to act inside your network.

Enable it in Settings → Integrations → Cloud Functions (cloud_functions_enabled), then configure a package store in the same panel. The Functions page is at /functions. Design notes: docs/design/cloud-functions.md.

What is it?

One handler, three clouds. You write (or pick) a workload — a single Python function — and the dashboard deploys it as an AWS Lambda, an Azure Linux Function App, or a GCP Cloud Run function, with the same behaviour on each. Every function gets a stable HTTPS endpoint protected by a shared bearer secret, and can optionally be attached to a VPC/VNet so it can reach private resources.

The handler source lives in the repo at web_dashboard/functions/ and ships inside the dashboard image, so there is no build pipeline to run and no artifact to publish yourself.

Use cases

The dashboard already reaches private resources for its own work by running one-shot containers inside the target cloud (ECS / ACI / Cloud Run jobs). Reach is not what this adds — an always-on, externally callable endpoint is.

Prerequisites

A missing GCP role surfaces as a 403 roughly 90 seconds into the build, after the plan succeeded. If a GCP deploy fails late, check the roles above first.

Setup

1. Settings → Integrations → turn on Cloud Functions. The nav entry and /api/functions appear immediately; no restart.
2. Settings → Integrations → Cloud Functions (Configure) → set the package store for each cloud you intend to use. A cloud without one is shown in the deploy form but blocked, with the reason.
3. (Optional) Fill in the VPC / VNet attachment section if you want functions that reach private resources. See Networking.
4. Go to Functions → Deploy function, pick echo_diag, and deploy. Then use Test invoke to confirm it works.

The adapter workloads (db_grant, portainer_access, azure_role_grant) read their target out of the function's environment and do nothing without it — the deploy form names what each one needs and refuses a deploy that omits it, because the alternative is a function that builds successfully and then fails on every request. db_grant in particular should always be deployed for you — by the Function (DB grant) button on a database's row, or at provision time: see Cloud databases and the clouddb_adapter_pair job. POST /check_config is the route to ask an already-deployed adapter whether it is configured; it answers {"data": {"valid": false, "problems": [...]}} rather than failing when it is not. Once db_grant is armed (FN_DB_DRY_RUN=0) it also opens one real connection, so it answers the question a dry run cannot: whether the function can actually reach the database.

Field reference

What it enables in the dashboard

Workloads

Each is one module in web_dashboard/functions/fnworkloads/. The filesystem is the catalog — adding a module makes it deployable, no registry to edit. Sample request payloads for each, and a template for writing your own, are in examples/functions/.

Pages

Each workload, and the work around them, has a page:

Dashboard permissions

The fourth integration is not a function at all: granting dashboard permissions happens on a dashboard-hosted endpoint, because there the dashboard is the target system and there is no function to deploy. See Entitle dashboard permissions.

Credentials

A workload that needs a credential — a database admin password, a Portainer token, an Azure client secret — gets it by reference on every cloud. You name a secret that already lives in the cloud's own secret store, and the dashboard wires up that cloud's resolution mechanism:

On AWS it must be the full ARN: the role's policy names ARNs, and AWS appends a random suffix to every one, so a name cannot be turned into an ARN by concatenation.

POST /api/functions
{
  "cloud": "gcp", "region": "us-central1", "name": "portainer-jit",
  "workload": "portainer_access",
  "environment": { "FN_PORTAINER_URL": "https://portainer.internal",
                   "FN_PORTAINER_DRY_RUN": "0" },
  "secret_environment": { "FN_PORTAINER_API_KEY": "portainer-jit-token" }
}

environment is for non-secret settings, and the dashboard enforces that. A credential-shaped value there is refused at deploy with a message pointing here. The reason it is an error rather than a warning: environment is stored in the deploy job's metadata, streams into the job's Live Output as Terraform renders the plan, and stays readable on the function's own console page — so by the time you saw a warning, the credential would need rotating.

Automatic pairing already works this way; nothing to configure. A db_grant adapter deployed by Register in Entitle stages the admin password in the cloud's secret store and passes only the reference.

Provenance: what is actually running

A deployed function runs privileged code from inside your network, so the question "what exactly is running in there, and where did it come from?" needs to stay answerable months later — especially once workloads come from more than one image.

Every deploy records three things on the function:

The tree hash is computed from the files that produced the package, so it cannot be wrong. Git metadata is best-effort — an image built without the build args records "unknown" rather than a guess, because a confidently wrong commit is worse than an honest blank. A build from a modified working tree is marked -dirty.

To get git provenance into your image:

docker build \
  --build-arg GIT_SHA="$(git rev-parse HEAD)" \
  --build-arg GIT_REF="$(git rev-parse --abbrev-ref HEAD)" \
  --build-arg GIT_ORIGIN="$(git config --get remote.origin.url)" \
  --build-arg BUILT_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)" .

It also lands as the standard org.opencontainers.image.revision label.

Ask the function, don't trust the record. The same values are injected as FN_SOURCE_COMMIT / FN_SOURCE_TREE, and echo_diag reports them in its provenance block. So verifying a deployment is one request — and it catches the case the dashboard row cannot: a deploy that half-failed, or a function someone changed by hand.

curl -sS -X POST "$FN_URL" -H "Authorization: Bearer $SECRET" \
  -d '{"egress": false}' | jq .provenance

Networking

network_mode: "public" deploys an internet-reachable endpoint. "vpc" also attaches the function to your network.

Which subnet, in which region

Every cloud has a per-region functions network field, and it is what makes a function land on its own region's network rather than the default region's:

Set them under Settings → Multi-region (the sandbox scripts emit both halves). A field a region leaves blank falls back to its flat key, so a single-region install needs none of this and behaves exactly as before.

The fields are deliberately purpose-specific rather than reusing the generic default_subnet_id/subnetwork: a flat *_functions_* key answers two questions at once — which subnet do functions use and in the default region — and overriding it with a generic per-region subnet fixes the region by discarding the purpose, and only for non-default regions. That asymmetry (the same feature choosing a different-purpose subnet depending on whether the region happened to be the default) is the bug these fields exist to avoid.

For a caller that supplies the region programmatically rather than from a picker — the cloud-DB adapter pairing uses the database's region — the deploy is refused when that region has no per-region config set at all, rather than quietly attaching to the default region's network.

Phase 2 — Entitle REST integrations

Entitle's REST integration posts Give Access / Revoke Access to a target system and expects a synchronous response. A function is the natural receiver: it is externally reachable, responds in milliseconds, and can sit inside the VPC beside the resource being granted.

Use entitle_webhook_echo to validate the whole path — network, front door, secret, timeouts, retries — before any grant logic exists. It reports exactly which fields it recognised in the payload, which is how the schema gets pinned against a real tenant.

Planned integrations: ephemeral MySQL/SQL Server database accounts, Azure machine identity, Portainer access, and dashboard user identity. See the design doc.