From 5ef549f41fcb3baccd5f602fe1c2e2bc897f565e Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sun, 19 Jul 2026 20:00:14 +0530 Subject: [PATCH 01/26] docs: durable & async Fission RFC series (statestore, async invocation, workflows) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document three recently-merged, related features as one coherent series and highlight them for the upcoming release: the statestore is the foundation; asynchronous invocation and durable workflows are what you build on it. New pages: - architecture/statestore.md (RFC-0021) — KV + event log + queue substrate, embedded SQLite vs external Postgres, Helm config, consumers. - usage/function/async-invocation.md (RFC-0024) — fire-and-forget contract, retries, dead-letter queue, result destinations, KEDA autoscaling. - concepts/workflows.md (RFC-0022) — Workflow vs WorkflowRun, durability model. - usage/workflows/ (RFC-0022) — overview, authoring reference, run-and-inspect, and the three worked examples. Edits: - Nav: architecture/concepts/usage index pages. - releases/v1.28.0.md (draft: true) — three highlights, finalized at cut. - Homepage "What's New" card (config.toml + _index.html, kept in sync). - examples.json — three workflow examples in the Misc group. - Regenerated fission-cli reference (workflow/dlq/topic + async flags). Held as a draft until the release cut. Co-Authored-By: Claude Opus 4.8 --- config.toml | 11 +- content/en/_index.html | 15 +- content/en/docs/architecture/_index.md | 3 + content/en/docs/architecture/statestore.md | 107 +++++++++ content/en/docs/concepts/_index.md | 1 + content/en/docs/concepts/workflows.md | 77 +++++++ .../en/docs/reference/fission-cli/fission.md | 2 + .../reference/fission-cli/fission_function.md | 1 + .../fission-cli/fission_function_create.md | 96 ++++---- .../fission-cli/fission_function_dlq.md | 31 +++ .../fission-cli/fission_function_dlq_list.md | 34 +++ .../fission-cli/fission_function_dlq_purge.md | 32 +++ .../fission_function_dlq_redrive.md | 34 +++ .../fission-cli/fission_function_dlq_show.md | 33 +++ .../fission-cli/fission_function_log.md | 4 +- .../fission-cli/fission_function_test.md | 3 +- .../fission-cli/fission_function_update.md | 90 ++++---- .../fission-cli/fission_httptrigger_create.md | 1 + .../fission-cli/fission_httptrigger_update.md | 1 + .../fission-cli/fission_mqtrigger_create.md | 4 +- .../reference/fission-cli/fission_topic.md | 29 +++ .../fission-cli/fission_topic_peek.md | 33 +++ .../fission-cli/fission_topic_publish.md | 35 +++ .../reference/fission-cli/fission_workflow.md | 35 +++ .../fission-cli/fission_workflow_create.md | 39 ++++ .../fission-cli/fission_workflow_delete.md | 33 +++ .../fission-cli/fission_workflow_graph.md | 34 +++ .../fission-cli/fission_workflow_list.md | 37 +++ .../fission-cli/fission_workflow_run.md | 33 +++ .../fission-cli/fission_workflow_runs.md | 32 +++ .../fission_workflow_runs_cancel.md | 32 +++ .../fission_workflow_runs_describe.md | 32 +++ .../fission_workflow_runs_graph.md | 37 +++ .../fission_workflow_runs_history.md | 33 +++ .../fission-cli/fission_workflow_runs_list.md | 34 +++ .../fission-cli/fission_workflow_update.md | 37 +++ .../fission-cli/fission_workflow_validate.md | 34 +++ content/en/docs/releases/v1.28.0.md | 48 ++++ content/en/docs/usage/_index.en.md | 5 + .../docs/usage/function/async-invocation.md | 146 ++++++++++++ content/en/docs/usage/workflows/_index.md | 68 ++++++ content/en/docs/usage/workflows/authoring.md | 211 ++++++++++++++++++ content/en/docs/usage/workflows/examples.md | 43 ++++ .../docs/usage/workflows/run-and-inspect.md | 88 ++++++++ static/data/examples.json | 28 +++ 45 files changed, 1695 insertions(+), 101 deletions(-) create mode 100644 content/en/docs/architecture/statestore.md create mode 100644 content/en/docs/concepts/workflows.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_dlq.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_dlq_list.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_dlq_purge.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_dlq_redrive.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_dlq_show.md create mode 100644 content/en/docs/reference/fission-cli/fission_topic.md create mode 100644 content/en/docs/reference/fission-cli/fission_topic_peek.md create mode 100644 content/en/docs/reference/fission-cli/fission_topic_publish.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_create.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_delete.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_graph.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_list.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_run.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_runs.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_runs_cancel.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_runs_describe.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_runs_graph.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_runs_history.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_runs_list.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_update.md create mode 100644 content/en/docs/reference/fission-cli/fission_workflow_validate.md create mode 100644 content/en/docs/releases/v1.28.0.md create mode 100644 content/en/docs/usage/function/async-invocation.md create mode 100644 content/en/docs/usage/workflows/_index.md create mode 100644 content/en/docs/usage/workflows/authoring.md create mode 100644 content/en/docs/usage/workflows/examples.md create mode 100644 content/en/docs/usage/workflows/run-and-inspect.md diff --git a/config.toml b/config.toml index e2bb1183..5a5bfe39 100644 --- a/config.toml +++ b/config.toml @@ -183,12 +183,21 @@ github = 'fission' slackurl = "/slack" twitter = 'fissionio' +[[params.whatsnew]] +badge = 'NEW' +body = 'Durable & async Fission: a statestore substrate, fire-and-forget asynchronous invocation with retries and a dead-letter queue, and durable workflows that orchestrate functions as a resumable state machine.' +heading = 'Durable & Async Workflows' +[params.whatsnew.button] +hero_class = 'mid' +text = 'Explore Workflows' +url = '/docs/usage/workflows/' + [[params.whatsnew]] badge = 'RELEASE' body = 'Fission v1.27.0 is out! Zero-restart multi-namespace tenancy with per-namespace isolation, plus a developer toolkit — invocation correlation and failure attribution, fission function describe, and local development with run-local.' heading = 'Announcing Fission v1.27.0' [params.whatsnew.button] -hero_class = 'mid' +hero_class = 'mid-2' text = 'Read Release Notes' url = '/docs/releases/v1.27.0/' diff --git a/content/en/_index.html b/content/en/_index.html index 982e91cb..1e2100bc 100644 --- a/content/en/_index.html +++ b/content/en/_index.html @@ -338,19 +338,18 @@

What's New

- RELEASE + NEW

- Announcing Fission v1.27.0 + Durable & Async Workflows

- Fission v1.27.0 is out! Zero-restart multi-namespace tenancy with - per-namespace isolation, invocation correlation and failure - attribution, fission function describe, and local development with - run-local. + A statestore substrate, fire-and-forget asynchronous invocation + with retries and a dead-letter queue, and durable workflows that + orchestrate functions as a resumable state machine.

-
diff --git a/content/en/docs/architecture/_index.md b/content/en/docs/architecture/_index.md index 2d5b0e46..dd6f1be0 100644 --- a/content/en/docs/architecture/_index.md +++ b/content/en/docs/architecture/_index.md @@ -100,6 +100,9 @@ Invokes functions on a cron schedule. ### Canary Config Shifts traffic gradually between two function versions and rolls back automatically on failures. +### [Statestore]({{% ref "statestore.md" %}}) +A durable state substrate (key/value, event log, queue) that backs durable workflows, asynchronous invocation, and eventing. + ## Deprecated components ### [Controller]({{% ref "controller.md" %}}) diff --git a/content/en/docs/architecture/statestore.md b/content/en/docs/architecture/statestore.md new file mode 100644 index 00000000..115cdaa0 --- /dev/null +++ b/content/en/docs/architecture/statestore.md @@ -0,0 +1,107 @@ +--- +title: "Statestore" +weight: 16 +description: > + A durable state substrate — key/value, an append-only event log, and a visibility-timeout queue — behind one interface with pluggable drivers. +--- + +**The statestore is the durable substrate the control plane writes to when a feature needs state that outlives a single request or a single pod.** + +It exposes three capabilities behind one interface — a **key/value** store, an append-only **event log**, and a visibility-timeout **queue** — served by a pluggable driver. +Fission itself never deploys a database product: you either use the bundled embedded driver for development, or point the external driver at a database you already run. + +The statestore is what makes Fission's newer durable features possible. +Starting with Fission {{< release-version >}}, three subsystems build on it: + +- **[Durable Workflows]({{% ref "/docs/usage/workflows/_index.md" %}})** record every step of a run in the event log, so a run survives a controller restart and resumes exactly where it stopped. +- **[Asynchronous invocation]({{% ref "/docs/usage/function/async-invocation.md" %}})** enqueues each fire-and-forget call on the queue and delivers it in the background with retries and a dead-letter queue. +- **Eventing** uses the event log and queue as its zero-broker transport. + +The statestore is off by default; a feature that needs it will tell you to enable it. + +```mermaid +flowchart TB + wf["Workflow Engine"]:::fission + async["Async Router / Worker"]:::fission + evt["Eventing"]:::fission + subgraph ss["Statestore"] + kv["Key/Value"]:::store + log["Event Log (append-only, CAS)"]:::store + queue["Queue (visibility timeout)"]:::store + end + driver["Driver"]:::fission + embedded["SQLite on a PVC
(embedded)"]:::pod + external["Postgres via DSN Secret
(external)"]:::pod + + wf --> log + async --> queue + evt --> log + evt --> queue + kv --> driver + log --> driver + queue --> driver + driver -->|"embedded"| embedded + driver -->|"external"| external + + classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43 + classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3 + classDef store fill:#fff7e0,stroke:#dba514,color:#1f2a43,stroke-dasharray:5 3 +``` + +## Embedded vs external + +The driver is chosen with `statestore.mode`. +The two modes differ only in where the state lives; the interface the features use is identical. + +| Mode | Driver | Where state lives | Use it for | +| --- | --- | --- | --- | +| `embedded` | SQLite | A bundled SQLite file on a `PersistentVolumeClaim` | Development, single-node, and evaluation. Simple to run; not highly available. | +| `external` | Postgres | A database **you** run and manage | Production, high availability, and anything that needs KEDA autoscaling. | + +{{% notice warning %}} +KEDA autoscaling for asynchronous invocation requires `statestore.mode=external`. +The KEDA PostgreSQL scaler reads the backlog directly from the database and cannot reach the embedded SQLite file inside the pod. +{{% /notice %}} + +## Enable the statestore + +The statestore is **off by default**. +Enable it and pick a mode with Helm values. + +Embedded (SQLite on a PVC — development): + +```bash +helm upgrade --install fission fission-charts/fission-all \ + --namespace fission \ + --set statestore.enabled=true \ + --set statestore.mode=embedded \ + --set statestore.embedded.size=1Gi +``` + +External (Postgres — production): create a Secret holding the DSN, then point the chart at it: + +```bash +kubectl create secret generic statestore-postgres \ + --namespace fission \ + --from-literal=dsn='postgres://user:password@postgres.db.svc:5432/fission?sslmode=require' + +helm upgrade --install fission fission-charts/fission-all \ + --namespace fission \ + --set statestore.enabled=true \ + --set statestore.mode=external +``` + +| Helm value | Default | Meaning | +| --- | --- | --- | +| `statestore.enabled` | `false` | Provision the statestore. Required by workflows, async invocation, and eventing. | +| `statestore.mode` | `embedded` | `embedded` (SQLite on a PVC) or `external` (a Postgres DSN Secret). | +| `statestore.embedded.size` | `1Gi` | Size of the PVC backing the embedded SQLite file. | +| `statestore.external` | — | Name of the DSN Secret for external mode (defaults to `statestore-postgres`, key `dsn`). | + +Fission runs no database of its own in either mode: embedded is a file on a volume, and external is a database you already operate. + +## Related + +- [Durable Workflows]({{% ref "/docs/usage/workflows/_index.md" %}}) — multi-step orchestration recorded in the event log. +- [Asynchronous Invocation]({{% ref "/docs/usage/function/async-invocation.md" %}}) — fire-and-forget calls delivered from the queue. +- [Architecture overview]({{% ref "/docs/architecture/_index.md" %}}) — how the statestore sits alongside the other components. diff --git a/content/en/docs/concepts/_index.md b/content/en/docs/concepts/_index.md index 89f2b23a..c18264a7 100644 --- a/content/en/docs/concepts/_index.md +++ b/content/en/docs/concepts/_index.md @@ -59,6 +59,7 @@ Read the pages in order — they build on each other. - **[Executors]({{% ref "/docs/concepts/executors.md" %}})** — how Fission provisions and scales function pods (poolmgr vs newdeploy vs container). - **[Triggers]({{% ref "/docs/concepts/triggers.md" %}})** — the event sources that invoke your functions. - **[Packages and builds]({{% ref "/docs/concepts/packages-and-builds.md" %}})** — source and deployment archives, and the build pipeline. +- **[Workflows]({{% ref "/docs/concepts/workflows.md" %}})** — orchestrate several functions as one durable, resumable state machine. - **[Comparison]({{% ref "/docs/concepts/comparison.md" %}})** — how Fission compares to Knative, OpenFaaS, Kubeless, and managed FaaS, and when to choose each. ## Specs: declarative configuration diff --git a/content/en/docs/concepts/workflows.md b/content/en/docs/concepts/workflows.md new file mode 100644 index 00000000..15314d65 --- /dev/null +++ b/content/en/docs/concepts/workflows.md @@ -0,0 +1,77 @@ +--- +title: "Workflows" +weight: 7 +description: > + A durable state machine over functions — a Workflow definition and its WorkflowRun executions, recorded step by step in the statestore so a run survives restarts and resumes where it stopped. +--- + +**A workflow is a durable state machine that orchestrates several functions as one reliable unit of work.** + +A single function is the right tool for one step. +Real processes are usually several steps with logic between them — validate an order, screen it for fraud, charge the card, fulfil or reject — where some steps run in parallel, some are conditional, and some can fail transiently and must be retried. +You *can* wire that together by having functions call each other, but then the orchestration lives in your code, nothing records how far a given execution got, and a crash midway leaves you guessing. +A workflow makes the orchestration a first-class, durable object instead. + +## Definition and execution + +Workflows use two custom resources, mirroring the split between a program and a running process: + +- A **`Workflow`** is the *definition* — a named state machine that says which functions run, in what order, with what branching, retries, and error handling. +- A **`WorkflowRun`** is one *execution* of that definition against a specific input. You create a run each time you want the workflow to happen; each run has its own state and history. + +The definition is authored once and reused; every invocation is a new run. + +## What makes it durable + +Every step a run takes — scheduled, succeeded, failed, retried, a timer fired, branches joined — is appended to an event log in the [statestore]({{% ref "/docs/architecture/statestore.md" %}}) using compare-and-swap, so the log is the single source of truth for where a run is. +The engine's own state is derived: it rebuilds a run's position by folding its event log, then decides the next step. + +That design buys four things: + +- **Restart survival.** If the controller restarts mid-run, it reads the log back and continues — nothing is re-run that already succeeded, and nothing is lost. +- **Resume exactly where it stopped.** A run picks up from its last recorded step, not from the beginning. +- **Retries with backoff.** A transient function failure (a 5xx) is retried automatically; a permanent one (a 4xx typed error) is not. +- **Typed-error routing.** A step can catch a named business error (`PaymentDeclined`) and route to a different state, separately from infrastructure retries. + +```mermaid +flowchart TB + trigger["CLI / Trigger"]:::user -->|"create WorkflowRun"| engine["Workflow Engine"]:::fission + engine -->|"invoke step (internal path)"| router["Router"]:::fission + router --> pod["Function Pod"]:::pod + engine -->|"append every step (CAS)"| log["Statestore Event Log"]:::store + engine -->|"durable delay"| timers["wf-timers Queue"]:::store + log -.->|"fold to resume"| engine + + classDef user fill:#ffffff,stroke:#94a3b8,color:#1f2a43 + classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43 + classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3 + classDef store fill:#fff7e0,stroke:#dba514,color:#1f2a43,stroke-dasharray:5 3 +``` + +## The state types + +A workflow is built from a small set of state types: + +- **Task** — invoke a function. +- **Choice** — branch on the data, with no function call. +- **Parallel** — run several branches concurrently and join their results. +- **Map** — run one branch per element of an array, with a concurrency limit. +- **Wait** — pause the run durably for a set duration. +- **Succeed** / **Fail** — terminate the run. + +See [Authoring workflows]({{% ref "/docs/usage/workflows/authoring.md" %}}) for the full field reference. + +## When to use a workflow + +Reach for a workflow when an operation is **multiple steps that must complete reliably as a whole** — especially with parallelism, conditional routing, retries, durable waits, or a need to know afterward exactly what happened. + +Prefer the simpler tools when they fit: + +- A single function, possibly async, is enough for one unit of work — see [Asynchronous invocation]({{% ref "/docs/usage/function/async-invocation.md" %}}). +- Independent event-driven reactions are better modeled as separate [triggers]({{% ref "/docs/concepts/triggers.md" %}}). + +## Related + +- [Workflows usage guide]({{% ref "/docs/usage/workflows/_index.md" %}}) — enable, author, run, and inspect workflows. +- [Statestore]({{% ref "/docs/architecture/statestore.md" %}}) — the durable event log a run is recorded in. +- [Functions]({{% ref "/docs/concepts/functions.md" %}}) — the steps a workflow orchestrates. diff --git a/content/en/docs/reference/fission-cli/fission.md b/content/en/docs/reference/fission-cli/fission.md index 6e982560..c5c31b5d 100644 --- a/content/en/docs/reference/fission-cli/fission.md +++ b/content/en/docs/reference/fission-cli/fission.md @@ -39,6 +39,8 @@ Fission: Fast and Simple Serverless Functions for Kubernetes * [fission tenant](/docs/reference/fission-cli/fission_tenant/) - Manage multi-namespace tenancy (onboard/offboard namespaces) * [fission timetrigger](/docs/reference/fission-cli/fission_timetrigger/) - Create, update and manage time triggers * [fission token](/docs/reference/fission-cli/fission_token/) - Create a JWT token for function invocation +* [fission topic](/docs/reference/fission-cli/fission_topic/) - Publish to and inspect RFC-0027 eventing topics * [fission version](/docs/reference/fission-cli/fission_version/) - Show client/server version information * [fission watch](/docs/reference/fission-cli/fission_watch/) - Create, update and manage kube watcher +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows diff --git a/content/en/docs/reference/fission-cli/fission_function.md b/content/en/docs/reference/fission-cli/fission_function.md index 8098ce50..1b447ecb 100644 --- a/content/en/docs/reference/fission-cli/fission_function.md +++ b/content/en/docs/reference/fission-cli/fission_function.md @@ -27,6 +27,7 @@ Create, update and manage functions * [fission function create](/docs/reference/fission-cli/fission_function_create/) - Create a function (and optionally, an HTTP route to it) * [fission function delete](/docs/reference/fission-cli/fission_function_delete/) - Delete a function * [fission function describe](/docs/reference/fission-cli/fission_function_describe/) - Describe a function's health in one view (summary, conditions, build, pods) +* [fission function dlq](/docs/reference/fission-cli/fission_function_dlq/) - Inspect and manage the async invocation dead-letter queue * [fission function get](/docs/reference/fission-cli/fission_function_get/) - Get function source code * [fission function getmeta](/docs/reference/fission-cli/fission_function_getmeta/) - Get function metadata * [fission function list](/docs/reference/fission-cli/fission_function_list/) - List functions diff --git a/content/en/docs/reference/fission-cli/fission_function_create.md b/content/en/docs/reference/fission-cli/fission_function_create.md index a7649b30..41b9fa23 100644 --- a/content/en/docs/reference/fission-cli/fission_function_create.md +++ b/content/en/docs/reference/fission-cli/fission_function_create.md @@ -14,51 +14,57 @@ fission function create [flags] ### Options ``` - --name string Function name - --env string Environment name for function - --entrypoint string --entry |:|: Entry point for environment v2 to load with - --pkgname string --pkg |:|: Name of the existing package (--deploy and --src and --env will be ignored), should be in the same namespace as the function - --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") - --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. - --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. - --specializationtimeout int --st |:|: Timeout for executor to wait for function pod creation (default 120) - --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) - --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) - --concurrency poolmgr --con |:|: Maximum number of pods specialized concurrently to serve requests (Only valid for executortype; poolmgr) (default 500) - --requestsperpod poolmgr --rpp |:|: Maximum number of concurrent requests that can be served by a specialized pod (Only valid for executortype; poolmgr) (default 1) - --streaming Enable streaming (SSE/chunked/WebSocket) responses for this function; the response is flushed incrementally and not cut by the function timeout - --streamingprotocol string Streaming protocol when --streaming is set; one of 'auto', 'sse', 'chunked', 'websocket' (default "auto") - --streamingidletimeout int Idle timeout (seconds) for a streaming response before it is aborted; reset on each chunk (default 60) - --streamingmaxduration int Hard ceiling (seconds) on total streaming response lifetime; 0 means no ceiling (the idle timeout governs) - --expose-as-mcp Advertise this function as a Model Context Protocol (MCP) tool on the MCP server - --tool-description string Agent-facing tool description (required with --expose-as-mcp) - --tool-input-schema string Path to a JSON Schema file describing the tool's arguments; advertised verbatim as the MCP tool inputSchema - --tool-name string Override the advertised MCP tool name (defaults to -) - --onceonly poolmgr --yolo |:|: Specifies if specialized pod will serve exactly one request in its lifetime (Only valid for executortype; poolmgr) - --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" - --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" - --retainpods int Number of pods to retain after pods specialization. - --code string URL or local path for single file source code - --sourcearchive stringArray --source |:|: --src |:|: URL or local paths for source archive - --deployarchive stringArray --deploy |:|: URL or local paths for binary archive - --srcchecksum string SHA256 checksum of source archive when providing URL - --deploychecksum string SHA256 checksum of deploy archive when providing URL - --insecure Skip generating SHA256 checksum for file integrity validation - --oci string Pre-built OCI image reference containing the deployment code (registry/repo:tag[@digest]) - --buildcmd string Package build command for builder to run with - --url string URL pattern (supports {var} and {var:regexp} path templates) [DEPRECATED for 'fn create', use 'route create' instead] - --prefix string Prefix with which functions are exposed. NOTE: Prefix takes precedence over URL/RelativeURL [DEPRECATED for 'fn create', use 'route create' instead] - --method stringArray HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method: --method GET and for multiple methods --method GET --method POST. [DEPRECATED for 'fn create', use 'route create' instead] (default [GET]) - --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) - --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) - --minmemory int Minimum memory to be assigned to pod (In megabyte) - --maxmemory int Maximum memory to be assigned to pod (In megabyte) - --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) - --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) - --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) - --spec Save to the spec directory instead of creating on cluster - --dry View the generated specs - -h, --help help for create + --name string Function name + --env string Environment name for function + --entrypoint string --entry |:|: Entry point for environment v2 to load with + --pkgname string --pkg |:|: Name of the existing package (--deploy and --src and --env will be ignored), should be in the same namespace as the function + --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") + --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. + --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. + --specializationtimeout int --st |:|: Timeout for executor to wait for function pod creation (default 120) + --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) + --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) + --concurrency poolmgr --con |:|: Maximum number of pods specialized concurrently to serve requests (Only valid for executortype; poolmgr) (default 500) + --requestsperpod poolmgr --rpp |:|: Maximum number of concurrent requests that can be served by a specialized pod (Only valid for executortype; poolmgr) (default 1) + --streaming Enable streaming (SSE/chunked/WebSocket) responses for this function; the response is flushed incrementally and not cut by the function timeout + --streamingprotocol string Streaming protocol when --streaming is set; one of 'auto', 'sse', 'chunked', 'websocket' (default "auto") + --streamingidletimeout int Idle timeout (seconds) for a streaming response before it is aborted; reset on each chunk (default 60) + --streamingmaxduration int Hard ceiling (seconds) on total streaming response lifetime; 0 means no ceiling (the idle timeout governs) + --expose-as-mcp Advertise this function as a Model Context Protocol (MCP) tool on the MCP server + --tool-description string Agent-facing tool description (required with --expose-as-mcp) + --tool-input-schema string Path to a JSON Schema file describing the tool's arguments; advertised verbatim as the MCP tool inputSchema + --tool-name string Override the advertised MCP tool name (defaults to -) + --async-retry-max-attempts int Async delivery attempt budget before dead-lettering (RFC-0024) + --async-max-age duration Max time an async invocation may wait for successful delivery before it is dead-lettered (RFC-0024) + --async-on-success string Same-namespace function to invoke with the result after a successful async delivery (RFC-0024); empty clears it + --async-on-failure string Same-namespace function to invoke with the result after a permanent async failure (RFC-0024); empty clears it + --async-on-success-topic string Statestore topic to publish the result envelope to after a successful async delivery (RFC-0027); empty clears it + --async-on-failure-topic string Statestore topic to publish the result envelope to after a permanent async failure (RFC-0027); empty clears it + --onceonly poolmgr --yolo |:|: Specifies if specialized pod will serve exactly one request in its lifetime (Only valid for executortype; poolmgr) + --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" + --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" + --retainpods int Number of pods to retain after pods specialization. + --code string URL or local path for single file source code + --sourcearchive stringArray --source |:|: --src |:|: URL or local paths for source archive + --deployarchive stringArray --deploy |:|: URL or local paths for binary archive + --srcchecksum string SHA256 checksum of source archive when providing URL + --deploychecksum string SHA256 checksum of deploy archive when providing URL + --insecure Skip generating SHA256 checksum for file integrity validation + --oci string Pre-built OCI image reference containing the deployment code (registry/repo:tag[@digest]) + --buildcmd string Package build command for builder to run with + --url string URL pattern (supports {var} and {var:regexp} path templates) [DEPRECATED for 'fn create', use 'route create' instead] + --prefix string Prefix with which functions are exposed. NOTE: Prefix takes precedence over URL/RelativeURL [DEPRECATED for 'fn create', use 'route create' instead] + --method stringArray HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method: --method GET and for multiple methods --method GET --method POST. [DEPRECATED for 'fn create', use 'route create' instead] (default [GET]) + --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) + --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) + --minmemory int Minimum memory to be assigned to pod (In megabyte) + --maxmemory int Maximum memory to be assigned to pod (In megabyte) + --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) + --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) + --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) + --spec Save to the spec directory instead of creating on cluster + --dry View the generated specs + -h, --help help for create ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq.md b/content/en/docs/reference/fission-cli/fission_function_dlq.md new file mode 100644 index 00000000..d4ad427b --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_dlq.md @@ -0,0 +1,31 @@ +--- +title: fission function dlq +slug: fission_function_dlq +url: /docs/reference/fission-cli/fission_function_dlq/ +--- +## fission function dlq + +Inspect and manage the async invocation dead-letter queue + +### Options + +``` + -h, --help help for dlq +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function](/docs/reference/fission-cli/fission_function/) - Create, update and manage functions +* [fission function dlq list](/docs/reference/fission-cli/fission_function_dlq_list/) - List dead-lettered async invocations +* [fission function dlq purge](/docs/reference/fission-cli/fission_function_dlq_purge/) - Permanently delete every dead-lettered async invocation +* [fission function dlq redrive](/docs/reference/fission-cli/fission_function_dlq_redrive/) - Re-enqueue dead-lettered async invocations for another delivery +* [fission function dlq show](/docs/reference/fission-cli/fission_function_dlq_show/) - Show the full envelope of one dead-lettered async invocation + diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq_list.md b/content/en/docs/reference/fission-cli/fission_function_dlq_list.md new file mode 100644 index 00000000..03267754 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_dlq_list.md @@ -0,0 +1,34 @@ +--- +title: fission function dlq list +slug: fission_function_dlq_list +url: /docs/reference/fission-cli/fission_function_dlq_list/ +--- +## fission function dlq list + +List dead-lettered async invocations + +``` +fission function dlq list [flags] +``` + +### Options + +``` + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + --limit int Maximum number of dead-lettered invocations to list (default 100) + -o, --output string -o |:|: Output format: wide, json or yaml (default: table) + --queue string Dead-letter queue to operate on: empty for async invocations, or an RFC-0027 broker egress queue (mq-egress-, e.g. mq-egress-kafka) + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function dlq](/docs/reference/fission-cli/fission_function_dlq/) - Inspect and manage the async invocation dead-letter queue + diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq_purge.md b/content/en/docs/reference/fission-cli/fission_function_dlq_purge.md new file mode 100644 index 00000000..6be65eca --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_dlq_purge.md @@ -0,0 +1,32 @@ +--- +title: fission function dlq purge +slug: fission_function_dlq_purge +url: /docs/reference/fission-cli/fission_function_dlq_purge/ +--- +## fission function dlq purge + +Permanently delete every dead-lettered async invocation + +``` +fission function dlq purge [flags] +``` + +### Options + +``` + --queue string Dead-letter queue to operate on: empty for async invocations, or an RFC-0027 broker egress queue (mq-egress-, e.g. mq-egress-kafka) + -h, --help help for purge +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function dlq](/docs/reference/fission-cli/fission_function_dlq/) - Inspect and manage the async invocation dead-letter queue + diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq_redrive.md b/content/en/docs/reference/fission-cli/fission_function_dlq_redrive.md new file mode 100644 index 00000000..34912078 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_dlq_redrive.md @@ -0,0 +1,34 @@ +--- +title: fission function dlq redrive +slug: fission_function_dlq_redrive +url: /docs/reference/fission-cli/fission_function_dlq_redrive/ +--- +## fission function dlq redrive + +Re-enqueue dead-lettered async invocations for another delivery + +``` +fission function dlq redrive [flags] +``` + +### Options + +``` + --id string Durable invocation id of a dead-lettered async invocation + --all Apply to every dead-lettered invocation + --queue string Dead-letter queue to operate on: empty for async invocations, or an RFC-0027 broker egress queue (mq-egress-, e.g. mq-egress-kafka) + -h, --help help for redrive +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function dlq](/docs/reference/fission-cli/fission_function_dlq/) - Inspect and manage the async invocation dead-letter queue + diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq_show.md b/content/en/docs/reference/fission-cli/fission_function_dlq_show.md new file mode 100644 index 00000000..5f60af20 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_dlq_show.md @@ -0,0 +1,33 @@ +--- +title: fission function dlq show +slug: fission_function_dlq_show +url: /docs/reference/fission-cli/fission_function_dlq_show/ +--- +## fission function dlq show + +Show the full envelope of one dead-lettered async invocation + +``` +fission function dlq show [flags] +``` + +### Options + +``` + --id string Durable invocation id of a dead-lettered async invocation + --queue string Dead-letter queue to operate on: empty for async invocations, or an RFC-0027 broker egress queue (mq-egress-, e.g. mq-egress-kafka) + -h, --help help for show +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function dlq](/docs/reference/fission-cli/fission_function_dlq/) - Inspect and manage the async invocation dead-letter queue + diff --git a/content/en/docs/reference/fission-cli/fission_function_log.md b/content/en/docs/reference/fission-cli/fission_function_log.md index 3845edba..954c53ca 100644 --- a/content/en/docs/reference/fission-cli/fission_function_log.md +++ b/content/en/docs/reference/fission-cli/fission_function_log.md @@ -16,11 +16,11 @@ fission function log [flags] ``` --name string Function name -f, --follow -f |:|: Specify if the logs should be streamed - -r, --reverse -r |:|: Specify the log reverse query base on time, it will be invalid if the 'follow' flag is specified. valid for dbtype as influxdb or loki + -r, --reverse -r |:|: Specify the log reverse query base on time, it will be invalid if the 'follow' flag is specified. valid for dbtype as loki --recordcount int Get N most recent log records (default 20) -d, --detail -d |:|: Display detailed information --pod string Function pod name (use the latest pod name if unspecified) - --dbtype string Log database type: kubernetes (default), loki, or influxdb (deprecated) (default "kubernetes") + --dbtype string Log database type: kubernetes (default) or loki (default "kubernetes") --pod-namespace string Namespace in which function's pod are created. If not specified, function's namespace is used. Note: version <1.18 used fission-function as pod's default ns. --all-pods Get all pod's logs in the function. --request-id string Filter logs to a single invocation by its X-Fission-Request-ID (loki dbtype) diff --git a/content/en/docs/reference/fission-cli/fission_function_test.md b/content/en/docs/reference/fission-cli/fission_function_test.md index c1b1e411..fc3c35b8 100644 --- a/content/en/docs/reference/fission-cli/fission_function_test.md +++ b/content/en/docs/reference/fission-cli/fission_function_test.md @@ -20,7 +20,8 @@ fission function test [flags] -b, --body string -b |:|: Request body -q, --query stringArray -q |:|: Request query parameters: -q key1=value1 -q key2=value2 -t, --timeout duration -t |:|: Length of time to wait for the response. If set to zero or negative number, no timeout is set (default 1m0s) - --dbtype string Log database type: kubernetes (default), loki, or influxdb (deprecated) (default "kubernetes") + --async RFC-0024: invoke asynchronously (X-Fission-Invoke-Mode: async); prints the invocation id instead of waiting for the response. Set FISSION_INTERNAL_AUTH_SECRET when authentication is enabled. + --dbtype string Log database type: kubernetes (default) or loki (default "kubernetes") --subpath string Sub Path to check if function internally supports routing -h, --help help for test ``` diff --git a/content/en/docs/reference/fission-cli/fission_function_update.md b/content/en/docs/reference/fission-cli/fission_function_update.md index d66518a0..db4c34de 100644 --- a/content/en/docs/reference/fission-cli/fission_function_update.md +++ b/content/en/docs/reference/fission-cli/fission_function_update.md @@ -14,48 +14,54 @@ fission function update [flags] ### Options ``` - --name string Function name - --env string Environment name for function - --entrypoint string --entry |:|: Entry point for environment v2 to load with - --pkgname string --pkg |:|: Name of the existing package (--deploy and --src and --env will be ignored), should be in the same namespace as the function - --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") - --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. - --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. - --specializationtimeout int --st |:|: Timeout for executor to wait for function pod creation (default 120) - --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) - --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) - --concurrency poolmgr --con |:|: Maximum number of pods specialized concurrently to serve requests (Only valid for executortype; poolmgr) (default 500) - --requestsperpod poolmgr --rpp |:|: Maximum number of concurrent requests that can be served by a specialized pod (Only valid for executortype; poolmgr) (default 1) - --streaming Enable streaming (SSE/chunked/WebSocket) responses for this function; the response is flushed incrementally and not cut by the function timeout - --streamingprotocol string Streaming protocol when --streaming is set; one of 'auto', 'sse', 'chunked', 'websocket' (default "auto") - --streamingidletimeout int Idle timeout (seconds) for a streaming response before it is aborted; reset on each chunk (default 60) - --streamingmaxduration int Hard ceiling (seconds) on total streaming response lifetime; 0 means no ceiling (the idle timeout governs) - --expose-as-mcp Advertise this function as a Model Context Protocol (MCP) tool on the MCP server - --tool-description string Agent-facing tool description (required with --expose-as-mcp) - --tool-input-schema string Path to a JSON Schema file describing the tool's arguments; advertised verbatim as the MCP tool inputSchema - --tool-name string Override the advertised MCP tool name (defaults to -) - --onceonly poolmgr --yolo |:|: Specifies if specialized pod will serve exactly one request in its lifetime (Only valid for executortype; poolmgr) - --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" - --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" - --retainpods int Number of pods to retain after pods specialization. - --code string URL or local path for single file source code - --sourcearchive stringArray --source |:|: --src |:|: URL or local paths for source archive - --deployarchive stringArray --deploy |:|: URL or local paths for binary archive - --srcchecksum string SHA256 checksum of source archive when providing URL - --deploychecksum string SHA256 checksum of deploy archive when providing URL - --insecure Skip generating SHA256 checksum for file integrity validation - --oci string Pre-built OCI image reference containing the deployment code (registry/repo:tag[@digest]) - --buildcmd string Package build command for builder to run with - -f, --force -f |:|: Force update a package even if it is used by one or more functions - --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) - --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) - --minmemory int Minimum memory to be assigned to pod (In megabyte) - --maxmemory int Maximum memory to be assigned to pod (In megabyte) - --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) - --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) - --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) - --spec Save to the spec directory instead of creating on cluster - -h, --help help for update + --name string Function name + --env string Environment name for function + --entrypoint string --entry |:|: Entry point for environment v2 to load with + --pkgname string --pkg |:|: Name of the existing package (--deploy and --src and --env will be ignored), should be in the same namespace as the function + --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") + --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. + --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. + --specializationtimeout int --st |:|: Timeout for executor to wait for function pod creation (default 120) + --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) + --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) + --concurrency poolmgr --con |:|: Maximum number of pods specialized concurrently to serve requests (Only valid for executortype; poolmgr) (default 500) + --requestsperpod poolmgr --rpp |:|: Maximum number of concurrent requests that can be served by a specialized pod (Only valid for executortype; poolmgr) (default 1) + --streaming Enable streaming (SSE/chunked/WebSocket) responses for this function; the response is flushed incrementally and not cut by the function timeout + --streamingprotocol string Streaming protocol when --streaming is set; one of 'auto', 'sse', 'chunked', 'websocket' (default "auto") + --streamingidletimeout int Idle timeout (seconds) for a streaming response before it is aborted; reset on each chunk (default 60) + --streamingmaxduration int Hard ceiling (seconds) on total streaming response lifetime; 0 means no ceiling (the idle timeout governs) + --expose-as-mcp Advertise this function as a Model Context Protocol (MCP) tool on the MCP server + --tool-description string Agent-facing tool description (required with --expose-as-mcp) + --tool-input-schema string Path to a JSON Schema file describing the tool's arguments; advertised verbatim as the MCP tool inputSchema + --tool-name string Override the advertised MCP tool name (defaults to -) + --async-retry-max-attempts int Async delivery attempt budget before dead-lettering (RFC-0024) + --async-max-age duration Max time an async invocation may wait for successful delivery before it is dead-lettered (RFC-0024) + --async-on-success string Same-namespace function to invoke with the result after a successful async delivery (RFC-0024); empty clears it + --async-on-failure string Same-namespace function to invoke with the result after a permanent async failure (RFC-0024); empty clears it + --async-on-success-topic string Statestore topic to publish the result envelope to after a successful async delivery (RFC-0027); empty clears it + --async-on-failure-topic string Statestore topic to publish the result envelope to after a permanent async failure (RFC-0027); empty clears it + --onceonly poolmgr --yolo |:|: Specifies if specialized pod will serve exactly one request in its lifetime (Only valid for executortype; poolmgr) + --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" + --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" + --retainpods int Number of pods to retain after pods specialization. + --code string URL or local path for single file source code + --sourcearchive stringArray --source |:|: --src |:|: URL or local paths for source archive + --deployarchive stringArray --deploy |:|: URL or local paths for binary archive + --srcchecksum string SHA256 checksum of source archive when providing URL + --deploychecksum string SHA256 checksum of deploy archive when providing URL + --insecure Skip generating SHA256 checksum for file integrity validation + --oci string Pre-built OCI image reference containing the deployment code (registry/repo:tag[@digest]) + --buildcmd string Package build command for builder to run with + -f, --force -f |:|: Force update a package even if it is used by one or more functions + --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) + --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) + --minmemory int Minimum memory to be assigned to pod (In megabyte) + --maxmemory int Maximum memory to be assigned to pod (In megabyte) + --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) + --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) + --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) + --spec Save to the spec directory instead of creating on cluster + -h, --help help for update ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_httptrigger_create.md b/content/en/docs/reference/fission-cli/fission_httptrigger_create.md index a337bbfb..0fcfce30 100644 --- a/content/en/docs/reference/fission-cli/fission_httptrigger_create.md +++ b/content/en/docs/reference/fission-cli/fission_httptrigger_create.md @@ -33,6 +33,7 @@ fission httptrigger create [flags] --dry View the generated specs --prefix string Prefix with which functions are exposed. NOTE: Prefix takes precedence over URL/RelativeURL [DEPRECATED for 'fn create', use 'route create' instead] --keepprefix Keep the prefix in the URL while forwarding request to the function + --invocation-mode string RFC-0024: 'async' makes every request through this trigger asynchronous (durable 202 + invocation id); empty is the default synchronous mode -h, --help help for create ``` diff --git a/content/en/docs/reference/fission-cli/fission_httptrigger_update.md b/content/en/docs/reference/fission-cli/fission_httptrigger_update.md index 5c7c8131..d24544d8 100644 --- a/content/en/docs/reference/fission-cli/fission_httptrigger_update.md +++ b/content/en/docs/reference/fission-cli/fission_httptrigger_update.md @@ -31,6 +31,7 @@ fission httptrigger update [flags] --weight ints Weight for each function supplied with --function flag, in the same order. Used for canary deployment --prefix string Prefix with which functions are exposed. NOTE: Prefix takes precedence over URL/RelativeURL [DEPRECATED for 'fn create', use 'route create' instead] --keepprefix Keep the prefix in the URL while forwarding request to the function + --invocation-mode string RFC-0024: 'async' makes every request through this trigger asynchronous (durable 202 + invocation id); empty is the default synchronous mode -h, --help help for update ``` diff --git a/content/en/docs/reference/fission-cli/fission_mqtrigger_create.md b/content/en/docs/reference/fission-cli/fission_mqtrigger_create.md index 898ee163..50431eb5 100644 --- a/content/en/docs/reference/fission-cli/fission_mqtrigger_create.md +++ b/content/en/docs/reference/fission-cli/fission_mqtrigger_create.md @@ -17,8 +17,8 @@ fission mqtrigger create [flags] --function string Function name --topic string Message queue Topic the trigger listens on --name string Message queue trigger name - --mqtype string For mqtype "fission" => kafka - For mqtype "keda" => kafka, aws-sqs-queue, aws-kinesis-stream, gcp-pubsub, stan, nats-jetstream, rabbitmq, redis (default "kafka") + --mqtype string For mqtkind "fission" => kafka, statestore (the RFC-0027 built-in, no broker) + For mqtkind "keda" => kafka, aws-sqs-queue, aws-kinesis-stream, gcp-pubsub, stan, nats-jetstream, rabbitmq, redis (default "kafka") --resptopic string Topic that the function response is sent on (response discarded if unspecified) --errortopic string Topic that the function error messages are sent to (errors discarded if unspecified --maxretries int Maximum number of times the function will be retried upon failure diff --git a/content/en/docs/reference/fission-cli/fission_topic.md b/content/en/docs/reference/fission-cli/fission_topic.md new file mode 100644 index 00000000..08b3e496 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_topic.md @@ -0,0 +1,29 @@ +--- +title: fission topic +slug: fission_topic +url: /docs/reference/fission-cli/fission_topic/ +--- +## fission topic + +Publish to and inspect RFC-0027 eventing topics + +### Options + +``` + -h, --help help for topic +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission](/docs/reference/fission-cli/fission/) - Serverless framework for Kubernetes +* [fission topic peek](/docs/reference/fission-cli/fission_topic_peek/) - Show the most recent events on a statestore topic +* [fission topic publish](/docs/reference/fission-cli/fission_topic_publish/) - Publish an event to a topic (statestore direct, or a broker via egress) + diff --git a/content/en/docs/reference/fission-cli/fission_topic_peek.md b/content/en/docs/reference/fission-cli/fission_topic_peek.md new file mode 100644 index 00000000..03a068be --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_topic_peek.md @@ -0,0 +1,33 @@ +--- +title: fission topic peek +slug: fission_topic_peek +url: /docs/reference/fission-cli/fission_topic_peek/ +--- +## fission topic peek + +Show the most recent events on a statestore topic + +``` +fission topic peek [flags] +``` + +### Options + +``` + --topic string Topic name + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + --limit int Maximum events to peek (default 10) + -h, --help help for peek +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission topic](/docs/reference/fission-cli/fission_topic/) - Publish to and inspect RFC-0027 eventing topics + diff --git a/content/en/docs/reference/fission-cli/fission_topic_publish.md b/content/en/docs/reference/fission-cli/fission_topic_publish.md new file mode 100644 index 00000000..82bb3e87 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_topic_publish.md @@ -0,0 +1,35 @@ +--- +title: fission topic publish +slug: fission_topic_publish +url: /docs/reference/fission-cli/fission_topic_publish/ +--- +## fission topic publish + +Publish an event to a topic (statestore direct, or a broker via egress) + +``` +fission topic publish [flags] +``` + +### Options + +``` + --topic string Topic name + --data string Event payload to publish + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + --content-type string Content type the payload travels with (consuming triggers replay it) (default "application/json") + --mqtype string Message queue provider: statestore (built-in, namespace-scoped), or a broker type with an egress head (kafka — broker topics are cluster-flat, like kafka mqtriggers) (default "statestore") + -h, --help help for publish +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission topic](/docs/reference/fission-cli/fission_topic/) - Publish to and inspect RFC-0027 eventing topics + diff --git a/content/en/docs/reference/fission-cli/fission_workflow.md b/content/en/docs/reference/fission-cli/fission_workflow.md new file mode 100644 index 00000000..c0905d61 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow.md @@ -0,0 +1,35 @@ +--- +title: fission workflow +slug: fission_workflow +url: /docs/reference/fission-cli/fission_workflow/ +--- +## fission workflow + +Create, update and manage workflows + +### Options + +``` + -h, --help help for workflow +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission](/docs/reference/fission-cli/fission/) - Serverless framework for Kubernetes +* [fission workflow create](/docs/reference/fission-cli/fission_workflow_create/) - Create a workflow from a manifest +* [fission workflow delete](/docs/reference/fission-cli/fission_workflow_delete/) - Delete a workflow +* [fission workflow graph](/docs/reference/fission-cli/fission_workflow_graph/) - Render a workflow's state machine as a mermaid diagram +* [fission workflow list](/docs/reference/fission-cli/fission_workflow_list/) - List workflows +* [fission workflow run](/docs/reference/fission-cli/fission_workflow_run/) - Start one execution of a workflow +* [fission workflow runs](/docs/reference/fission-cli/fission_workflow_runs/) - List and inspect workflow runs (executions) +* [fission workflow update](/docs/reference/fission-cli/fission_workflow_update/) - Update a workflow from a manifest +* [fission workflow validate](/docs/reference/fission-cli/fission_workflow_validate/) - Validate a workflow manifest offline (graph, expressions), plus referenced-function existence against the cluster unless --offline + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_create.md b/content/en/docs/reference/fission-cli/fission_workflow_create.md new file mode 100644 index 00000000..e10f310f --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_create.md @@ -0,0 +1,39 @@ +--- +title: fission workflow create +slug: fission_workflow_create +url: /docs/reference/fission-cli/fission_workflow_create/ +--- +## fission workflow create + +Create a workflow from a manifest + +### Synopsis + +Create a workflow from a manifest. --name overrides the manifest's metadata.name. + +``` +fission workflow create [flags] +``` + +### Options + +``` + -f, --file string -f |:|: Path to a Workflow manifest (kind: Workflow) or a bare WorkflowSpec YAML + --name string Name of the workflow + --spec Save to the spec directory instead of creating on cluster + --dry View the generated specs + -h, --help help for create +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_delete.md b/content/en/docs/reference/fission-cli/fission_workflow_delete.md new file mode 100644 index 00000000..4f5b67d5 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_delete.md @@ -0,0 +1,33 @@ +--- +title: fission workflow delete +slug: fission_workflow_delete +url: /docs/reference/fission-cli/fission_workflow_delete/ +--- +## fission workflow delete + +Delete a workflow + +``` +fission workflow delete [flags] +``` + +### Options + +``` + --name string Name of the workflow + --ignorenotfound Treat "resource not found" as a successful delete. + -h, --help help for delete +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_graph.md b/content/en/docs/reference/fission-cli/fission_workflow_graph.md new file mode 100644 index 00000000..8bd06312 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_graph.md @@ -0,0 +1,34 @@ +--- +title: fission workflow graph +slug: fission_workflow_graph +url: /docs/reference/fission-cli/fission_workflow_graph/ +--- +## fission workflow graph + +Render a workflow's state machine as a mermaid diagram + +``` +fission workflow graph [flags] +``` + +### Options + +``` + --name string Name of the workflow + -f, --file string -f |:|: Path to a Workflow manifest (kind: Workflow) or a bare WorkflowSpec YAML + --open Render the diagram in a browser (served locally; the graph never leaves your machine) + -h, --help help for graph +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_list.md b/content/en/docs/reference/fission-cli/fission_workflow_list.md new file mode 100644 index 00000000..0672d0da --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_list.md @@ -0,0 +1,37 @@ +--- +title: fission workflow list +slug: fission_workflow_list +url: /docs/reference/fission-cli/fission_workflow_list/ +--- +## fission workflow list + +List workflows + +### Synopsis + +List all workflows in a namespace if specified, else, list workflows across all namespaces + +``` +fission workflow list [flags] +``` + +### Options + +``` + -A, --all-namespaces -A |:|: Fetch resources from all namespaces + -o, --output string -o |:|: Output format: wide, json or yaml (default: table) + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_run.md b/content/en/docs/reference/fission-cli/fission_workflow_run.md new file mode 100644 index 00000000..3c0b6e5e --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_run.md @@ -0,0 +1,33 @@ +--- +title: fission workflow run +slug: fission_workflow_run +url: /docs/reference/fission-cli/fission_workflow_run/ +--- +## fission workflow run + +Start one execution of a workflow + +``` +fission workflow run [flags] +``` + +### Options + +``` + --name string Name of the workflow + --input string Run input as inline JSON, or @path/to/file.json + -h, --help help for run +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_runs.md b/content/en/docs/reference/fission-cli/fission_workflow_runs.md new file mode 100644 index 00000000..2ed2271d --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_runs.md @@ -0,0 +1,32 @@ +--- +title: fission workflow runs +slug: fission_workflow_runs +url: /docs/reference/fission-cli/fission_workflow_runs/ +--- +## fission workflow runs + +List and inspect workflow runs (executions) + +### Options + +``` + -h, --help help for runs +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows +* [fission workflow runs cancel](/docs/reference/fission-cli/fission_workflow_runs_cancel/) - Request cancellation of a workflow run (in-flight steps drain) +* [fission workflow runs describe](/docs/reference/fission-cli/fission_workflow_runs_describe/) - Answer "where did this run stop": phase, active state, last error, attempts +* [fission workflow runs graph](/docs/reference/fission-cli/fission_workflow_runs_graph/) - Render a run's state machine with each state colored by what the run did +* [fission workflow runs history](/docs/reference/fission-cli/fission_workflow_runs_history/) - Show a run's full step-level event history +* [fission workflow runs list](/docs/reference/fission-cli/fission_workflow_runs_list/) - List workflow runs + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_runs_cancel.md b/content/en/docs/reference/fission-cli/fission_workflow_runs_cancel.md new file mode 100644 index 00000000..db3c5697 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_runs_cancel.md @@ -0,0 +1,32 @@ +--- +title: fission workflow runs cancel +slug: fission_workflow_runs_cancel +url: /docs/reference/fission-cli/fission_workflow_runs_cancel/ +--- +## fission workflow runs cancel + +Request cancellation of a workflow run (in-flight steps drain) + +``` +fission workflow runs cancel [flags] +``` + +### Options + +``` + --name string Name of the workflow run + -h, --help help for cancel +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow runs](/docs/reference/fission-cli/fission_workflow_runs/) - List and inspect workflow runs (executions) + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_runs_describe.md b/content/en/docs/reference/fission-cli/fission_workflow_runs_describe.md new file mode 100644 index 00000000..1668d2d6 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_runs_describe.md @@ -0,0 +1,32 @@ +--- +title: fission workflow runs describe +slug: fission_workflow_runs_describe +url: /docs/reference/fission-cli/fission_workflow_runs_describe/ +--- +## fission workflow runs describe + +Answer "where did this run stop": phase, active state, last error, attempts + +``` +fission workflow runs describe [flags] +``` + +### Options + +``` + --name string Name of the workflow run + -h, --help help for describe +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow runs](/docs/reference/fission-cli/fission_workflow_runs/) - List and inspect workflow runs (executions) + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_runs_graph.md b/content/en/docs/reference/fission-cli/fission_workflow_runs_graph.md new file mode 100644 index 00000000..7174aef3 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_runs_graph.md @@ -0,0 +1,37 @@ +--- +title: fission workflow runs graph +slug: fission_workflow_runs_graph +url: /docs/reference/fission-cli/fission_workflow_runs_graph/ +--- +## fission workflow runs graph + +Render a run's state machine with each state colored by what the run did + +### Synopsis + +Render a run's state machine as a mermaid diagram, coloring each state by what this run did: succeeded, active, failed, or never reached. Drawn against the spec snapshot the run is executing, so it stays accurate even if the workflow was edited or deleted since. + +``` +fission workflow runs graph [flags] +``` + +### Options + +``` + --name string Name of the workflow run + --open Render the diagram in a browser (served locally; the graph never leaves your machine) + -h, --help help for graph +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow runs](/docs/reference/fission-cli/fission_workflow_runs/) - List and inspect workflow runs (executions) + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_runs_history.md b/content/en/docs/reference/fission-cli/fission_workflow_runs_history.md new file mode 100644 index 00000000..a8da5f4b --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_runs_history.md @@ -0,0 +1,33 @@ +--- +title: fission workflow runs history +slug: fission_workflow_runs_history +url: /docs/reference/fission-cli/fission_workflow_runs_history/ +--- +## fission workflow runs history + +Show a run's full step-level event history + +``` +fission workflow runs history [flags] +``` + +### Options + +``` + --name string Name of the workflow run + --io Include step input/output payloads (dereferences spilled documents) + -h, --help help for history +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow runs](/docs/reference/fission-cli/fission_workflow_runs/) - List and inspect workflow runs (executions) + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_runs_list.md b/content/en/docs/reference/fission-cli/fission_workflow_runs_list.md new file mode 100644 index 00000000..6873c809 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_runs_list.md @@ -0,0 +1,34 @@ +--- +title: fission workflow runs list +slug: fission_workflow_runs_list +url: /docs/reference/fission-cli/fission_workflow_runs_list/ +--- +## fission workflow runs list + +List workflow runs + +``` +fission workflow runs list [flags] +``` + +### Options + +``` + --workflow string Only show runs of this workflow + -A, --all-namespaces -A |:|: Fetch resources from all namespaces + -o, --output string -o |:|: Output format: wide, json or yaml (default: table) + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow runs](/docs/reference/fission-cli/fission_workflow_runs/) - List and inspect workflow runs (executions) + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_update.md b/content/en/docs/reference/fission-cli/fission_workflow_update.md new file mode 100644 index 00000000..a7e1e051 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_update.md @@ -0,0 +1,37 @@ +--- +title: fission workflow update +slug: fission_workflow_update +url: /docs/reference/fission-cli/fission_workflow_update/ +--- +## fission workflow update + +Update a workflow from a manifest + +### Synopsis + +Update a workflow from a manifest. --name overrides the manifest's metadata.name. + +``` +fission workflow update [flags] +``` + +### Options + +``` + -f, --file string -f |:|: Path to a Workflow manifest (kind: Workflow) or a bare WorkflowSpec YAML + --name string Name of the workflow + -h, --help help for update +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows + diff --git a/content/en/docs/reference/fission-cli/fission_workflow_validate.md b/content/en/docs/reference/fission-cli/fission_workflow_validate.md new file mode 100644 index 00000000..62c2ff63 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_workflow_validate.md @@ -0,0 +1,34 @@ +--- +title: fission workflow validate +slug: fission_workflow_validate +url: /docs/reference/fission-cli/fission_workflow_validate/ +--- +## fission workflow validate + +Validate a workflow manifest offline (graph, expressions), plus referenced-function existence against the cluster unless --offline + +``` +fission workflow validate [flags] +``` + +### Options + +``` + -f, --file string -f |:|: Path to a Workflow manifest (kind: Workflow) or a bare WorkflowSpec YAML + --name string Name of the workflow + --offline Skip cluster checks (e.g. referenced-function existence) + -h, --help help for validate +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission workflow](/docs/reference/fission-cli/fission_workflow/) - Create, update and manage workflows + diff --git a/content/en/docs/releases/v1.28.0.md b/content/en/docs/releases/v1.28.0.md new file mode 100644 index 00000000..3dc90989 --- /dev/null +++ b/content/en/docs/releases/v1.28.0.md @@ -0,0 +1,48 @@ +--- +title: "v1.28.0 Release Notes" +linkTitle: v1.28.0 +draft: true +weight: 65 +description: > + Fission v1.28.0 release notes: durable and asynchronous execution — a statestore substrate, asynchronous invocation with retries and a dead-letter queue, and durable workflows. +--- + +{{% notice info %}} +This page is a draft prepared ahead of the release cut. +Version numbers, upgrade notes, and the changelog are finalized when v1.28.0 ships. +{{% /notice %}} + +## Upgrade Notes + + + +All three headline features are **opt-in** and off by default, so a routine upgrade changes nothing for an existing install until you enable them. +For the general upgrade steps (CRDs, CLI, Helm chart), see the [Upgrade Guide](/docs/installation/upgrade/). + +## Highlights + +Fission v1.28.0 is themed around **durable and asynchronous execution**: a shared durable substrate, and two ways to build on it. + +- **Statestore — a durable state substrate.** + A single interface exposing key/value, an append-only event log, and a visibility-timeout queue, served by a pluggable driver: **embedded** SQLite on a PVC for development, or an **external** Postgres DSN for production and HA. + Fission deploys no database product of its own. + It is the foundation the next two features build on. + See [Statestore](/docs/architecture/statestore/). +- **Asynchronous invocation — fire-and-forget with durability.** + Send `X-Fission-Invoke-Mode: async` (or `fission fn test --async`) and the router enqueues the call, returns a durable invocation id with `202 Accepted`, and delivers it in the background with retries. + Per-function delivery config sets the attempt budget and max age; a **dead-letter queue** (`fission function dlq`) captures what cannot be delivered; result **destinations** route the outcome to another function; and an opt-in KEDA `ScaledObject` autoscales the workers on the backlog. + See [Asynchronous invocation](/docs/usage/function/async-invocation/). +- **Durable Workflows — orchestrate functions as a resumable state machine.** + A `Workflow` custom resource is a state machine over your functions; each execution is a `WorkflowRun` recorded step by step in the statestore event log, so a run survives controller restarts, resumes exactly where it stopped, retries transient failures with backoff, and routes typed business errors. + States cover `Task`, `Choice`, `Parallel`, `Map`, `Wait`, and `Succeed`/`Fail`, with a `fission workflow` CLI that includes a local day/night graph viewer and a per-run status overlay. + See [Workflows](/docs/usage/workflows/). + +## References + +- [Statestore](/docs/architecture/statestore/) +- [Asynchronous invocation](/docs/usage/function/async-invocation/) +- [Workflows](/docs/usage/workflows/) · [Concept](/docs/concepts/workflows/) · [Authoring](/docs/usage/workflows/authoring/) · [Examples](/docs/usage/workflows/examples/) + +## Changelog + + diff --git a/content/en/docs/usage/_index.en.md b/content/en/docs/usage/_index.en.md index 029a06b5..9c670f56 100644 --- a/content/en/docs/usage/_index.en.md +++ b/content/en/docs/usage/_index.en.md @@ -25,6 +25,11 @@ Work through the function workflow in roughly this order: * [Access URL parameters]({{% ref "function/accessing-url-params.md" %}}) — read path parameters from REST-style routes. * [Canary deployments]({{% ref "function/canary-deployments.md" %}}) — roll out a new function version gradually and roll back automatically on failure. +Durable and asynchronous execution: + +* [Asynchronous invocation]({{% ref "function/async-invocation.md" %}}) — invoke a function fire-and-forget with a durable id, background retries, a dead-letter queue, and result destinations. +* [Workflows]({{% ref "workflows/_index.md" %}}) — orchestrate several functions as one durable, resumable state machine with parallelism, retries, and durable waits. + Operational and advanced topics: * [Stream function responses]({{% ref "function/streaming.md" %}}) — return SSE, chunked, or WebSocket responses incrementally for LLM tokens, chat, and long-running calls. diff --git a/content/en/docs/usage/function/async-invocation.md b/content/en/docs/usage/function/async-invocation.md new file mode 100644 index 00000000..29abdd51 --- /dev/null +++ b/content/en/docs/usage/function/async-invocation.md @@ -0,0 +1,146 @@ +--- +title: "Asynchronous Invocation" +draft: false +weight: 50 +description: > + Invoke a Fission function fire-and-forget — the router enqueues the call, returns a durable invocation id, and delivers it in the background with retries, a dead-letter queue, and result destinations. +--- + +**Invoke a function fire-and-forget: the router accepts the call, returns a durable invocation id immediately, and delivers it in the background with retries — so the caller never waits for the work to finish.** + +A normal invocation is synchronous: the caller holds the connection open until the function returns a response. +That is wrong for work that is slow, spiky, or must not be lost if a caller disconnects — sending email, processing an upload, calling a rate-limited third party. +Starting with Fission {{< release-version >}}, an asynchronous invocation hands that work to Fission and returns right away. + +The caller sends `X-Fission-Invoke-Mode: async` (or uses `fission fn test --async`). +The router **enqueues** the call on the [statestore]({{% ref "/docs/architecture/statestore.md" %}}) queue, returns **`202 Accepted`** with a durable invocation id, and a background worker delivers it — retrying transient failures, dead-lettering what it cannot deliver, and optionally invoking a destination function with the result. + +```mermaid +flowchart TB + caller["Caller"]:::user -->|"1. request + X-Fission-Invoke-Mode: async"| router["Router"]:::fission + router -->|"2. enqueue"| queue["Statestore Queue"]:::store + router -->|"3. 202 + invocation id"| caller + queue -->|"4. dequeue"| worker["Async Worker"]:::fission + worker -->|"5. invoke"| pod["Function Pod"]:::pod + worker -.->|"exhausted / too old"| dlq["Dead-letter Queue"]:::store + worker -.->|"on success / failure"| dest["Destination Function"]:::pod + + classDef user fill:#ffffff,stroke:#94a3b8,color:#1f2a43 + classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43 + classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3 + classDef store fill:#fff7e0,stroke:#dba514,color:#1f2a43,stroke-dasharray:5 3 +``` + +## Prerequisites + +Asynchronous invocation is **off by default** and needs the [statestore]({{% ref "/docs/architecture/statestore.md" %}}) for its durable queue: + +```bash +helm upgrade --install fission fission-charts/fission-all \ + --namespace fission \ + --set statestore.enabled=true \ + --set asyncInvocation.enabled=true +``` + +Embedded statestore mode is enough to try async invocation. +[Autoscaling](#autoscaling) additionally requires `statestore.mode=external`. + +## Invoke asynchronously + +The CLI sends the async header and prints the durable invocation id instead of waiting for a response: + +```bash +$ fission fn test --name resize-image --method POST --body @photo.json --async +Invocation accepted: id=inv-8f2c1a9e +``` + +Any HTTP caller can do the same by setting the header on a request to the function's [HTTP trigger]({{% ref "/docs/usage/triggers/http-trigger.md" %}}): + +```bash +curl -XPOST -H "X-Fission-Invoke-Mode: async" \ + --data @photo.json \ + http://$FISSION_ROUTER/resize-image +# HTTP/1.1 202 Accepted +# X-Fission-Invocation-Id: inv-8f2c1a9e +``` + +{{% notice info %}} +When [authentication]({{% ref "/docs/installation/authentication.md" %}}) is enabled, set `FISSION_INTERNAL_AUTH_SECRET` so the CLI signs the internal invocation. +{{% /notice %}} + +## Delivery guarantees and retries + +The worker retries a failed delivery with exponential backoff until it either succeeds, exhausts the attempt budget, or the invocation gets too old. +When either bound is crossed the invocation is moved to the [dead-letter queue](#dead-letter-queue) rather than dropped. +Configure the bounds per function on `fn create` / `fn update`: + +```bash +fission fn update --name resize-image \ + --async-retry-max-attempts 5 \ + --async-max-age 1h +``` + +| Flag | Meaning | +| --- | --- | +| `--async-retry-max-attempts` | Maximum delivery attempts before dead-lettering. | +| `--async-max-age` | Maximum age of an invocation before dead-lettering, regardless of attempts. | + +## Result destinations + +An async invocation has no caller waiting for its result, so you can route the result to another function in the same namespace: + +```bash +fission fn update --name resize-image \ + --async-on-success notify-done \ + --async-on-failure alert-oncall +``` + +| Flag | Meaning | +| --- | --- | +| `--async-on-success` | Same-namespace function invoked with the result when delivery succeeds. | +| `--async-on-failure` | Same-namespace function invoked when the invocation is dead-lettered. | + +To fan the result out to an event topic instead of a single function, use the `--async-on-success-topic` / `--async-on-failure-topic` variants, which publish the result to a Fission eventing topic that any number of functions can subscribe to. + +## Dead-letter queue + +Invocations that exhaust their retries or age out land in the dead-letter queue, where you can inspect and act on them: + +```bash +# List dead-lettered invocations +fission function dlq list + +# Inspect one +fission function dlq show --id inv-8f2c1a9e + +# Re-drive one back onto the queue, or all of them +fission function dlq redrive --id inv-8f2c1a9e +fission function dlq redrive --all + +# Discard them +fission function dlq purge --all +``` + +| Flag | Meaning | +| --- | --- | +| `--id` | Operate on a single durable invocation id. | +| `--all` | Apply to every dead-lettered invocation. | +| `--queue` | Target queue: empty for async invocations, or an eventing broker egress queue (`mq-egress-`). | +| `--limit` | Cap the number of entries `dlq list` returns. | + +## Autoscaling + +An opt-in KEDA `ScaledObject` scales the async workers on the queue backlog, so a burst of enqueued work spins up more delivery capacity and idles back down when the queue drains. + +{{% notice warning %}} +Autoscaling requires `statestore.mode=external` (Postgres). +The KEDA PostgreSQL scaler reads the backlog from the database directly and cannot see the embedded SQLite file. +See [Statestore]({{% ref "/docs/architecture/statestore.md" %}}). +{{% /notice %}} + +## Related + +- [Statestore]({{% ref "/docs/architecture/statestore.md" %}}) — the durable queue behind async delivery. +- [Durable Workflows]({{% ref "/docs/usage/workflows/_index.md" %}}) — orchestrate multiple functions with the same durable substrate. +- [Create and run functions]({{% ref "functions.en.md" %}}) — the everyday function workflow. +- [Custom Resource Definition Specification]({{% ref "/docs/reference/crd-reference.md" %}}) — the async delivery fields on the `Function` resource. diff --git a/content/en/docs/usage/workflows/_index.md b/content/en/docs/usage/workflows/_index.md new file mode 100644 index 00000000..cbe70a40 --- /dev/null +++ b/content/en/docs/usage/workflows/_index.md @@ -0,0 +1,68 @@ +--- +title: "Workflows" +weight: 22 +description: > + Orchestrate several functions as one durable, resumable state machine — with parallel branches, data-driven routing, retries, durable waits, and typed-error handling. +--- + +**A workflow orchestrates several functions as one durable state machine: it survives controller restarts, resumes exactly where it stopped, retries transient failures, and routes typed business errors — all recorded step by step in the statestore.** + +Starting with Fission {{< release-version >}}, you define a `Workflow` as a state machine over your functions and start a `WorkflowRun` each time you want it to execute. +For the mental model behind the two resources and the durability guarantees, read the [Workflows concept]({{% ref "/docs/concepts/workflows.md" %}}); this guide is how to enable, author, run, and inspect them. + +## Prerequisites + +Workflows are **off by default** and require the [statestore]({{% ref "/docs/architecture/statestore.md" %}}), which holds each run's event log: + +```bash +helm upgrade --install fission fission-charts/fission-all \ + --namespace fission \ + --set statestore.enabled=true \ + --set workflows.enabled=true +``` + +Embedded statestore mode is enough to run workflows. + +## State types + +A workflow is a map of named states; each has a `type`: + +| State | Purpose | +| --- | --- | +| `Task` | Invoke a function, with per-step timeout, retry, and error catching. | +| `Choice` | Route to the next state based on the run's data — no function call. | +| `Parallel` | Run several branches concurrently and join their results in order. | +| `Map` | Run one branch per element of an array, bounded by `maxConcurrency`. | +| `Wait` | Pause the run durably for a `duration`. | +| `Succeed` / `Fail` | Terminate the run. | + +A run walks from `startAt` along each state's `next` until a state with `end: true` or a `Succeed`/`Fail` state. +The order-pipeline example below has this shape: + +```mermaid +stateDiagram-v2 + [*] --> validate + validate --> screening + validate --> reject: InvalidOrder + screening --> decision + decision --> reject: high risk / out of stock + decision --> charge + charge --> fulfil + charge --> reject: PaymentDeclined + fulfil --> [*] + reject --> [*] +``` + +`fission workflow graph --name ` renders exactly this diagram from a workflow's definition, and `--open` serves it in a local day/night viewer. + +## In this section + +- [Authoring workflows]({{% ref "authoring.md" %}}) — the full YAML reference for every state type, path shaping, retries, and the error model. +- [Run and inspect]({{% ref "run-and-inspect.md" %}}) — create, run, and manage workflows, and see where a run stopped with the `runs` commands and the graph viewer. +- [Examples]({{% ref "examples.md" %}}) — three worked workflows covering the full palette. + +## Related + +- [Workflows concept]({{% ref "/docs/concepts/workflows.md" %}}) — Workflow vs WorkflowRun and the durability model. +- [Statestore]({{% ref "/docs/architecture/statestore.md" %}}) — the durable event log workflows are recorded in. +- [Asynchronous invocation]({{% ref "/docs/usage/function/async-invocation.md" %}}) — the simpler durable primitive for single-function work. diff --git a/content/en/docs/usage/workflows/authoring.md b/content/en/docs/usage/workflows/authoring.md new file mode 100644 index 00000000..c2f21593 --- /dev/null +++ b/content/en/docs/usage/workflows/authoring.md @@ -0,0 +1,211 @@ +--- +title: "Authoring Workflows" +weight: 10 +description: > + The full YAML reference for a Workflow — every state type, JSONPath I/O shaping, retries and backoff, and the built-in error model. +--- + +**A `Workflow` is a YAML state machine: a `startAt` state and a map of named states, each of which invokes a function, branches on data, waits, or terminates.** + +This page is the field reference. +For the concepts, see [Workflows]({{% ref "/docs/concepts/workflows.md" %}}); to run and inspect what you author, see [Run and inspect]({{% ref "run-and-inspect.md" %}}). + +## Manifest skeleton + +```yaml +apiVersion: fission.io/v1 +kind: Workflow +metadata: + name: order-pipeline +spec: + startAt: validate # the first state + timeout: 1h # hard ceiling on total run time (default 24h) + defaultRetry: # optional; applied to Task states with no retry of their own + maxAttempts: 3 + backoffBase: 1s + backoffCap: 10s + historyRetention: # bound how many finished runs are kept + maxCount: 20 + maxAge: 24h + states: + validate: + type: Task + function: { name: wf-validate-order } + next: screening + # ... more states ... +``` + +Every state has a `type` and, unless it is terminal, either `next: ` or `end: true`. +The functions a workflow references are ordinary Fission functions in the same namespace. + +## Task + +Invoke a function. +This is the only state that runs your code. + +```yaml +charge: + type: Task + function: { name: wf-charge-card } + timeout: 30s # per-step timeout + retry: { maxAttempts: 3, backoffBase: 1s, backoffCap: 10s } + catch: + - errorType: PaymentDeclined # a typed business error + next: reject + resultPath: $.error + resultPath: $.charge # where the function result lands in the document + next: fulfil +``` + +| Field | Meaning | +| --- | --- | +| `function.name` | The function to invoke. | +| `timeout` | Per-step timeout (e.g. `30s`). | +| `retry` | Retry policy for this Task (overrides `spec.defaultRetry`). | +| `catch` | Ordered error routes (see [Error model](#error-model)). | +| `inputPath` / `resultPath` / `outputPath` | JSONPath I/O shaping (see [Shaping step I/O](#shaping-step-io)). | +| `next` / `end` | The next state, or terminate the run. | + +### Retry policy + +`retry` (and `spec.defaultRetry`) is a bounded exponential backoff: + +| Field | Meaning | +| --- | --- | +| `maxAttempts` | Total attempts before the failure is final. | +| `backoffBase` | Delay before the first retry; doubles each attempt. | +| `backoffCap` | Upper bound on the per-attempt delay. | + +Retries apply to **retryable** (transient, 5xx) failures. +A permanent (4xx typed) error is not retried — route it with `catch` instead. + +## Shaping step I/O + +A run carries a single JSON document. +Three optional JSONPath fields shape how a state reads from and writes to it: + +- **`inputPath`** selects the sub-document the state receives (default: the whole document). +- **`resultPath`** selects where the state's output is merged back (default: replace the document). +- **`outputPath`** selects what is passed on to the next state. + +`resultPath` is the one to be deliberate about. +Setting `resultPath: $.charge` merges the function's result under `$.charge`, **keeping** the rest of the document; omitting it **replaces** the whole document with the result. +The same applies to a caught error — merge it so the recovery step still sees the original input: + +```yaml +catch: + - errorType: InvalidOrder + next: reject + resultPath: $.error # merge the error at $.error, keep the order document +``` + +## Choice + +Route to the next state based on the document, with no function call. +Rules are evaluated in order; the first match wins, and `default` is taken if none match. + +```yaml +decision: + type: Choice + choices: + - variable: $.screening[0].riskScore + numericGreaterThan: 70 + next: reject + - variable: $.screening[1].status + stringEquals: OUT_OF_STOCK + next: reject + default: charge +``` + +Each rule names a `variable` (a JSONPath into the document), a comparator (for example `numericGreaterThan`, `stringEquals`), and the `next` state. + +## Parallel + +Run several branches concurrently and join their results into an **ordered array** — element *i* of the join is branch *i*'s result. + +```yaml +screening: + type: Parallel + branches: + - startAt: fraud + states: + fraud: { type: Task, function: { name: wf-fraud-score }, end: true } + - startAt: stock + states: + stock: { type: Task, function: { name: wf-inventory-check }, end: true } + resultPath: $.screening # the ordered [fraud, stock] array merges here + next: decision +``` + +Each branch is its own small state machine with a `startAt` and `states`. +If a branch fails terminally the Parallel state fails fast with `Fission.BranchFailed`, which a `catch` on the state can route. + +## Map + +Run one branch per element of an array, bounded by `maxConcurrency`. +The join is again an ordered array aligned with the input. + +```yaml +enrich: + type: Map + itemsPath: $.leads # the array to iterate + maxConcurrency: 3 # at most 3 branch executions in flight + branches: + - startAt: score + states: + score: { type: Task, function: { name: wf-enrich-lead }, end: true } + next: summarize +``` + +A Map has exactly one branch — the template applied to every item. + +## Wait + +Pause the run durably for a `duration`. +The run consumes no resources while waiting, survives controller restarts, and fires exactly once. + +```yaml +grace-period: + type: Wait + duration: 72h # days are fine — it is a durable timer, not a sleep + next: second-attempt +``` + +## Succeed and Fail + +Terminal states. +`Succeed` ends the run successfully; `Fail` ends it as failed. +A Task with `end: true` also terminates the run. + +```yaml +done: + type: Succeed +``` + +## Error model + +Fission classifies every step failure into a built-in error class that `catch.errorType` (and retries) key off: + +| Error class | Meaning | Retried? | +| --- | --- | --- | +| `Fission.FunctionError` | The function returned a 5xx — a transient/infrastructure failure. | Yes (per the retry policy). | +| `Fission.PermanentError` | The function returned a 4xx — a permanent failure retrying cannot fix. | No. | +| `Fission.Timeout` | The step exceeded its `timeout`. | Per policy. | +| `Fission.BranchFailed` | A `Parallel`/`Map` branch failed terminally. | — (route with `catch`). | +| `Fission.All` | Matches any error class in a `catch` route. | — | + +A function can also return its own **typed** business error by responding with a `{"errorType": "PaymentDeclined", ...}` body; `catch` routes on that name directly, so business recovery is separate from infrastructure retries. + +## Validate before applying + +`fission workflow validate` checks a manifest — unreachable states, dangling `next` targets, a missing `startAt` — without creating anything: + +```bash +fission workflow validate -f workflow.yaml +``` + +## Related + +- [Run and inspect]({{% ref "run-and-inspect.md" %}}) — create, run, and trace what you author here. +- [Examples]({{% ref "examples.md" %}}) — these fields assembled into three complete workflows. +- [Workflow CLI reference]({{% ref "/docs/reference/fission-cli/fission_workflow.md" %}}) — every command and flag. diff --git a/content/en/docs/usage/workflows/examples.md b/content/en/docs/usage/workflows/examples.md new file mode 100644 index 00000000..c12e28c8 --- /dev/null +++ b/content/en/docs/usage/workflows/examples.md @@ -0,0 +1,43 @@ +--- +title: "Workflow Examples" +weight: 30 +description: > + Three worked workflows — an order pipeline, a Map fan-out, and a durable Wait timer — that together exercise every state type. +--- + +**Three runnable workflows in the [examples repository](https://github.com/fission/examples/tree/main/miscellaneous/workflows) cover the full state-type palette.** + +Each directory has the `workflow.yaml`, the functions it calls, and sample inputs, plus a README with the deploy steps. +Read them alongside the [authoring reference]({{% ref "authoring.md" %}}). + +## Order pipeline — Parallel, Choice, retry, catch + +An e-commerce checkout: validate an order, screen it for fraud and stock **in parallel**, route on the results with a `Choice`, charge the card with **retry and a catch for declines**, then converge every failure onto one rejection path. +It is the flagship example — the one the [`stateDiagram`]({{% ref "_index.md" %}}#state-types) on the overview page is drawn from. + +- **Shows:** `Parallel` with an ordered join, data-driven `Choice`, `Task` `retry` for transient gateway errors, and `catch` on a typed `PaymentDeclined` error. +- **Inputs:** `happy`, `invalid`, `high-fraud`, `out-of-stock`, `declined-card`, `flaky-gateway` — one per route through the machine. +- [order-pipeline →](https://github.com/fission/examples/tree/main/miscellaneous/workflows/order-pipeline) + +## Batch enrichment — Map fan-out + +Enrich a batch of CRM leads: a `Map` state invokes a single-record scoring function once per element of `$.leads`, at most three concurrently, and the ordered join array feeds a summary step. +The function stays simple; the workflow owns the fan-out, throttling, retries, and ordering. + +- **Shows:** `Map` with `itemsPath` and `maxConcurrency`, and an ordered join feeding the next `Task`. +- **Inputs:** `leads` — the array the Map iterates. +- [batch-enrichment →](https://github.com/fission/examples/tree/main/miscellaneous/workflows/batch-enrichment) + +## Payment dunning — durable Wait timers + +Subscription renewal with a grace period: if a charge is declined, the run **waits out a grace period on a durable timer** and tries once more before cancelling. +The run consumes no pod, memory, or connection while waiting — the timer lives in the statestore and survives controller restarts. + +- **Shows:** `Wait` as a durable delay, and a `catch` route that changes behavior on the second attempt. +- **Inputs:** `valid`, `past-due` — one that charges cleanly, one that exercises the grace-period retry. +- [payment-dunning →](https://github.com/fission/examples/tree/main/miscellaneous/workflows/payment-dunning) + +## Related + +- [Authoring workflows]({{% ref "authoring.md" %}}) — the fields these examples use. +- [Run and inspect]({{% ref "run-and-inspect.md" %}}) — run them and trace where each input lands. diff --git a/content/en/docs/usage/workflows/run-and-inspect.md b/content/en/docs/usage/workflows/run-and-inspect.md new file mode 100644 index 00000000..7eee0845 --- /dev/null +++ b/content/en/docs/usage/workflows/run-and-inspect.md @@ -0,0 +1,88 @@ +--- +title: "Run and Inspect" +weight: 20 +description: > + Create, run, and manage workflows from the CLI — start runs, see where a run stopped with the runs commands, and visualize the state machine in a local viewer. +--- + +**Manage a workflow definition with `fission workflow`, start executions with `workflow run`, and trace each execution with the `workflow runs` subgroup.** + +This page assumes you have a manifest — see [Authoring workflows]({{% ref "authoring.md" %}}) — and that workflows are [enabled]({{% ref "_index.md" %}}#prerequisites). + +## Manage the definition + +`fission workflow` is the definition lifecycle; it mirrors the other Fission resources: + +```bash +fission workflow create -f workflow.yaml +fission workflow update -f workflow.yaml +fission workflow list +fission workflow delete --name order-pipeline +``` + +## Start a run + +`workflow run` creates a `WorkflowRun` and prints its name. +Pass input as inline JSON or `@path/to/file.json`: + +```bash +$ fission workflow run --name order-pipeline --input @inputs/happy.json +Run started: order-pipeline-7k2p9 +``` + +Each `run` is an independent execution with its own state and history; the definition is unchanged. + +## Inspect runs + +The `runs` subgroup operates on executions. +Every command takes `--name ` (the run name printed by `workflow run`), except `runs list`: + +```bash +# All runs, or just this workflow's +fission workflow runs list +fission workflow runs list --workflow order-pipeline + +# Where did this run stop, and why? +fission workflow runs describe --name order-pipeline-7k2p9 + +# The full event log; --io also shows step input/output payloads +fission workflow runs history --name order-pipeline-7k2p9 +fission workflow runs history --name order-pipeline-7k2p9 --io + +# Stop a running execution +fission workflow runs cancel --name order-pipeline-7k2p9 +``` + +`runs describe` is the "where is it / where did it stop" view: the phase, the active or final state, and the failure reason if it failed. +`runs history` is the underlying event log — the durable record the engine resumes from. + +## Visualize + +`workflow graph` renders a workflow's state machine as a diagram. +`--name` reads a stored workflow; `-f` reads a manifest that has not been applied yet: + +```bash +# Print a mermaid state diagram +fission workflow graph --name order-pipeline +fission workflow graph -f workflow.yaml + +# Open it in a local day/night viewer +fission workflow graph --name order-pipeline --open +``` + +`workflow runs graph --name ` draws the same diagram but overlays a specific run's status — each state colored by what that run actually did, so the picture *is* the answer to "where did this run stop": + +```bash +fission workflow runs graph --name order-pipeline-7k2p9 --open +``` + +{{% notice info %}} +`--open` serves the diagram from an ephemeral local web server and renders it in your own browser — the workflow never leaves your machine. +In a run overlay, states that only route (a `Choice`) emit no step events and are labelled "not tracked" rather than colored as a status. +{{% /notice %}} + +## Related + +- [Authoring workflows]({{% ref "authoring.md" %}}) — the manifest these commands operate on. +- [Examples]({{% ref "examples.md" %}}) — runnable workflows with sample inputs. +- [Workflow CLI reference]({{% ref "/docs/reference/fission-cli/fission_workflow.md" %}}) — every command and flag. diff --git a/static/data/examples.json b/static/data/examples.json index 73923b7b..3c48328a 100644 --- a/static/data/examples.json +++ b/static/data/examples.json @@ -913,6 +913,34 @@ "tags": [ "spec" ] + }, + { + "name": "Workflow: Order Pipeline", + "description": "Durable checkout workflow: parallel fraud/stock screening, data-driven routing, and payment charge with retry and typed-error catch.", + "link": "https://github.com/fission/examples/tree/main/miscellaneous/workflows/order-pipeline", + "tags": [ + "workflow", + "parallel", + "choice" + ] + }, + { + "name": "Workflow: Batch Lead Enrichment", + "description": "Map fan-out workflow: enrich a batch of leads one record per array element, bounded concurrency, ordered join into a summary step.", + "link": "https://github.com/fission/examples/tree/main/miscellaneous/workflows/batch-enrichment", + "tags": [ + "workflow", + "map" + ] + }, + { + "name": "Workflow: Payment Dunning", + "description": "Durable Wait-timer workflow: retry a declined subscription charge after a grace period, then cancel — the timer survives controller restarts.", + "link": "https://github.com/fission/examples/tree/main/miscellaneous/workflows/payment-dunning", + "tags": [ + "workflow", + "wait" + ] } ] } From ad1c4d82dc7cc0a400041a60a65d4014942df403 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sun, 19 Jul 2026 20:03:43 +0530 Subject: [PATCH 02/26] docs: use US spelling to satisfy the misspell CI gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fulfil→fulfill, cancelling→canceling, labelled→labeled; soften the graph-render claim now that the diagram uses the US spelling. Co-Authored-By: Claude Opus 4.8 --- content/en/docs/concepts/workflows.md | 2 +- content/en/docs/usage/workflows/_index.md | 6 +++--- content/en/docs/usage/workflows/authoring.md | 2 +- content/en/docs/usage/workflows/examples.md | 2 +- content/en/docs/usage/workflows/run-and-inspect.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/content/en/docs/concepts/workflows.md b/content/en/docs/concepts/workflows.md index 15314d65..35d355fd 100644 --- a/content/en/docs/concepts/workflows.md +++ b/content/en/docs/concepts/workflows.md @@ -8,7 +8,7 @@ description: > **A workflow is a durable state machine that orchestrates several functions as one reliable unit of work.** A single function is the right tool for one step. -Real processes are usually several steps with logic between them — validate an order, screen it for fraud, charge the card, fulfil or reject — where some steps run in parallel, some are conditional, and some can fail transiently and must be retried. +Real processes are usually several steps with logic between them — validate an order, screen it for fraud, charge the card, fulfill or reject — where some steps run in parallel, some are conditional, and some can fail transiently and must be retried. You *can* wire that together by having functions call each other, but then the orchestration lives in your code, nothing records how far a given execution got, and a crash midway leaves you guessing. A workflow makes the orchestration a first-class, durable object instead. diff --git a/content/en/docs/usage/workflows/_index.md b/content/en/docs/usage/workflows/_index.md index cbe70a40..99af26d6 100644 --- a/content/en/docs/usage/workflows/_index.md +++ b/content/en/docs/usage/workflows/_index.md @@ -47,13 +47,13 @@ stateDiagram-v2 screening --> decision decision --> reject: high risk / out of stock decision --> charge - charge --> fulfil + charge --> fulfill charge --> reject: PaymentDeclined - fulfil --> [*] + fulfill --> [*] reject --> [*] ``` -`fission workflow graph --name ` renders exactly this diagram from a workflow's definition, and `--open` serves it in a local day/night viewer. +`fission workflow graph --name ` renders this diagram from a workflow's definition, and `--open` serves it in a local day/night viewer. ## In this section diff --git a/content/en/docs/usage/workflows/authoring.md b/content/en/docs/usage/workflows/authoring.md index c2f21593..1cc13bf0 100644 --- a/content/en/docs/usage/workflows/authoring.md +++ b/content/en/docs/usage/workflows/authoring.md @@ -54,7 +54,7 @@ charge: next: reject resultPath: $.error resultPath: $.charge # where the function result lands in the document - next: fulfil + next: fulfill ``` | Field | Meaning | diff --git a/content/en/docs/usage/workflows/examples.md b/content/en/docs/usage/workflows/examples.md index c12e28c8..3afec805 100644 --- a/content/en/docs/usage/workflows/examples.md +++ b/content/en/docs/usage/workflows/examples.md @@ -30,7 +30,7 @@ The function stays simple; the workflow owns the fan-out, throttling, retries, a ## Payment dunning — durable Wait timers -Subscription renewal with a grace period: if a charge is declined, the run **waits out a grace period on a durable timer** and tries once more before cancelling. +Subscription renewal with a grace period: if a charge is declined, the run **waits out a grace period on a durable timer** and tries once more before canceling. The run consumes no pod, memory, or connection while waiting — the timer lives in the statestore and survives controller restarts. - **Shows:** `Wait` as a durable delay, and a `catch` route that changes behavior on the second attempt. diff --git a/content/en/docs/usage/workflows/run-and-inspect.md b/content/en/docs/usage/workflows/run-and-inspect.md index 7eee0845..1ea1fbb9 100644 --- a/content/en/docs/usage/workflows/run-and-inspect.md +++ b/content/en/docs/usage/workflows/run-and-inspect.md @@ -78,7 +78,7 @@ fission workflow runs graph --name order-pipeline-7k2p9 --open {{% notice info %}} `--open` serves the diagram from an ephemeral local web server and renders it in your own browser — the workflow never leaves your machine. -In a run overlay, states that only route (a `Choice`) emit no step events and are labelled "not tracked" rather than colored as a status. +In a run overlay, states that only route (a `Choice`) emit no step events and are labeled "not tracked" rather than colored as a status. {{% /notice %}} ## Related From b36eb0cd13579f6c07affb725eda239239c547f3 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Wed, 22 Jul 2026 15:30:08 +0530 Subject: [PATCH 03/26] docs: add Function State usage guide (practical keyed state patterns) A practical how-to for giving a function durable per-key state without an external Redis/database: opt-in, the injected state URL + scoped token, and worked patterns (per-user counter with compare-and-swap, session store with TTL, shopping cart, rate limiter, AI agent conversation memory), plus sticky routing for coherent in-memory caches, quotas/lifecycle, and the fission fn state CLI. Cross-linked from the statestore architecture page. Co-Authored-By: Claude Fable 5 --- content/en/docs/architecture/statestore.md | 3 +- content/en/docs/usage/function/keyed-state.md | 249 ++++++++++++++++++ 2 files changed, 251 insertions(+), 1 deletion(-) create mode 100644 content/en/docs/usage/function/keyed-state.md diff --git a/content/en/docs/architecture/statestore.md b/content/en/docs/architecture/statestore.md index 115cdaa0..0244859f 100644 --- a/content/en/docs/architecture/statestore.md +++ b/content/en/docs/architecture/statestore.md @@ -11,10 +11,11 @@ It exposes three capabilities behind one interface — a **key/value** store, an Fission itself never deploys a database product: you either use the bundled embedded driver for development, or point the external driver at a database you already run. The statestore is what makes Fission's newer durable features possible. -Starting with Fission {{< release-version >}}, three subsystems build on it: +Starting with Fission {{< release-version >}}, several subsystems build on it: - **[Durable Workflows]({{% ref "/docs/usage/workflows/_index.md" %}})** record every step of a run in the event log, so a run survives a controller restart and resumes exactly where it stopped. - **[Asynchronous invocation]({{% ref "/docs/usage/function/async-invocation.md" %}})** enqueues each fire-and-forget call on the queue and delivers it in the background with retries and a dead-letter queue. +- **[Function state]({{% ref "/docs/usage/function/keyed-state.md" %}})** gives a function a private keyspace of durable key/value entries — counters, sessions, carts, agent memory — with no external Redis or database. - **Eventing** uses the event log and queue as its zero-broker transport. The statestore is off by default; a feature that needs it will tell you to enable it. diff --git a/content/en/docs/usage/function/keyed-state.md b/content/en/docs/usage/function/keyed-state.md new file mode 100644 index 00000000..76bae390 --- /dev/null +++ b/content/en/docs/usage/function/keyed-state.md @@ -0,0 +1,249 @@ +--- +title: "Function State" +draft: false +weight: 47 +description: > + Give a function durable, per-key state — counters, sessions, carts, rate limits, agent memory — over a local HTTP API, with no external Redis or database and no credentials in your code. +--- + +**Give a function durable key/value state without bringing your own Redis or database.** +A Fission function is normally stateless: nothing it writes to memory survives the request, and two requests may land on two different pods. +Anything that needs to remember something between requests — a per-user counter, a shopping cart, a login session, a rate limit, an AI agent's conversation history — usually means standing up Redis or a database, wiring its connection string into every environment image, and re-implementing tenancy and quotas per team. + +Starting with Fission {{< release-version >}}, a function can opt into a **keyed state API** instead. +It gets a private keyspace of versioned key/value entries, reached over a local HTTP endpoint that Fission injects into the pod along with a scoped token. +Your code shrinks to `get` / `set` / `delete` / `list` against `localhost`-speed HTTP — portable across environments, with no client library and no secret to manage. + +State is **opt-in per function** and additive: functions that don't ask for it behave exactly as before. + +```mermaid +flowchart TB + req["Request"]:::user -->|"1. HTTP"| pod["Function Pod
(your code)"]:::pod + pod -->|"2. get / set / cas
Bearer token"| svc["State API"]:::fission + svc -->|"3. scoped to
this function's keyspace"| store["Statestore"]:::store + + classDef user fill:#ffffff,stroke:#94a3b8,color:#1f2a43 + classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43 + classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3 + classDef store fill:#fff7e0,stroke:#dba514,color:#1f2a43,stroke-dasharray:5 3 +``` + +## Prerequisites + +Function state is **off by default** and stores its data on the [statestore]({{% ref "/docs/architecture/statestore.md" %}}): + +```bash +helm upgrade --install fission fission-charts/fission-all \ + --namespace fission \ + --set statestore.enabled=true \ + --set functionState.enabled=true +``` + +Embedded statestore mode is enough to try it; point `statestore.mode=external` at Postgres when you want the data on managed storage. + +## Opt a function in + +Add `--state` at create (or update) time: + +```bash +fission function create --name cart --env nodejs --code cart.js --state +``` + +That is all a function needs. By default its keyspace is named after the function, values are capped at 256 KiB, and it may hold up to 10,000 live keys. You can tune those: + +```bash +fission function create --name sessions --env nodejs --code sessions.js \ + --state \ + --state-keyspace user-sessions \ # explicit name, so renaming the function keeps the data + --state-max-keys 100000 \ + --state-max-value-bytes 8192 \ + --state-ttl 30m # writes without their own TTL expire after 30 minutes +``` + +Give the keyspace an explicit `--state-keyspace` if you might rename the function later — the keyspace, not the function name, is what owns the data. + +## Read and write state from your code + +Fission injects two things into the function pod: + +- `FISSION_STATE_URL` — the base URL of the state API (an environment variable). +- `FISSION_STATE_TOKEN_PATH` — the path to a small JSON file holding this function's scoped credentials: `{ "namespace": "...", "keyspace": "...", "token": "..." }`. + +You present the token as a bearer header along with the namespace and keyspace it was minted for. There is no client library to install — it is plain HTTP. A ~20-line helper is all any language needs. + +{{< tabs >}} +{{< tab "Node.js" >}} +```javascript +const fs = require('fs'); + +function stateClient() { + const c = JSON.parse(fs.readFileSync(process.env.FISSION_STATE_TOKEN_PATH, 'utf8')); + const base = process.env.FISSION_STATE_URL; + const headers = { + 'Authorization': 'Bearer ' + c.token, + 'X-Fission-State-Namespace': c.namespace, + 'X-Fission-State-Keyspace': c.keyspace, + }; + return { + async get(key) { + const r = await fetch(`${base}/v1/state/${key}`, { headers }); + if (r.status === 404) return null; + return { value: await r.text(), version: Number(r.headers.get('x-fission-state-version')) }; + }, + async set(key, value, { ifVersion } = {}) { + const h = { ...headers }; + if (ifVersion !== undefined) h['If-Match'] = String(ifVersion); // compare-and-swap + const r = await fetch(`${base}/v1/state/${key}`, { method: 'PUT', headers: h, body: value }); + return r.status; // 204 ok, 412 version conflict + }, + del: (key) => fetch(`${base}/v1/state/${key}`, { method: 'DELETE', headers }), + async list(prefix = '') { + const r = await fetch(`${base}/v1/state?prefix=${prefix}`, { headers }); + return (await r.json()).keys; + }, + }; +} +``` +{{< /tab >}} +{{< tab "Python" >}} +```python +import json, os, urllib.request + +def state_client(): + with open(os.environ["FISSION_STATE_TOKEN_PATH"]) as f: + c = json.load(f) + base = os.environ["FISSION_STATE_URL"] + headers = { + "Authorization": "Bearer " + c["token"], + "X-Fission-State-Namespace": c["namespace"], + "X-Fission-State-Keyspace": c["keyspace"], + } + + def req(method, path, body=None, extra=None): + h = dict(headers, **(extra or {})) + r = urllib.request.Request(base + path, data=body, method=method, headers=h) + try: + resp = urllib.request.urlopen(r) + return resp.status, resp.read(), resp.headers + except urllib.error.HTTPError as e: + return e.code, e.read(), e.headers + + class Client: + def get(self, key): + s, b, hdr = req("GET", f"/v1/state/{key}") + if s == 404: + return None + return b.decode(), int(hdr.get("X-Fission-State-Version", 0)) + + def set(self, key, value, if_version=None): + extra = {"If-Match": str(if_version)} if if_version is not None else None + s, _, _ = req("PUT", f"/v1/state/{key}", value.encode(), extra) + return s # 204 ok, 412 version conflict + + def delete(self, key): + req("DELETE", f"/v1/state/{key}") + + return Client() +``` +{{< /tab >}} +{{< /tabs >}} + +## Practical patterns + +### A per-user counter + +The simplest useful pattern: increment a value keyed by user id. Because two requests for the same user can race, use the version returned by `get` as a **compare-and-swap** token on the `set` — the write only lands if nobody changed the value in between, and you retry on a conflict. No lost increments, no locks. + +```javascript +module.exports = async function (context) { + const state = stateClient(); + const user = context.request.query.user || 'anon'; + for (let attempt = 0; attempt < 10; attempt++) { + const cur = await state.get(user); + const next = (cur ? Number(cur.value) : 0) + 1; + const code = await state.set(user, String(next), { ifVersion: cur ? cur.version : 0 }); + if (code === 204) return { status: 200, body: String(next) }; + // 412: someone else incremented first — read again and retry + } + return { status: 500, body: 'too much contention' }; +}; +``` + +The same shape covers **rate limiting** (increment a counter keyed by `client-ip`, reject past a threshold, let it expire with a TTL) and any other read-modify-write on a single key. + +### A login session + +Store a session document keyed by session id, with a TTL so it expires on its own: + +```javascript +// on login +await state.set(sessionId, JSON.stringify({ user, roles }), { }); // ttl comes from --state-ttl +// on each request +const s = await state.get(sessionId); +if (!s) return { status: 401, body: 'session expired' }; +``` + +Set `--state-ttl 30m` on the function and stale sessions clean themselves up — you never write a reaper. + +### A shopping cart + +A cart is a value keyed by cart id; add-item is a read-modify-write with the same compare-and-swap retry as the counter, so two tabs adding items at once never clobber each other: + +```javascript +const cur = await state.get(cartId); +const cart = cur ? JSON.parse(cur.value) : { items: [] }; +cart.items.push(item); +const code = await state.set(cartId, JSON.stringify(cart), { ifVersion: cur ? cur.version : 0 }); +// retry on 412 +``` + +### AI agent conversation memory + +Give an agent function a durable memory keyed by conversation id — append each turn and read the history back on the next call, so the agent remembers across requests without a vector store or database for the transcript itself. + +```javascript +const key = `conv:${conversationId}`; +const cur = await state.get(key); +const history = cur ? JSON.parse(cur.value) : []; +history.push({ role: 'user', content: userMessage }); +// ... call the model with `history`, append the reply ... +await state.set(key, JSON.stringify(history), { ifVersion: cur ? cur.version : 0 }); +``` + +## Keep an in-memory cache coherent with sticky routing + +Everything above is durable and correct no matter which pod serves a request. +If your function also keeps an **in-memory cache** on top of that durable state — to avoid a round trip on hot keys — you want all requests for one key to keep landing on the same pod so that cache stays warm and coherent. Turn on **sticky routing** by telling Fission where the key lives in the request: + +```bash +fission function create --name game-room --env nodejs --code room.js --state \ + --state-sticky-source header \ + --state-sticky-name X-Room-Id +``` + +Now requests carrying the same `X-Room-Id` are consistent-hashed onto the same ready pod while the pod set is stable. Sources can be a `header` or a `queryparam`. + +Sticky routing is a **performance optimization, not a correctness guarantee**: on a scale event or pod replacement a key may move to another pod, and its in-memory cache warms up again from the state API. The durable truth always lives in the state API, so a request that lands on a different pod is never wrong — only, briefly, colder. Requests that don't carry the key fall back to normal routing. + +## Inspect and manage state from the CLI + +`fission function state` reaches the same keyspace as an operator, useful for debugging and cleanup (it needs the cluster's internal auth secret, so it fails closed if that is not configured): + +```bash +fission function state set --name cart --key demo-cart --value '{"items":[]}' +fission function state get --name cart --key demo-cart +fission function state list --name cart --prefix demo +fission function state delete --name cart --key demo-cart +``` + +## Lifecycle, limits, and cleanup + +- **Deleting a function purges its keyspace** by default, so state doesn't leak after the function is gone. Annotate the function with `fission.io/state-retain: "true"` to keep the data (for example to re-attach a replacement function to the same keyspace). +- **Quotas are enforced for you.** A value larger than `--state-max-value-bytes` is rejected; creating a key past `--state-max-keys` is rejected — atomically, so concurrent writers can't overshoot the budget. +- **This is key/value, not a database.** There are no cross-key transactions, no secondary indexes, and values are capped (256 KiB by default) — large blobs belong in object storage, relational data in a real database. It is exactly the right tool for the "remember a small thing per key" workloads above. +- **Executor type.** State works with the `poolmgr` (default) and `newdeploy` executors. The container executor and the `infinite` functions-per-container environment mode aren't supported, because a scoped per-function token can't be delivered to them. + +## Multi-namespace tenancy + +Function state is supported under the default single-namespace / static tenancy model. +The dynamic and cluster multi-namespace tenancy modes are not yet supported for function state — enable it on a statically-scoped install for now. From b37130205d7d786c910c01970ca944ab7559d3e6 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Fri, 24 Jul 2026 19:51:53 +0530 Subject: [PATCH 04/26] docs: function versions & aliases user guide Add two usage pages for the new function versioning feature: - versions-aliases.md: concepts (immutable versions, movable aliases), publishing, listing, alias-routed triggers (CLI and spec YAML), weighted splits, instant rollback (incl. the GitOps guard and --detach), and declarative/digest-pinned aliases. - versions-lifecycle.md: automatic publishing (versioning.mode), retention GC, environment drift (EnvDrift, env impact), behavior of MQ/timer/watch/MCP/async/state/sticky paths through an alias, and canary rollouts over an alias. Cross-link from the async (enqueue-time version pinning), canary (alias mode recommended), and keyed-state (state shared across versions) pages; add both pages to the usage guide map and the v1.28.0 draft release notes. Co-Authored-By: Claude Fable 5 --- content/en/docs/releases/v1.28.0.md | 10 +- content/en/docs/usage/_index.en.md | 2 + .../docs/usage/function/async-invocation.md | 5 + .../docs/usage/function/canary-deployments.md | 6 + content/en/docs/usage/function/keyed-state.md | 38 ++- .../docs/usage/function/versions-aliases.md | 255 ++++++++++++++++++ .../docs/usage/function/versions-lifecycle.md | 134 +++++++++ 7 files changed, 438 insertions(+), 12 deletions(-) create mode 100644 content/en/docs/usage/function/versions-aliases.md create mode 100644 content/en/docs/usage/function/versions-lifecycle.md diff --git a/content/en/docs/releases/v1.28.0.md b/content/en/docs/releases/v1.28.0.md index 3dc90989..67d03229 100644 --- a/content/en/docs/releases/v1.28.0.md +++ b/content/en/docs/releases/v1.28.0.md @@ -16,12 +16,12 @@ Version numbers, upgrade notes, and the changelog are finalized when v1.28.0 shi -All three headline features are **opt-in** and off by default, so a routine upgrade changes nothing for an existing install until you enable them. +All headline features are **opt-in** and off by default, so a routine upgrade changes nothing for an existing install until you enable them. For the general upgrade steps (CRDs, CLI, Helm chart), see the [Upgrade Guide](/docs/installation/upgrade/). ## Highlights -Fission v1.28.0 is themed around **durable and asynchronous execution**: a shared durable substrate, and two ways to build on it. +Fission v1.28.0 is themed around **durable and asynchronous execution** — a shared durable substrate and two ways to build on it — plus first-class **function versioning** for safe rollouts and instant rollbacks. - **Statestore — a durable state substrate.** A single interface exposing key/value, an append-only event log, and a visibility-timeout queue, served by a pluggable driver: **embedded** SQLite on a PVC for development, or an **external** Postgres DSN for production and HA. @@ -32,6 +32,11 @@ Fission v1.28.0 is themed around **durable and asynchronous execution**: a share Send `X-Fission-Invoke-Mode: async` (or `fission fn test --async`) and the router enqueues the call, returns a durable invocation id with `202 Accepted`, and delivers it in the background with retries. Per-function delivery config sets the attempt budget and max age; a **dead-letter queue** (`fission function dlq`) captures what cannot be delivered; result **destinations** route the outcome to another function; and an opt-in KEDA `ScaledObject` autoscales the workers on the backlog. See [Asynchronous invocation](/docs/usage/function/async-invocation/). +- **Function versions and aliases — publish, promote, roll back.** + Every runtime-affecting update can be published as an immutable `FunctionVersion` snapshot (automatically with `spec.versioning.mode: auto`, or explicitly via `fission fn publish`); movable `FunctionAlias` pointers like `prod` and `staging` are what triggers reference; and `fission fn rollback` repoints an alias atomically with no pod churn and no cold start. + Weighted aliases split traffic between two versions, canary configs can drive the split automatically, and digest pinning makes aliases GitOps-friendly. + Bare function names keep meaning "the live function", so nothing changes until you opt in. + See [Function versions and aliases](/docs/usage/function/versions-aliases/). - **Durable Workflows — orchestrate functions as a resumable state machine.** A `Workflow` custom resource is a state machine over your functions; each execution is a `WorkflowRun` recorded step by step in the statestore event log, so a run survives controller restarts, resumes exactly where it stopped, retries transient failures with backoff, and routes typed business errors. States cover `Task`, `Choice`, `Parallel`, `Map`, `Wait`, and `Succeed`/`Fail`, with a `fission workflow` CLI that includes a local day/night graph viewer and a per-run status overlay. @@ -42,6 +47,7 @@ Fission v1.28.0 is themed around **durable and asynchronous execution**: a share - [Statestore](/docs/architecture/statestore/) - [Asynchronous invocation](/docs/usage/function/async-invocation/) - [Workflows](/docs/usage/workflows/) · [Concept](/docs/concepts/workflows/) · [Authoring](/docs/usage/workflows/authoring/) · [Examples](/docs/usage/workflows/examples/) +- [Function versions and aliases](/docs/usage/function/versions-aliases/) · [Lifecycle and interactions](/docs/usage/function/versions-lifecycle/) ## Changelog diff --git a/content/en/docs/usage/_index.en.md b/content/en/docs/usage/_index.en.md index 9c670f56..bae37a7c 100644 --- a/content/en/docs/usage/_index.en.md +++ b/content/en/docs/usage/_index.en.md @@ -23,6 +23,8 @@ Work through the function workflow in roughly this order: * [Run a container as a function]({{% ref "function/container-functions.md" %}}) — turn any existing container image into a Fission function. * [Access secrets and ConfigMaps]({{% ref "function/access-secret-cfgmap-in-function.en.md" %}}) — read Kubernetes Secrets and ConfigMaps from inside a function. * [Access URL parameters]({{% ref "function/accessing-url-params.md" %}}) — read path parameters from REST-style routes. +* [Function versions and aliases]({{% ref "function/versions-aliases.md" %}}) — publish immutable versions, route traffic through movable aliases like `prod` and `staging`, split traffic between two versions, and roll back instantly. +* [Version lifecycle and interactions]({{% ref "function/versions-lifecycle.md" %}}) — automatic publishing, retention, environment drift, and how versions interact with the rest of Fission. * [Canary deployments]({{% ref "function/canary-deployments.md" %}}) — roll out a new function version gradually and roll back automatically on failure. Durable and asynchronous execution: diff --git a/content/en/docs/usage/function/async-invocation.md b/content/en/docs/usage/function/async-invocation.md index 29abdd51..5919fc15 100644 --- a/content/en/docs/usage/function/async-invocation.md +++ b/content/en/docs/usage/function/async-invocation.md @@ -85,6 +85,10 @@ fission fn update --name resize-image \ | `--async-retry-max-attempts` | Maximum delivery attempts before dead-lettering. | | `--async-max-age` | Maximum age of an invocation before dead-lettering, regardless of attempts. | +{{% notice info %}} +When the function is invoked through a [function alias]({{% ref "versions-aliases.md" %}}), the invocation is pinned to the version resolved at enqueue time — retries re-run that same version even if the alias moves or is rolled back in between, so retries stay deterministic. +{{% /notice %}} + ## Result destinations An async invocation has no caller waiting for its result, so you can route the result to another function in the same namespace: @@ -141,6 +145,7 @@ See [Statestore]({{% ref "/docs/architecture/statestore.md" %}}). ## Related - [Statestore]({{% ref "/docs/architecture/statestore.md" %}}) — the durable queue behind async delivery. +- [Function versions and aliases]({{% ref "versions-aliases.md" %}}) — async retries pin the version resolved at enqueue time. - [Durable Workflows]({{% ref "/docs/usage/workflows/_index.md" %}}) — orchestrate multiple functions with the same durable substrate. - [Create and run functions]({{% ref "functions.en.md" %}}) — the everyday function workflow. - [Custom Resource Definition Specification]({{% ref "/docs/reference/crd-reference.md" %}}) — the async delivery fields on the `Function` resource. diff --git a/content/en/docs/usage/function/canary-deployments.md b/content/en/docs/usage/function/canary-deployments.md index 3068413d..3280215b 100644 --- a/content/en/docs/usage/function/canary-deployments.md +++ b/content/en/docs/usage/function/canary-deployments.md @@ -9,6 +9,12 @@ description: > **A CanaryConfig gradually shifts HTTP traffic to a new function version, using Prometheus health checks to roll back automatically if the new version becomes unhealthy.** Traffic starts at 0% and increases in steps up to 100%, unless the failure threshold is exceeded first. +{{% notice tip %}} +Starting with Fission {{< release-version >}}, the recommended way to canary is over [function versions and aliases]({{% ref "versions-aliases.md" %}}): point the trigger at an alias and name two published **versions** of the same function as `--newfn`/`--oldfn`, instead of deploying the new code as a second function. +See [canary rollouts over an alias]({{% ref "versions-lifecycle.md#canary-rollouts-over-an-alias" %}}). +The classic two-function pattern below keeps working unchanged. +{{% /notice %}} + ### Setup & pre-requisites Enable the canary feature by setting `canaryDeployment.enabled` to `true` in the Helm chart during Fission installation. diff --git a/content/en/docs/usage/function/keyed-state.md b/content/en/docs/usage/function/keyed-state.md index 76bae390..966f709b 100644 --- a/content/en/docs/usage/function/keyed-state.md +++ b/content/en/docs/usage/function/keyed-state.md @@ -49,7 +49,9 @@ Add `--state` at create (or update) time: fission function create --name cart --env nodejs --code cart.js --state ``` -That is all a function needs. By default its keyspace is named after the function, values are capped at 256 KiB, and it may hold up to 10,000 live keys. You can tune those: +That is all a function needs. +By default its keyspace is named after the function, values are capped at 256 KiB, and it may hold up to 10,000 live keys. +You can tune those: ```bash fission function create --name sessions --env nodejs --code sessions.js \ @@ -69,7 +71,9 @@ Fission injects two things into the function pod: - `FISSION_STATE_URL` — the base URL of the state API (an environment variable). - `FISSION_STATE_TOKEN_PATH` — the path to a small JSON file holding this function's scoped credentials: `{ "namespace": "...", "keyspace": "...", "token": "..." }`. -You present the token as a bearer header along with the namespace and keyspace it was minted for. There is no client library to install — it is plain HTTP. A ~20-line helper is all any language needs. +You present the token as a bearer header along with the namespace and keyspace it was minted for. +There is no client library to install — it is plain HTTP. +A ~20-line helper is all any language needs. {{< tabs >}} {{< tab "Node.js" >}} @@ -152,7 +156,9 @@ def state_client(): ### A per-user counter -The simplest useful pattern: increment a value keyed by user id. Because two requests for the same user can race, use the version returned by `get` as a **compare-and-swap** token on the `set` — the write only lands if nobody changed the value in between, and you retry on a conflict. No lost increments, no locks. +The simplest useful pattern: increment a value keyed by user id. +Because two requests for the same user can race, use the version returned by `get` as a **compare-and-swap** token on the `set` — the write only lands if nobody changed the value in between, and you retry on a conflict. +No lost increments, no locks. ```javascript module.exports = async function (context) { @@ -213,7 +219,8 @@ await state.set(key, JSON.stringify(history), { ifVersion: cur ? cur.version : 0 ## Keep an in-memory cache coherent with sticky routing Everything above is durable and correct no matter which pod serves a request. -If your function also keeps an **in-memory cache** on top of that durable state — to avoid a round trip on hot keys — you want all requests for one key to keep landing on the same pod so that cache stays warm and coherent. Turn on **sticky routing** by telling Fission where the key lives in the request: +If your function also keeps an **in-memory cache** on top of that durable state — to avoid a round trip on hot keys — you want all requests for one key to keep landing on the same pod so that cache stays warm and coherent. +Turn on **sticky routing** by telling Fission where the key lives in the request: ```bash fission function create --name game-room --env nodejs --code room.js --state \ @@ -221,9 +228,12 @@ fission function create --name game-room --env nodejs --code room.js --state \ --state-sticky-name X-Room-Id ``` -Now requests carrying the same `X-Room-Id` are consistent-hashed onto the same ready pod while the pod set is stable. Sources can be a `header` or a `queryparam`. +Now requests carrying the same `X-Room-Id` are consistent-hashed onto the same ready pod while the pod set is stable. +Sources can be a `header` or a `queryparam`. -Sticky routing is a **performance optimization, not a correctness guarantee**: on a scale event or pod replacement a key may move to another pod, and its in-memory cache warms up again from the state API. The durable truth always lives in the state API, so a request that lands on a different pod is never wrong — only, briefly, colder. Requests that don't carry the key fall back to normal routing. +Sticky routing is a **performance optimization, not a correctness guarantee**: on a scale event or pod replacement a key may move to another pod, and its in-memory cache warms up again from the state API. +The durable truth always lives in the state API, so a request that lands on a different pod is never wrong — only, briefly, colder. +Requests that don't carry the key fall back to normal routing. ## Inspect and manage state from the CLI @@ -238,10 +248,18 @@ fission function state delete --name cart --key demo-cart ## Lifecycle, limits, and cleanup -- **Deleting a function purges its keyspace** by default, so state doesn't leak after the function is gone. Annotate the function with `fission.io/state-retain: "true"` to keep the data (for example to re-attach a replacement function to the same keyspace). -- **Quotas are enforced for you.** A value larger than `--state-max-value-bytes` is rejected; creating a key past `--state-max-keys` is rejected — atomically, so concurrent writers can't overshoot the budget. -- **This is key/value, not a database.** There are no cross-key transactions, no secondary indexes, and values are capped (256 KiB by default) — large blobs belong in object storage, relational data in a real database. It is exactly the right tool for the "remember a small thing per key" workloads above. -- **Executor type.** State works with the `poolmgr` (default) and `newdeploy` executors. The container executor and the `infinite` functions-per-container environment mode aren't supported, because a scoped per-function token can't be delivered to them. +- **State is shared across [function versions]({{% ref "versions-aliases.md" %}}).** + The keyspace belongs to the function, not to any one published version, so repointing or rolling back an alias rolls back code — never data — and both sides of a weighted split read and write the same keyspace. +- **Deleting a function purges its keyspace** by default, so state doesn't leak after the function is gone. + Annotate the function with `fission.io/state-retain: "true"` to keep the data (for example to re-attach a replacement function to the same keyspace). +- **Quotas are enforced for you.** + A value larger than `--state-max-value-bytes` is rejected; creating a key past `--state-max-keys` is rejected — atomically, so concurrent writers can't overshoot the budget. +- **This is key/value, not a database.** + There are no cross-key transactions, no secondary indexes, and values are capped (256 KiB by default) — large blobs belong in object storage, relational data in a real database. + It is exactly the right tool for the "remember a small thing per key" workloads above. +- **Executor type.** + State works with the `poolmgr` (default) and `newdeploy` executors. + The container executor and the `infinite` functions-per-container environment mode aren't supported, because a scoped per-function token can't be delivered to them. ## Multi-namespace tenancy diff --git a/content/en/docs/usage/function/versions-aliases.md b/content/en/docs/usage/function/versions-aliases.md new file mode 100644 index 00000000..2c17789f --- /dev/null +++ b/content/en/docs/usage/function/versions-aliases.md @@ -0,0 +1,255 @@ +--- +title: "Function Versions and Aliases" +draft: false +weight: 49 +description: > + Publish immutable versions of a function, route traffic through movable aliases like prod and staging, split traffic between two versions, and roll back instantly — without touching triggers or paying a cold start. +--- + +**Publish a function as immutable versions, point named aliases like `prod` and `staging` at them, and roll back a bad deploy in seconds — without editing a single trigger and without a cold start.** + +A plain `fission fn update` changes the live function in place: every trigger that names the function immediately serves the new code, and the only way back is another update. +Starting with Fission {{< release-version >}}, a function can also have **versions** and **aliases**: + +- A **version** (`FunctionVersion`, `kubectl get fnver`) is an immutable snapshot of the function's spec and package content at publish time, named `-v` (for example `orders-v3`). + It is never mutated after creation, only garbage collected once nothing references it. +- An **alias** (`FunctionAlias`, `kubectl get fnalias`) is a movable, named pointer at one version — or at two versions during a weighted traffic split. + Triggers reference the alias; moving the alias is how a rollout or a rollback happens. + +```mermaid +flowchart LR + api["/api route"]:::user --> prod["alias: prod"]:::fission + beta["/beta route"]:::user --> staging["alias: staging"]:::fission + prod --> v3["orders-v3"]:::pod + staging --> v4["orders-v4"]:::pod + + classDef user fill:#ffffff,stroke:#94a3b8,color:#1f2a43 + classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43 + classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3 +``` + +This is fully backward compatible. +A trigger that references a bare function name keeps meaning "the live function", exactly as before — nothing changes until you publish a version and point something at it. + +## Publish a version + +`fission fn publish` snapshots the function's current spec and package content as the next version: + +```bash +$ fission fn update --name orders --code orders-v2.js +function 'orders' updated + +$ fission fn publish --name orders --description "checkout rounding fix" +created orders-v3 +``` + +Publishing is idempotent: if nothing runtime-affecting changed since the last publish, the existing newest version is returned instead of minting a duplicate: + +```bash +$ fission fn publish --name orders +unchanged orders-v3 +``` + +| Flag | Meaning | +| --- | --- | +| `--description` | Human-readable note recorded on the version. | +| `--wait` | Wait for the function's package build to finish before publishing (see `--timeout`); without it, publishing against a still-building package fails fast. | +| `-o name` | Print only the version name, for scripting. | +| `-o json` / `-o yaml` | Print the full version object. | + +Versions can also be minted automatically on every runtime-affecting update — see [automatic publishing]({{% ref "versions-lifecycle.md#automatic-publishing" %}}). + +## List versions + +```bash +$ fission fn versions --name orders +NAME SEQUENCE DIGEST PUBLISHED AGE +orders-v1 1 sha256:1f8ac10f23c5 2026-07-10T09:14:02Z 14d +orders-v2 2 sha256:60303ae22b99 2026-07-17T16:41:55Z 7d +orders-v3 3 sha256:fd61a03af4f7 2026-07-24T08:03:11Z 2m +``` + +The `DIGEST` column pins the exact package content of each version. +The table truncates it; `-o wide` prints full digests and adds an `ENVDRIFT` column showing whether the version was published under an older generation of its environment (see [environment updates and drift]({{% ref "versions-lifecycle.md#environment-updates-and-drift" %}})). +`-o json` / `-o yaml` print the full objects. + +## Point an alias at a version + +```bash +$ fission alias create --name prod --function orders --version orders-v3 +function alias 'prod' created + +$ fission alias list +NAME FUNCTION VERSION PACKAGE-DIGEST WEIGHT SECONDARY-VERSION RESOLVED-VERSION +prod orders orders-v3 orders-v3 +staging orders orders-v4 orders-v4 +``` + +`fission alias get --name prod` shows the same row plus the alias's status conditions, and `fission alias delete --name prod` removes it. +An alias lives in the same namespace as its function, and one function can have any number of aliases. + +## Route triggers through the alias + +A trigger targets an alias through the optional `alias` field on its function reference. +The router resolves the alias **at request time**, so repointing the alias redirects traffic without touching the trigger. + +The `fission` CLI has no dedicated flag for this yet, so set the field declaratively. +Either write the trigger with `--spec` and edit the generated file, or apply YAML directly: + +```yaml +apiVersion: fission.io/v1 +kind: HTTPTrigger +metadata: + name: orders-api + namespace: default +spec: + relativeurl: /api/orders + methods: + - POST + functionref: + type: name + name: orders + alias: prod +``` + +Different routes can target different aliases of the **same** function: + +```yaml +# /api/orders -> alias prod (stable), /beta/orders -> alias staging (next) +functionref: + type: name + name: orders + alias: prod +--- +functionref: + type: name + name: orders + alias: staging +``` + +To pin a route permanently to one immutable snapshot instead, set `functionref.version: orders-v3` — unlike an alias, a version pin never moves. +`alias` and `version` are mutually exclusive, and both are valid on every trigger kind that embeds a function reference (HTTP, message queue, timer, Kubernetes watch). + +## Deploy by moving the alias + +A deploy becomes: publish, then repoint. + +```bash +$ fission fn update --name orders --code orders-v3.js +function 'orders' updated + +$ fission fn publish --name orders --wait +created orders-v4 + +$ fission alias update --name prod --version orders-v4 --wait +function alias 'prod' updated +function alias 'prod' resolved +``` + +`--wait` blocks until the alias's `Resolved` condition reports the new target, so a CI job can gate the next step on the switch actually happening. +You can also wait separately: `fission alias wait --name prod --for condition=Resolved`. + +### Weighted traffic splits + +An alias can spread traffic across two versions — the primary gets `--weight` percent, the secondary gets the rest: + +```bash +$ fission alias update --name prod --version orders-v3 --weight 90 --secondary-version orders-v4 +function alias 'prod' updated +``` + +Now 90% of requests through `prod` run `orders-v3` and 10% run `orders-v4`. +Step `--weight` down as confidence grows, then finish with a full repoint: + +```bash +$ fission alias update --name prod --version orders-v4 --clear-weight +function alias 'prod' updated +``` + +`--weight` requires `--secondary-version`, and `--clear-weight` drops the split (it wins if combined with other flags in the same call). +To have Fission step the weight for you based on error rates, drive the split with a [canary config over the alias]({{% ref "versions-lifecycle.md#canary-rollouts-over-an-alias" %}}). + +## Instant rollback + +`fission fn rollback` repoints one alias back at a previous version — atomically, and without recycling any pods: + +```bash +$ fission fn rollback --name orders --alias prod --wait +function alias 'prod' rolled back: orders-v4 -> orders-v3 +function alias 'prod' resolved +``` + +By default the alias returns to its **previous target**, which Fission records in the alias's history on every switch. +Pass `--to` to pick any version explicitly: + +```bash +$ fission fn rollback --name orders --alias prod --to orders-v1 +function alias 'prod' rolled back: orders-v3 -> orders-v1 +``` + +Three properties make this safe to reach for during an incident: + +- **No cold start.** + A version that any alias references keeps at least one specialized pod warm, so the rollback target is already running when traffic arrives. +- **Full repoint.** + A rollback clears any weighted split, so a rollback issued mid-canary stops the split entirely rather than rolling back only the primary side. +- **Atomic.** + The alias flips in a single update; there is no window where triggers see a half-moved state. + +### Rolling back a GitOps-managed alias + +If the alias is owned by a `fission spec` directory (deployed with `fission spec apply`), a bare rollback is refused: + +```bash +$ fission fn rollback --name orders --alias prod +Error: function alias 'prod' is managed by `fission spec` (Git); the next spec apply will revert this rollback. Re-run with --detach to strip spec ownership, and update your Git repo: set spec.version: orders-v3 in the FunctionAlias manifest +``` + +The guard exists because the next `fission spec apply` would reconcile the alias back to whatever `spec.version` says in Git — silently undoing the rollback. +You have two options: + +- **Git-first (preferred):** change `spec.version` in the FunctionAlias manifest in your repository and let the pipeline apply it. +- **Emergency:** re-run with `--detach`, which strips the spec-ownership annotations in the same update as the repoint, so a later `spec apply` no longer reverts it. + Update the manifest afterwards, then re-apply to re-adopt the alias. + +## Declarative aliases and digest pinning + +Aliases are ordinary objects in a [spec directory]({{% ref "/docs/usage/spec/_index.md" %}}), so a Git repository can own them: + +```yaml +apiVersion: fission.io/v1 +kind: FunctionAlias +metadata: + name: prod + namespace: default +spec: + functionName: orders + version: orders-v3 +``` + +For pipelines that build content before versions exist, an alias can pin by **package digest** instead of by version name: + +```yaml +spec: + functionName: orders + packageDigest: sha256:fd61a03af4f77d870fc21e05e7e80678095c92d808cfb3b5c279ee04c74aca13 +``` + +The pipeline commits the content hash it built; Fission resolves the digest to the version that recorded it, asynchronously, once that version exists. +Because resolution is eventually consistent, gate on it in CI: + +```bash +$ fission alias wait --name prod --for condition=Resolved --timeout 120s +``` + +`version` and `packageDigest` are mutually exclusive — exactly one must be set. +Promotion between environments is then just two aliases converging: point `staging` at a new version, test through the staging route, and promote by repointing `prod` at the **same** version — the identical immutable snapshot, not a rebuild. + +Versions themselves are deliberately **not** spec-managed: the cluster mints them, and Git references them by name or digest. + +## Related + +- [Version lifecycle and interactions]({{% ref "versions-lifecycle.md" %}}) — automatic publishing, retention, environment drift, and how versions interact with async invocation, canaries, and state. +- [Canary deployments]({{% ref "canary-deployments.md" %}}) — automated, metrics-driven weight stepping. +- [Declarative specs]({{% ref "/docs/usage/spec/_index.md" %}}) — the `fission spec` workflow that can own aliases. +- [Create and run functions]({{% ref "functions.en.md" %}}) — the everyday function workflow. diff --git a/content/en/docs/usage/function/versions-lifecycle.md b/content/en/docs/usage/function/versions-lifecycle.md new file mode 100644 index 00000000..d7548917 --- /dev/null +++ b/content/en/docs/usage/function/versions-lifecycle.md @@ -0,0 +1,134 @@ +--- +title: "Version Lifecycle and Interactions" +draft: false +weight: 50 +description: > + Mint function versions automatically on every update, bound version history with retention GC, track environment drift, and understand how versions interact with async invocation, canaries, state, and other triggers. +--- + +**How function versions are minted automatically, how old ones are cleaned up, what an environment update means for rollback, and how every other Fission feature behaves when traffic flows through an alias.** + +This page continues from [Function versions and aliases]({{% ref "versions-aliases.md" %}}), which covers publishing, aliases, routing, and rollback. + +## Automatic publishing + +Instead of calling `fission fn publish` after every deploy, a function can opt into minting versions automatically. +Opt-in is a field on the function's spec — set it in a [spec file]({{% ref "/docs/usage/spec/_index.md" %}}) or with `kubectl`; there is no CLI flag for it: + +```yaml +apiVersion: fission.io/v1 +kind: Function +metadata: + name: orders +spec: + # ... + versioning: + mode: auto # "auto" is the default once versioning is present + retain: 10 # optional; see retention below +``` + +In `auto` mode, Fission publishes a new version after every **runtime-affecting** update — a change to what actually runs or is observable by an invocation, such as new code, a changed entry point, or changed resources. +Cosmetic edits (labels, annotations) do not mint versions. + +The version is minted only **after the referenced package build succeeds**, so a broken build never becomes a version an alias could point at. +If a build is in flight when you update, the version appears when the build completes. + +Set `mode: manual` to keep versioning opted in (retention GC, alias support) but mint versions only on explicit `fission fn publish`. +`fission fn publish` itself works on any function, whether or not `spec.versioning` is set. + +## Retention + +Version history is bounded per function so old snapshots do not accumulate forever: + +- `spec.versioning.retain` bounds how many **unaliased** versions are kept (default 10, minimum 1). +- A version referenced by any alias is **never** garbage collected, no matter how old. +- The newest version is never deleted. + +The sweep runs automatically for opted-in functions. +Run one on demand — for example to preview a lower retain value before committing it to the spec — with: + +```bash +$ fission fn gc-versions --name orders --keep 5 +deleted 3, skipped 1, retained 5 +``` + +`skipped` counts versions that were beyond the keep floor but protected by an alias reference. + +## Environment updates and drift + +Versions snapshot the function's **code and configuration** — not the environment's runtime image. +An environment update (say, bumping `node` to a new image) recycles pods under **every** version of every function using it; it sits outside the version boundary entirely. +That has one operational consequence worth internalizing: + +{{% notice warning %}} +Rolling back an alias restores the function's code and configuration, **not** the runtime image it originally ran on. +If an incident started with an environment update, roll the environment back too. +{{% /notice %}} + +Fission surfaces this drift in three places: + +**On the alias**, as an `EnvDrift` condition, set when the alias's resolved version was published under an older generation of its environment. + +**On rollback**, as a non-blocking warning: + +```bash +$ fission fn rollback --name orders --alias prod +WARNING: target version orders-v2 was published under env default/node generation 4; live env is generation 5 — rollback restores code/config, not the runtime image +function alias 'prod' rolled back: orders-v3 -> orders-v2 +``` + +**Before an environment update**, as a blast-radius report. +`fission env impact` lists every function referencing the environment, each of its aliases, and whether each alias's current target already drifts: + +```bash +$ fission env impact --name node +FUNCTION ALIAS TARGET-VERSION ENV-OBSERVED-GEN LIVE-GEN DRIFT +orders prod orders-v2 4 5 True +orders staging orders-v3 5 5 False +reports 5 +``` + +`DRIFT` is `True` (published under an older environment generation), `False` (current), `OtherEnv` (the version was published when the function still used a different environment), or `` (no alias or not assessable). +`fission fn versions --name orders -o wide` shows the same verdict per version in its `ENVDRIFT` column. + +## How other invocation paths behave + +HTTP triggers are not the only way traffic reaches a function. +Every path has a defined relationship with aliases and versions: + +| Path | Behavior with an alias | +| --- | --- | +| HTTP trigger | Resolved at **request time**: repointing the alias redirects the very next request. | +| Message queue, timer, and Kubernetes watch triggers | Resolved at **delivery/firing time**: the invocation runs whatever the alias points at when the event fires, so you upgrade consumers by moving the alias — without redeploying any trigger. | +| [MCP tools]({{% ref "mcp-tools.md" %}}) | Resolved at **call time**, like HTTP: an LLM agent's tool call runs the alias's current target. | +| [Async invocation]({{% ref "async-invocation.md" %}}) retries | Pinned at **enqueue time**: an async invocation records the version it resolved to when accepted, and every retry re-runs that same version — retries stay deterministic even across a rollback. | +| [Keyed state]({{% ref "keyed-state.md" %}}) | **Shared across versions**: state belongs to the function, not to a version, so a rollback rolls back code, never data. | +| Sticky sessions | A session key stays on **one version** through a weighted split, so a user is not bounced between old and new behavior mid-session. | + +## Canary rollouts over an alias + +A weighted alias is the manual form of a canary; a [CanaryConfig]({{% ref "canary-deployments.md" %}}) automates the stepping. +When the canary's HTTP trigger references an alias, `--newfn` and `--oldfn` name two **versions** of the alias's function (see `fission fn versions`) — not two functions: + +```bash +$ fission alias create --name prod --function orders --version orders-v3 +function alias 'prod' created + +$ fission canary create --name orders-canary --httptrigger orders-api \ + --newfn orders-v4 --oldfn orders-v3 \ + --increment-step 20 --increment-interval 2m --failure-threshold 10 +``` + +The canary controller then steps the alias's weight toward `orders-v4`, watching the error rate. +On success it promotes: the alias is repointed fully at the new version. +On failure it rolls back: traffic returns to `orders-v3` — which is still warm, because the alias never stopped referencing it. + +Prefer this over the classic two-function canary pattern (deploying `orders-v2` as a separate function next to `orders`): with versions there is nothing to duplicate, the history stays on one function, and cleanup is automatic via retention. +The classic pattern keeps working unchanged. + +## Related + +- [Function versions and aliases]({{% ref "versions-aliases.md" %}}) — publishing, aliases, weighted splits, rollback, and GitOps workflows. +- [Canary deployments]({{% ref "canary-deployments.md" %}}) — the full canary reference, including the metrics setup. +- [Asynchronous invocation]({{% ref "async-invocation.md" %}}) — durable fire-and-forget delivery. +- [Function state]({{% ref "keyed-state.md" %}}) — durable per-key state shared by all versions of a function. From 2acbf3349e490f306a18b8f816f106b8ce95b102 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 25 Jul 2026 21:28:23 +0530 Subject: [PATCH 05/26] docs: fn test --alias/--version Co-Authored-By: Claude Fable 5 --- .../docs/usage/function/versions-aliases.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/content/en/docs/usage/function/versions-aliases.md b/content/en/docs/usage/function/versions-aliases.md index 2c17789f..e057674e 100644 --- a/content/en/docs/usage/function/versions-aliases.md +++ b/content/en/docs/usage/function/versions-aliases.md @@ -88,6 +88,29 @@ staging orders orders-v4 orders-v4 `fission alias get --name prod` shows the same row plus the alias's status conditions, and `fission alias delete --name prod` removes it. An alias lives in the same namespace as its function, and one function can have any number of aliases. +## Testing an alias or version + +`fission fn test` takes `--alias` and `--version` so you can smoke-test one alias or one pinned version directly, without touching a trigger and without waiting for the alias to actually see traffic: + +```bash +$ fission fn test --name orders --alias prod +{"order":"ok"} + +$ fission fn test --name orders --version orders-v3 +{"order":"ok"} +``` + +`--alias` and `--version` are mutually exclusive. +Each is checked against the function before the request is sent, so a typo'd name fails immediately with a clear error instead of an opaque router 404: + +```bash +$ fission fn test --name orders --alias staging +Error: alias "staging" not found for function "orders": functionaliases.fission.io "staging" not found +``` + +`--async` works with either flag too. +The invocation is enqueued against the resolved alias/version route, so it stays pinned to that target even if the alias moves before the function actually runs. + ## Route triggers through the alias A trigger targets an alias through the optional `alias` field on its function reference. From 471603cadeead00686223d1822af4f8bc5274407 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 25 Jul 2026 21:43:58 +0530 Subject: [PATCH 06/26] docs: fn --versioning/--retain flags Co-Authored-By: Claude Fable 5 --- .../docs/usage/function/versions-lifecycle.md | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/content/en/docs/usage/function/versions-lifecycle.md b/content/en/docs/usage/function/versions-lifecycle.md index d7548917..10aa654c 100644 --- a/content/en/docs/usage/function/versions-lifecycle.md +++ b/content/en/docs/usage/function/versions-lifecycle.md @@ -13,7 +13,21 @@ This page continues from [Function versions and aliases]({{% ref "versions-alias ## Automatic publishing Instead of calling `fission fn publish` after every deploy, a function can opt into minting versions automatically. -Opt-in is a field on the function's spec — set it in a [spec file]({{% ref "/docs/usage/spec/_index.md" %}}) or with `kubectl`; there is no CLI flag for it: +Opt in from the CLI with `--versioning`, on either `fission fn create` or `fission fn update`: + +```bash +$ fission fn update --name orders --versioning auto +Function 'orders' updated + +$ fission fn update --name orders --versioning auto --retain 10 +Function 'orders' updated +``` + +`--versioning` takes `auto` (the default once versioning is enabled), `manual`, or `off`. +`off` is only meaningful on `fn update` — it clears the versioning config; on `fn create` there is nothing to clear yet, so omitting `--versioning` and passing `--versioning off` are equivalent. +`--retain` sets the retention floor (see below) and requires versioning to already be enabled — pass `--versioning` in the same command, or add `--retain` on its own once the function already carries a `versioning` block. + +The same fields are also settable directly on the function's spec — in a [spec file]({{% ref "/docs/usage/spec/_index.md" %}}) or with `kubectl patch`, if you'd rather manage it that way: ```yaml apiVersion: fission.io/v1 @@ -27,13 +41,17 @@ spec: retain: 10 # optional; see retention below ``` +```bash +$ kubectl patch function orders --type merge -p '{"spec":{"versioning":{"mode":"auto","retain":10}}}' +``` + In `auto` mode, Fission publishes a new version after every **runtime-affecting** update — a change to what actually runs or is observable by an invocation, such as new code, a changed entry point, or changed resources. Cosmetic edits (labels, annotations) do not mint versions. The version is minted only **after the referenced package build succeeds**, so a broken build never becomes a version an alias could point at. If a build is in flight when you update, the version appears when the build completes. -Set `mode: manual` to keep versioning opted in (retention GC, alias support) but mint versions only on explicit `fission fn publish`. +Set `--versioning manual` (or `mode: manual` in the spec) to keep versioning opted in (retention GC, alias support) but mint versions only on explicit `fission fn publish`. `fission fn publish` itself works on any function, whether or not `spec.versioning` is set. ## Retention From 48e65c4d4de2344a4dc8f6d8bdafe89b127951d2 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 25 Jul 2026 22:01:37 +0530 Subject: [PATCH 07/26] docs: versions/aliases CLI surface sweep MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-checked the versions/aliases pages against the RFC-0025 implementation (fission fission@651ac3bf): flags, error strings, and transcript output already matched. Added the two gaps found — a `fn test --alias` rollback-verification transcript, and an imperative `--package-digest` example alongside the existing YAML digest-pin example. Co-Authored-By: Claude Fable 5 --- .../en/docs/usage/function/versions-aliases.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/content/en/docs/usage/function/versions-aliases.md b/content/en/docs/usage/function/versions-aliases.md index e057674e..cfab49ff 100644 --- a/content/en/docs/usage/function/versions-aliases.md +++ b/content/en/docs/usage/function/versions-aliases.md @@ -202,6 +202,13 @@ function alias 'prod' rolled back: orders-v4 -> orders-v3 function alias 'prod' resolved ``` +Confirm the alias is actually serving the rolled-back target with the same `--alias` flag `fn test` uses for smoke-testing: + +```bash +$ fission fn test --name orders --alias prod +{"order":"ok"} +``` + By default the alias returns to its **previous target**, which Fission records in the alias's history on every switch. Pass `--to` to pick any version explicitly: @@ -258,6 +265,14 @@ spec: packageDigest: sha256:fd61a03af4f77d870fc21e05e7e80678095c92d808cfb3b5c279ee04c74aca13 ``` +The same pin works imperatively with `--package-digest`, on either `alias create` or `alias update`: + +```bash +$ fission alias create --name prod --function orders \ + --package-digest sha256:fd61a03af4f77d870fc21e05e7e80678095c92d808cfb3b5c279ee04c74aca13 +function alias 'prod' created +``` + The pipeline commits the content hash it built; Fission resolves the digest to the version that recorded it, asynchronously, once that version exists. Because resolution is eventually consistent, gate on it in CI: From 74e7e630a3b4a5b8432b2658070adc0767c983fd Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 25 Jul 2026 22:21:04 +0530 Subject: [PATCH 08/26] docs: --retain-versions rename Fission renamed the `fn create/update` version-retention flag from --retain to --retain-versions to disambiguate it from the pre-existing --retainpods pod-warming knob. Update the transcript and prose in versions-lifecycle.md; the versioning.retain spec field is unchanged. Co-Authored-By: Claude Fable 5 --- content/en/docs/usage/function/versions-lifecycle.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/en/docs/usage/function/versions-lifecycle.md b/content/en/docs/usage/function/versions-lifecycle.md index 10aa654c..d6fbfaee 100644 --- a/content/en/docs/usage/function/versions-lifecycle.md +++ b/content/en/docs/usage/function/versions-lifecycle.md @@ -19,13 +19,14 @@ Opt in from the CLI with `--versioning`, on either `fission fn create` or `fissi $ fission fn update --name orders --versioning auto Function 'orders' updated -$ fission fn update --name orders --versioning auto --retain 10 +$ fission fn update --name orders --versioning auto --retain-versions 10 Function 'orders' updated ``` `--versioning` takes `auto` (the default once versioning is enabled), `manual`, or `off`. `off` is only meaningful on `fn update` — it clears the versioning config; on `fn create` there is nothing to clear yet, so omitting `--versioning` and passing `--versioning off` are equivalent. -`--retain` sets the retention floor (see below) and requires versioning to already be enabled — pass `--versioning` in the same command, or add `--retain` on its own once the function already carries a `versioning` block. +`--retain-versions` sets the retention floor (see below) and requires versioning to already be enabled — pass `--versioning` in the same command, or add `--retain-versions` on its own once the function already carries a `versioning` block. +`--retain-versions` is distinct from `--retainpods`, which controls how many specialized pods stay warm — not how many function versions are kept. The same fields are also settable directly on the function's spec — in a [spec file]({{% ref "/docs/usage/spec/_index.md" %}}) or with `kubectl patch`, if you'd rather manage it that way: From 8506b37a9412d38280af337de9c66d1e7963f851 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sun, 26 Jul 2026 00:59:25 +0530 Subject: [PATCH 09/26] =?UTF-8?q?docs:=20versioning=20CLI=20surface=20?= =?UTF-8?q?=E2=80=94=20routing=20flags,=20inspection=20views,=20waits?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .../docs/usage/function/versions-aliases.md | 127 ++++++++++++++++-- .../docs/usage/function/versions-lifecycle.md | 22 ++- 2 files changed, 135 insertions(+), 14 deletions(-) diff --git a/content/en/docs/usage/function/versions-aliases.md b/content/en/docs/usage/function/versions-aliases.md index cfab49ff..f629c83c 100644 --- a/content/en/docs/usage/function/versions-aliases.md +++ b/content/en/docs/usage/function/versions-aliases.md @@ -37,17 +37,20 @@ A trigger that references a bare function name keeps meaning "the live function" ```bash $ fission fn update --name orders --code orders-v2.js -function 'orders' updated +Function 'orders' updated $ fission fn publish --name orders --description "checkout rounding fix" created orders-v3 +next: fission alias create --function orders --name --version orders-v3 ``` +The first line is machine-readable (`created `); the `next:` breadcrumb suggests the usual follow-up — pointing an alias at the fresh version. Publishing is idempotent: if nothing runtime-affecting changed since the last publish, the existing newest version is returned instead of minting a duplicate: ```bash $ fission fn publish --name orders unchanged orders-v3 +next: fission alias create --function orders --name --version orders-v3 ``` | Flag | Meaning | @@ -63,21 +66,31 @@ Versions can also be minted automatically on every runtime-affecting update — ```bash $ fission fn versions --name orders -NAME SEQUENCE DIGEST PUBLISHED AGE -orders-v1 1 sha256:1f8ac10f23c5 2026-07-10T09:14:02Z 14d -orders-v2 2 sha256:60303ae22b99 2026-07-17T16:41:55Z 7d -orders-v3 3 sha256:fd61a03af4f7 2026-07-24T08:03:11Z 2m +NAME SEQUENCE DIGEST PUBLISHED ALIASED-BY AGE +orders-v1 1 sha256:1f8ac10f23c5 2026-07-10T09:14:02Z - 14d +orders-v2 2 sha256:60303ae22b99 2026-07-17T16:41:55Z - 7d +orders-v3 3 sha256:fd61a03af4f7 2026-07-24T08:03:11Z prod 2m ``` -The `DIGEST` column pins the exact package content of each version. -The table truncates it; `-o wide` prints full digests and adds an `ENVDRIFT` column showing whether the version was published under an older generation of its environment (see [environment updates and drift]({{% ref "versions-lifecycle.md#environment-updates-and-drift" %}})). -`-o json` / `-o yaml` print the full objects. +The `DIGEST` column pins the exact package content of each version, and `ALIASED-BY` shows which aliases currently reference it — a `-` means the version is unreferenced and eligible for [retention GC]({{% ref "versions-lifecycle.md#retention" %}}). +The table truncates digests; `-o wide` prints them in full and adds an `ENVDRIFT` column showing whether the version was published under an older generation of its environment (see [environment updates and drift]({{% ref "versions-lifecycle.md#environment-updates-and-drift" %}})), plus the `DESCRIPTION` recorded at publish time. +`-o name` prints one version name per line, for scripting; `-o json` / `-o yaml` print the full objects. + +To read a version rather than list them, `fission fn get --version` prints the exact source snapshot the version froze: + +```bash +$ fission fn get --name orders --version orders-v2 +module.exports = async (context) => { + // ... +} +``` ## Point an alias at a version ```bash -$ fission alias create --name prod --function orders --version orders-v3 +$ fission alias create --name prod --function orders --version orders-v3 --wait function alias 'prod' created +function alias 'prod' resolved $ fission alias list NAME FUNCTION VERSION PACKAGE-DIGEST WEIGHT SECONDARY-VERSION RESOLVED-VERSION @@ -85,7 +98,29 @@ prod orders orders-v3 orders-v3 staging orders orders-v4 orders-v4 ``` -`fission alias get --name prod` shows the same row plus the alias's status conditions, and `fission alias delete --name prod` removes it. +`--wait` blocks until the alias's `Resolved` condition confirms the target — the same flag `alias update` takes, so a CI job can gate on either. +Without it, creation returns immediately and resolution completes asynchronously. + +`fission alias get --name prod` shows the same row plus the alias's status conditions and — once the alias has been repointed at least once — a `HISTORY` block listing its previous targets, most recent last: + +```bash +$ fission alias get --name prod +NAME FUNCTION VERSION PACKAGE-DIGEST WEIGHT SECONDARY-VERSION RESOLVED-VERSION +prod orders orders-v4 orders-v4 + +CONDITIONS: +TYPE STATUS REASON MESSAGE LASTTRANSITION +Resolved True Resolved resolved to FunctionVersion "orders-v4" 8s +EnvDrift False EnvCurrent environment default/node generation 5 matches version "orders-v4"'s recorded generation 5 8s + +HISTORY: +VERSION SWITCHED-AT +orders-v2 2d +orders-v3 8s +``` + +The last history entry is what a bare `fission fn rollback` returns to, so `alias get` is the fastest way to see where a rollback would land. +`fission alias delete --name prod` removes the alias. An alias lives in the same namespace as its function, and one function can have any number of aliases. ## Testing an alias or version @@ -111,13 +146,79 @@ Error: alias "staging" not found for function "orders": functionaliases.fission. `--async` works with either flag too. The invocation is enqueued against the resolved alias/version route, so it stays pinned to that target even if the alias moves before the function actually runs. +## Inspecting versions, aliases, and their pods + +`fission fn describe` on a versioned function ends with a `VERSIONING` section — the versioning mode, the version count, and one row per alias — and its `PODS` table gains a `VERSION` column showing which version each specialized pod is serving: + +```bash +$ fission fn describe --name orders +... +PODS: +NAME NAMESPACE READY STATUS IP EXECUTORTYPE MANAGED SERVED VERSION +poolmgr-node-default-8750-844bd45565-9tvrj default 2/2 Running 10.244.0.77 poolmgr false true orders-v4 +poolmgr-node-default-8750-844bd45565-pg8rk default 2/2 Running 10.244.0.78 poolmgr false true orders-v3 + +VERSIONING: +Versioning: mode=auto retain=10 +Versions: 4 +NAME TARGET WEIGHT ENVDRIFT +prod orders-v3 False +staging orders-v4 False +``` + +Add `--version` to describe one version instead of the function — an inspector over the immutable snapshot, including its digest, publish-time description, the environment generation it was published under, and which aliases reference it: + +```bash +$ fission fn describe --name orders --version orders-v3 +Name: orders-v3 +Function: orders +Sequence: 3 +Digest: sha256:fd61a03af4f77d870fc21e05e7e80678095c92d808cfb3b5c279ee04c74aca13 +Description: checkout rounding fix +Published: 2026-07-24T08:03:11Z +Age: 2d +Entrypoint: +Environment: node +Env Observed Generation: 5 +Env Runtime Image: ghcr.io/fission/node-env +Env Drift: current + +ALIASED-BY: +NAME TARGET WEIGHT ENVDRIFT +prod orders-v3 False +``` + +The same per-target filtering works on `fission fn pods` and `fission fn logs`: `--version` narrows to pods serving one pinned version, `--alias` follows an alias to whatever it currently resolves to. +During a weighted split or an incident, that is the difference between reading interleaved logs from two versions and reading exactly the one you care about: + +```bash +$ fission fn pods --name orders --version orders-v3 +NAME NAMESPACE READY STATUS IP EXECUTORTYPE MANAGED SERVED VERSION +poolmgr-node-default-8750-844bd45565-pg8rk default 2/2 Running 10.244.0.78 poolmgr false true orders-v3 + +$ fission fn logs --name orders --alias prod +... +``` + +`--version` and `--alias` are mutually exclusive on both commands. + ## Route triggers through the alias A trigger targets an alias through the optional `alias` field on its function reference. The router resolves the alias **at request time**, so repointing the alias redirects traffic without touching the trigger. -The `fission` CLI has no dedicated flag for this yet, so set the field declaratively. -Either write the trigger with `--spec` and edit the generated file, or apply YAML directly: +Create the route with `--function-alias`: + +```bash +$ fission route create --name orders-api --url /api/orders --method POST \ + --function orders --function-alias prod +trigger 'orders-api' created +``` + +`--function-alias` requires exactly one `--function` and is mutually exclusive with `--function-version` and with weighted multi-function routing. +The same flag works on `fission route update`, with one wrinkle: pass `--function` again alongside it — `route update` does not infer the target function from the existing route. + +For GitOps pipelines, the same field is settable declaratively — write the trigger with `--spec` and edit the generated file, or apply YAML directly: ```yaml apiVersion: fission.io/v1 @@ -150,7 +251,7 @@ functionref: alias: staging ``` -To pin a route permanently to one immutable snapshot instead, set `functionref.version: orders-v3` — unlike an alias, a version pin never moves. +To pin a route permanently to one immutable snapshot instead, pass `--function-version orders-v3` (or set `functionref.version: orders-v3` in YAML) — unlike an alias, a version pin never moves. `alias` and `version` are mutually exclusive, and both are valid on every trigger kind that embeds a function reference (HTTP, message queue, timer, Kubernetes watch). ## Deploy by moving the alias diff --git a/content/en/docs/usage/function/versions-lifecycle.md b/content/en/docs/usage/function/versions-lifecycle.md index d6fbfaee..6951e907 100644 --- a/content/en/docs/usage/function/versions-lifecycle.md +++ b/content/en/docs/usage/function/versions-lifecycle.md @@ -48,6 +48,14 @@ $ kubectl patch function orders --type merge -p '{"spec":{"versioning":{"mode":" In `auto` mode, Fission publishes a new version after every **runtime-affecting** update — a change to what actually runs or is observable by an invocation, such as new code, a changed entry point, or changed resources. Cosmetic edits (labels, annotations) do not mint versions. +The CLI reminds you that the mint is pending after every such update: + +```bash +$ fission fn update --name orders --code orders-v3.js +Package 'orders-4c266a01-9182-4d40-b1b6-8a24b0e9e62b' updated +Function 'orders' updated +versioning=auto: a new version is minted once the build succeeds (fission fn versions --name orders) +``` The version is minted only **after the referenced package build succeeds**, so a broken build never becomes a version an alias could point at. If a build is in flight when you update, the version appears when the build completes. @@ -72,6 +80,18 @@ deleted 3, skipped 1, retained 5 ``` `skipped` counts versions that were beyond the keep floor but protected by an alias reference. +The `ALIASED-BY` column of `fission fn versions` shows exactly which alias protects which version. + +### Deleting the function + +Deleting a versioned function cascades: its versions and aliases go with it. +`fission fn delete` says so before doing it, and calls out any triggers that route through the doomed aliases — those triggers are **not** deleted, but they stop resolving: + +```bash +$ fission fn delete --name orders +warning: deleting function 'orders' also deletes 4 versions and 2 aliases (prod, staging); HTTPTriggers [orders-api] reference these aliases and will stop resolving +function 'orders' deleted +``` ## Environment updates and drift @@ -108,7 +128,7 @@ reports 5 ``` `DRIFT` is `True` (published under an older environment generation), `False` (current), `OtherEnv` (the version was published when the function still used a different environment), or `` (no alias or not assessable). -`fission fn versions --name orders -o wide` shows the same verdict per version in its `ENVDRIFT` column. +`fission fn versions --name orders -o wide` shows the same verdict per version in its `ENVDRIFT` column, and the per-version inspector (`fission fn describe --name orders --version orders-v2`) spells it out in full — the environment generation the version was published under, the live runtime image, and an `Env Drift` verdict. ## How other invocation paths behave From 53c422310222d3cb73733ac063c984d00d4dcf0c Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:01:04 +0530 Subject: [PATCH 10/26] docs: regenerate CLI and CRD reference from fission main CLI: adds alias, function versions/publish/rollback/gc-versions/state, environment impact pages; picks up --provisioned-concurrency, --provisioned-schedule, --env-var, --env-from-secret, --env-from-configmap. CRD: adds Workflow, FunctionVersion, FunctionAlias; terminationGracePeriod default corrected to 90s. --- content/en/docs/reference/crd-reference.md | 848 +++++++++++++++++- .../en/docs/reference/fission-cli/fission.md | 1 + .../reference/fission-cli/fission_alias.md | 33 + .../fission-cli/fission_alias_create.md | 39 + .../fission-cli/fission_alias_delete.md | 33 + .../fission-cli/fission_alias_get.md | 33 + .../fission-cli/fission_alias_list.md | 38 + .../fission-cli/fission_alias_update.md | 43 + .../fission-cli/fission_alias_wait.md | 38 + .../fission-cli/fission_canary_create.md | 26 + .../fission-cli/fission_environment.md | 1 + .../fission-cli/fission_environment_impact.md | 37 + .../reference/fission-cli/fission_function.md | 5 + .../fission-cli/fission_function_create.md | 116 +-- .../fission-cli/fission_function_describe.md | 5 +- .../fission-cli/fission_function_dlq_list.md | 2 +- .../fission-cli/fission_function_dlq_purge.md | 2 +- .../fission_function_dlq_redrive.md | 2 +- .../fission-cli/fission_function_dlq_show.md | 2 +- .../fission_function_gc-versions.md | 37 + .../fission-cli/fission_function_get.md | 5 +- .../fission-cli/fission_function_log.md | 2 + .../fission-cli/fission_function_pods.md | 6 +- .../fission-cli/fission_function_publish.md | 40 + .../fission-cli/fission_function_rollback.md | 41 + .../fission_function_run-container.md | 49 +- .../fission-cli/fission_function_run-local.md | 50 +- .../fission-cli/fission_function_state.md | 31 + .../fission_function_state_delete.md | 34 + .../fission-cli/fission_function_state_get.md | 33 + .../fission_function_state_list.md | 33 + .../fission-cli/fission_function_state_set.md | 36 + .../fission-cli/fission_function_test.md | 4 +- .../fission_function_update-container.md | 43 +- .../fission-cli/fission_function_update.md | 110 ++- .../fission-cli/fission_function_versions.md | 33 + .../fission-cli/fission_httptrigger_create.md | 4 +- .../fission-cli/fission_httptrigger_update.md | 4 +- .../fission-cli/fission_mqtrigger_create.md | 2 +- 39 files changed, 1718 insertions(+), 183 deletions(-) create mode 100644 content/en/docs/reference/fission-cli/fission_alias.md create mode 100644 content/en/docs/reference/fission-cli/fission_alias_create.md create mode 100644 content/en/docs/reference/fission-cli/fission_alias_delete.md create mode 100644 content/en/docs/reference/fission-cli/fission_alias_get.md create mode 100644 content/en/docs/reference/fission-cli/fission_alias_list.md create mode 100644 content/en/docs/reference/fission-cli/fission_alias_update.md create mode 100644 content/en/docs/reference/fission-cli/fission_alias_wait.md create mode 100644 content/en/docs/reference/fission-cli/fission_environment_impact.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_gc-versions.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_publish.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_rollback.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_state.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_state_delete.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_state_get.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_state_list.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_state_set.md create mode 100644 content/en/docs/reference/fission-cli/fission_function_versions.md diff --git a/content/en/docs/reference/crd-reference.md b/content/en/docs/reference/crd-reference.md index dc2e6a2d..bc1fd5f7 100644 --- a/content/en/docs/reference/crd-reference.md +++ b/content/en/docs/reference/crd-reference.md @@ -21,14 +21,41 @@ Package v1 contains API Schema definitions for the fission.io v1 API group - [FissionTenant](#fissiontenant) - [FissionTenantList](#fissiontenantlist) - [Function](#function) +- [FunctionAlias](#functionalias) +- [FunctionAliasList](#functionaliaslist) +- [FunctionVersion](#functionversion) +- [FunctionVersionList](#functionversionlist) - [HTTPTrigger](#httptrigger) - [KubernetesWatchTrigger](#kuberneteswatchtrigger) - [MessageQueueTrigger](#messagequeuetrigger) - [Package](#package) - [TimeTrigger](#timetrigger) +- [Workflow](#workflow) +- [WorkflowList](#workflowlist) +- [WorkflowRun](#workflowrun) +- [WorkflowRunList](#workflowrunlist) +#### AliasTargetRecord + + + +AliasTargetRecord is one entry in FunctionAliasStatus.History: a +previously resolved target, kept for audit / rollback visibility. + + + +_Appears in:_ +- [FunctionAliasStatus](#functionaliasstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `version` _string_ | | | | +| `packageDigest` _string_ | | | | +| `switchedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | | | | + + #### AllowedFunctionsPerContainer _Underlying type:_ _string_ @@ -235,6 +262,29 @@ _Appears in:_ | --- | --- | --- | --- | | `namespace` _string_ | | | | | `name` _string_ | | | MaxLength: 63
Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
| +| `mountPath` _string_ | MountPath redirects this configmap's file projection from the
default /configs//; relative to the /configs root.
See SecretReference.MountPath for the constraint rationale. | | | + + +#### DestinationRef + + + +DestinationRef routes an async invocation's result to exactly one target: a +Function (invoked async through the same machinery, depth-capped) or a Topic +(published to a message queue). Exactly one of Function/Topic must be set. +Topic destinations on the built-in statestore provider are supported +(RFC-0027); broker types are rejected by the webhook until the egress phase +lands. + + + +_Appears in:_ +- [InvocationConfig](#invocationconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `function` _[FunctionReference](#functionreference)_ | Function is a same-namespace function destination, invoked asynchronously
with the result envelope as its body (depth-capped to stop runaway chains). | | | +| `topic` _[TopicRef](#topicref)_ | Topic publishes the result envelope to a message-queue topic. | | | #### Environment @@ -297,7 +347,7 @@ _Appears in:_ | `allowAccessToExternalNetwork` _boolean_ | Istio default blocks all egress traffic for safety.
To enable accessibility of external network for builder/function pod, set to 'true'.
(Optional) defaults to 'false' | | | | `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core)_ | The request and limit CPU/MEM resource setting for poolmanager to set up pods in the pre-warm pool.
(Optional) defaults to no limitation. | | | | `poolsize` _integer_ | The initial pool size for environment | | Minimum: 0
| -| `terminationGracePeriod` _integer_ | The grace time for pod to perform connection draining before termination. The unit is in seconds.
(Optional) defaults to 360 seconds | | Minimum: 0
| +| `terminationGracePeriod` _integer_ | The grace time for pod to perform connection draining before termination. The unit is in seconds.
A terminating function pod keeps serving for the WHOLE grace window
(the preStop hook sleeps through it, then the kubelet kills the pod),
so this value is exactly how long every teardown — idle reap, env
update roll, upgrade, node drain — takes per pod. 90s covers endpoint
propagation (seconds) plus the 60s default function timeout with
margin, mirroring the router's own 75s-drain/90s-grace posture; set
it per environment for functions with longer request timeouts.
The CRD default below is what makes the documented default true for
API-created Environments: nil means "use the default" and the
apiserver fills an absent field with 90 at serving time.
The *pointer* is what makes an EXPLICIT 0 ("no drain window, kill
instantly") expressible from typed Go clients: on the previous
int64 field, omitempty marshalled 0 as absent and the apiserver
served it back as 90, so raw YAML was the only way to say 0.
In-process readers must use EffectiveTerminationGracePeriod()
(env_validation.go), which mirrors the CRD default for objects
that never crossed the apiserver.
(Optional) defaults to 90 seconds | 90 | Minimum: 0
| | `keeparchive` _boolean_ | KeepArchive is used by fetcher to determine if the extracted archive
or unarchived file should be placed, which is then used by specialize handler.
(This is mainly for the JVM environment because .jar is one kind of zip archive.) | | | | `imagepullsecret` _string_ | ImagePullSecret is the secret for Kubernetes to pull an image from a
private registry. | | | @@ -489,6 +539,89 @@ Function is function runs within environment runtime with given package and secr | `status` _[FunctionStatus](#functionstatus)_ | | | | +#### FunctionAlias + + + +FunctionAlias is a mutable, named pointer at one (or, during a weighted +rollout, two) FunctionVersion(s) of a Function (RFC-0025). Aliases are +what triggers reference in production; moving an alias is how a rollout +or rollback happens without touching the trigger. + + + +_Appears in:_ +- [FunctionAliasList](#functionaliaslist) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `fission.io/v1` | | | +| `kind` _string_ | `FunctionAlias` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[FunctionAliasSpec](#functionaliasspec)_ | | | | +| `status` _[FunctionAliasStatus](#functionaliasstatus)_ | | | | + + +#### FunctionAliasList + + + +FunctionAliasList is a list of FunctionAliases. + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `fission.io/v1` | | | +| `kind` _string_ | `FunctionAliasList` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `items` _[FunctionAlias](#functionalias) array_ | | | | + + +#### FunctionAliasSpec + + + +Repo convention (types.go:755,778,955): guard BOTH absent and explicit-empty on optional strings. + + + +_Appears in:_ +- [FunctionAlias](#functionalias) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `functionName` _string_ | | | MaxLength: 63
| +| `version` _string_ | Version pins by FunctionVersion name (imperative path). XOR PackageDigest. | | | +| `packageDigest` _string_ | PackageDigest pins declaratively (GitOps): resolved asynchronously to
the FunctionVersion that recorded this digest; eventually consistent. | | Pattern: `^sha256:[a-f0-9]\{64\}$`
| +| `weight` _integer_ | Weight (0-100) served by the primary target; nil = 100%. | | Maximum: 100
Minimum: 0
| +| `secondaryVersion` _string_ | SecondaryVersion receives 100-Weight. Name-pinned only. | | | + + +#### FunctionAliasStatus + + + +FunctionAliasStatus describes the observed state of a FunctionAlias. + + + +_Appears in:_ +- [FunctionAlias](#functionalias) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `resolvedVersion` _string_ | ResolvedVersion is the FunctionVersion name this alias currently
resolves to (always name-pinned, even when Spec.PackageDigest
declares the target declaratively). | | | +| `history` _[AliasTargetRecord](#aliastargetrecord) array_ | History is a bounded tail of previously resolved targets, most
recent last. | | | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | | | | + + #### FunctionPackageRef @@ -515,15 +648,20 @@ FunctionReference refers to a function _Appears in:_ +- [DestinationRef](#destinationref) - [HTTPTriggerSpec](#httptriggerspec) - [KubernetesWatchTriggerSpec](#kuberneteswatchtriggerspec) - [MessageQueueTriggerSpec](#messagequeuetriggerspec) - [TimeTriggerSpec](#timetriggerspec) +- [WorkflowBranchState](#workflowbranchstate) +- [WorkflowState](#workflowstate) | Field | Description | Default | Validation | | --- | --- | --- | --- | | `type` _[FunctionReferenceType](#functionreferencetype)_ | Type indicates whether this function reference is by name or selector. For now,
the only supported reference type is by "name". Future reference types:
* Function by label or annotation
* Branch or tag of a versioned function
* A "rolling upgrade" from one version of a function to another
Available value:
- name
- function-weights | | Enum: [name function-weights]
| -| `name` _string_ | Name of the function. | | | +| `name` _string_ | Name of the function. Bounded to a DNS-1123 label length: the CEL
rule on this type needs the schema bound so the apiserver's cost
estimator can price the regex — without it, embedding the type
under a map (WorkflowSpec.States) blows the per-CRD cost budget. | | MaxLength: 63
| +| `alias` _string_ | Alias, when set, targets a FunctionAlias by name instead of the live
Function directly (RFC-0025): the alias is a movable pointer that the
router resolves at request time to whatever FunctionVersion it
currently points at, so repointing the alias (e.g. for a canary
rollout or a rollback) redirects traffic without touching this
reference. Valid only when Type is "name"; mutually exclusive with
Version. Empty (the default) preserves today's behavior: route
straight to the live Function. | | MaxLength: 63
| +| `version` _string_ | Version, when set, pins this reference to one FunctionVersion CR by
name (RFC-0025) — an immutable published snapshot that never moves,
unlike Alias. Valid only when Type is "name"; mutually exclusive
with Alias. Empty (the default) preserves today's behavior: route
straight to the live Function. | | MaxLength: 63
| | `functionweights` _object (keys:string, values:integer)_ | Function Reference by weight. this map contains function name as key and its weight
as the value. This is for canary upgrade purpose. | | | @@ -557,6 +695,7 @@ and CEL errors with "no such key" if the rule accesses an absent field. _Appears in:_ - [Function](#function) +- [FunctionVersionSpec](#functionversionspec) | Field | Description | Default | Validation | | --- | --- | --- | --- | @@ -564,16 +703,22 @@ _Appears in:_ | `package` _[FunctionPackageRef](#functionpackageref)_ | Reference to a package containing deployment and optionally the source. | | | | `secrets` _[SecretReference](#secretreference) array_ | Reference to a list of secrets. | | | | `configmaps` _[ConfigMapReference](#configmapreference) array_ | Reference to a list of configmaps. | | | +| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envvar-v1-core) array_ | Env lists per-function environment variables set on the function's
runtime container: literals, plus key-level references into
same-namespace Secrets/ConfigMaps via valueFrom (secretKeyRef /
configMapKeyRef only — fieldRef and resourceFieldRef are rejected at
admission because poolmgr's specialize-time injection cannot honor
pod-level field refs portably; RFC-0030 §1). Function Env wins over
EnvFrom, which wins over the environment podspec's merged env.
Platform-reserved names (FISSION_*, RESOURCE_VERSION_COUNT, and the
interpreter/proxy-hijack set) are denied at admission and enforced
at injection. Additive and backward compatible. | | | +| `envFrom` _[EnvFromSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#envfromsource-v1-core) array_ | EnvFrom projects whole same-namespace Secrets/ConfigMaps into the
function's environment, with an optional prefix; later sources win
over earlier ones (Kubernetes semantics), and function Env literals
win over all EnvFrom keys.
Two phase-1 limits, both inherent to native (kubelet) injection:
the kubelet expands envFrom BEFORE container env, so a name the
environment podspec sets as a literal still beats an EnvFrom-supplied
key of the same name; and reserved platform names appearing as data
keys of a referenced object are not filtered (they are unknowable at
admission and mutable afterwards) — they are only shadowed by the
platform vars actually present on the container. Key-level filtering
and full precedence arrive with the poolmgr phase, which resolves
values itself. Additive and backward compatible. | | | | `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core)_ | cpu and memory resources as per K8S standards
This is only for newdeploy to set up resource limitation
when creating deployment for a function. | | | | `InvokeStrategy` _[InvokeStrategy](#invokestrategy)_ | InvokeStrategy is a set of controls which affect how function executes | | | | `functionTimeout` _integer_ | FunctionTimeout provides a maximum amount of duration within which a request for
a particular function execution should be complete.
This is optional. If not specified default value will be taken as 60s | | | | `idletimeout` _integer_ | IdleTimeout specifies the length of time that a function is idle before the
function pod(s) are eligible for deletion. If no traffic to the function
is detected within the idle timeout, the executor will then recycle the
function pod(s) to release resources. | | | | `streaming` _[StreamingConfig](#streamingconfig)_ | Streaming opts this function into the router's streaming invocation path:
incremental flushing, an idle/max timeout split, and a router-driven pod
keepalive for the connection's lifetime. When nil (the default) the function
uses the classic buffered, retry-on-transient-error proxy path with a single
FunctionTimeout deadline. Additive and backward compatible. | | | | `tool` _[ToolConfig](#toolconfig)_ | Tool, when non-nil, advertises this function as a Model Context Protocol
(MCP) tool on the fission-bundle --mcpPort server. The MCP server watches
Function CRDs and hot-updates its tool list from this field. Presence is
the on switch (like Streaming): nil (the default) means the function is
never advertised as a tool. Additive and backward compatible. | | | +| `state` _[StateConfig](#stateconfig)_ | State, when non-nil, opts this function into the RFC-0023 keyed-state
API: a scoped statesvc keyspace backed by the RFC-0021 statestore, with
a per-function token injected at specialization time. Presence is the
on switch (like Streaming and Tool): nil (the default) means exactly
today's behavior. Additive and backward compatible. | | | +| `invocation` _[InvocationConfig](#invocationconfig)_ | Invocation, when non-nil, tunes RFC-0024 asynchronous invocation
(X-Fission-Invoke-Mode: async) for this function: the durable retry policy
and the maximum event age before an undelivered invocation is
dead-lettered. A function without it still accepts async mode with platform
defaults; this field only tunes them. Additive and backward compatible. | | | | `concurrency` _integer_ | Maximum number of pods to be specialized which will serve requests
This is optional. If not specified default value will be taken as 500 | | | | `requestsPerPod` _integer_ | RequestsPerPod indicates the maximum number of concurrent requests that can be served by a specialized pod
This is optional. If not specified default value will be taken as 1 | | | | `onceOnly` _boolean_ | OnceOnly specifies if specialized pod will serve exactly one request in its lifetime and would be garbage collected after serving that one request
This is optional. If not specified default value will be taken as false | | | | `retainPods` _integer_ | RetainPods specifies the number of specialized pods that should be retained after serving requests
This is optional. If not specified default value will be taken as 0 | | | +| `provisionedConcurrency` _[ProvisionedConcurrencyConfig](#provisionedconcurrencyconfig)_ | ProvisionedConcurrency, when non-nil, opts this function into eager
pre-warming of specialized pods (RFC-0026). The executor's provisioner
keeps at least the configured Target specialized pods warm, published to
the function's headless Service, and exempt from the idle reaper. nil
(the default) is the classic on-demand cold-start path. Additive and
backward compatible. Only valid when
InvokeStrategy.ExecutionStrategy.ExecutorType is poolmgr. | | | +| `versioning` _[VersioningConfig](#versioningconfig)_ | Versioning, when non-nil, opts this function into RFC-0025 immutable
version snapshots and named aliases. Presence is the on switch (like
Streaming and Tool): nil (the default) means exactly today's mutable
in-place behavior. Additive and backward compatible. | | | | `podspec` _[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#podspec-v1-core)_ | Podspec specifies podspec to use for executor type container based functions
Different arguments mentioned for container based function are populated inside a pod. | | | @@ -591,9 +736,82 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `observedGeneration` _integer_ | ObservedGeneration reflects the .metadata.generation that the
controller observed when it last updated the status. | | | +| `provisionedReady` _integer_ | ProvisionedReady is the number of warm specialized pods the provisioner
is currently maintaining for this function (RFC-0026). Only meaningful
when Spec.ProvisionedConcurrency is non-nil. Reported by the executor's
provisioner on each reconcile pass. | | | +| `provisionedTarget` _integer_ | ProvisionedTarget is the effective target the provisioner is currently
aiming for (base Target, or a schedule-window override in PR 2). Lets
`fission fn get` show "3/5 provisioned pods ready". | | | +| `provisionedSpecTarget` _integer_ | ProvisionedSpecTarget is the raw Target from spec (before the namespace
cap clamp). When ProvisionedSpecTarget > ProvisionedTarget, the
provisioner clamped the target to the namespace cap
(executor.provisionedConcurrency.maxPerFunction) and the Provisioned
condition carries reason ProvisionedClamped. Lets `fission fn get`
show the spec-vs-effective divergence. | | | | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | Conditions represent the latest observations of the function's state. | | | +#### FunctionVersion + + + +FunctionVersion is an immutable snapshot of a Function's spec at publish +time (RFC-0025). Versions are minted by the version-control loop (auto +mode) or `fission fn publish` (manual mode) and are never mutated after +creation — only garbage collected once unreferenced by any FunctionAlias +and beyond the retain floor. FunctionVersion carries no Status: its +content is fixed at creation, so there is nothing to reconcile. + + + +_Appears in:_ +- [FunctionVersionList](#functionversionlist) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `fission.io/v1` | | | +| `kind` _string_ | `FunctionVersion` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[FunctionVersionSpec](#functionversionspec)_ | | | | + + +#### FunctionVersionList + + + +FunctionVersionList is a list of FunctionVersions. + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `fission.io/v1` | | | +| `kind` _string_ | `FunctionVersionList` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `items` _[FunctionVersion](#functionversion) array_ | | | | + + +#### FunctionVersionSpec + + + +FunctionVersionSpec is the immutable snapshot recorded by one publish. + + + +_Appears in:_ +- [FunctionVersion](#functionversion) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `functionName` _string_ | | | MaxLength: 63
| +| `functionUID` _[UID](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#uid-types-pkg)_ | FunctionUID and FunctionGeneration pin the executor identity of this
snapshot: (UID, Generation) is the pool/cache key (crd.CacheKeyUG),
so a version is a generation pin, not a new identity. | | | +| `functionGeneration` _integer_ | | | | +| `sequence` _integer_ | | | Minimum: 1
| +| `snapshot` _[FunctionSpec](#functionspec)_ | Snapshot is the function spec at publish time with Versioning
zeroed (never nested) and, for legacy packages, PackageRef
repointed at the version-owned snapshot Package. | | | +| `packageDigest` _string_ | PackageDigest pins content: the OCI digest or sha256:. | | | +| `envObservedGeneration` _integer_ | Environment observation at publish time (observational, not pinning). | | | +| `envRuntimeImage` _string_ | | | | +| `publishedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | | | | + + #### GatewayParentRef @@ -696,6 +914,7 @@ _Appears in:_ | `keepPrefix` _boolean_ | When function is exposed with Prefix based path,
keepPrefix decides whether to keep or trim prefix in URL while invoking function. | | | | `method` _string_ | Use Methods instead of Method. This field is going to be deprecated in a future release
HTTP method to access a function. | | Enum: [ GET HEAD POST PUT PATCH DELETE CONNECT OPTIONS TRACE]
| | `methods` _string array_ | HTTP methods to access a function | | items:Enum: [GET HEAD POST PUT PATCH DELETE CONNECT OPTIONS TRACE]
| +| `invocationMode` _string_ | InvocationMode, when "async", forces every request to this trigger into
RFC-0024 asynchronous invocation even without the X-Fission-Invoke-Mode
header (webhooks from third parties cannot set headers). "" (the default)
leaves the per-request header in control. | | Enum: [ async]
| | `functionref` _[FunctionReference](#functionreference)_ | FunctionReference is a reference to the target function. | | | | `createingress` _boolean_ | If CreateIngress is true, router will create an ingress definition.
Deprecated: the Kubernetes Ingress API is frozen. Use RouteConfig
(with Provider "gateway") to expose functions through the Gateway API
instead. CreateIngress + IngressConfig keep working for the
deprecation window but will be removed in a future release. | | | | `ingressconfig` _[IngressConfig](#ingressconfig)_ | IngressConfig for router to set up Ingress.
Deprecated: superseded by RouteConfig. See CreateIngress. | | | @@ -741,6 +960,31 @@ _Appears in:_ | `tls` _string_ | TLS is for user to specify a Secret that contains
TLS key and certificate. The domain name in the
key and crt must match the value of Host field. | | | +#### InvocationConfig + + + +InvocationConfig tunes RFC-0024 asynchronous invocation for a function. +Presence of the enclosing FunctionSpec.Invocation is optional — a function +without it still accepts async mode (X-Fission-Invoke-Mode: async) with +platform defaults; this struct only tunes them. Field bounds are validated in +Go (InvocationConfig.Validate, run at admission via validateForAdmission), +not CEL, because metav1.Duration CEL rules are unproven in this CRD. +An external dead-letter target is a later RFC-0024 phase. + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `retry` _[RetryPolicy](#retrypolicy)_ | Retry is the durable delivery retry policy. The zero value means platform
defaults (a bounded exponential backoff over DefaultMaxAttempts attempts). | | | +| `maxAge` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | MaxAge caps how long an invocation may wait for successful delivery,
measured from its enqueue time; once exceeded it is dead-lettered with
reason "expired". nil means the platform default. Must be > 0 when set. | | | +| `onSuccess` _[DestinationRef](#destinationref)_ | OnSuccess, when set, invokes a destination with a Lambda-shaped result
envelope after the invocation is delivered successfully (2xx). | | | +| `onFailure` _[DestinationRef](#destinationref)_ | OnFailure, when set, invokes a destination with the result envelope after
the invocation permanently fails (a non-retryable 4xx, the retry budget
spent, or MaxAge exceeded). | | | + + #### InvokeStrategy @@ -901,6 +1145,7 @@ MessageQueueType refers to Type of message queue _Appears in:_ - [MessageQueueTriggerSpec](#messagequeuetriggerspec) +- [TopicRef](#topicref) @@ -999,10 +1244,79 @@ _Appears in:_ | --- | --- | --- | --- | | `buildstatus` _[BuildStatus](#buildstatus)_ | BuildStatus is the package build status. | pending | Enum: [ pending running succeeded failed none]
| | `buildlog` _string_ | BuildLog stores build log during the compilation. | | | +| `contentHash` _string_ | ContentHash fingerprints the package's INPUT content (RFC-0029 §3):
the source archive when one is present, otherwise the deployment
archive. A source package's deployment is the build's own product,
so folding it in would make every successful build look like a
fresh change and rebuild forever.
It is what makes a Git-applied Package
converge without the CLI: buildermgr compares the spec's current
hash against this one to decide whether the content actually
changed, rather than relying on the CLI's status->pending poke.
It also covers packages that never build. A deploy-only or OCI
package settles at BuildStatusNone, so the build-success path that
re-stamps referencing Functions never runs for it — exactly the
digest-pinned-OCI-in-Git golden path. Keying the re-stamp on this
hash instead covers both shapes on one code path.
An EMPTY value means "not yet recorded" and must never read as
"changed": every package has an empty hash on the first reconcile
after this ships, and treating that as a change would rebuild the
whole cluster at once. The reconciler seeds it without rebuilding. | | | | `lastUpdateTimestamp` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | LastUpdateTimestamp will store the timestamp the package was last updated
metav1.Time is a wrapper around time.Time which supports correct marshaling to YAML and JSON.
https://github.com/kubernetes/apimachinery/blob/44bd77c24ef93cd3a5eb6fef64e514025d10d44e/pkg/apis/meta/v1/time.go#L26-L35 | | | | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | Conditions represent the latest observations of the package's state. | | | +#### ProvisionedConcurrencyConfig + + + +ProvisionedConcurrencyConfig opts this function into eager pre-warming of +specialized pods (RFC-0026). Presence is the on switch: nil (the default) +means the function uses the classic on-demand cold-start path. When non-nil, +the executor's provisioner keeps at least Target specialized pods warm and +published to the function's headless Service, exempt from the idle reaper. +Additive and backward compatible. + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `target` _integer_ | Target is the base number of warm specialized pods to maintain outside
any schedule window. Must be >= 1. Schedule windows may override this
(see Windows). Bounded by the namespace cap
(executor.provisionedConcurrency.maxPerFunction, default 20). | | Minimum: 1
| +| `windows` _[ProvisionedWindow](#provisionedwindow) array_ | Windows is an optional list of schedule windows that override Target
during specific time ranges (RFC-0026 PR 2). Empty in PR 1 — base Target
is always in effect. Each window: a cron start expression, a duration,
and a window-local target (0 means "un-warm" for the window's duration). | | MaxItems: 32
| + + +#### ProvisionedWindow + + + +ProvisionedWindow describes a schedule window that overrides the base +ProvisionedConcurrencyConfig.Target during a time range. The window is +active from the cron-triggered start for Duration; while active, the +effective target is the window's Target (overlapping windows take the max). + + + +_Appears in:_ +- [ProvisionedConcurrencyConfig](#provisionedconcurrencyconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name identifies this window within the function's
ProvisionedConcurrencyConfig.Windows list. Must be unique within the
list (listMapKey=name). | | MaxLength: 63
MinLength: 1
| +| `start` _string_ | Start is a cron expression (5-field, robfig/cron, same parser as
TimeTrigger) marking when each window instance opens. Prefix with
"CRON_TZ=" (e.g. "CRON_TZ=America/New_York 0 9 * * *") to
evaluate the schedule in a fixed timezone. Without a CRON_TZ
prefix, the schedule is evaluated in the executor process's local
timezone (UTC unless the deployment is configured otherwise) —
this is intended behavior, not a default that may change; specify
CRON_TZ explicitly if the window must not shift when the
executor's local timezone changes. | | MinLength: 1
| +| `duration` _string_ | Duration is how long each window instance stays open. Format is Go
time.ParseDuration (e.g. "12h", "30m"). Must be > 0. | | Pattern: `^[0-9]+(ns\|us\|µs\|ms\|s\|m\|h)$`
| +| `target` _integer_ | Target is the effective target while the window is open. 0 means
"un-warm" — provisioned pods are drained for the window's duration. | | Minimum: 0
| + + +#### RetryPolicy + + + +RetryPolicy is the async delivery retry policy: the attempt budget and the +exponential-backoff schedule between delivery attempts. All fields are +optional; a nil field takes the platform default. + + + +_Appears in:_ +- [InvocationConfig](#invocationconfig) +- [WorkflowBranchState](#workflowbranchstate) +- [WorkflowSpec](#workflowspec) +- [WorkflowState](#workflowstate) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `maxAttempts` _integer_ | MaxAttempts is the total number of delivery attempts before the invocation
is dead-lettered. nil means DefaultMaxAttempts. Must be >= 1 when set. | | | +| `backoffBase` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | BackoffBase is the delay before the first retry; it grows exponentially per
attempt up to BackoffCap. nil means the platform default. Must be >= 0. | | | +| `backoffCap` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | BackoffCap bounds the per-retry backoff. nil means the platform default.
Must be >= 0 and >= BackoffBase when both are set. | | | +| `jitter` _boolean_ | Jitter, when non-nil and false, disables the randomized jitter the
dispatcher otherwise adds to each backoff to avoid synchronized retries.
nil means the platform default (jitter enabled). | | | + + #### RouteConfig @@ -1086,6 +1400,68 @@ _Appears in:_ | --- | --- | --- | --- | | `namespace` _string_ | | | | | `name` _string_ | | | MaxLength: 63
Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
| +| `mountPath` _string_ | MountPath redirects this secret's file projection from the default
/secrets// to the given path, which is relative to
the /secrets root (RFC-0030 §4): generic pool pods share a fixed
volume set frozen at pool creation, so an arbitrary absolute path is
not materializable there, and the container executor applies the
same constraint for cross-executor consistency. Empty keeps today's
/ layout, so functions that do not set it are
unaffected. No two secrets on one function may RESOLVE to the same
directory (an explicit path colliding with another reference's
default counts): the final segment written is the object's data
key and keys are mutable after admission, so sharing a directory
would let one object's later-added key collide with the other's
file; the fetcher refuses such a write rather than truncating.
Honoured on every executor: poolmgr and newdeploy via the fetcher,
the container executor via a native projected volume. Not supported
on an allowedFunctionsPerContainer:infinite environment, whose pods
share one secrets tree across functions. | | | + + +#### StateConfig + + + +StateConfig declares a function's keyed-state keyspace and quotas +(RFC-0023). Presence of the enclosing FunctionSpec.State is the on switch — +there is no separate enabled flag, so the in-memory zero value and the +stored object never disagree (the same rationale as StreamingConfig). + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `keyspace` _string_ | Keyspace names the durable keyspace this function reads and writes.
Defaults to the function name; explicit so a function can be renamed
without orphaning its data. The charset deliberately excludes ':' and
'#' — ':' is a token-derivation info-string separator and '#' marks the
platform-reserved "#meta" quota-accounting sibling. | | MaxLength: 63
Pattern: `^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$`
| +| `defaultTTL` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | DefaultTTL, when set, is applied to writes that carry no explicit TTL.
Must be >= 0; zero (or nil) means keys do not expire by default. | | | +| `maxValueBytes` _integer_ | MaxValueBytes caps a single value's size. 0 means the platform default
(DefaultStateMaxValueBytes, 256KiB). Blobs belong in object storage. | | Minimum: 0
| +| `maxKeys` _integer_ | MaxKeys caps the number of live keys in the keyspace, enforced
atomically with each write (quota.tla S3). 0 means the platform
default (DefaultStateMaxKeys). | | Minimum: 0
| +| `backend` _string_ | Backend selects a named statestore driver for this keyspace. Accepted
and validated in v1 but not yet acted on: statesvc serves every
keyspace from its single configured driver (per-function backend
selection is a documented deferral). | | | +| `sticky` _[StickyConfig](#stickyconfig)_ | Sticky, when non-nil, opts the function into sticky routing: the
router consistent-hashes the declared request key onto the ready-pod
set so one key's requests land on one pod while the pod set is stable.
Best-effort (an optimization, never a correctness dependency — S6):
durable truth stays behind the state API. | | | + + +#### StickyConfig + + + +StickyConfig declares how the sticky routing key is extracted from a +request. Requests missing the key fall back to the default endpoint pick. + + + +_Appears in:_ +- [StateConfig](#stateconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `source` _[StickySource](#stickysource)_ | Source is where to look for the key. | | Enum: [header queryparam]
| +| `name` _string_ | Name is the header or query-parameter name holding the key,
e.g. "X-Session-Id". | | | + + +#### StickySource + +_Underlying type:_ _string_ + +StickySource selects where the router extracts the sticky routing key +from an incoming request. + +_Validation:_ +- Enum: [header queryparam] + +_Appears in:_ +- [StickyConfig](#stickyconfig) + +| Field | Description | +| --- | --- | +| `header` | | +| `queryparam` | | #### StrategyType @@ -1178,7 +1554,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `cron` _string_ | Cron schedule | | | -| `functionref` _[FunctionReference](#functionreference)_ | The reference to function | | | +| `functionref` _[FunctionReference](#functionreference)_ | The reference to function. Alias is read from the embedded
FunctionReference.Alias (RFC-0025) — TimeTriggerSpec has no field of
its own for it, so there is exactly one JSON path (spec.functionref.alias)
and one Go path (spec.Alias, promoted) for the concept, never two
competing ones. The timer publisher (a later RFC-0025 task) reads it
the same way timer.go:80 already reads the promoted spec.Name today. | | | | `method` _string_ | HTTP Method for trigger, ex : GET, POST, PUT, DELETE, HEAD (default: "POST") | POST | | | `subpath` _string_ | Subpath to trigger a specific route if function
internally supports routing, (default: "/") | / | | @@ -1221,6 +1597,26 @@ _Appears in:_ | `description` _string_ | Description is the human/agent-facing tool description surfaced in the MCP
tools/list response. Required. | | | | `inputSchema` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#json-v1-apiextensions-k8s-io)_ | InputSchema is the JSON Schema (draft 2020-12) for the tool's arguments,
surfaced verbatim as the MCP tool inputSchema. Stored as raw JSON so the
CRD does not constrain the schema shape. When empty the tool advertises an
open object schema (\{"type":"object"\}). | | | | `toolName` _string_ | ToolName overrides the advertised tool name. Defaults to
"-". Must match ^[a-zA-Z0-9_-]\{1,64\}$. | | Pattern: `^[a-zA-Z0-9_-]\{1,64\}$`
| +| `alias` _string_ | Alias, when set, targets a FunctionAlias by name (RFC-0025) instead of
the live Function: the MCP registry serves the tool from the alias's
currently-resolved FunctionVersion snapshot, and tools/call is proxied
to the ":" route rather than straight to the live Function.
Empty (the default) preserves today's behavior. Router/registry-side
resolution lands in a later RFC-0025 task — until then this field is
accepted but inert. | | MaxLength: 63
| + + +#### TopicRef + + + +TopicRef is a message-queue topic destination for an async invocation result. +Topics are namespace-scoped: the destination publishes to the source +function's namespace (RFC-0024 rule R6). + + + +_Appears in:_ +- [DestinationRef](#destinationref) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `messageQueueType` _[MessageQueueType](#messagequeuetype)_ | MessageQueueType selects the provider: "statestore" (the RFC-0027
built-in, no broker) now; broker types (e.g. kafka) with the egress phase. | | | +| `topic` _string_ | Topic is the topic the result envelope is published to. The schema bounds
mirror ValidateTopicName: a stream-safe charset excluding "/" so the
topic// mapping cannot alias across namespaces. | | MaxLength: 249
Pattern: `^[a-zA-Z0-9._-]+$`
| @@ -1238,3 +1634,449 @@ _Appears in:_ +#### VersioningConfig + + + +VersioningConfig opts a Function into RFC-0025 immutable version +snapshots and named aliases. + + + +_Appears in:_ +- [FunctionSpec](#functionspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `mode` _[VersioningMode](#versioningmode)_ | Mode auto (default) mints a version on every runtime-affecting
update once the referenced package build succeeds; manual mints
only on explicit `fission fn publish`. | auto | Enum: [auto manual]
| +| `retain` _integer_ | Retain bounds unaliased version history per function (GC floor 1).
Defaults to 10. Alias-referenced versions are never GC'd. | | Minimum: 1
| + + +#### VersioningMode + +_Underlying type:_ _string_ + +VersioningMode selects when versions are minted. + +_Validation:_ +- Enum: [auto manual] + +_Appears in:_ +- [VersioningConfig](#versioningconfig) + +| Field | Description | +| --- | --- | +| `auto` | | +| `manual` | | + + +#### Workflow + + + +Workflow declares a durable state machine whose task states are Fission +functions (RFC-0022). The engine executes WorkflowRuns against a snapshot +of this spec embedded in the run's event stream; editing a Workflow never +changes in-flight runs. + + + +_Appears in:_ +- [WorkflowList](#workflowlist) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `fission.io/v1` | | | +| `kind` _string_ | `Workflow` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[WorkflowSpec](#workflowspec)_ | | | | +| `status` _[WorkflowStatus](#workflowstatus)_ | | | | + + +#### WorkflowBranch + + + +WorkflowBranch is one concurrent sub-machine of a Parallel state (or +the iterator template of a Map state). + + + +_Appears in:_ +- [WorkflowState](#workflowstate) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `startAt` _string_ | | | | +| `states` _object (keys:string, values:[WorkflowBranchState](#workflowbranchstate))_ | MaxProperties=20 (vs 100 top-level) keeps the apiserver's CEL cost
estimate for doubly-nested rules under budget — the phase-1 lesson. | | MaxProperties: 20
MinProperties: 1
| + + +#### WorkflowBranchState + + + +WorkflowBranchState is WorkflowState minus the fan-out fields: nested +Parallel/Map is impossible BY TYPE, which is what keeps the CRD schema +non-recursive (controller-gen cannot render a self-referential type). + + + +_Appears in:_ +- [WorkflowBranch](#workflowbranch) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[WorkflowStateType](#workflowstatetype)_ | | | Enum: [Task Choice Parallel Map Wait Succeed Fail]
| +| `function` _[FunctionReference](#functionreference)_ | | | | +| `duration` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | | | | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | | | | +| `retry` _[RetryPolicy](#retrypolicy)_ | | | | +| `catch` _[WorkflowCatchRoute](#workflowcatchroute) array_ | | | | +| `choices` _[WorkflowChoiceRule](#workflowchoicerule) array_ | | | | +| `default` _string_ | | | | +| `inputPath` _string_ | | | | +| `resultPath` _string_ | | | | +| `outputPath` _string_ | | | | +| `next` _string_ | | | | +| `end` _boolean_ | | | | + + +#### WorkflowCatchRoute + + + +WorkflowCatchRoute routes a matched error class to a next state. + + + +_Appears in:_ +- [WorkflowBranchState](#workflowbranchstate) +- [WorkflowState](#workflowstate) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `errorType` _string_ | ErrorType matches a typed function error (\{"errorType": ...\} body),
a built-in class (Fission.PermanentError, Fission.FunctionError,
Fission.Timeout), or Fission.All (matches anything). | | | +| `next` _string_ | | | | +| `resultPath` _string_ | ResultPath, when set, merges the error object
(\{"errorType": ..., "cause": ...\}) into the flowing document at
this JSONPath, so the catch target still sees the business data
(e.g. retry a charge after a grace period). Unset keeps the
Step-Functions-parity default: the error object REPLACES the
document. | | | + + +#### WorkflowChoiceCondition + + + +WorkflowChoiceCondition is a leaf comparison against the state input. +Exactly one operator must be set. Numeric values use resource.Quantity +(CRDs cannot carry floats; Quantity accepts YAML numbers and strings). + + + +_Appears in:_ +- [WorkflowChoiceRule](#workflowchoicerule) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `variable` _string_ | Variable is a JSONPath into the state's (shaped) input. Required on
every leaf condition — enforced by the webhook, not the schema: this
struct is inline-embedded in WorkflowChoiceRule, and a
schema-required field would wrongly reject composite (and/or/not)
rules that carry no inline leaf. | | | +| `stringEquals` _string_ | | | | +| `numericEquals` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#quantity-resource-api)_ | | | | +| `numericGreaterThan` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#quantity-resource-api)_ | | | | +| `numericLessThan` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#quantity-resource-api)_ | | | | +| `booleanEquals` _boolean_ | | | | +| `isPresent` _boolean_ | | | | +| `isNull` _boolean_ | | | | + + +#### WorkflowChoiceRule + + + +WorkflowChoiceRule is one ordered rule of a Choice state: either a leaf +condition (inline) or exactly one of And/Or/Not over leaf conditions +(depth-1 composition; deeper nesting is additive later). + + + +_Appears in:_ +- [WorkflowBranchState](#workflowbranchstate) +- [WorkflowState](#workflowstate) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `variable` _string_ | Variable is a JSONPath into the state's (shaped) input. Required on
every leaf condition — enforced by the webhook, not the schema: this
struct is inline-embedded in WorkflowChoiceRule, and a
schema-required field would wrongly reject composite (and/or/not)
rules that carry no inline leaf. | | | +| `stringEquals` _string_ | | | | +| `numericEquals` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#quantity-resource-api)_ | | | | +| `numericGreaterThan` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#quantity-resource-api)_ | | | | +| `numericLessThan` _[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#quantity-resource-api)_ | | | | +| `booleanEquals` _boolean_ | | | | +| `isPresent` _boolean_ | | | | +| `isNull` _boolean_ | | | | +| `and` _[WorkflowChoiceCondition](#workflowchoicecondition) array_ | | | | +| `or` _[WorkflowChoiceCondition](#workflowchoicecondition) array_ | | | | +| `not` _[WorkflowChoiceCondition](#workflowchoicecondition)_ | | | | +| `next` _string_ | Next names the state to transition to when this rule matches. | | | + + +#### WorkflowList + + + +WorkflowList is a list of Workflows. + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `fission.io/v1` | | | +| `kind` _string_ | `WorkflowList` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `items` _[Workflow](#workflow) array_ | | | | + + +#### WorkflowRetentionPolicy + + + +WorkflowRetentionPolicy bounds retained history for finished runs. + + + +_Appears in:_ +- [WorkflowSpec](#workflowspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `maxCount` _integer_ | | | | +| `maxAge` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | | | | + + +#### WorkflowRun + + + +WorkflowRun is one execution of a Workflow. Full step history lives in +the statestore EventLog stream for the run, never in etcd; status carries +a bounded tail for kubectl visibility. + + + +_Appears in:_ +- [WorkflowRunList](#workflowrunlist) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `fission.io/v1` | | | +| `kind` _string_ | `WorkflowRun` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[WorkflowRunSpec](#workflowrunspec)_ | | | | +| `status` _[WorkflowRunStatus](#workflowrunstatus)_ | | | | + + +#### WorkflowRunEventSummary + + + +WorkflowRunEventSummary is one bounded-tail history entry for kubectl +visibility; the full history lives in the statestore EventLog. + + + +_Appears in:_ +- [WorkflowRunStatus](#workflowrunstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `seq` _integer_ | | | | +| `type` _string_ | | | | +| `state` _string_ | | | | +| `attempt` _integer_ | | | | +| `at` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | | | | +| `note` _string_ | | | | + + +#### WorkflowRunList + + + +WorkflowRunList is a list of WorkflowRuns. + + + + + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `fission.io/v1` | | | +| `kind` _string_ | `WorkflowRunList` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `items` _[WorkflowRun](#workflowrun) array_ | | | | + + +#### WorkflowRunPhase + +_Underlying type:_ _string_ + +WorkflowRunPhase is the run's coarse lifecycle phase. + +_Validation:_ +- Enum: [Pending Running Succeeded Failed Cancelled TimedOut] + +_Appears in:_ +- [WorkflowRunStatus](#workflowrunstatus) + +| Field | Description | +| --- | --- | +| `Pending` | | +| `Running` | | +| `Succeeded` | | +| `Failed` | | +| `Cancelled` | | +| `TimedOut` | | + + +#### WorkflowRunSpec + + + +WorkflowRunSpec identifies the Workflow to execute and the run's input. + + + +_Appears in:_ +- [WorkflowRun](#workflowrun) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `workflowRef` _string_ | WorkflowRef names the Workflow (same namespace) this run executes. | | | +| `workflowGeneration` _integer_ | WorkflowGeneration records (for observability) which Workflow
generation this run executes. It is NOT the pinning mechanism: the
authoritative spec is the snapshot the engine embeds in the run's
event stream at RunStarted; a Workflow edit or deletion mid-run can
neither fork nor strand a run. Set by the CLI; 0 means unknown. | | | +| `input` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#json-v1-apiextensions-k8s-io)_ | Input is the run's initial input document — ANY JSON value
(apiextensionsv1.JSON, not RawExtension: the RawExtension schema is
type=object and the apiserver would reject a bare string/array/
number). Webhook-capped at 256KiB (etcd objects cap at ~1.5MiB) —
pass larger inputs by reference. | | | + + +#### WorkflowRunStatus + + + +WorkflowRunStatus describes the observed state of a WorkflowRun. + + + +_Appears in:_ +- [WorkflowRun](#workflowrun) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `phase` _[WorkflowRunPhase](#workflowrunphase)_ | | | Enum: [Pending Running Succeeded Failed Cancelled TimedOut]
| +| `activeStates` _string array_ | ActiveStates lists the state names currently executing. | | | +| `startedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | | | | +| `finishedAt` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#time-v1-meta)_ | | | | +| `output` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#json-v1-apiextensions-k8s-io)_ | Output holds the final output inline up to the step-I/O spill
threshold — ANY JSON value (see Input for why apiextensionsv1.JSON);
larger outputs spill to the statestore KV and OutputRef points
there (the CLI dereferences). | | | +| `outputRef` _string_ | | | | +| `errorType` _string_ | ErrorType and Cause carry the terminal failure classification so
kubectl answers "why did it fail" without the history endpoint.
Cause is bounded; the full detail lives in the run history. | | | +| `cause` _string_ | | | MaxLength: 1024
| +| `recentEvents` _[WorkflowRunEventSummary](#workflowruneventsummary) array_ | RecentEvents is a bounded (<=20) tail; full history is in the
EventLog. | | | +| `observedGeneration` _integer_ | | | | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | | | | + + +#### WorkflowSpec + + + +WorkflowSpec is a state machine: states are data, logic lives in +functions. + + + +_Appears in:_ +- [Workflow](#workflow) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `startAt` _string_ | StartAt names the state execution begins at. | | | +| `states` _object (keys:string, values:[WorkflowState](#workflowstate))_ | States is the state machine graph, keyed by state name. The size
bound mirrors validation.MaxWorkflowStates and lets the apiserver's
CEL cost estimator bound rules on nested types. | | MaxProperties: 100
MinProperties: 1
| +| `defaultRetry` _[RetryPolicy](#retrypolicy)_ | DefaultRetry applies to Task states that do not set their own Retry. | | | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | Timeout bounds a whole run; expiry fails it with errorType
Fission.Timeout. Defaults to 24h (a mis-authored graph or endlessly
caught-and-retried loop must not hold an active run forever). | | | +| `historyRetention` _[WorkflowRetentionPolicy](#workflowretentionpolicy)_ | HistoryRetention bounds stored history (count + age) per finished run. | | | + + +#### WorkflowState + + + +WorkflowState is one state in the machine. Exactly the fields for its +Type may be set (enforced at admission). + + + +_Appears in:_ +- [WorkflowSpec](#workflowspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[WorkflowStateType](#workflowstatetype)_ | | | Enum: [Task Choice Parallel Map Wait Succeed Fail]
| +| `function` _[FunctionReference](#functionreference)_ | Function is the Task state's target. | | | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | Timeout bounds one attempt of a Task invocation. | | | +| `retry` _[RetryPolicy](#retrypolicy)_ | Retry overrides the workflow's DefaultRetry for this Task. | | | +| `catch` _[WorkflowCatchRoute](#workflowcatchroute) array_ | Catch routes a failed Task (retries exhausted, or a permanent error)
to another state by matched errorType; first match wins. | | | +| `choices` _[WorkflowChoiceRule](#workflowchoicerule) array_ | Choices are the Choice state's ordered rules; first match wins. | | | +| `default` _string_ | Default names the state a Choice falls through to when no rule
matches; without it, no-match fails the run (Fission.NoChoiceMatched). | | | +| `branches` _[WorkflowBranch](#workflowbranch) array_ | Branches are the Parallel state's concurrent sub-machines (or the
Map state's single iterator template). Branch states cannot nest
further fan-out — enforced by the bounded WorkflowBranchState type. | | MaxItems: 10
| +| `itemsPath` _string_ | ItemsPath selects the array a Map state iterates (one branch per
element, input = the element). | | | +| `duration` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#duration-v1-meta)_ | Duration is how long a Wait state pauses the run — durably: the
delay is a statestore Queue message, so a controller restart never
loses it (robfig/cron-style absolute schedules stay with the timer
subsystem; only durations here). | | | +| `maxConcurrency` _integer_ | MaxConcurrency throttles how many branches execute at once. Zero
means the engine default (10) — NOT unbounded: an unthrottled
large Map against poolmgr is a self-inflicted cold-start burst.
The default is applied by the engine, not the schema: a schema
default would stamp the field onto every state type. | | Minimum: 0
| +| `inputPath` _string_ | InputPath/ResultPath/OutputPath shape step I/O with JSONPath
(Step Functions semantics; dialect pinned in pkg/workflow/expr). | | | +| `resultPath` _string_ | | | | +| `outputPath` _string_ | | | | +| `next` _string_ | Next names the state to run after this one; exactly one of Next/End
is set on Task states (Succeed/Fail are implicitly terminal). | | | +| `end` _boolean_ | | | | + + +#### WorkflowStateType + +_Underlying type:_ _string_ + +WorkflowStateType enumerates the state kinds the engine executes. + +_Validation:_ +- Enum: [Task Choice Parallel Map Wait Succeed Fail] + +_Appears in:_ +- [WorkflowBranchState](#workflowbranchstate) +- [WorkflowState](#workflowstate) + +| Field | Description | +| --- | --- | +| `Task` | | +| `Choice` | | +| `Parallel` | | +| `Map` | | +| `Wait` | | +| `Succeed` | | +| `Fail` | | + + +#### WorkflowStatus + + + +WorkflowStatus describes the observed state of a Workflow. + + + +_Appears in:_ +- [Workflow](#workflow) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `observedGeneration` _integer_ | | | | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#condition-v1-meta) array_ | | | | + + diff --git a/content/en/docs/reference/fission-cli/fission.md b/content/en/docs/reference/fission-cli/fission.md index c5c31b5d..17a7dc6b 100644 --- a/content/en/docs/reference/fission-cli/fission.md +++ b/content/en/docs/reference/fission-cli/fission.md @@ -26,6 +26,7 @@ Fission: Fast and Simple Serverless Functions for Kubernetes ### SEE ALSO +* [fission alias](/docs/reference/fission-cli/fission_alias/) - Create, update and manage function aliases * [fission archive](/docs/reference/fission-cli/fission_archive/) - Manage archives stored with Fission Storage Service. * [fission canary](/docs/reference/fission-cli/fission_canary/) - Create, Update and manage canary configs * [fission check](/docs/reference/fission-cli/fission_check/) - Check the fission installation for potential problems diff --git a/content/en/docs/reference/fission-cli/fission_alias.md b/content/en/docs/reference/fission-cli/fission_alias.md new file mode 100644 index 00000000..1c43feab --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_alias.md @@ -0,0 +1,33 @@ +--- +title: fission alias +slug: fission_alias +url: /docs/reference/fission-cli/fission_alias/ +--- +## fission alias + +Create, update and manage function aliases + +### Options + +``` + -h, --help help for alias +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission](/docs/reference/fission-cli/fission/) - Serverless framework for Kubernetes +* [fission alias create](/docs/reference/fission-cli/fission_alias_create/) - Create a function alias +* [fission alias delete](/docs/reference/fission-cli/fission_alias_delete/) - Delete a function alias +* [fission alias get](/docs/reference/fission-cli/fission_alias_get/) - Get a function alias +* [fission alias list](/docs/reference/fission-cli/fission_alias_list/) - List function aliases +* [fission alias update](/docs/reference/fission-cli/fission_alias_update/) - Update a function alias +* [fission alias wait](/docs/reference/fission-cli/fission_alias_wait/) - Wait for a function alias to reach a status condition + diff --git a/content/en/docs/reference/fission-cli/fission_alias_create.md b/content/en/docs/reference/fission-cli/fission_alias_create.md new file mode 100644 index 00000000..059af972 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_alias_create.md @@ -0,0 +1,39 @@ +--- +title: fission alias create +slug: fission_alias_create +url: /docs/reference/fission-cli/fission_alias_create/ +--- +## fission alias create + +Create a function alias + +``` +fission alias create [flags] +``` + +### Options + +``` + --name string Name for the function alias + --function string Function this alias points at + --version string FunctionVersion name the alias resolves to (exactly one of --version/--package-digest) + --package-digest string Package digest (sha256:) the alias resolves to declaratively (exactly one of --version/--package-digest) + --weight int Percentage (0-100) of traffic served by the primary target; the remainder goes to --secondary-version. Requires --secondary-version; omit --weight entirely for 100% to the primary + --secondary-version string Secondary FunctionVersion name receiving the 100-minus-weight remainder of traffic + --wait Wait for the alias to resolve to its updated target (see --timeout) + --timeout duration Maximum time to wait for the condition before giving up (default 1m0s) + -h, --help help for create +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission alias](/docs/reference/fission-cli/fission_alias/) - Create, update and manage function aliases + diff --git a/content/en/docs/reference/fission-cli/fission_alias_delete.md b/content/en/docs/reference/fission-cli/fission_alias_delete.md new file mode 100644 index 00000000..b29b6621 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_alias_delete.md @@ -0,0 +1,33 @@ +--- +title: fission alias delete +slug: fission_alias_delete +url: /docs/reference/fission-cli/fission_alias_delete/ +--- +## fission alias delete + +Delete a function alias + +``` +fission alias delete [flags] +``` + +### Options + +``` + --name string Name for the function alias + --ignorenotfound Treat "resource not found" as a successful delete. + -h, --help help for delete +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission alias](/docs/reference/fission-cli/fission_alias/) - Create, update and manage function aliases + diff --git a/content/en/docs/reference/fission-cli/fission_alias_get.md b/content/en/docs/reference/fission-cli/fission_alias_get.md new file mode 100644 index 00000000..a0a2faf5 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_alias_get.md @@ -0,0 +1,33 @@ +--- +title: fission alias get +slug: fission_alias_get +url: /docs/reference/fission-cli/fission_alias_get/ +--- +## fission alias get + +Get a function alias + +``` +fission alias get [flags] +``` + +### Options + +``` + --name string Name for the function alias + -o, --output string -o |:|: Output format: wide, json or yaml (default: table) + -h, --help help for get +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission alias](/docs/reference/fission-cli/fission_alias/) - Create, update and manage function aliases + diff --git a/content/en/docs/reference/fission-cli/fission_alias_list.md b/content/en/docs/reference/fission-cli/fission_alias_list.md new file mode 100644 index 00000000..743b4abc --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_alias_list.md @@ -0,0 +1,38 @@ +--- +title: fission alias list +slug: fission_alias_list +url: /docs/reference/fission-cli/fission_alias_list/ +--- +## fission alias list + +List function aliases + +### Synopsis + +List all function aliases in a namespace if specified, else, list function aliases across all namespaces + +``` +fission alias list [flags] +``` + +### Options + +``` + --function string Function this alias points at + -A, --all-namespaces -A |:|: Fetch resources from all namespaces + -o, --output string -o |:|: Output format: wide, json or yaml (default: table) + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission alias](/docs/reference/fission-cli/fission_alias/) - Create, update and manage function aliases + diff --git a/content/en/docs/reference/fission-cli/fission_alias_update.md b/content/en/docs/reference/fission-cli/fission_alias_update.md new file mode 100644 index 00000000..860f4c95 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_alias_update.md @@ -0,0 +1,43 @@ +--- +title: fission alias update +slug: fission_alias_update +url: /docs/reference/fission-cli/fission_alias_update/ +--- +## fission alias update + +Update a function alias + +### Synopsis + +Update a FunctionAlias's target (--version or --package-digest, mutually exclusive) or traffic split (--weight/--secondary-version, or --clear-weight to drop it). To repoint back to a previously resolved target using the alias's own Status.History instead of naming a version by hand, see `fission fn rollback` instead. + +``` +fission alias update [flags] +``` + +### Options + +``` + --name string Name for the function alias + --version string FunctionVersion name the alias resolves to (exactly one of --version/--package-digest) + --package-digest string Package digest (sha256:) the alias resolves to declaratively (exactly one of --version/--package-digest) + --weight int Percentage (0-100) of traffic served by the primary target; the remainder goes to --secondary-version. Requires --secondary-version; omit --weight entirely for 100% to the primary + --secondary-version string Secondary FunctionVersion name receiving the 100-minus-weight remainder of traffic + --clear-weight Clear the weighted split (drop --weight and --secondary-version) + --wait Wait for the alias to resolve to its updated target (see --timeout) + --timeout duration Maximum time to wait for the condition before giving up (default 1m0s) + -h, --help help for update +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission alias](/docs/reference/fission-cli/fission_alias/) - Create, update and manage function aliases + diff --git a/content/en/docs/reference/fission-cli/fission_alias_wait.md b/content/en/docs/reference/fission-cli/fission_alias_wait.md new file mode 100644 index 00000000..28a08c1d --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_alias_wait.md @@ -0,0 +1,38 @@ +--- +title: fission alias wait +slug: fission_alias_wait +url: /docs/reference/fission-cli/fission_alias_wait/ +--- +## fission alias wait + +Wait for a function alias to reach a status condition + +### Synopsis + +Wait for a FunctionAlias to reach a status condition, e.g. `fission alias wait --name prod --for condition=Resolved` after an `alias create`/`alias update`/`fn rollback`, so a caller (CI, a script) can tell when the alias resolver has actually converged on the new target rather than racing it. FunctionAlias's only condition type is Resolved. + +``` +fission alias wait [flags] +``` + +### Options + +``` + --name string Name for the function alias + --for string Condition to wait for, e.g. condition=Ready or condition=Ready=False + --timeout duration Maximum time to wait for the condition before giving up (default 1m0s) + -h, --help help for wait +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission alias](/docs/reference/fission-cli/fission_alias/) - Create, update and manage function aliases + diff --git a/content/en/docs/reference/fission-cli/fission_canary_create.md b/content/en/docs/reference/fission-cli/fission_canary_create.md index c03babd7..dfb39c26 100644 --- a/content/en/docs/reference/fission-cli/fission_canary_create.md +++ b/content/en/docs/reference/fission-cli/fission_canary_create.md @@ -7,6 +7,32 @@ url: /docs/reference/fission-cli/fission_canary_create/ Create a canary config +### Synopsis + +Create a canary config that gradually shifts HTTP traffic from an old +target to a new one, watching the new target's Prometheus error rate and +rolling back automatically if it crosses --threshold. + +Two modes, selected by what --httptrigger references: + + function-weights mode (classic): the trigger's function reference type is + "function-weights" and --newfn/--oldfn name two FUNCTIONS already present + in its weights map. The controller steps HTTPTrigger.FunctionWeights. + + alias mode (RFC-0025): the trigger references a FunctionAlias (created via + 'fission alias create'). --newfn/--oldfn then name two FunctionVersions + (see 'fission fn versions') of the alias's function — not functions. The + controller steps the FunctionAlias's Weight/SecondaryVersion instead, + leaving the alias's primary Version pinned at --oldfn until the rollout + either promotes (repoints the alias at --newfn) or rolls back. + +Example (alias mode): + + fission alias create --function orders --name prod --version orders-v3 + fission canary create --name orders-canary --httptrigger prod-route \ + --newfn orders-v4 --oldfn orders-v3 --increment-step 20 --increment-interval 2m --failure-threshold 10 + + ``` fission canary create [flags] ``` diff --git a/content/en/docs/reference/fission-cli/fission_environment.md b/content/en/docs/reference/fission-cli/fission_environment.md index d2718721..6ff76766 100644 --- a/content/en/docs/reference/fission-cli/fission_environment.md +++ b/content/en/docs/reference/fission-cli/fission_environment.md @@ -27,6 +27,7 @@ Create, update and manage environments * [fission environment create](/docs/reference/fission-cli/fission_environment_create/) - Create an environment * [fission environment delete](/docs/reference/fission-cli/fission_environment_delete/) - Delete an environment * [fission environment get](/docs/reference/fission-cli/fission_environment_get/) - Get environment details +* [fission environment impact](/docs/reference/fission-cli/fission_environment_impact/) - Show functions and aliases affected by this environment, and their env-drift status * [fission environment list](/docs/reference/fission-cli/fission_environment_list/) - List environments * [fission environment pods](/docs/reference/fission-cli/fission_environment_pods/) - List pods currently maintained by an environment * [fission environment update](/docs/reference/fission-cli/fission_environment_update/) - Update an environment diff --git a/content/en/docs/reference/fission-cli/fission_environment_impact.md b/content/en/docs/reference/fission-cli/fission_environment_impact.md new file mode 100644 index 00000000..53b71b7a --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_environment_impact.md @@ -0,0 +1,37 @@ +--- +title: fission environment impact +slug: fission_environment_impact +url: /docs/reference/fission-cli/fission_environment_impact/ +--- +## fission environment impact + +Show functions and aliases affected by this environment, and their env-drift status + +### Synopsis + +List every function that references this environment and, for each of its aliases, whether the alias's resolved version was published under an environment generation the live environment has since moved past (RFC-0025 env drift) — the batch, ahead-of-an-update view of `fission fn describe`'s per-alias EnvDrift condition. + +``` +fission environment impact [flags] +``` + +### Options + +``` + --name string Environment name + -o, --output string -o |:|: Output format: wide, json or yaml (default: table) + -h, --help help for impact +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission environment](/docs/reference/fission-cli/fission_environment/) - Create, update and manage environments + diff --git a/content/en/docs/reference/fission-cli/fission_function.md b/content/en/docs/reference/fission-cli/fission_function.md index 1b447ecb..16098b82 100644 --- a/content/en/docs/reference/fission-cli/fission_function.md +++ b/content/en/docs/reference/fission-cli/fission_function.md @@ -28,16 +28,21 @@ Create, update and manage functions * [fission function delete](/docs/reference/fission-cli/fission_function_delete/) - Delete a function * [fission function describe](/docs/reference/fission-cli/fission_function_describe/) - Describe a function's health in one view (summary, conditions, build, pods) * [fission function dlq](/docs/reference/fission-cli/fission_function_dlq/) - Inspect and manage the async invocation dead-letter queue +* [fission function gc-versions](/docs/reference/fission-cli/fission_function_gc-versions/) - Sweep a function's old FunctionVersions down to its retain floor (RFC-0025) * [fission function get](/docs/reference/fission-cli/fission_function_get/) - Get function source code * [fission function getmeta](/docs/reference/fission-cli/fission_function_getmeta/) - Get function metadata * [fission function list](/docs/reference/fission-cli/fission_function_list/) - List functions * [fission function log](/docs/reference/fission-cli/fission_function_log/) - Display function logs * [fission function pods](/docs/reference/fission-cli/fission_function_pods/) - List pods currently used by a function +* [fission function publish](/docs/reference/fission-cli/fission_function_publish/) - Publish the function's current spec as an immutable version +* [fission function rollback](/docs/reference/fission-cli/fission_function_rollback/) - Roll a function alias back to a previous FunctionVersion (RFC-0025) * [fission function run-container](/docs/reference/fission-cli/fission_function_run-container/) - Alpha: Run a container image as a function * [fission function run-local](/docs/reference/fission-cli/fission_function_run-local/) - Alpha: Run a function locally in Docker (RFC-0018) +* [fission function state](/docs/reference/fission-cli/fission_function_state/) - Inspect and manage a function's keyed state (RFC-0023) * [fission function test](/docs/reference/fission-cli/fission_function_test/) - Test a function * [fission function tools](/docs/reference/fission-cli/fission_function_tools/) - List functions exposed as MCP (Model Context Protocol) tools * [fission function update](/docs/reference/fission-cli/fission_function_update/) - Update a function * [fission function update-container](/docs/reference/fission-cli/fission_function_update-container/) - Alpha: Update a function running a container +* [fission function versions](/docs/reference/fission-cli/fission_function_versions/) - List a function's published versions * [fission function wait](/docs/reference/fission-cli/fission_function_wait/) - Wait for a function to reach a status condition diff --git a/content/en/docs/reference/fission-cli/fission_function_create.md b/content/en/docs/reference/fission-cli/fission_function_create.md index 41b9fa23..c1b41100 100644 --- a/content/en/docs/reference/fission-cli/fission_function_create.md +++ b/content/en/docs/reference/fission-cli/fission_function_create.md @@ -14,57 +14,71 @@ fission function create [flags] ### Options ``` - --name string Function name - --env string Environment name for function - --entrypoint string --entry |:|: Entry point for environment v2 to load with - --pkgname string --pkg |:|: Name of the existing package (--deploy and --src and --env will be ignored), should be in the same namespace as the function - --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") - --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. - --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. - --specializationtimeout int --st |:|: Timeout for executor to wait for function pod creation (default 120) - --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) - --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) - --concurrency poolmgr --con |:|: Maximum number of pods specialized concurrently to serve requests (Only valid for executortype; poolmgr) (default 500) - --requestsperpod poolmgr --rpp |:|: Maximum number of concurrent requests that can be served by a specialized pod (Only valid for executortype; poolmgr) (default 1) - --streaming Enable streaming (SSE/chunked/WebSocket) responses for this function; the response is flushed incrementally and not cut by the function timeout - --streamingprotocol string Streaming protocol when --streaming is set; one of 'auto', 'sse', 'chunked', 'websocket' (default "auto") - --streamingidletimeout int Idle timeout (seconds) for a streaming response before it is aborted; reset on each chunk (default 60) - --streamingmaxduration int Hard ceiling (seconds) on total streaming response lifetime; 0 means no ceiling (the idle timeout governs) - --expose-as-mcp Advertise this function as a Model Context Protocol (MCP) tool on the MCP server - --tool-description string Agent-facing tool description (required with --expose-as-mcp) - --tool-input-schema string Path to a JSON Schema file describing the tool's arguments; advertised verbatim as the MCP tool inputSchema - --tool-name string Override the advertised MCP tool name (defaults to -) - --async-retry-max-attempts int Async delivery attempt budget before dead-lettering (RFC-0024) - --async-max-age duration Max time an async invocation may wait for successful delivery before it is dead-lettered (RFC-0024) - --async-on-success string Same-namespace function to invoke with the result after a successful async delivery (RFC-0024); empty clears it - --async-on-failure string Same-namespace function to invoke with the result after a permanent async failure (RFC-0024); empty clears it - --async-on-success-topic string Statestore topic to publish the result envelope to after a successful async delivery (RFC-0027); empty clears it - --async-on-failure-topic string Statestore topic to publish the result envelope to after a permanent async failure (RFC-0027); empty clears it - --onceonly poolmgr --yolo |:|: Specifies if specialized pod will serve exactly one request in its lifetime (Only valid for executortype; poolmgr) - --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" - --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" - --retainpods int Number of pods to retain after pods specialization. - --code string URL or local path for single file source code - --sourcearchive stringArray --source |:|: --src |:|: URL or local paths for source archive - --deployarchive stringArray --deploy |:|: URL or local paths for binary archive - --srcchecksum string SHA256 checksum of source archive when providing URL - --deploychecksum string SHA256 checksum of deploy archive when providing URL - --insecure Skip generating SHA256 checksum for file integrity validation - --oci string Pre-built OCI image reference containing the deployment code (registry/repo:tag[@digest]) - --buildcmd string Package build command for builder to run with - --url string URL pattern (supports {var} and {var:regexp} path templates) [DEPRECATED for 'fn create', use 'route create' instead] - --prefix string Prefix with which functions are exposed. NOTE: Prefix takes precedence over URL/RelativeURL [DEPRECATED for 'fn create', use 'route create' instead] - --method stringArray HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method: --method GET and for multiple methods --method GET --method POST. [DEPRECATED for 'fn create', use 'route create' instead] (default [GET]) - --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) - --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) - --minmemory int Minimum memory to be assigned to pod (In megabyte) - --maxmemory int Maximum memory to be assigned to pod (In megabyte) - --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) - --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) - --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) - --spec Save to the spec directory instead of creating on cluster - --dry View the generated specs - -h, --help help for create + --name string Function name + --env string Environment name for function + --entrypoint string --entry |:|: Entry point for environment v2 to load with + --pkgname string --pkg |:|: Name of the existing package (--deploy and --src and --env will be ignored), should be in the same namespace as the function + --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") + --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. + --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. + -e, --env-var stringArray -e |:|: Per-function environment variable as KEY=VALUE; repeatable. On fn update the provided list replaces the function's env vars. (--env keeps meaning the Environment name.) + --env-from-secret stringArray Project a same-namespace Secret into the function's environment: 'name' for the whole object, 'name/key' for one key (variable named after the key), 'name/key:ENV' to rename it; repeatable. On fn update the provided list replaces the previous one. + --env-from-configmap stringArray Project a same-namespace ConfigMap into the function's environment: 'name' for the whole object, 'name/key' for one key (variable named after the key), 'name/key:ENV' to rename it; repeatable. On fn update the provided list replaces the previous one. + --specializationtimeout int --st |:|: Timeout for executor to wait for function pod creation (default 120) + --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) + --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) + --concurrency poolmgr --con |:|: Maximum number of pods specialized concurrently to serve requests (Only valid for executortype; poolmgr) (default 500) + --requestsperpod poolmgr --rpp |:|: Maximum number of concurrent requests that can be served by a specialized pod (Only valid for executortype; poolmgr) (default 1) + --streaming Enable streaming (SSE/chunked/WebSocket) responses for this function; the response is flushed incrementally and not cut by the function timeout + --streamingprotocol string Streaming protocol when --streaming is set; one of 'auto', 'sse', 'chunked', 'websocket' (default "auto") + --streamingidletimeout int Idle timeout (seconds) for a streaming response before it is aborted; reset on each chunk (default 60) + --streamingmaxduration int Hard ceiling (seconds) on total streaming response lifetime; 0 means no ceiling (the idle timeout governs) + --expose-as-mcp Advertise this function as a Model Context Protocol (MCP) tool on the MCP server + --tool-description string Agent-facing tool description (required with --expose-as-mcp) + --tool-input-schema string Path to a JSON Schema file describing the tool's arguments; advertised verbatim as the MCP tool inputSchema + --tool-name string Override the advertised MCP tool name (defaults to -) + --state Opt the function into the keyed-state API + --state-keyspace string State keyspace name (defaults to the function name; explicit so a rename keeps the data) + --state-max-keys int Max live keys in the keyspace (0 = platform default) + --state-max-value-bytes int Max size of one state value in bytes (0 = platform default) + --state-ttl duration Default TTL applied to state writes without an explicit TTL (0 = keys do not expire) + --state-sticky-source string Sticky routing key source: header or queryparam + --state-sticky-name string Header or query-parameter name holding the sticky routing key + --async-retry-max-attempts int Async delivery attempt budget before dead-lettering + --async-max-age duration Max time an async invocation may wait for successful delivery before it is dead-lettered + --async-on-success string Same-namespace function to invoke with the result after a successful async delivery; empty clears it + --async-on-failure string Same-namespace function to invoke with the result after a permanent async failure; empty clears it + --async-on-success-topic string Statestore topic to publish the result envelope to after a successful async delivery; empty clears it + --async-on-failure-topic string Statestore topic to publish the result envelope to after a permanent async failure; empty clears it + --onceonly poolmgr --yolo |:|: Specifies if specialized pod will serve exactly one request in its lifetime (Only valid for executortype; poolmgr) + --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" + --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" + --retainpods int Number of pods to retain after pods specialization. + --provisioned-concurrency int Number of warm specialized pods to maintain eagerly (poolmgr only). 0 (default)=no provisioned concurrency + --versioning fission fn publish Opt the function into immutable version snapshots and named aliases; one of 'auto' (mint a version on every runtime-affecting update), 'manual' (mint only on fission fn publish), or 'off' (disable, update only) + --retain-versions int Number of unaliased versions to keep per function before older ones are garbage collected (requires --versioning auto|manual, or an existing versioning config); disambiguates from --retainpods, which retains specialized pods rather than function versions + --provisioned-schedule stringArray name=;start=;duration=<10h(time.Duration)>;target= + --code string URL or local path for single file source code + --sourcearchive stringArray --source |:|: --src |:|: URL or local paths for source archive + --deployarchive stringArray --deploy |:|: URL or local paths for binary archive + --srcchecksum string SHA256 checksum of source archive when providing URL + --deploychecksum string SHA256 checksum of deploy archive when providing URL + --insecure Skip generating SHA256 checksum for file integrity validation + --oci string Pre-built OCI image reference containing the deployment code (registry/repo:tag[@digest]) + --buildcmd string Package build command for builder to run with + --url string URL pattern (supports {var} and {var:regexp} path templates) [DEPRECATED for 'fn create', use 'route create' instead] + --prefix string Prefix with which functions are exposed. NOTE: Prefix takes precedence over URL/RelativeURL [DEPRECATED for 'fn create', use 'route create' instead] + --method stringArray HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method: --method GET and for multiple methods --method GET --method POST. [DEPRECATED for 'fn create', use 'route create' instead] (default [GET]) + --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) + --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) + --minmemory int Minimum memory to be assigned to pod (In megabyte) + --maxmemory int Maximum memory to be assigned to pod (In megabyte) + --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) + --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) + --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) + --spec Save to the spec directory instead of creating on cluster + --dry View the generated specs + -h, --help help for create ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_describe.md b/content/en/docs/reference/fission-cli/fission_function_describe.md index 1386f957..0e06cbf4 100644 --- a/content/en/docs/reference/fission-cli/fission_function_describe.md +++ b/content/en/docs/reference/fission-cli/fission_function_describe.md @@ -14,8 +14,9 @@ fission function describe [flags] ### Options ``` - --name string Function name - -h, --help help for describe + --name string Function name + --version string Describe a specific pinned FunctionVersion's snapshot instead of the live function + -h, --help help for describe ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq_list.md b/content/en/docs/reference/fission-cli/fission_function_dlq_list.md index 03267754..fdb9ddfc 100644 --- a/content/en/docs/reference/fission-cli/fission_function_dlq_list.md +++ b/content/en/docs/reference/fission-cli/fission_function_dlq_list.md @@ -17,7 +17,7 @@ fission function dlq list [flags] -n, --namespace string -n |:|: If present, the namespace scope for this CLI request --limit int Maximum number of dead-lettered invocations to list (default 100) -o, --output string -o |:|: Output format: wide, json or yaml (default: table) - --queue string Dead-letter queue to operate on: empty for async invocations, or an RFC-0027 broker egress queue (mq-egress-, e.g. mq-egress-kafka) + --queue string Dead-letter queue to operate on: empty for async invocations, or a broker egress queue (mq-egress-, e.g. mq-egress-kafka) -h, --help help for list ``` diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq_purge.md b/content/en/docs/reference/fission-cli/fission_function_dlq_purge.md index 6be65eca..5adfd32e 100644 --- a/content/en/docs/reference/fission-cli/fission_function_dlq_purge.md +++ b/content/en/docs/reference/fission-cli/fission_function_dlq_purge.md @@ -14,7 +14,7 @@ fission function dlq purge [flags] ### Options ``` - --queue string Dead-letter queue to operate on: empty for async invocations, or an RFC-0027 broker egress queue (mq-egress-, e.g. mq-egress-kafka) + --queue string Dead-letter queue to operate on: empty for async invocations, or a broker egress queue (mq-egress-, e.g. mq-egress-kafka) -h, --help help for purge ``` diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq_redrive.md b/content/en/docs/reference/fission-cli/fission_function_dlq_redrive.md index 34912078..9efede5f 100644 --- a/content/en/docs/reference/fission-cli/fission_function_dlq_redrive.md +++ b/content/en/docs/reference/fission-cli/fission_function_dlq_redrive.md @@ -16,7 +16,7 @@ fission function dlq redrive [flags] ``` --id string Durable invocation id of a dead-lettered async invocation --all Apply to every dead-lettered invocation - --queue string Dead-letter queue to operate on: empty for async invocations, or an RFC-0027 broker egress queue (mq-egress-, e.g. mq-egress-kafka) + --queue string Dead-letter queue to operate on: empty for async invocations, or a broker egress queue (mq-egress-, e.g. mq-egress-kafka) -h, --help help for redrive ``` diff --git a/content/en/docs/reference/fission-cli/fission_function_dlq_show.md b/content/en/docs/reference/fission-cli/fission_function_dlq_show.md index 5f60af20..10816297 100644 --- a/content/en/docs/reference/fission-cli/fission_function_dlq_show.md +++ b/content/en/docs/reference/fission-cli/fission_function_dlq_show.md @@ -15,7 +15,7 @@ fission function dlq show [flags] ``` --id string Durable invocation id of a dead-lettered async invocation - --queue string Dead-letter queue to operate on: empty for async invocations, or an RFC-0027 broker egress queue (mq-egress-, e.g. mq-egress-kafka) + --queue string Dead-letter queue to operate on: empty for async invocations, or a broker egress queue (mq-egress-, e.g. mq-egress-kafka) -h, --help help for show ``` diff --git a/content/en/docs/reference/fission-cli/fission_function_gc-versions.md b/content/en/docs/reference/fission-cli/fission_function_gc-versions.md new file mode 100644 index 00000000..d46189f3 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_gc-versions.md @@ -0,0 +1,37 @@ +--- +title: fission function gc-versions +slug: fission_function_gc-versions +url: /docs/reference/fission-cli/fission_function_gc-versions/ +--- +## fission function gc-versions + +Sweep a function's old FunctionVersions down to its retain floor (RFC-0025) + +### Synopsis + +Runs one on-demand retention-GC sweep, the same engine the buildermgr-hosted controller runs automatically. Never deletes a version referenced by any FunctionAlias, or the newest/only version, however low --keep is set. + +``` +fission function gc-versions [flags] +``` + +### Options + +``` + --name string Function name + --keep int Override the retain count for this sweep (default: the function's Spec.Versioning.Retain, or 10) + -h, --help help for gc-versions +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function](/docs/reference/fission-cli/fission_function/) - Create, update and manage functions + diff --git a/content/en/docs/reference/fission-cli/fission_function_get.md b/content/en/docs/reference/fission-cli/fission_function_get.md index 90684649..9d8dad7f 100644 --- a/content/en/docs/reference/fission-cli/fission_function_get.md +++ b/content/en/docs/reference/fission-cli/fission_function_get.md @@ -14,8 +14,9 @@ fission function get [flags] ### Options ``` - --name string Function name - -h, --help help for get + --name string Function name + --version string Get a specific pinned FunctionVersion's snapshot source instead of the live function + -h, --help help for get ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_log.md b/content/en/docs/reference/fission-cli/fission_function_log.md index 954c53ca..e95e5ff9 100644 --- a/content/en/docs/reference/fission-cli/fission_function_log.md +++ b/content/en/docs/reference/fission-cli/fission_function_log.md @@ -26,6 +26,8 @@ fission function log [flags] --request-id string Filter logs to a single invocation by its X-Fission-Request-ID (loki dbtype) --trace-id string Filter logs by trace id (loki dbtype) --level string Filter logs by level, e.g. error (loki dbtype) + --alias string Show logs for a specific alias's (e.g. prod) resolved version instead of the live function; mutually exclusive with --version; kubernetes dbtype only + --version string Show logs for a specific pinned FunctionVersion instead of the live function; mutually exclusive with --alias; kubernetes dbtype only -h, --help help for log ``` diff --git a/content/en/docs/reference/fission-cli/fission_function_pods.md b/content/en/docs/reference/fission-cli/fission_function_pods.md index 785c9164..0ed510ba 100644 --- a/content/en/docs/reference/fission-cli/fission_function_pods.md +++ b/content/en/docs/reference/fission-cli/fission_function_pods.md @@ -18,8 +18,10 @@ fission function pods [flags] ### Options ``` - --name string Function name - -h, --help help for pods + --name string Function name + --alias string List only pods for a specific alias's (e.g. prod) resolved version; mutually exclusive with --version + --version string List only pods for a specific pinned FunctionVersion; mutually exclusive with --alias + -h, --help help for pods ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_publish.md b/content/en/docs/reference/fission-cli/fission_function_publish.md new file mode 100644 index 00000000..eeb8952c --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_publish.md @@ -0,0 +1,40 @@ +--- +title: fission function publish +slug: fission_function_publish +url: /docs/reference/fission-cli/fission_function_publish/ +--- +## fission function publish + +Publish the function's current spec as an immutable version + +### Synopsis + +Publish the function's current spec as an immutable FunctionVersion snapshot (RFC-0025); idempotent -- called again with an unchanged spec and package digest, it returns the existing newest version instead of minting a duplicate. --output/-o accepts: (default table) prints "created " or "unchanged "; "name" prints only the bare FunctionVersion name, one line, for scripting (mirrors kubectl's -o name); "json"/"yaml" marshal the full FunctionVersion object; "wide" renders the same as the default table (no extra columns). + +``` +fission function publish [flags] +``` + +### Options + +``` + --name string Function name + --description string Human-readable description recorded on the minted FunctionVersion + --wait Wait for the function's referenced package build to finish before publishing (see --timeout) + --timeout duration Maximum time to wait for the condition before giving up (default 1m0s) + -o, --output string -o |:|: Output format: wide, json or yaml (default: table) + -h, --help help for publish +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function](/docs/reference/fission-cli/fission_function/) - Create, update and manage functions + diff --git a/content/en/docs/reference/fission-cli/fission_function_rollback.md b/content/en/docs/reference/fission-cli/fission_function_rollback.md new file mode 100644 index 00000000..67db9a8d --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_rollback.md @@ -0,0 +1,41 @@ +--- +title: fission function rollback +slug: fission_function_rollback +url: /docs/reference/fission-cli/fission_function_rollback/ +--- +## fission function rollback + +Roll a function alias back to a previous FunctionVersion (RFC-0025) + +### Synopsis + +Repoint a FunctionAlias at a previously resolved FunctionVersion: by default the alias's previous target (Status.History's last entry), or an explicit --to version. Always a full repoint — clears Weight/SecondaryVersion, so a rollback issued mid-canary stops the traffic split rather than only rolling back the primary target. Refuses to touch an alias managed by `fission spec` (Git) unless --detach. For a one-off repoint to a version you already know, see `fission alias update --version --wait` instead. + +``` +fission function rollback [flags] +``` + +### Options + +``` + --name string Function name + --alias string FunctionAlias to roll back + --to string Explicit FunctionVersion name to roll back to (default: the alias's previous target, Status.History's last entry) + --detach fission spec Strip fission spec (Git) ownership annotations from the alias so a future `spec apply` does not revert the rollback + --wait Wait for the alias to resolve to the rollback target (see --timeout) + --timeout duration Maximum time to wait for the condition before giving up (default 1m0s) + -h, --help help for rollback +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function](/docs/reference/fission-cli/fission_function/) - Create, update and manage functions + diff --git a/content/en/docs/reference/fission-cli/fission_function_run-container.md b/content/en/docs/reference/fission-cli/fission_function_run-container.md index 891a61f1..61e5fe34 100644 --- a/content/en/docs/reference/fission-cli/fission_function_run-container.md +++ b/content/en/docs/reference/fission-cli/fission_function_run-container.md @@ -14,29 +14,32 @@ fission function run-container [flags] ### Options ``` - --name string Function name - --image string Name of the Docker image to be deployed as a function. Valid only when executorType is set to 'container' - --port int Port where the application is running (default 8888) - --command string Command to be passed to the container. If not specified , the ones defined in the image are used - --args string Args to be passed to the command on the container. If not specified , the ones defined in the image are used - --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. - --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. - --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) - --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) - --graceperiod int Grace time (in seconds) for pod to perform connection draining before termination (only non-negative values considered) - --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" - --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" - --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) - --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) - --minmemory int Minimum memory to be assigned to pod (In megabyte) - --maxmemory int Maximum memory to be assigned to pod (In megabyte) - --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) - --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) - --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) - --imagepullsecret string Secret for Kubernetes to pull an image from a private registry - --spec Save to the spec directory instead of creating on cluster - --dry View the generated specs - -h, --help help for run-container + --name string Function name + --image string Name of the Docker image to be deployed as a function. Valid only when executorType is set to 'container' + --port int Port where the application is running (default 8888) + --command string Command to be passed to the container. If not specified , the ones defined in the image are used + --args string Args to be passed to the command on the container. If not specified , the ones defined in the image are used + --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. + --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. + -e, --env-var stringArray -e |:|: Per-function environment variable as KEY=VALUE; repeatable. On fn update the provided list replaces the function's env vars. (--env keeps meaning the Environment name.) + --env-from-secret stringArray Project a same-namespace Secret into the function's environment: 'name' for the whole object, 'name/key' for one key (variable named after the key), 'name/key:ENV' to rename it; repeatable. On fn update the provided list replaces the previous one. + --env-from-configmap stringArray Project a same-namespace ConfigMap into the function's environment: 'name' for the whole object, 'name/key' for one key (variable named after the key), 'name/key:ENV' to rename it; repeatable. On fn update the provided list replaces the previous one. + --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) + --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) + --graceperiod int Grace time (in seconds) for pod to perform connection draining before termination (only non-negative values considered) + --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" + --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" + --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) + --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) + --minmemory int Minimum memory to be assigned to pod (In megabyte) + --maxmemory int Maximum memory to be assigned to pod (In megabyte) + --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) + --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) + --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) + --imagepullsecret string Secret for Kubernetes to pull an image from a private registry + --spec Save to the spec directory instead of creating on cluster + --dry View the generated specs + -h, --help help for run-container ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_run-local.md b/content/en/docs/reference/fission-cli/fission_function_run-local.md index 98db01b6..fa19b739 100644 --- a/content/en/docs/reference/fission-cli/fission_function_run-local.md +++ b/content/en/docs/reference/fission-cli/fission_function_run-local.md @@ -18,30 +18,32 @@ fission function run-local [flags] ### Options ``` - --name string Function name - --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") - --code string URL or local path for single file source code - --deployarchive stringArray --deploy |:|: URL or local paths for binary archive - --env string Environment name for function - --image string Name of the Docker image to be deployed as a function. Valid only when executorType is set to 'container' - --env-version int Environment API version of the runtime image when running locally with --image (ignored when --env resolves it) (default 2) - --entrypoint string --entry |:|: Entry point for environment v2 to load with - --port int Port where the application is running (default 8888) - --method stringArray HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method: --method GET and for multiple methods --method GET --method POST. [DEPRECATED for 'fn create', use 'route create' instead] (default [GET]) - -H, --header stringArray -H |:|: Request headers - -b, --body string -b |:|: Request body - --subpath string Sub Path to check if function internally supports routing - --keep Keep the local function container and mount running after the invocation instead of tearing it down - -w, --watch -w |:|: Serve the function locally and re-specialize on source change (hot reload); env executors only - -e, --env-var stringArray -e |:|: Set a runtime env var KEY=VALUE in the local container (repeatable) - --env-from string Read runtime env vars from a file (one KEY=VALUE per line); -e overrides - --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. - --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. - --debug-port int Publish an additional container port for a debugger (delve/debugpy) to attach to - --build Compile the source with the environment builder image before running (compiled environments) - --builder-image string Builder image to use with --build when running cluster-less (defaults to the environment's builder image) - --buildcmd string Package build command for builder to run with - -h, --help help for run-local + --name string Function name + --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") + --code string URL or local path for single file source code + --deployarchive stringArray --deploy |:|: URL or local paths for binary archive + --env string Environment name for function + --image string Name of the Docker image to be deployed as a function. Valid only when executorType is set to 'container' + --env-version int Environment API version of the runtime image when running locally with --image (ignored when --env resolves it) (default 2) + --entrypoint string --entry |:|: Entry point for environment v2 to load with + --port int Port where the application is running (default 8888) + --method stringArray HTTP Methods: GET,POST,PUT,DELETE,HEAD. To mention single method: --method GET and for multiple methods --method GET --method POST. [DEPRECATED for 'fn create', use 'route create' instead] (default [GET]) + -H, --header stringArray -H |:|: Request headers + -b, --body string -b |:|: Request body + --subpath string Sub Path to check if function internally supports routing + --keep Keep the local function container and mount running after the invocation instead of tearing it down + -w, --watch -w |:|: Serve the function locally and re-specialize on source change (hot reload); env executors only + -e, --env-var stringArray -e |:|: Set a runtime env var KEY=VALUE in the local container (repeatable) + --env-from string Read runtime env vars from a file (one KEY=VALUE per line); -e overrides + --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. + --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. + --secret-mount stringArray Mount a secret at a path relative to /secrets, matching the function's spec.secrets[].mountPath in-cluster. Format NAME=PATH, e.g. --secret-mount db-creds=app/creds. Repeatable. Without this a secret lands at the default /secrets//. + --configmap-mount stringArray Mount a configmap at a path relative to /configs, matching the function's spec.configmaps[].mountPath in-cluster. Format NAME=PATH, e.g. --configmap-mount app-config=app/conf. Repeatable. Without this a configmap lands at the default /configs//. + --debug-port int Publish an additional container port for a debugger (delve/debugpy) to attach to + --build Compile the source with the environment builder image before running (compiled environments) + --builder-image string Builder image to use with --build when running cluster-less (defaults to the environment's builder image) + --buildcmd string Package build command for builder to run with + -h, --help help for run-local ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_state.md b/content/en/docs/reference/fission-cli/fission_function_state.md new file mode 100644 index 00000000..6be31d6a --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_state.md @@ -0,0 +1,31 @@ +--- +title: fission function state +slug: fission_function_state +url: /docs/reference/fission-cli/fission_function_state/ +--- +## fission function state + +Inspect and manage a function's keyed state (RFC-0023) + +### Options + +``` + -h, --help help for state +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function](/docs/reference/fission-cli/fission_function/) - Create, update and manage functions +* [fission function state delete](/docs/reference/fission-cli/fission_function_state_delete/) - Delete a key from a function's state keyspace +* [fission function state get](/docs/reference/fission-cli/fission_function_state_get/) - Get a key from a function's state keyspace +* [fission function state list](/docs/reference/fission-cli/fission_function_state_list/) - List keys in a function's state keyspace +* [fission function state set](/docs/reference/fission-cli/fission_function_state_set/) - Set a key in a function's state keyspace + diff --git a/content/en/docs/reference/fission-cli/fission_function_state_delete.md b/content/en/docs/reference/fission-cli/fission_function_state_delete.md new file mode 100644 index 00000000..b4434ea0 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_state_delete.md @@ -0,0 +1,34 @@ +--- +title: fission function state delete +slug: fission_function_state_delete +url: /docs/reference/fission-cli/fission_function_state_delete/ +--- +## fission function state delete + +Delete a key from a function's state keyspace + +``` +fission function state delete [flags] +``` + +### Options + +``` + --name string Function name + --key string State key to operate on + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + --if-version int Compare-and-swap version precondition (0 = create-only for set; unset = unconditional) + -h, --help help for delete +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function state](/docs/reference/fission-cli/fission_function_state/) - Inspect and manage a function's keyed state (RFC-0023) + diff --git a/content/en/docs/reference/fission-cli/fission_function_state_get.md b/content/en/docs/reference/fission-cli/fission_function_state_get.md new file mode 100644 index 00000000..09f412eb --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_state_get.md @@ -0,0 +1,33 @@ +--- +title: fission function state get +slug: fission_function_state_get +url: /docs/reference/fission-cli/fission_function_state_get/ +--- +## fission function state get + +Get a key from a function's state keyspace + +``` +fission function state get [flags] +``` + +### Options + +``` + --name string Function name + --key string State key to operate on + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -h, --help help for get +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function state](/docs/reference/fission-cli/fission_function_state/) - Inspect and manage a function's keyed state (RFC-0023) + diff --git a/content/en/docs/reference/fission-cli/fission_function_state_list.md b/content/en/docs/reference/fission-cli/fission_function_state_list.md new file mode 100644 index 00000000..0f2ac042 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_state_list.md @@ -0,0 +1,33 @@ +--- +title: fission function state list +slug: fission_function_state_list +url: /docs/reference/fission-cli/fission_function_state_list/ +--- +## fission function state list + +List keys in a function's state keyspace + +``` +fission function state list [flags] +``` + +### Options + +``` + --name string Function name + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + --prefix string Key prefix to list + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function state](/docs/reference/fission-cli/fission_function_state/) - Inspect and manage a function's keyed state (RFC-0023) + diff --git a/content/en/docs/reference/fission-cli/fission_function_state_set.md b/content/en/docs/reference/fission-cli/fission_function_state_set.md new file mode 100644 index 00000000..65894e83 --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_state_set.md @@ -0,0 +1,36 @@ +--- +title: fission function state set +slug: fission_function_state_set +url: /docs/reference/fission-cli/fission_function_state_set/ +--- +## fission function state set + +Set a key in a function's state keyspace + +``` +fission function state set [flags] +``` + +### Options + +``` + --name string Function name + --key string State key to operate on + --value string Value to store + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + --ttl duration Time-to-live for the written key (e.g. 300s, 1h); 0 uses the keyspace default + --if-version int Compare-and-swap version precondition (0 = create-only for set; unset = unconditional) + -h, --help help for set +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function state](/docs/reference/fission-cli/fission_function_state/) - Inspect and manage a function's keyed state (RFC-0023) + diff --git a/content/en/docs/reference/fission-cli/fission_function_test.md b/content/en/docs/reference/fission-cli/fission_function_test.md index fc3c35b8..6e797897 100644 --- a/content/en/docs/reference/fission-cli/fission_function_test.md +++ b/content/en/docs/reference/fission-cli/fission_function_test.md @@ -20,9 +20,11 @@ fission function test [flags] -b, --body string -b |:|: Request body -q, --query stringArray -q |:|: Request query parameters: -q key1=value1 -q key2=value2 -t, --timeout duration -t |:|: Length of time to wait for the response. If set to zero or negative number, no timeout is set (default 1m0s) - --async RFC-0024: invoke asynchronously (X-Fission-Invoke-Mode: async); prints the invocation id instead of waiting for the response. Set FISSION_INTERNAL_AUTH_SECRET when authentication is enabled. + --async Invoke asynchronously (X-Fission-Invoke-Mode: async); prints the invocation id instead of waiting for the response. Set FISSION_INTERNAL_AUTH_SECRET when authentication is enabled. --dbtype string Log database type: kubernetes (default) or loki (default "kubernetes") --subpath string Sub Path to check if function internally supports routing + --alias string Test a specific alias (e.g. prod) instead of the live function; mutually exclusive with --version + --version string Test a specific pinned FunctionVersion instead of the live function; mutually exclusive with --alias -h, --help help for test ``` diff --git a/content/en/docs/reference/fission-cli/fission_function_update-container.md b/content/en/docs/reference/fission-cli/fission_function_update-container.md index a98d4017..d6ec0a59 100644 --- a/content/en/docs/reference/fission-cli/fission_function_update-container.md +++ b/content/en/docs/reference/fission-cli/fission_function_update-container.md @@ -14,26 +14,29 @@ fission function update-container [flags] ### Options ``` - --name string Function name - --image string Name of the Docker image to be deployed as a function. Valid only when executorType is set to 'container' - --port int Port where the application is running (default 8888) - --command string Command to be passed to the container. If not specified , the ones defined in the image are used - --args string Args to be passed to the command on the container. If not specified , the ones defined in the image are used - --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. - --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. - --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) - --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) - --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" - --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" - --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) - --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) - --minmemory int Minimum memory to be assigned to pod (In megabyte) - --maxmemory int Maximum memory to be assigned to pod (In megabyte) - --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) - --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) - --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) - --spec Save to the spec directory instead of creating on cluster - -h, --help help for update-container + --name string Function name + --image string Name of the Docker image to be deployed as a function. Valid only when executorType is set to 'container' + --port int Port where the application is running (default 8888) + --command string Command to be passed to the container. If not specified , the ones defined in the image are used + --args string Args to be passed to the command on the container. If not specified , the ones defined in the image are used + --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. + --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. + -e, --env-var stringArray -e |:|: Per-function environment variable as KEY=VALUE; repeatable. On fn update the provided list replaces the function's env vars. (--env keeps meaning the Environment name.) + --env-from-secret stringArray Project a same-namespace Secret into the function's environment: 'name' for the whole object, 'name/key' for one key (variable named after the key), 'name/key:ENV' to rename it; repeatable. On fn update the provided list replaces the previous one. + --env-from-configmap stringArray Project a same-namespace ConfigMap into the function's environment: 'name' for the whole object, 'name/key' for one key (variable named after the key), 'name/key:ENV' to rename it; repeatable. On fn update the provided list replaces the previous one. + --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) + --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) + --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" + --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" + --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) + --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) + --minmemory int Minimum memory to be assigned to pod (In megabyte) + --maxmemory int Maximum memory to be assigned to pod (In megabyte) + --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) + --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) + --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) + --spec Save to the spec directory instead of creating on cluster + -h, --help help for update-container ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_update.md b/content/en/docs/reference/fission-cli/fission_function_update.md index db4c34de..93e1a66e 100644 --- a/content/en/docs/reference/fission-cli/fission_function_update.md +++ b/content/en/docs/reference/fission-cli/fission_function_update.md @@ -14,54 +14,68 @@ fission function update [flags] ### Options ``` - --name string Function name - --env string Environment name for function - --entrypoint string --entry |:|: Entry point for environment v2 to load with - --pkgname string --pkg |:|: Name of the existing package (--deploy and --src and --env will be ignored), should be in the same namespace as the function - --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") - --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. - --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. - --specializationtimeout int --st |:|: Timeout for executor to wait for function pod creation (default 120) - --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) - --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) - --concurrency poolmgr --con |:|: Maximum number of pods specialized concurrently to serve requests (Only valid for executortype; poolmgr) (default 500) - --requestsperpod poolmgr --rpp |:|: Maximum number of concurrent requests that can be served by a specialized pod (Only valid for executortype; poolmgr) (default 1) - --streaming Enable streaming (SSE/chunked/WebSocket) responses for this function; the response is flushed incrementally and not cut by the function timeout - --streamingprotocol string Streaming protocol when --streaming is set; one of 'auto', 'sse', 'chunked', 'websocket' (default "auto") - --streamingidletimeout int Idle timeout (seconds) for a streaming response before it is aborted; reset on each chunk (default 60) - --streamingmaxduration int Hard ceiling (seconds) on total streaming response lifetime; 0 means no ceiling (the idle timeout governs) - --expose-as-mcp Advertise this function as a Model Context Protocol (MCP) tool on the MCP server - --tool-description string Agent-facing tool description (required with --expose-as-mcp) - --tool-input-schema string Path to a JSON Schema file describing the tool's arguments; advertised verbatim as the MCP tool inputSchema - --tool-name string Override the advertised MCP tool name (defaults to -) - --async-retry-max-attempts int Async delivery attempt budget before dead-lettering (RFC-0024) - --async-max-age duration Max time an async invocation may wait for successful delivery before it is dead-lettered (RFC-0024) - --async-on-success string Same-namespace function to invoke with the result after a successful async delivery (RFC-0024); empty clears it - --async-on-failure string Same-namespace function to invoke with the result after a permanent async failure (RFC-0024); empty clears it - --async-on-success-topic string Statestore topic to publish the result envelope to after a successful async delivery (RFC-0027); empty clears it - --async-on-failure-topic string Statestore topic to publish the result envelope to after a permanent async failure (RFC-0027); empty clears it - --onceonly poolmgr --yolo |:|: Specifies if specialized pod will serve exactly one request in its lifetime (Only valid for executortype; poolmgr) - --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" - --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" - --retainpods int Number of pods to retain after pods specialization. - --code string URL or local path for single file source code - --sourcearchive stringArray --source |:|: --src |:|: URL or local paths for source archive - --deployarchive stringArray --deploy |:|: URL or local paths for binary archive - --srcchecksum string SHA256 checksum of source archive when providing URL - --deploychecksum string SHA256 checksum of deploy archive when providing URL - --insecure Skip generating SHA256 checksum for file integrity validation - --oci string Pre-built OCI image reference containing the deployment code (registry/repo:tag[@digest]) - --buildcmd string Package build command for builder to run with - -f, --force -f |:|: Force update a package even if it is used by one or more functions - --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) - --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) - --minmemory int Minimum memory to be assigned to pod (In megabyte) - --maxmemory int Maximum memory to be assigned to pod (In megabyte) - --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) - --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) - --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) - --spec Save to the spec directory instead of creating on cluster - -h, --help help for update + --name string Function name + --env string Environment name for function + --entrypoint string --entry |:|: Entry point for environment v2 to load with + --pkgname string --pkg |:|: Name of the existing package (--deploy and --src and --env will be ignored), should be in the same namespace as the function + --executortype string Executor type for execution; one of 'poolmgr', 'newdeploy' (default "poolmgr") + --secret stringArray Function access to secret, should be present in the same namespace as the function. You can provide multiple secrets using multiple --secrets flags. In the case of fn update the secrets will be replaced by the provided list of secrets. + --configmap stringArray Function access to configmap, should be present in the same namespace as the function. You can provide multiple configmaps using multiple --configmap flags. In case of fn update the configmaps will be replaced by the provided list of configmaps. + -e, --env-var stringArray -e |:|: Per-function environment variable as KEY=VALUE; repeatable. On fn update the provided list replaces the function's env vars. (--env keeps meaning the Environment name.) + --env-from-secret stringArray Project a same-namespace Secret into the function's environment: 'name' for the whole object, 'name/key' for one key (variable named after the key), 'name/key:ENV' to rename it; repeatable. On fn update the provided list replaces the previous one. + --env-from-configmap stringArray Project a same-namespace ConfigMap into the function's environment: 'name' for the whole object, 'name/key' for one key (variable named after the key), 'name/key:ENV' to rename it; repeatable. On fn update the provided list replaces the previous one. + --specializationtimeout int --st |:|: Timeout for executor to wait for function pod creation (default 120) + --fntimeout int --ft |:|: Maximum time for a request to wait for the response from the function (default 60) + --idletimeout int The length of time (in seconds) that a function is idle before pod(s) are eligible for recycling (default 120) + --concurrency poolmgr --con |:|: Maximum number of pods specialized concurrently to serve requests (Only valid for executortype; poolmgr) (default 500) + --requestsperpod poolmgr --rpp |:|: Maximum number of concurrent requests that can be served by a specialized pod (Only valid for executortype; poolmgr) (default 1) + --streaming Enable streaming (SSE/chunked/WebSocket) responses for this function; the response is flushed incrementally and not cut by the function timeout + --streamingprotocol string Streaming protocol when --streaming is set; one of 'auto', 'sse', 'chunked', 'websocket' (default "auto") + --streamingidletimeout int Idle timeout (seconds) for a streaming response before it is aborted; reset on each chunk (default 60) + --streamingmaxduration int Hard ceiling (seconds) on total streaming response lifetime; 0 means no ceiling (the idle timeout governs) + --expose-as-mcp Advertise this function as a Model Context Protocol (MCP) tool on the MCP server + --tool-description string Agent-facing tool description (required with --expose-as-mcp) + --tool-input-schema string Path to a JSON Schema file describing the tool's arguments; advertised verbatim as the MCP tool inputSchema + --tool-name string Override the advertised MCP tool name (defaults to -) + --state Opt the function into the keyed-state API + --state-keyspace string State keyspace name (defaults to the function name; explicit so a rename keeps the data) + --state-max-keys int Max live keys in the keyspace (0 = platform default) + --state-max-value-bytes int Max size of one state value in bytes (0 = platform default) + --state-ttl duration Default TTL applied to state writes without an explicit TTL (0 = keys do not expire) + --state-sticky-source string Sticky routing key source: header or queryparam + --state-sticky-name string Header or query-parameter name holding the sticky routing key + --async-retry-max-attempts int Async delivery attempt budget before dead-lettering + --async-max-age duration Max time an async invocation may wait for successful delivery before it is dead-lettered + --async-on-success string Same-namespace function to invoke with the result after a successful async delivery; empty clears it + --async-on-failure string Same-namespace function to invoke with the result after a permanent async failure; empty clears it + --async-on-success-topic string Statestore topic to publish the result envelope to after a successful async delivery; empty clears it + --async-on-failure-topic string Statestore topic to publish the result envelope to after a permanent async failure; empty clears it + --onceonly poolmgr --yolo |:|: Specifies if specialized pod will serve exactly one request in its lifetime (Only valid for executortype; poolmgr) + --labels string Comma separated labels to apply to the function. E.g. --labels="environment=dev,application=analytics" + --annotation stringArray Annotation to apply to the function. To mention multiple annotations --annotation="abc.com/team=dev" --annotation="foo=bar" + --retainpods int Number of pods to retain after pods specialization. + --provisioned-concurrency int Number of warm specialized pods to maintain eagerly (poolmgr only). 0 (default)=no provisioned concurrency + --versioning fission fn publish Opt the function into immutable version snapshots and named aliases; one of 'auto' (mint a version on every runtime-affecting update), 'manual' (mint only on fission fn publish), or 'off' (disable, update only) + --retain-versions int Number of unaliased versions to keep per function before older ones are garbage collected (requires --versioning auto|manual, or an existing versioning config); disambiguates from --retainpods, which retains specialized pods rather than function versions + --provisioned-schedule stringArray name=;start=;duration=<10h(time.Duration)>;target= + --code string URL or local path for single file source code + --sourcearchive stringArray --source |:|: --src |:|: URL or local paths for source archive + --deployarchive stringArray --deploy |:|: URL or local paths for binary archive + --srcchecksum string SHA256 checksum of source archive when providing URL + --deploychecksum string SHA256 checksum of deploy archive when providing URL + --insecure Skip generating SHA256 checksum for file integrity validation + --oci string Pre-built OCI image reference containing the deployment code (registry/repo:tag[@digest]) + --buildcmd string Package build command for builder to run with + -f, --force -f |:|: Force update a package even if it is used by one or more functions + --mincpu int Minimum CPU to be assigned to pod (In millicore, minimum 1) + --maxcpu int Maximum CPU to be assigned to pod (In millicore, minimum 1) + --minmemory int Minimum memory to be assigned to pod (In megabyte) + --maxmemory int Maximum memory to be assigned to pod (In megabyte) + --minscale int Minimum number of pods (Uses resource inputs to configure HPA) (default 1) + --maxscale int Maximum number of pods (Uses resource inputs to configure HPA) (default 1) + --targetcpu int Target average CPU usage percentage across pods for scaling (default 80) + --spec Save to the spec directory instead of creating on cluster + -h, --help help for update ``` ### Options inherited from parent commands diff --git a/content/en/docs/reference/fission-cli/fission_function_versions.md b/content/en/docs/reference/fission-cli/fission_function_versions.md new file mode 100644 index 00000000..d6ef336a --- /dev/null +++ b/content/en/docs/reference/fission-cli/fission_function_versions.md @@ -0,0 +1,33 @@ +--- +title: fission function versions +slug: fission_function_versions +url: /docs/reference/fission-cli/fission_function_versions/ +--- +## fission function versions + +List a function's published versions + +``` +fission function versions [flags] +``` + +### Options + +``` + --name string Function name + -o, --output string -o |:|: Output format: wide, json or yaml (default: table) + -h, --help help for versions +``` + +### Options inherited from parent commands + +``` + --kube-context string Kubernetes context to be used for the execution of Fission commands + -n, --namespace string -n |:|: If present, the namespace scope for this CLI request + -v, --verbosity int -v |:|: CLI verbosity (0 is quiet, 1 is the default, 2 is verbose) (default 1) +``` + +### SEE ALSO + +* [fission function](/docs/reference/fission-cli/fission_function/) - Create, update and manage functions + diff --git a/content/en/docs/reference/fission-cli/fission_httptrigger_create.md b/content/en/docs/reference/fission-cli/fission_httptrigger_create.md index 0fcfce30..9e0e779e 100644 --- a/content/en/docs/reference/fission-cli/fission_httptrigger_create.md +++ b/content/en/docs/reference/fission-cli/fission_httptrigger_create.md @@ -29,11 +29,13 @@ fission httptrigger create [flags] --route-tls string Name of the Secret holding TLS key and cert (ingress provider only; gateway TLS is configured on the Gateway listener) --gateway stringArray Parent Gateway the HTTPRoute attaches to (gateway provider): --gateway name or --gateway namespace/name (repeatable) --weight ints Weight for each function supplied with --function flag, in the same order. Used for canary deployment + --function-alias string Route through this FunctionAlias (RFC-0025) instead of the live function; requires exactly one --function, mutually exclusive with --function-version and with weighted multi-function routing + --function-version string Pin the route to this FunctionVersion (RFC-0025) instead of the live function; requires exactly one --function, mutually exclusive with --function-alias and with weighted multi-function routing --spec Save to the spec directory instead of creating on cluster --dry View the generated specs --prefix string Prefix with which functions are exposed. NOTE: Prefix takes precedence over URL/RelativeURL [DEPRECATED for 'fn create', use 'route create' instead] --keepprefix Keep the prefix in the URL while forwarding request to the function - --invocation-mode string RFC-0024: 'async' makes every request through this trigger asynchronous (durable 202 + invocation id); empty is the default synchronous mode + --invocation-mode string 'async' makes every request through this trigger asynchronous (durable 202 + invocation id); empty is the default synchronous mode -h, --help help for create ``` diff --git a/content/en/docs/reference/fission-cli/fission_httptrigger_update.md b/content/en/docs/reference/fission-cli/fission_httptrigger_update.md index d24544d8..850fa502 100644 --- a/content/en/docs/reference/fission-cli/fission_httptrigger_update.md +++ b/content/en/docs/reference/fission-cli/fission_httptrigger_update.md @@ -29,9 +29,11 @@ fission httptrigger update [flags] --route-tls string Name of the Secret holding TLS key and cert (ingress provider only; gateway TLS is configured on the Gateway listener) --gateway stringArray Parent Gateway the HTTPRoute attaches to (gateway provider): --gateway name or --gateway namespace/name (repeatable) --weight ints Weight for each function supplied with --function flag, in the same order. Used for canary deployment + --function-alias string Route through this FunctionAlias (RFC-0025) instead of the live function; requires exactly one --function, mutually exclusive with --function-version and with weighted multi-function routing + --function-version string Pin the route to this FunctionVersion (RFC-0025) instead of the live function; requires exactly one --function, mutually exclusive with --function-alias and with weighted multi-function routing --prefix string Prefix with which functions are exposed. NOTE: Prefix takes precedence over URL/RelativeURL [DEPRECATED for 'fn create', use 'route create' instead] --keepprefix Keep the prefix in the URL while forwarding request to the function - --invocation-mode string RFC-0024: 'async' makes every request through this trigger asynchronous (durable 202 + invocation id); empty is the default synchronous mode + --invocation-mode string 'async' makes every request through this trigger asynchronous (durable 202 + invocation id); empty is the default synchronous mode -h, --help help for update ``` diff --git a/content/en/docs/reference/fission-cli/fission_mqtrigger_create.md b/content/en/docs/reference/fission-cli/fission_mqtrigger_create.md index 50431eb5..37d82f12 100644 --- a/content/en/docs/reference/fission-cli/fission_mqtrigger_create.md +++ b/content/en/docs/reference/fission-cli/fission_mqtrigger_create.md @@ -17,7 +17,7 @@ fission mqtrigger create [flags] --function string Function name --topic string Message queue Topic the trigger listens on --name string Message queue trigger name - --mqtype string For mqtkind "fission" => kafka, statestore (the RFC-0027 built-in, no broker) + --mqtype string For mqtkind "fission" => kafka, statestore (the built-in, no-broker option) For mqtkind "keda" => kafka, aws-sqs-queue, aws-kinesis-stream, gcp-pubsub, stan, nats-jetstream, rabbitmq, redis (default "kafka") --resptopic string Topic that the function response is sent on (response discarded if unspecified) --errortopic string Topic that the function error messages are sent to (errors discarded if unspecified From 67189a68b27398b91e47f377a750fbe9c7e08f37 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:17:55 +0530 Subject: [PATCH 11/26] docs: fix async-invocation page against verified CLI surface - helm snippet: statestore.mode is required when statestore.enabled - retry attempts capped at 3 (MaxAsyncAttempts), example used 5 - real fn test --async output format and asyncinv/ id format - router 202 returns header + JSON body with invocationId - fn test --body does not expand @file; use inline JSON - dlq purge takes no --all flag; note redrive resets attempts --- .../docs/usage/function/async-invocation.md | 30 +++++++++++-------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/content/en/docs/usage/function/async-invocation.md b/content/en/docs/usage/function/async-invocation.md index 5919fc15..5b118fe9 100644 --- a/content/en/docs/usage/function/async-invocation.md +++ b/content/en/docs/usage/function/async-invocation.md @@ -39,10 +39,12 @@ Asynchronous invocation is **off by default** and needs the [statestore]({{% ref helm upgrade --install fission fission-charts/fission-all \ --namespace fission \ --set statestore.enabled=true \ + --set statestore.mode=embedded \ --set asyncInvocation.enabled=true ``` -Embedded statestore mode is enough to try async invocation. +The chart requires an explicit `statestore.mode` (`embedded` or `external`) when the statestore is enabled. +Embedded mode is enough to try async invocation. [Autoscaling](#autoscaling) additionally requires `statestore.mode=external`. ## Invoke asynchronously @@ -50,8 +52,9 @@ Embedded statestore mode is enough to try async invocation. The CLI sends the async header and prints the durable invocation id instead of waiting for a response: ```bash -$ fission fn test --name resize-image --method POST --body @photo.json --async -Invocation accepted: id=inv-8f2c1a9e +$ fission fn test --name resize-image --method POST --body '{"path": "photos/cat.jpg"}' --async +Accepted (202) +invocationId: asyncinv/8f2c1a9e4b7d3c2a9f1e6b5d4c3a2b1f ``` Any HTTP caller can do the same by setting the header on a request to the function's [HTTP trigger]({{% ref "/docs/usage/triggers/http-trigger.md" %}}): @@ -61,7 +64,8 @@ curl -XPOST -H "X-Fission-Invoke-Mode: async" \ --data @photo.json \ http://$FISSION_ROUTER/resize-image # HTTP/1.1 202 Accepted -# X-Fission-Invocation-Id: inv-8f2c1a9e +# X-Fission-Invocation-Id: asyncinv/8f2c1a9e4b7d3c2a9f1e6b5d4c3a2b1f +# {"invocationId":"asyncinv/8f2c1a9e4b7d3c2a9f1e6b5d4c3a2b1f"} ``` {{% notice info %}} @@ -76,13 +80,13 @@ Configure the bounds per function on `fn create` / `fn update`: ```bash fission fn update --name resize-image \ - --async-retry-max-attempts 5 \ + --async-retry-max-attempts 3 \ --async-max-age 1h ``` | Flag | Meaning | | --- | --- | -| `--async-retry-max-attempts` | Maximum delivery attempts before dead-lettering. | +| `--async-retry-max-attempts` | Maximum delivery attempts before dead-lettering (1 to 3). | | `--async-max-age` | Maximum age of an invocation before dead-lettering, regardless of attempts. | {{% notice info %}} @@ -115,20 +119,22 @@ Invocations that exhaust their retries or age out land in the dead-letter queue, fission function dlq list # Inspect one -fission function dlq show --id inv-8f2c1a9e +fission function dlq show --id asyncinv/8f2c1a9e4b7d3c2a9f1e6b5d4c3a2b1f # Re-drive one back onto the queue, or all of them -fission function dlq redrive --id inv-8f2c1a9e +fission function dlq redrive --id asyncinv/8f2c1a9e4b7d3c2a9f1e6b5d4c3a2b1f fission function dlq redrive --all -# Discard them -fission function dlq purge --all +# Discard every dead-lettered async invocation +fission function dlq purge ``` +A re-driven invocation starts with a fresh attempt budget. + | Flag | Meaning | | --- | --- | -| `--id` | Operate on a single durable invocation id. | -| `--all` | Apply to every dead-lettered invocation. | +| `--id` | Operate on a single durable invocation id (`show`, `redrive`). | +| `--all` | Re-drive every dead-lettered invocation (`redrive`). | | `--queue` | Target queue: empty for async invocations, or an eventing broker egress queue (`mq-egress-`). | | `--limit` | Cap the number of entries `dlq list` returns. | From 7f3dbb059f40d467dcb794aaf75af6c5fdcca4a2 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:21:21 +0530 Subject: [PATCH 12/26] docs: catalog entries for stateful, async, and eventing examples Stateful counter/session (merged fission/examples#95) plus the new async-invocation and eventing-topics examples on the examples/async-and-eventing branch. --- static/data/examples.json | 47 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/static/data/examples.json b/static/data/examples.json index 3c48328a..ab01ec20 100644 --- a/static/data/examples.json +++ b/static/data/examples.json @@ -87,6 +87,24 @@ "websocket" ], "language": "JavaScript" + }, + { + "name": "Stateful Counter", + "description": "Per-user counter on built-in function state with compare-and-swap, so increments are never lost.", + "link": "https://github.com/fission/examples/blob/main/nodejs/stateful-counter.js", + "tags": [ + "state", + "keyed-state" + ] + }, + { + "name": "Stateful Session", + "description": "Self-expiring login sessions kept in built-in function state with a TTL, no external store.", + "link": "https://github.com/fission/examples/blob/main/nodejs/stateful-session.js", + "tags": [ + "state", + "session" + ] } ] }, @@ -228,6 +246,15 @@ "websocket" ], "language": "Python" + }, + { + "name": "Stateful Counter", + "description": "Per-user counter on built-in function state with compare-and-swap, standard library only.", + "link": "https://github.com/fission/examples/blob/main/python/stateful_counter.py", + "tags": [ + "state", + "keyed-state" + ] } ] }, @@ -941,6 +968,26 @@ "workflow", "wait" ] + }, + { + "name": "Async Invocation: Webhook Order Booking", + "description": "Fire-and-forget webhook processing with retries, dead-letter queue inspect and redrive, and result destinations.", + "link": "https://github.com/fission/examples/tree/main/miscellaneous/async-invocation", + "tags": [ + "async", + "dlq" + ], + "language": "JavaScript" + }, + { + "name": "Statestore Eventing: Order Events Fan-out", + "description": "Producer and two consumers on a built-in durable topic with fission topic publish and peek, no external broker.", + "link": "https://github.com/fission/examples/tree/main/miscellaneous/eventing-topics", + "tags": [ + "eventing", + "topics" + ], + "language": "JavaScript" } ] } From 18e370b39b49d95754fcc3d47dc4df74e23beec8 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:30:56 +0530 Subject: [PATCH 13/26] docs: provisioned concurrency & scheduled warming guide (RFC-0026) --- .../usage/function/provisioned-concurrency.md | 170 ++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 content/en/docs/usage/function/provisioned-concurrency.md diff --git a/content/en/docs/usage/function/provisioned-concurrency.md b/content/en/docs/usage/function/provisioned-concurrency.md new file mode 100644 index 00000000..bd523bde --- /dev/null +++ b/content/en/docs/usage/function/provisioned-concurrency.md @@ -0,0 +1,170 @@ +--- +title: "Provisioned Concurrency" +draft: false +weight: 46 +description: > + Keep a floor of warm specialized pods for a poolmgr function, with cron-scheduled warming windows, so requests inside the floor never pay a cold start. +--- + +**Declare a floor of always-warm capacity: the executor keeps N specialized pods ready before any request arrives, and cron-scheduled windows raise or lower that floor for known traffic patterns.** + +The poolmgr warm pool is generic: pods idle without your code loaded. +The first request per pod pays package fetch and load, and the idle reaper un-warms quiet functions, so off-hours traffic pays it again. +Starting with Fission {{< release-version >}}, provisioned concurrency removes that cold start for opted-in functions. +The executor specializes pods eagerly, exempts them from the idle reaper, and publishes them to the router, so requests within the floor always hit a warm pod. +Requests beyond the floor behave exactly as before: they pay a normal on-demand cold start. + +```mermaid +flowchart TB + spec["Function spec:
target + windows"]:::user -->|"1. effective target = base, or active window"| prov["Provisioner (Executor)"]:::fission + prov -->|"2. below target: specialize eagerly"| pool["Generic pool pod"]:::pod + pool -->|"3. label fission.io/provisioned"| warm["Warm specialized pod"]:::pod + router["Router"]:::fission -->|"requests: no cold start"| warm + prov -.->|"4. above target: clear label"| warm + reaper["Idle reaper"]:::fission -.->|"5. retires unlabeled idle pods"| warm + + classDef user fill:#ffffff,stroke:#94a3b8,color:#1f2a43 + classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43 + classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3 +``` + +## Prerequisites + +Provisioned concurrency is **off by default**. +Enable the provisioner in the executor at install or upgrade time: + +```bash +helm upgrade --install fission fission-charts/fission-all \ + --namespace fission \ + --set executor.provisionedConcurrency.enabled=true +``` + +{{% notice warning %}} +With the Helm gate off, Fission still accepts a function spec that sets provisioned concurrency — but warms nothing, silently. +If your function never shows warm pods, check `executor.provisionedConcurrency.enabled` first. +{{% /notice %}} + +Provisioned concurrency works with the [poolmgr executor](/docs/usage/function/executor/) only; the API server rejects the field on other executor types. +For newdeploy or container functions, set `--minscale` instead — those executors already keep a minimum replica count. + +## Keep pods warm + +Set a base target on `fn create` or `fn update`: + +```bash +$ fission fn create --name checkout --env node --code checkout.js \ + --provisioned-concurrency 2 +function 'checkout' created +``` + +The executor's provisioner reconciles every 30 seconds (Helm: `executor.provisionedConcurrency.reconcileInterval`). +On each pass it counts ready warm pods for the function. +If the count is below the target, it specializes more pods from the generic pool — the same code path a cold start uses, so the pods are identical. +If the count is above the target, it removes the exemption label from the excess pods and lets the idle reaper retire them. + +Warming is paced, not instant. +At most 4 eager specializations run per function at a time (Helm: `executor.provisionedConcurrency.maxInflightPerFunction`), so one function's warm-up burst cannot starve cold starts of other functions. +A target of 20 therefore takes several reconcile passes to fill. + +## Scheduled warming + +A schedule window overrides the base target during a time range. +Add one or more windows with the repeatable `--provisioned-schedule` flag: + +```bash +fission fn update --name checkout \ + --provisioned-concurrency 2 \ + --provisioned-schedule "name=business-hours;start=CRON_TZ=America/New_York 0 9 * * 1-5;duration=10h;target=10" \ + --provisioned-schedule "name=nightly-batch;start=0 2 * * *;duration=90m;target=5" +``` + +Each window is one string with four required keys, separated by `;`: + +| Key | Meaning | +| --- | --- | +| `name` | Unique name within the function's window list (max 32 windows). | +| `start` | Cron expression that opens each window instance. | +| `duration` | How long each instance stays open. Go duration, **single unit only** — `10h` and `90m` are valid, `1h30m` is rejected by the API server. | +| `target` | Warm-pod target while the window is open. `0` un-warms the function for the window. | + +Quote the whole string in the shell — it contains `;` and spaces. +`--provisioned-schedule` requires `--provisioned-concurrency` of 1 or more. + +### Window semantics + +- `start` uses the same 5-field cron format as [time triggers](/docs/usage/triggers/timer/): minute, hour, day-of-month, month, day-of-week. +An optional leading seconds field and descriptors such as `@daily` also parse. +- Without a timezone prefix, the schedule fires in the executor's local timezone (UTC in most deployments). +Prefix with `CRON_TZ=` to pin a fixed timezone, as in the example above. +- **An active window replaces the base target completely — even when the window target is lower.** +When several windows are open at once, the highest window target wins. +The base target applies only while no window is open. +- A window with `target=0` drains the warm pods for its duration. +Use it to un-warm a function off-hours while keeping a base floor the rest of the time. + +In the example above: 2 warm pods by default, 10 during New York business hours, and 5 during the nightly batch window — not 2+5. + +## Update and disable + +- `fission fn update --provisioned-concurrency 5` changes the base target and **keeps** the existing windows. +- Passing any `--provisioned-schedule` flag **replaces the whole window list** — repeat every window you want to keep. +`--provisioned-schedule` always needs `--provisioned-concurrency` in the same command; alone it is an error. +- `fission fn update --provisioned-concurrency 0` turns the feature off and clears the windows. +The provisioner removes the exemption labels and the idle reaper retires the pods gracefully. + +## Observe it working + +The function status reports the warm-pod count against the effective target: + +```bash +$ kubectl get function checkout -o jsonpath='{.status.provisionedReady}/{.status.provisionedTarget}{"\n"}' +2/2 +``` + +| Status field | Meaning | +| --- | --- | +| `provisionedReady` | Warm specialized pods currently ready. | +| `provisionedTarget` | Effective target right now (base, or the active window, after the namespace cap). | +| `provisionedSpecTarget` | Raw target from the spec. When it exceeds `provisionedTarget`, the namespace cap clamped it. | + +The `Provisioned` condition summarizes the state with reason `ProvisionedSatisfied`, `ProvisionedWarming`, `ProvisionedDisabled`, or `ProvisionedClamped`: + +```bash +kubectl get function checkout \ + -o jsonpath='{.status.conditions[?(@.type=="Provisioned")].reason}{"\n"}' +``` + +Warm pods carry the `fission.io/provisioned=true` label: + +```bash +kubectl get pods -A -l fission.io/provisioned=true +``` + +`fission fn pods --name checkout` lists the same pods, but its columns do not show the provisioned label — use the kubectl label filter to tell warm floor pods apart. + +The executor also exports metrics: `fission_provisioned_target`, `fission_provisioned_ready`, `fission_provisioned_eager_specializations_total` (by outcome), and `fission_provisioned_window_transitions_total`. + +## Limits and caveats + +- **Warm pods hold resources continuously.** +That is the point of the feature — the memory and CPU requests are the price of zero cold starts. +- **Namespace cap.** +The provisioner clamps the effective target to `executor.provisionedConcurrency.maxPerFunction` (Helm, default 20), so one function cannot reserve a cluster. +A clamped function shows `provisionedSpecTarget > provisionedTarget` and reason `ProvisionedClamped`. +- **Size the generic pool for the draws.** +Eager specialization consumes generic pool pods. +If the pool cannot supply them, warming stalls until the pool refills — raise the environment `--poolsize` to absorb the largest window target. +- **Warm-up bursts can slow other functions' worst-case cold starts.** +While one function eagerly warms a large burst, on-demand cold starts of other functions in the same environment pool can be several times slower at the tail; the median stays bounded. +The in-flight limit and a larger pool reduce the effect. +- **Latest generation only.** +After a function update, the provisioner warms the new generation and lets old-generation pods drain. +- Warming does not invoke your function; it loads the package and runs the environment's specialization, nothing more. + +## Related + +- [Executors](/docs/usage/function/executor/) — poolmgr and newdeploy, and where `--minscale` fits. +- [Environments](/docs/usage/function/environments/) — set the generic pool size with `--poolsize`. +- [Timers](/docs/usage/triggers/timer/) — the same cron format, used for scheduled invocations. +- [Custom Resource Definition Specification](/docs/reference/crd-reference/#provisionedconcurrencyconfig) — `provisionedConcurrency` spec and status fields. +- [fission function create](/docs/reference/fission-cli/fission_function_create/) — full flag reference. From a26a23bbe6c02019e45f223cb6a2bcf5aa1a1877 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:30:56 +0530 Subject: [PATCH 14/26] docs: statestore eventing user guide + fission topic CLI (RFC-0027) --- content/en/docs/usage/triggers/_index.md | 2 + .../usage/triggers/statestore-eventing.md | 179 ++++++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 content/en/docs/usage/triggers/statestore-eventing.md diff --git a/content/en/docs/usage/triggers/_index.md b/content/en/docs/usage/triggers/_index.md index 0f20de57..fc17a8a8 100644 --- a/content/en/docs/usage/triggers/_index.md +++ b/content/en/docs/usage/triggers/_index.md @@ -18,6 +18,7 @@ Pick the trigger that matches where your events come from. | HTTP trigger | An incoming HTTP request to a URL path | `fission httptrigger create` (alias `route`) | {{% ref "http-trigger.md" %}} | | Time trigger | A cron schedule | `fission timetrigger create` (alias `timer`) | {{% ref "timer.md" %}} | | Message queue trigger | A message published to a queue or stream | `fission mqtrigger create` (alias `mqt`) | {{% ref "message-queue-trigger-kind-keda/_index.md" %}} | +| Statestore eventing | An event published to a built-in statestore topic | `fission mqtrigger create --mqtkind fission --mqtype statestore` | {{% ref "statestore-eventing.md" %}} | | Kubernetes watch trigger | A change to a Kubernetes object | `fission watch create` | {{% ref "kubewatcher.md" %}} | {{% notice info %}} @@ -62,5 +63,6 @@ This is why understanding HTTP triggers and the router helps when debugging any - [HTTP Trigger]({{% ref "http-trigger.md" %}}) - [Time Trigger]({{% ref "timer.md" %}}) - [Message Queue Trigger: KEDA]({{% ref "message-queue-trigger-kind-keda/_index.md" %}}) +- [Statestore Eventing]({{% ref "statestore-eventing.md" %}}) - [Kubernetes Watch Trigger]({{% ref "kubewatcher.md" %}}) - [Router architecture]({{% ref "/docs/architecture/router.md" %}}) diff --git a/content/en/docs/usage/triggers/statestore-eventing.md b/content/en/docs/usage/triggers/statestore-eventing.md new file mode 100644 index 00000000..fa63bee9 --- /dev/null +++ b/content/en/docs/usage/triggers/statestore-eventing.md @@ -0,0 +1,179 @@ +--- +title: "Statestore Eventing" +draft: false +weight: 2 +description: > + Publish and subscribe with durable topics on the built-in statestore — message queue triggers that need no external broker. +--- + +**Statestore eventing gives you durable publish/subscribe topics on the built-in [statestore](/docs/architecture/statestore/) — no Kafka, no external broker, no extra infrastructure.** + +Statestore eventing is available starting with Fission {{< release-version >}}. +A topic is a durable, replayable stream in the statestore event log. +Any producer appends events to it: the `fission topic publish` command, or an [async invocation](/docs/usage/function/async-invocation/) result destination. +A message queue trigger with `--mqtype statestore` subscribes a function to the topic. +Fission delivers each event to the function at least once, with retries and an error topic for events that keep failing. + +```mermaid +flowchart TB + pub["Publisher
(fission topic publish, async destination)"]:::user + pub -->|"1. append"| stream["Topic Stream"]:::store + stream -->|"2. read from cursor"| mqt["Statestore MQ Consumer"]:::fission + mqt -->|"3. invoke via router"| pod["Function Pod"]:::pod + mqt -.->|"retries exhausted"| err["Error Topic"]:::store + mqt -.->|"response body"| resp["Response Topic"]:::store + + classDef user fill:#ffffff,stroke:#94a3b8,color:#1f2a43 + classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43 + classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3 + classDef store fill:#fff7e0,stroke:#dba514,color:#1f2a43,stroke-dasharray:5 3 +``` + +## When to use it + +| You need | Use | +| --- | --- | +| Function-to-function events inside the cluster, zero extra infrastructure | Statestore eventing (this page) | +| Events from an external broker you already run (Kafka, SQS, RabbitMQ, …) | [KEDA message queue triggers](/docs/usage/triggers/message-queue-trigger-kind-keda/) | +| High throughput, partitioned ordering, or consumer groups | An external broker | + +The statestore provider targets small and medium event volumes. +When you outgrow it, change `--mqtype` to `kafka` and point at a broker — the trigger fields stay the same. + +## Prerequisites + +Eventing needs the [statestore](/docs/architecture/statestore/); the embedded mode is enough: + +```bash +helm upgrade --install fission fission-charts/fission-all \ + --namespace fission \ + --set statestore.enabled=true +``` + +The chart value `eventing.enabled` defaults to `true`, so a statestore-enabled install already runs the eventing consumer. +Without the statestore, `fission topic` commands fail with `eventing is not enabled on this cluster (requires the statestore)`. + +{{% notice info %}} +When [internal service authentication](/docs/installation/internal-auth/) is enabled, set `FISSION_INTERNAL_AUTH_SECRET` so `fission topic publish` and `fission topic peek` can sign their requests. +{{% /notice %}} + +## Worked example + +Wire a function to a topic named `orders`, publish an event, and watch it flow. + +Create the consumer function: + +```js +// process-order.js +module.exports = async function (context) { + console.log("processing order:", JSON.stringify(context.request.body)); + return { status: 200, body: "ok" }; +} +``` + +```bash +fission env create --name node --image ghcr.io/fission/node-env +fission fn create --name process-order --env node --code process-order.js +``` + +Create the trigger **before** you publish. +A new trigger starts at the head of the stream: it sees only events published after it starts. + +```bash +fission mqtrigger create --name order-consumer \ + --mqtkind fission --mqtype statestore \ + --topic orders --function process-order \ + --pollinginterval 1 \ + --maxretries 3 --errortopic orders-errors +``` + +| Flag | Meaning | +| --- | --- | +| `--mqtkind fission` | The statestore provider runs in the classic head; the default `keda` kind rejects it. | +| `--topic` | Topic to consume; 1–249 characters of `[a-zA-Z0-9._-]`. | +| `--pollinginterval` | Seconds between reads on an idle topic; the CLI default of 30 adds up to 30 s of delivery latency. | +| `--maxretries` | Delivery retries per event before the event goes to the error topic. | +| `--errortopic` | Topic that receives events that exhaust their retries. | +| `--resptopic` | Topic that receives the function's response body (optional). | + +Publish an event: + +```bash +$ fission topic publish --topic orders --data '{"orderId":"A-1042"}' +published to topic "orders" in namespace "default" (statestore) +``` + +Peek at the topic to confirm the event is durably stored: + +```bash +$ fission topic peek --topic orders +head: 1 +SEQ TYPE AGE PAYLOAD +1 application/json 10s {"orderId":"A-1042"} +``` + +Verify delivery in the function's log: + +```bash +$ fission fn log --name process-order +... processing order: {"orderId":"A-1042"} +``` + +`fission topic publish` also accepts `--mqtype kafka` to publish to a broker topic through the egress queue; this page covers the default `statestore` type. + +## Publish from a function + +Async invocations can fan their results out to a topic instead of a single destination function: + +```bash +fission fn update --name resize-image \ + --async-on-success-topic image-resized \ + --async-on-failure-topic image-failures +``` + +Every statestore trigger on `image-resized` then receives the result envelope of each successful delivery. +See [Asynchronous Invocation](/docs/usage/function/async-invocation/) for the async delivery pipeline itself. + +## Delivery semantics + +| Behavior | As implemented | +| --- | --- | +| Guarantee | At-least-once per trigger; make consumers idempotent. | +| Start position | Stream head at first subscribe; no backlog replay. | +| Ordering | Single stream, roughly FIFO; no partitions. | +| Fan-out | Each trigger on a topic keeps its own durable cursor and receives every event. | +| Success | Any 2xx response from the function. | +| Retry | Up to `--maxretries` retries per event, 500 ms apart. | +| Exhausted | Event is published to `--errortopic`; without one it is dropped with a log line. | +| Response topic | The 2xx response body is published to `--resptopic`, best effort. | + +The consumer advances its cursor only after an event reaches terminal handling: delivered, or routed to the error topic. +One failing event therefore cannot wedge the topic, and a crash mid-batch redelivers the tail rather than skipping it. + +## Retention + +A reaper in the statestore MQ consumer trims each subscribed topic once per minute: + +- Events that every trigger on the topic has consumed are trimmed — no live subscriber loses an unconsumed event. +- Two backstops trim past a stalled subscriber: events older than 7 days, and any backlog beyond 100,000 events per topic. +A subscriber that resumes after a backstop trim logs the gap and counts it in the `fission_eventing_gap_events_total` metric. + +A topic with **no** statestore trigger is not trimmed at all — the orphan-stream age sweep is not implemented yet. +Instead, a per-topic backlog cap of 10,000 events bounds the growth: publishes to a capped topic fail with `topic backlog cap reached` instead of dropping silently. +To recover a capped orphan topic, create a statestore trigger on it. +The trigger's cursor starts at the head, so the reaper trims the old backlog within about a minute and publishes flow again; the trimmed backlog is not delivered. + +## Limits + +- One durable cursor per trigger; there are no consumer groups, so you cannot parallelize one trigger across replicas. +- Throughput is bounded by the statestore, not by Fission. +- Topics are namespace-scoped; a trigger can only consume topics in its own namespace. +- Exactly-once delivery is out of scope; design consumers to tolerate duplicates. + +## Related + +- [Statestore](/docs/architecture/statestore/) — the durable store behind topics. +- [Asynchronous Invocation](/docs/usage/function/async-invocation/) — async results as topic publishers. +- [KEDA message queue triggers](/docs/usage/triggers/message-queue-trigger-kind-keda/) — external brokers with autoscaled consumers. +- [`fission topic` CLI reference](/docs/reference/fission-cli/fission_topic/) — publish and peek flags. +- [`fission mqtrigger create` CLI reference](/docs/reference/fission-cli/fission_mqtrigger_create/) — the full trigger flag set. From e2e4cf9ca4a7c9a9016c17e678aa380b9d2ec24f Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:30:56 +0530 Subject: [PATCH 15/26] =?UTF-8?q?docs:=20secrets/configmaps=20page=20?= =?UTF-8?q?=E2=80=94=20RFC-0030=20env=20vars,=20mountPath,=20executor=20ma?= =?UTF-8?q?trix?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../access-secret-cfgmap-in-function.en.md | 190 ++++++++++++++++-- 1 file changed, 172 insertions(+), 18 deletions(-) diff --git a/content/en/docs/usage/function/access-secret-cfgmap-in-function.en.md b/content/en/docs/usage/function/access-secret-cfgmap-in-function.en.md index b615e7ea..7fda9122 100644 --- a/content/en/docs/usage/function/access-secret-cfgmap-in-function.en.md +++ b/content/en/docs/usage/function/access-secret-cfgmap-in-function.en.md @@ -1,18 +1,19 @@ --- -title: "Accessing Secrets/ConfigMaps" +title: "Secrets, ConfigMaps, and Environment Variables" draft: false weight: 4 description: > - Mount Kubernetes Secrets and ConfigMaps into a Fission function and read their values for API keys and configuration. + Mount Kubernetes Secrets and ConfigMaps into a Fission function as files, or inject them and literal values as per-function environment variables. --- -**Fission functions can mount Kubernetes [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) and [ConfigMaps](https://kubernetes.io/docs/concepts/storage/volumes/#configmap) as files, so your code can read API keys and other configuration at runtime.** -Use Secrets for sensitive values like API keys and authentication tokens. -Use ConfigMaps for any other configuration that doesn't need to be secret. +**Fission functions read configuration through two channels: [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) and [ConfigMaps](https://kubernetes.io/docs/concepts/storage/volumes/#configmap) mounted as files, and — starting with Fission {{< release-version >}} — per-function environment variables that can also project Secret and ConfigMap values.** +Use Secrets for sensitive values such as API keys and tokens. +Use ConfigMaps for configuration that is not secret. +Use environment variables for 12-factor configuration such as `DATABASE_URL` or `LOG_LEVEL`. ## Create a Secret or a ConfigMap -You can create a Secret or ConfigMap with the Kubernetes CLI: +Create a Secret or ConfigMap with the Kubernetes CLI: ```bash $ kubectl -n default create secret generic my-secret --from-literal=TEST_KEY="TESTVALUE" @@ -42,10 +43,12 @@ data: TEST_KEY: TESTVALUE ``` -## Accessing Secrets and ConfigMaps +The object must be in the same namespace as the function. -Secrets and ConfigMaps are accessed the same way. -Each is a set of key-value pairs, and Fission exposes each key as a file your function can read. +## Access as files + +Attach a Secret or ConfigMap to a function with `--secret` or `--configmap`. +Fission exposes each key of the object as a file: ```text # Secret path @@ -61,11 +64,11 @@ From the previous example, the paths are: # secret my-secret /secrets/default/my-secret/TEST_KEY -# confimap my-configmap +# configmap my-configmap /configs/default/my-configmap/TEST_KEY ``` -This Python function (`leaker.py`) reads both files and returns the Secret `my-secret` and ConfigMap `my-configmap` values: +This Python function (`leaker.py`) reads both files and returns the values: ```python # leaker.py @@ -99,13 +102,15 @@ $ fission fn create --name leaker --env python --code leaker.py --secret my-secr To attach multiple ConfigMaps or Secrets, repeat the flag: ```bash -# Provide multiple Configmaps +# Provide multiple ConfigMaps $ fission fn create --name --env --code --configmap --configmap # Provide multiple Secrets $ fission fn create --name --env --code --secret --secret ``` +On `fission fn update`, the `--secret` and `--configmap` lists replace the function's previous lists. + Run the function to confirm both values are readable: ```bash @@ -114,16 +119,165 @@ ConfigMap: TESTVALUE Secret: TESTVALUE ``` -## Updating Secrets and ConfigMaps +{{% notice info %}} +The poolmgr and newdeploy executors write these files through the fetcher. +The container executor has no fetcher: it projects a name-only `--secret` / `--configmap` reference as environment variables instead of files. +See the [executor support matrix](#executor-support) below. +{{% /notice %}} + +### Change the mount path + +By default an object's files land under `/secrets//` or `/configs//`. +Set `mountPath` on the reference in the function spec to redirect them. +There is no `fn create` / `fn update` flag for it; edit the spec YAML (the `fission spec` workflow or `kubectl`): + +```yaml +# in the Function spec +secrets: + - namespace: default + name: my-secret + mountPath: app/creds # files land at /secrets/app/creds/ +configmaps: + - namespace: default + name: my-configmap + mountPath: app/conf # files land at /configs/app/conf/ +``` + +Rules, enforced at admission: + +- The path is **relative** to the `/secrets` or `/configs` root; absolute paths are rejected. +- No two Secrets (or two ConfigMaps) on one function may resolve to the same directory. +- Environments with `allowedFunctionsPerContainer: infinite` do not support `mountPath` — their pods share one file tree across functions. + +All three executors honor `mountPath`: poolmgr and newdeploy through the fetcher, the container executor through a native read-only volume. +On the container executor the env-var projection of a name-only reference remains in addition to the mounted files. + +For the local loop, `fission fn run-local` reproduces the same layout with `--secret-mount NAME=PATH` and `--configmap-mount NAME=PATH`. + +## Inject environment variables + +Starting with Fission {{< release-version >}}, a function carries its own environment variables: literal values, single Secret/ConfigMap keys, or whole-object projections. + +{{% notice warning %}} +Per-function environment variables work on the **newdeploy** and **container** executors only. +The **poolmgr** executor (the default) does not support them yet; admission rejects the function rather than deploying it with empty variables. +Poolmgr support is phase 2 of RFC-0030 and is tracked in [fission/fission#3666](https://github.com/fission/fission/issues/3666). +{{% /notice %}} + +Create the objects to project: + +```bash +$ kubectl -n default create secret generic db-creds \ + --from-literal=username=app --from-literal=password=hunter2 + +$ kubectl -n default create configmap app-config \ + --from-literal=LOG_LEVEL=debug --from-literal=REGION=eu-west-1 +``` + +This Python function (`env-reader.py`) reads its process environment: + +```python +# env-reader.py +import os + +def main(): + return "\n".join([ + "DATABASE_URL=%s" % os.environ["DATABASE_URL"], + "DB_PASSWORD=%s" % os.environ["DB_PASSWORD"], + "LOG_LEVEL=%s" % os.environ["LOG_LEVEL"], + "REGION=%s" % os.environ["REGION"], + ]), 200 +``` + +Create the function with all three flag forms — a literal, a renamed single key, and a whole-object projection: + +```bash +$ fission fn create --name env-reader --env python --code env-reader.py \ + --executortype newdeploy \ + --env-var DATABASE_URL=postgres://db.default:5432/app \ + --env-from-secret db-creds/password:DB_PASSWORD \ + --env-from-configmap app-config +``` + +```bash +$ fission fn test --name env-reader +DATABASE_URL=postgres://db.default:5432/app +DB_PASSWORD=hunter2 +LOG_LEVEL=debug +REGION=eu-west-1 +``` + +The reference forms of `--env-from-secret` and `--env-from-configmap`: + +| Form | Result | +| --- | --- | +| `name` | Projects every key of the object as an environment variable. | +| `name/key` | Injects one key; the variable takes the key's name. | +| `name/key:ENV` | Injects one key; the variable is named `ENV`. | + +All three flags are repeatable. +`--env` keeps its existing meaning — the Environment name — so literals use `--env-var` (short form `-e`). + +Without `--executortype newdeploy`, the create is rejected, because the default executor is poolmgr: + +```text +$ fission fn create --name env-reader --env python --code env-reader.py --env-var LOG_LEVEL=debug +Error: ... FunctionSpec.Env: ... env/envFrom are not supported on the poolmgr executor yet +(lands with RFC-0030 phase 2); use the newdeploy or container executor +``` + +### Replacement on update + +The three env flags replace the function's env configuration **as one unit**. +Pass every env flag the function needs in one `fn update`: + +```bash +$ fission fn update --name env-reader \ + --env-var DATABASE_URL=postgres://db.default:5432/app \ + --env-var LOG_LEVEL=info \ + --env-from-secret db-creds/password:DB_PASSWORD \ + --env-from-configmap app-config +``` + +If you pass only some of the three flags, the variables set through the omitted flags are removed; the CLI prints a warning when that happens. +An env change is a runtime-affecting update: the function's pods roll and new pods see the new values. + +### Precedence and reserved names + +- `--env-var` literals win over `--env-from-*` whole-object projections. +- A `name/key` selection counts as a literal-level entry, so a named single key also beats a whole-object projection. +- Function env wins over environment variables from the Environment's pod spec. +- Platform-reserved names are rejected at admission: any `FISSION_*` name, `RESOURCE_VERSION_COUNT`, the proxy set (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, in either case), `LD_PRELOAD`, `NODE_OPTIONS`, and `PYTHONPATH`. {{% notice note %}} -If a large number of functions use the same ConfigMap or Secret, updating it will cause a large number of pods to be re-created at once. -Make sure the cluster has enough capacity to absorb that short spike of pods terminating and starting. +A Secret value injected as an environment variable is visible to `kubectl exec` and to crash handlers — the standard Kubernetes caveat. +For high-sensitivity material, prefer the [file mount](#access-as-files) pattern. {{% /notice %}} -Updating a ConfigMap or Secret updates the function pods, and the new value is used for subsequent function executions. -How long the change takes to reflect depends on how long the rolling update takes to finish. +## Executor support + +| Access pattern | poolmgr | newdeploy | container | +| --- | --- | --- | --- | +| `--secret` / `--configmap` as files | Yes (fetcher) | Yes (fetcher) | No — projected as env vars instead | +| `mountPath` redirect (spec field) | Yes (fetcher) | Yes (fetcher) | Yes (native volume) | +| `--env-var` / `--env-from-secret` / `--env-from-configmap` | No — rejected at admission ([#3666](https://github.com/fission/fission/issues/3666)) | Yes | Yes | + +On the container executor, combining `--env-from-*` with `--secret` / `--configmap` is rejected: `envFrom` replaces the legacy whole-object projection, so declare the objects in `--env-from-*` instead of alongside it. + +## Updating Secrets and ConfigMaps + +Updating a Secret or ConfigMap recycles the pods of every function that references it — through `--secret` / `--configmap` or through the env flags. +Subsequent executions see the new value; how fast depends on how long the rolling update takes. +Kubernetes never refreshes environment variables in a running container, so env values change only when pods are recreated. {{% notice note %}} -In Fission versions prior to 1.4, an updated Secret or ConfigMap value may not reach the function, which can keep reading a cached, older value. +If a large number of functions use the same ConfigMap or Secret, updating it re-creates a large number of pods at once. +Make sure the cluster has enough capacity to absorb that short spike of pods terminating and starting. {{% /notice %}} + +## Related + +- [Executors](/docs/usage/function/executor/) — what poolmgr, newdeploy, and container executors are. +- [Container functions](/docs/usage/function/container-functions/) — the container executor workflow. +- [`fission function create` reference](/docs/reference/fission-cli/fission_function_create/) — the full flag list. +- [CRD reference](/docs/reference/crd-reference/) — the `env`, `envFrom`, and `mountPath` fields on the `Function` resource. From ff9106857cd6ed110b92c4313acb7199e3fe31be Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:30:56 +0530 Subject: [PATCH 16/26] =?UTF-8?q?docs:=20upgrade=20guide=20=E2=80=94=20rol?= =?UTF-8?q?lout=20posture,=20drain=20windows,=20hook=20CRDs=20(RFC-0028)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/en/docs/installation/upgrade.md | 140 +++++++++++++++++++++--- 1 file changed, 125 insertions(+), 15 deletions(-) diff --git a/content/en/docs/installation/upgrade.md b/content/en/docs/installation/upgrade.md index c184b3f9..7fc7c431 100644 --- a/content/en/docs/installation/upgrade.md +++ b/content/en/docs/installation/upgrade.md @@ -2,31 +2,25 @@ title: "Upgrade Guide" weight: 60 description: > - Upgrade guidance 1.13 onwards + Upgrade Fission with Helm: the routine steps, what happens to in-flight traffic and warm pods during the roll, and how to tune the drain windows. --- -{{% notice warning %}} -Fission upgrades currently cause a short downtime, though we work to minimize it. -Please upvote [issue #1856](https://github.com/fission/fission/issues/1856) so we can prioritize fixing it. +{{% notice info %}} +Zero-downtime upgrades are the goal of Fission's upgrade design ([issue #1856](https://github.com/fission/fission/issues/1856)). +Recent releases ship rollout defaults that keep warm function traffic serving while the control plane rolls. +Fission does not yet test or guarantee zero downtime for every request, so schedule upgrades in a low-traffic window when that matters. {{% /notice %}} ## Upgrade to the latest Fission version -**Every upgrade needs three steps, in order: replace the CRDs, update the CLI, then upgrade the chart.** +**Every upgrade needs two steps, in order: update the CLI, then upgrade the chart.** +Starting with Fission {{< release-version >}}, `helm upgrade` applies the matching CRDs itself through a pre-upgrade hook, so a separate CRD step is needed only when you opt out. Check the version-specific sections below for anything extra your target release requires. -### Upgrade/Replace the CRDs - -Apply the CRD manifest for the version you're upgrading to: - -```sh -kubectl replace -k "github.com/fission/fission/crds/v1?ref={{% release-version %}}" -``` - ### Install the latest Fission CLI Make sure you have the latest CLI installed. -Refer to [Fission CLI Installation]({{< ref "_index.en.md#install-fission-cli">}}). +Refer to [Fission CLI Installation](/docs/installation/#install-fission-cli). ### Upgrade Fission chart @@ -38,8 +32,124 @@ helm repo update helm upgrade --namespace $FISSION_NAMESPACE fission fission-charts/fission-all ``` +With the default `crds.mode=hook`, the chart's [pre-upgrade checks](#pre-upgrade-checks) Job applies the target version's CRDs before any component rolls. + +If you set `crds.mode=none` because your organization does not grant CRD write to a chart, apply the CRD manifest yourself **before** the `helm upgrade`: + +```sh +kubectl replace -k "github.com/fission/fission/crds/v1?ref={{% release-version %}}" +``` + +Releases before v1.28.0 always need this manual CRD step. + _See [configuration](#configuration) below._ +### Verify the upgrade + +Confirm the client and server versions match, and run the cluster diagnostics: + +```sh +fission version +fission check +``` + +## What happens during an upgrade + +`helm upgrade` replaces the Fission control-plane pods, not your function pods. +This section describes what each component does while it rolls. + +### Pre-upgrade checks + +A Helm hook Job runs before any manifest changes (`preUpgradeChecks.enabled`, default `true`). +The Job: + +- applies the target version's CRD bundle (`crds.mode=hook`, the default), so controllers never run against stale schemas; +- confirms the latest CRD schema is live on the cluster; +- checks that every function references secrets, configmaps, and packages in its own namespace. + +If a check fails, the upgrade stops before any component rolls, and the existing installation keeps running unchanged. + +### Router + +The router runs two replicas by default and rolls surge-first (`maxSurge: 1`, `maxUnavailable: 0`), so the serving replica count never dips. +A new router pod reports Ready only after it builds its route table and syncs its endpoint index. +A terminating router pod first sleeps for `router.preStopSleep` (default 5 seconds) so its removal from the Service propagates, then drains in-flight requests for up to `router.gracefulShutdownTimeout` (default `75s`). +A PodDisruptionBudget (`minAvailable: 1`) protects the router during node drains. +The chart renders the budget only when the router can satisfy it: two or more replicas, or an autoscaler with a floor of two. + +### Warm function pods + +Warm pods keep serving through the upgrade: + +- The restarted executor **adopts** existing function Deployments and pods (`executor.adoptExistingResources`, default `true`) instead of recreating them. +- **Specialized** poolmgr pods survive executor-side template changes, such as a new fetcher image; the pool controller recycles them only when their environment changes. +- **Generic** (not yet specialized) pool pods roll and pick up the new images. +- Warm traffic does not need a live executor: the router serves warm requests directly from EndpointSlices. + +### Executor + +The executor is a single-writer control plane, so it rolls overlap-free (`maxSurge: 0`, `maxUnavailable: 1`): the old pod stops before the new one starts. +This gives a bounded executor-down window per roll. +Warm traffic keeps serving throughout; only cold starts wait for the new executor pod. +To shorten failover, run `executor.replicas: 2` with `executor.leaderElection.enabled: true` (active-passive HA). + +### Webhook + +The validating webhook runs two replicas by default with a surge rollout and a PodDisruptionBudget, so Fission CR writes stay available while it rolls. +One caveat remains on the default certificate path: the chart mints a new serving certificate on every `helm upgrade`, so a short window can reject CR writes while old pods still serve the old certificate. +Set `webhook.certManager.enabled=true` to let cert-manager manage a stable certificate and close that window. +Function invocations are not affected; the webhook sits only on the CR write path. + +### Embedded statestore + +This applies only when `statestore.enabled=true` with `mode: embedded`. +The embedded statestore is a single-replica Deployment with `strategy: Recreate`, because two pods must never hold the SQLite file at once. +Its pod is therefore down for a short window during the upgrade. +Invocations already enqueued are durable on the persistent volume, and delivery resumes when the pod returns. +New [asynchronous enqueues](/docs/usage/function/async-invocation/) during that window fail, and the caller must retry. +`statestore.mode=external` (Postgres) has no such window; see [Statestore](/docs/architecture/statestore/). + +## Tune the drain windows + +### Function pods: `terminationGracePeriod` + +Each environment sets how long its function pods drain before Kubernetes removes them: `spec.terminationGracePeriod`, default **90 seconds**. +A terminating function pod keeps serving for the whole window — the preStop hook sleeps through it, then the kubelet kills the pod. +Set the window above your longest function timeout, or the slowest in-flight requests end with a connection reset: + +```sh +fission env update --name node --graceperiod 180 +``` + +The same window applies to every pod teardown — idle reap, environment update, upgrade, node drain — so a larger value makes each teardown take longer per pod. +An explicit `0` disables draining and removes pods instantly. +See the [`terminationGracePeriod` field reference](/docs/reference/crd-reference/#environmentspec). + +### Router: grace period and shutdown timeout + +Two chart values control the router drain, and they must move together: + +```sh +helm upgrade --namespace $FISSION_NAMESPACE fission fission-charts/fission-all \ + --set router.terminationGracePeriodSeconds=150 \ + --set router.gracefulShutdownTimeout=120s +``` + +Keep `terminationGracePeriodSeconds` greater than `gracefulShutdownTimeout`, and `gracefulShutdownTimeout` greater than your longest function timeout. +Raising the grace period alone does nothing: the drain still stops at `gracefulShutdownTimeout`. + +## Upgrade to 1.28.x release + +v1.28.0 flips the chart's rollout-posture defaults so that upgrades keep warm traffic serving: + +- The **router** and the **webhook** default to two replicas each, with surge rollouts and PodDisruptionBudgets. +- The chart applies **CRDs** itself through the pre-upgrade hook (`crds.mode: hook`), so the manual `kubectl` CRD step is no longer part of the routine upgrade. + +Small-footprint installs (kind, single node) can set `router.replicas=1` and `webhook.replicas=1` to keep the previous footprint; the PodDisruptionBudgets drop automatically at one replica. +Set `crds.mode=none` to keep delivering CRDs yourself. + +See the [v1.28.0 release notes](/docs/releases/v1.28.0/#upgrade-notes) for the full list of changes. + ## Upgrade to 1.27.x release v1.27.0 adds opt-in multi-namespace tenancy and a function-developer observability toolkit (invocation correlation, `fission function describe`, and local `run-local` development). @@ -115,7 +225,7 @@ helm upgrade --namespace $FISSION_NAMESPACE fission fission-charts/fission-all \ --set internalAuth.enabled=false ``` -With `enabled=false`, every signer/verifier short-circuits to pass-through and the cluster falls back to `NetworkPolicy` + namespace isolation alone — matching pre-1.23 in-cluster behaviour. +With `enabled=false`, every signer/verifier short-circuits to pass-through and the cluster falls back to `NetworkPolicy` + namespace isolation alone — matching pre-1.23 in-cluster behavior. See [Internal Service Authentication]({{% ref "internal-auth.md" %}}) for the full toggle matrix, secret rotation, and longer-term mitigation. From 65b3f3eb4f6e50bd3d41b4b62f353c3b68c4e75b Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:30:57 +0530 Subject: [PATCH 17/26] =?UTF-8?q?docs:=20spec=20workflow=20rewrite=20for?= =?UTF-8?q?=20RFC-0029=20=E2=80=94=20idempotent=20apply,=20GitOps/CI=20sec?= =?UTF-8?q?tion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/en/docs/usage/spec/_index.md | 285 ++++++++++++++++----------- 1 file changed, 167 insertions(+), 118 deletions(-) diff --git a/content/en/docs/usage/spec/_index.md b/content/en/docs/usage/spec/_index.md index 3fcaf317..013ac2e1 100644 --- a/content/en/docs/usage/spec/_index.md +++ b/content/en/docs/usage/spec/_index.md @@ -2,59 +2,29 @@ title: "YAML Specs" weight: 30 description: > - Source Code Organization and Your Development Workflow + Manage a Fission application as version-controlled YAML specs, and deploy it with the idempotent fission spec apply — from your laptop or from a CI pipeline. --- -**Specify your whole Fission application — environments, functions, triggers — as version-controlled YAML, and deploy it with a single idempotent `fission spec apply`.** +**Specify your whole Fission application — environments, functions, triggers, workflows — as version-controlled YAML, and deploy it with a single idempotent `fission spec apply`.** -You've made a Hello World function in your favorite language, and you've run it on your Fission deployment. -What's next? +Individual `fission ... create` commands work well for one function. +They do not scale to an application with many functions, shared environments, and triggers. +Specs solve this: the whole application lives in a `specs/` directory that you track in Git, review in pull requests, and apply as one unit. -How should you organize source code when you have lots of functions? -How should you automate deployment into the cluster? -What about version control? -How do you test before deploying? +Applying a spec means reconciling the cluster to match the files: -The answers to these questions start from a common first step: how do you ***specify an application***? - -## Spec - -Instead of invoking the Fission CLI commands, you can specify your functions in a set of YAML files. -This is better than scripting the `fission` CLI, which is meant as a user interface, not a programming interface. - -You'll usually want to track these YAML files in version control along with your source code. -Fission provides CLI tools for generating these specification files, validating them, and "applying" them to a Fission installation. - -What does it mean to _apply_ a specification? -It means putting specification to effect: figuring out the things that need to be changed on the cluster, and updating them to make them the same as the specification. - -Applying a Fission spec goes through these steps: - -* Resources (functions, triggers, etc) that are in the specification but don't exist on the cluster are created. +* Resources in the specs but not on the cluster are created. Local source files are packaged and uploaded. -* Resources that are both in the specs and on the cluster are compared. - If they're different, the ones on the cluster are changed to match the spec. -* Resources present only on the cluster and not in the spec are destroyed. - (This deletion is limited to resources that were created by a previous _apply_; this makes sure that Fission doesn't delete unrelated resources. - See below for how this calculation works.) - -Running _apply_ more than once is equivalent to running it once: in other words, it's ***idempotent***. - -## Usage Summary - -Start using Fission's declarative application specifications in 3 steps: - - 1. Initialize a directory of specs: `fission spec init` - 1. Generate some YAMLs: `fission function create --spec ...` - 1. Apply them to a cluster: `fission spec apply --wait` - -You can also deploy continuously with `fission spec apply --watch`. +* Resources in both are compared, and the cluster copy is updated when it differs. +* With `--delete`, resources this spec created earlier but no longer declares are removed. + Deletion is opt-in; a plain `fission spec apply` never deletes anything. -We'll see examples of all these commands in the tutorial below. +Running apply again with unchanged specs changes nothing on the cluster: apply is ***idempotent***. +This makes it safe to run on every commit from a CI pipeline — see [Run spec apply from CI](#run-spec-apply-from-ci-gitops). -### The spec workflow +## The spec workflow -The `fission spec` subcommands form a simple loop: generate specs locally, validate them, then apply them to the cluster. +The `fission spec` subcommands form a loop: generate specs locally, validate them, then apply them to the cluster. `fission spec destroy` tears down everything a previous apply created. ```mermaid @@ -74,21 +44,70 @@ The full set of subcommands: | Command | What it does | | ------- | ------------ | -| `fission spec init` | Creates the `specs/` directory and a `fission-config.yaml` carrying the deployment ID. | -| `fission ... create --spec` | Writes a resource (function, environment, trigger, ...) as a YAML file under `specs/` instead of creating it on the cluster. | -| `fission spec validate` | Checks the specs for duplicate names and broken references between resources. | -| `fission spec apply` | Reconciles the cluster to match the specs (create, update, delete). Add `--wait` to block on builds or `--watch` for continuous deployment. | -| `fission spec list` | Lists the resources defined by the specs in the directory. | -| `fission spec destroy` | Deletes every resource that a previous apply created from these specs. | +| `fission spec init` | Creates the `specs/` directory with a `fission-deployment-config.yaml` that carries the deployment ID. | +| `fission ... create --spec` | Writes a resource (function, environment, trigger, workflow, ...) as a YAML file under `specs/` instead of creating it on the cluster. | +| `fission spec validate` | Checks the specs for duplicate names, broken references between resources, and name conflicts with resources already on the cluster. | +| `fission spec apply` | Reconciles the cluster to match the specs. Add `--delete` to prune, `--wait` to block on builds, `--watch` for continuous deployment, or `--dry-run` to preview. | +| `fission spec list` | Lists the cluster resources that carry this spec's deployment ID. | +| `fission spec destroy` | Deletes the resources declared in the spec files. With `--force`, deletes every resource carrying the deployment ID, across all namespaces. | + +All of these commands accept `--specdir` to point at a non-default directory. +They also accept `--specignore` to point at an ignore file (default `.specignore`) that excludes paths from being read as specs, much like `.gitignore`. +See the [`fission spec` CLI reference](/docs/reference/fission-cli/fission_spec/) for every flag. + +## Ownership: the deployment ID + +`fission spec init` writes a unique deployment ID into `fission-deployment-config.yaml`. +Every resource that apply creates is annotated with this ID. +Apply only updates or deletes resources that carry its own deployment ID. +Resources without the annotation — created by hand, by `kubectl`, or by another spec directory — are never modified or deleted. + +If a spec resource's name collides with an unowned cluster resource, apply fails instead of overwriting it. +Pass `--allowconflicts` to adopt such resources into the spec deployment. + +## Idempotency and drift reconciliation + +Reapplying an unchanged spec directory is a no-op: + +```bash +$ fission spec apply +Everything up to date. +``` + +A no-op reapply writes nothing to the cluster: no function generation bumps, no pod recycles, and no new [function versions](/docs/usage/function/versions-aliases/). +This is what makes a periodic or per-commit apply from automation safe. -All of these commands accept `--specdir` to point at a non-default directory and `--specignore` to point at a `.specignore` file (default `.specignore`) that excludes paths from being read as specs, much like `.gitignore`. +Apply reconciles real drift, and only real drift: + +* **Archives** are content-addressed by checksum. + An archive whose bytes already exist on the cluster is not uploaded again (`archive ... exists, not uploading`). +* **A source change** updates the package and re-triggers its build automatically. + A package whose last build failed is also re-triggered on the next apply. +* **A spec edit** to any resource updates only that resource and its dependents. + For example, a package update re-stamps the functions that reference it, so running pods pick up the new code. +* **Untouched resources** stay byte-identical, even across many reapplies. + +### Preview with --dry-run + +`fission spec apply --dry-run` computes the same diff read-only and reports what a real apply would do: + +```bash +$ fission spec apply --dry-run +would upload archive archive://eval-xk2p +1 package would be updated: calc-eval-0f36e9b8 +1 function would be updated: calc-eval +(dry run - no changes made) +``` + +The preview also surfaces errors a real apply would hit, such as a name conflict with a resource this spec does not own. +`--wait` and `--watch` are inert under `--dry-run`. ## Tutorial -This tutorial assumes you've already set up Fission, and tested a simple hello world function to make sure everything's working. -To learn how to do that, head over to the [installation guide]({{% ref "../../installation" %}}). +This tutorial assumes you have already set up Fission and tested a simple hello world function. +To learn how to do that, head over to the [installation guide](/docs/installation/). -We'll make a small calculator app with one python environment and two functions, all of which will be declaratively specified using YAML files. +We make a small calculator app with one Python environment and two functions, all specified as YAML files. This is a contrived example, meant purely as an illustration. ### Make an empty directory @@ -106,13 +125,11 @@ $ cd spec-tutorial $ fission spec init ``` -This creates a `specs/` directory. -You'll see a `fission-config.yaml` in there. -This file has a unique ID (deployment ID) in it; everything created on the cluster from these specs will be annotated with that deployment ID. +This creates a `specs/` directory with a `fission-deployment-config.yaml` in it. +This file carries the deployment ID; everything created on the cluster from these specs is annotated with that ID. -The deployment ID is generated automatically when you initialize the specs directory. -In some cases you may want to run initialization multiple times. -To update the same set of resources each time, specify the deployment ID with `--deployid`. +The deployment ID is generated automatically. +To make a re-initialized directory manage the same set of resources, pass the same ID with `--deployid`: ```bash $ fission spec init --deployid xxxx-yyyy-zzzz @@ -126,19 +143,18 @@ $ fission env create --spec --name python --image ghcr.io/fission/python-env --b This command creates a YAML file under specs called `specs/env-python.yaml`. -## Code two functions +### Code two functions -We will create two functions in python along with an empty `requirements.txt` file so that builder is able to build the code. -We will put the functions in their own directory with the requirements.txt file. +We create two Python functions, each in its own directory with an empty `requirements.txt` file so the builder can build the code. ```bash . ├── eval -│   ├── eval.py -│   └── requirements.txt +│ ├── eval.py +│ └── requirements.txt ├── form -│   ├── form.py -│   └── requirements.txt +│ ├── form.py +│ └── requirements.txt └── specs ``` @@ -186,8 +202,8 @@ def main(): ### Create specs for these functions -Let's create a specification for each of these functions. -This specifies the function name, where the code lives, and associates the function with the python environment: +Create a specification for each function. +This specifies the function name, where the code lives, and associates the function with the Python environment: ```bash $ fission function create --spec --name calc-form --env python --src "form/*" --entrypoint form.main @@ -207,7 +223,8 @@ This creates YAML files specifying that GET requests on `/form` and `/eval` invo ### Validate your specs -Spec validation does some basic checks: it makes sure there are no duplicate functions with the same name, and that references between various resources are correct. +Validation checks for duplicate resource names and broken references between resources. +It also checks that no spec name collides with a cluster resource owned by a different deployment ID, so it needs a cluster connection. ```bash $ fission spec validate @@ -215,53 +232,55 @@ $ fission spec validate You should see no errors. -## Apply: deploy your functions to Fission +### Apply: deploy your functions to Fission -You can use apply to deploy the environment, functions, and HTTP triggers to the cluster. -This command will wait for builds of both functions to complete before exiting: +Apply deploys the environment, functions, and HTTP triggers to the cluster. +With `--wait`, the command waits for the builds of both functions to complete before exiting: ```bash $ fission spec apply --wait +uploading archive archive://form-o4e9 +uploading archive archive://eval-xk2p 1 environment created: python -2 packages created: python-1543660299-o4e9, python-1543660287-byam +2 packages created: calc-form-a4c8e21d, calc-eval-0f36e9b8 2 functions created: calc-eval, calc-form 2 HTTPTriggers created: bac55924-03a8-42e1-81b9-8079a8885f3a, f16c8459-3c23-46ad-901f-9312f38cec2a --- Build SUCCEEDED --- --- Build SUCCEEDED --- ``` -If the build fails, you can rebuild the package using rebuild command: +If a build fails, you can rebuild the package with the rebuild command: ```bash --- Build FAILED: --- Build timeout due to environment builder not ready ------ -$ fission package rebuild --name python-1543660299-o4e9 +$ fission package rebuild --name calc-eval-0f36e9b8 ``` ### Test a function -You can check the function is working with `fission fn test` but since this function returns a HTML, it is best to open in browser. +You can check the function with `fission fn test`, but since this function returns HTML, it is best to open it in a browser. ```bash $ fission function test --name calc-form ``` -Open the URL of the Fission router service suffixed by the name of route at which form function is exposed. -For more details on getting the address of Fission router please check [the link](/docs/installation/env_vars/#fission-router-address). +Open the URL of the Fission router service, suffixed by the route at which the form function is exposed. +For details on getting the router address, see [accessing the router](/docs/installation/env_vars/#fission-router-address). ```text http://$FISSION_ROUTER/form ``` -You can enter two number and operator and see the results. +Enter two numbers and an operator to see the result. Currently this function only supports addition and subtraction. -(If you don't know the address of the Fission router, you can find it with kubectl: `kubectl -n fission get service router`.) +(If you do not know the address of the Fission router, you can find it with kubectl: `kubectl -n fission get service router`.) ### Modify the function and re-deploy it -Let's try modifying a function: let's change the `calc-eval` function to support multiplication, too. +Change the `calc-eval` function to support multiplication, too: ```python ... @@ -272,68 +291,98 @@ Let's try modifying a function: let's change the `calc-eval` function to support ... ``` -You can add the above lines to `eval.py`. -To deploy your changes, apply the specs again: +Add the above lines to `eval.py`. +To deploy the change, apply the specs again: ```bash $ fission spec apply --wait +uploading archive archive://eval-xk2p +1 package updated: calc-eval-0f36e9b8 +1 function updated: calc-eval +--- Build SUCCEEDED --- ``` -This should output something like: +Apply detects the changed source, uploads only that archive, rebuilds the package, and updates the function so running pods pick up the new code. +The unchanged `calc-form` function is not touched. +Test the change by entering a `*` for the operator in the form. -```text -1 archive updated: calc-eval-xyz -1 package updated: calc-eval-xyz -1 function updated: calc-eval +### Remove a resource + +To remove a resource, delete its YAML file and apply with `--delete`: + +```bash +$ rm specs/route-f16c8459-3c23-46ad-901f-9312f38cec2a.yaml +$ fission spec apply --delete +1 HTTPTrigger deleted: f16c8459-3c23-46ad-901f-9312f38cec2a ``` -Your new updated function is deployed! -Test it out by entering a `*` for the operator in the form! +`--delete` only removes resources that carry this spec's deployment ID. +To tear down the whole application, run `fission spec destroy`. -### Add dependencies to the function +## Run spec apply from CI (GitOps) -Let's say you'd like to add a pip dependency in `requirements.txt` to your function, and include some libraries in it, so you can `import` them in your functions. -Add a library to the requirements.txt and modify the ArchiveUploadSpec inside specs/function-``.yaml. -Once again, deploying is the same: +Because apply is idempotent and scoped to its deployment ID, a pipeline can run it on every commit: ```bash -$ fission spec apply --wait +fission spec validate +fission spec apply --delete --wait +``` + +* **Safe to re-apply.** A sync with no spec change writes nothing: no rebuilds, no pod restarts, no new function versions. +* **`--delete` completes the loop.** Removing a spec file from Git removes the resource from the cluster on the next apply. + Without it, deletions in Git never reach the cluster. +* **`--wait` fails the pipeline on a failed build**, instead of reporting success while the package is broken. +* **`--commitlabel` records provenance.** Each resource gets a `commit` label with the Git commit hash of its spec file, so you can trace any cluster object back to the commit that produced it. +* **Apply warns on a dirty work tree**, so uncommitted local changes do not silently ship from a workstation. +* **Preview in pull requests.** Run `fission spec apply --dry-run` in the PR pipeline to post what a merge would change. + +### Specs with OCI image packages + +Specs that use `ArchiveUploadSpec` need the `fission` CLI at apply time, because the CLI packages and uploads the source archives. +[OCI image packages](/docs/usage/function/oci-packages/) remove that step: + +```bash +$ fission function create --spec --name hello --env go \ + --oci ghcr.io/example/pkgs/hello:1.2.0@sha256:4c2a... --entrypoint Handler ``` -This command figures out that one function has changed, uploads the source to the cluster, and waits until the Fission builder on the cluster finishes rebuilding this updated source code. +The generated package spec carries only the image reference. +Nothing is uploaded at apply time, and the digest pins exactly what runs. +Your CI builds and pushes the image, then bumps the digest in the spec file; the same spec promotes unchanged across dev, QA, and production. +Because such specs contain only plain Kubernetes resources, a GitOps controller such as Argo CD or Flux can also apply them directly, without the `fission` CLI in the loop. +One exclusion applies: `fission-deployment-config.yaml` is CLI metadata, not a cluster resource, so point the sync at the resource YAMLs only. ## A bit about how this works Kubernetes manages its state as a set of _resources_. -Deployments, Pod, Services are examples of resources. -They represent a target state, and Kubernetes then does the work to ensure this target state is met. +Deployments, Pods, and Services are examples of resources. +They represent a target state, and Kubernetes does the work to reach it. Kubernetes resources can be extended, using _Custom Resources_. -Fission runs on top of Kubernetes and sets up your functions, environments and triggers as Custom Resources. -You can see even these custom resources from `kubectl`: try `kubectl get customresourcedefinitions` or `kubectl get function.fission.io` +Fission runs on top of Kubernetes and stores your functions, environments, and triggers as Custom Resources. +You can see these custom resources with `kubectl`: try `kubectl get customresourcedefinitions` or `kubectl get function.fission.io`. -Your specs directory is, basically, set of resources plus a bit of configuration. -Each YAML file contains one or more resources. -They are separated by a "---" separator. -The resources are functions, environments, triggers. +Your specs directory is a set of these resources plus a bit of configuration. +Each YAML file contains one or more resources, separated by a `---` separator. +The supported kinds are functions, environments, packages, HTTP triggers, message queue triggers, time triggers, Kubernetes watch triggers, [workflows](/docs/usage/workflows/), and [function aliases](/docs/usage/function/versions-aliases/). -There's a special resource there, _ArchiveUploadSpec_. -This is in fact not a resource, just looks like one in the YAML files. -It is used to specify and name a set of files that will be uploaded to the cluster. -`fission spec apply` uses these `ArchiveUploadSpec`s to create archives locally and upload them. -The specs reference these archives using `archive://` URLs. -These aren't "real" URLs; they are replaced by http URLs by the `fission spec` implementation after the archives are uploaded to the cluster. -On the cluster, Archives are tracked with checksums; the Fission CLI only uploads archives when their checksum has changed. +There is one special kind, _ArchiveUploadSpec_. +It is not a cluster resource; it names a set of local files to upload. +`fission spec apply` uses each `ArchiveUploadSpec` to create an archive locally and upload it. +Package specs reference these archives with `archive://` URLs. +These are not real URLs; apply replaces them with HTTP URLs after it uploads the archives. +On the cluster, archives are tracked with checksums, so apply only uploads an archive when its content has changed. -## Improve Portability of Spec (1.7.0+) +## Improve portability of specs -Sometimes you may want to release spec files only without the function source code or the compiled binary. -To improve the portability, you can specify a URL that points to the target archive by following the step described in [here]({{% ref "../function/url-as-archive-source.md" %}}). +Sometimes you may want to release spec files without the function source code or the compiled binary. +You can point the spec at a URL that serves the target archive; see [using a URL as archive source](/docs/usage/function/url-as-archive-source/). +For full GitOps portability, prefer [OCI image packages](#specs-with-oci-image-packages). -## Custom Resources References +## Custom Resource references -You can find the latest definitions for Fission Custom Resources at [doc.crds.dev/github.com/fission/fission](https://doc.crds.dev/github.com/fission/fission) +You can find the definitions for Fission Custom Resources in the [CRD reference](/docs/reference/crd-reference/) and at [doc.crds.dev/github.com/fission/fission](https://doc.crds.dev/github.com/fission/fission). -## More Examples +## More examples For more spec examples, please visit [fission/examples](https://github.com/fission/examples/tree/main/miscellaneous/spec-example). From 97a1d705ca5978edca40860df530b52a7ef3bdde Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:30:57 +0530 Subject: [PATCH 18/26] docs: wire 0026-0030 features into v1.28.0 notes, IA, and What's New --- config.toml | 2 +- content/en/_index.html | 5 ++-- content/en/docs/releases/v1.28.0.md | 36 ++++++++++++++++++++++++++--- content/en/docs/usage/_index.en.md | 2 ++ 4 files changed, 39 insertions(+), 6 deletions(-) diff --git a/config.toml b/config.toml index 5a5bfe39..4b695257 100644 --- a/config.toml +++ b/config.toml @@ -185,7 +185,7 @@ twitter = 'fissionio' [[params.whatsnew]] badge = 'NEW' -body = 'Durable & async Fission: a statestore substrate, fire-and-forget asynchronous invocation with retries and a dead-letter queue, and durable workflows that orchestrate functions as a resumable state machine.' +body = 'Durable & async Fission: a statestore substrate, fire-and-forget asynchronous invocation with retries and a dead-letter queue, broker-free eventing topics, and durable workflows that orchestrate functions as a resumable state machine.' heading = 'Durable & Async Workflows' [params.whatsnew.button] hero_class = 'mid' diff --git a/content/en/_index.html b/content/en/_index.html index 1e2100bc..d735792e 100644 --- a/content/en/_index.html +++ b/content/en/_index.html @@ -345,8 +345,9 @@

A statestore substrate, fire-and-forget asynchronous invocation - with retries and a dead-letter queue, and durable workflows that - orchestrate functions as a resumable state machine. + with retries and a dead-letter queue, broker-free eventing + topics, and durable workflows that orchestrate functions as a + resumable state machine.

- Fission v1.28.0 release notes: durable and asynchronous execution — a statestore substrate, asynchronous invocation with retries and a dead-letter queue, and durable workflows. + Fission v1.28.0 release notes: durable and asynchronous execution — statestore, async invocation, eventing, workflows, function versioning — plus provisioned concurrency, per-function environment variables, smoother upgrades, and GitOps-ready specs. --- {{% notice info %}} @@ -17,21 +17,29 @@ Version numbers, upgrade notes, and the changelog are finalized when v1.28.0 shi All headline features are **opt-in** and off by default, so a routine upgrade changes nothing for an existing install until you enable them. +One set of chart defaults does change: the router and webhook now run two replicas with surge rollouts, and `helm upgrade` applies the CRDs itself through a pre-upgrade hook. +See [Upgrade to 1.28.x release](/docs/installation/upgrade/#upgrade-to-128x-release) for the details and the opt-outs. For the general upgrade steps (CRDs, CLI, Helm chart), see the [Upgrade Guide](/docs/installation/upgrade/). ## Highlights -Fission v1.28.0 is themed around **durable and asynchronous execution** — a shared durable substrate and two ways to build on it — plus first-class **function versioning** for safe rollouts and instant rollbacks. +Fission v1.28.0 is themed around **durable and asynchronous execution** — a shared durable substrate and the features that build on it — plus first-class **function versioning** for safe rollouts and instant rollbacks. +A second group of improvements covers day-2 operation: provisioned warm capacity, per-function environment variables, smoother upgrades, and GitOps-grade specs. - **Statestore — a durable state substrate.** A single interface exposing key/value, an append-only event log, and a visibility-timeout queue, served by a pluggable driver: **embedded** SQLite on a PVC for development, or an **external** Postgres DSN for production and HA. Fission deploys no database product of its own. - It is the foundation the next two features build on. + It is the foundation that asynchronous invocation, eventing, and workflows build on. See [Statestore](/docs/architecture/statestore/). - **Asynchronous invocation — fire-and-forget with durability.** Send `X-Fission-Invoke-Mode: async` (or `fission fn test --async`) and the router enqueues the call, returns a durable invocation id with `202 Accepted`, and delivers it in the background with retries. Per-function delivery config sets the attempt budget and max age; a **dead-letter queue** (`fission function dlq`) captures what cannot be delivered; result **destinations** route the outcome to another function; and an opt-in KEDA `ScaledObject` autoscales the workers on the backlog. See [Asynchronous invocation](/docs/usage/function/async-invocation/). +- **Statestore eventing — durable pub/sub topics with no external broker.** + A topic is a durable, replayable stream on the statestore: `fission topic publish` appends events, and a message queue trigger with `--mqtkind fission --mqtype statestore` subscribes a function. + Delivery is at-least-once with retries, an error topic for events that keep failing, and an optional response topic. + Async invocations can fan their results out to a topic with `--async-on-success-topic`. + See [Statestore Eventing](/docs/usage/triggers/statestore-eventing/). - **Function versions and aliases — publish, promote, roll back.** Every runtime-affecting update can be published as an immutable `FunctionVersion` snapshot (automatically with `spec.versioning.mode: auto`, or explicitly via `fission fn publish`); movable `FunctionAlias` pointers like `prod` and `staging` are what triggers reference; and `fission fn rollback` repoints an alias atomically with no pod churn and no cold start. Weighted aliases split traffic between two versions, canary configs can drive the split automatically, and digest pinning makes aliases GitOps-friendly. @@ -41,6 +49,23 @@ Fission v1.28.0 is themed around **durable and asynchronous execution** — a sh A `Workflow` custom resource is a state machine over your functions; each execution is a `WorkflowRun` recorded step by step in the statestore event log, so a run survives controller restarts, resumes exactly where it stopped, retries transient failures with backoff, and routes typed business errors. States cover `Task`, `Choice`, `Parallel`, `Map`, `Wait`, and `Succeed`/`Fail`, with a `fission workflow` CLI that includes a local day/night graph viewer and a per-run status overlay. See [Workflows](/docs/usage/workflows/). +- **Provisioned concurrency — warm capacity on a schedule.** + Set `--provisioned-concurrency 2` on a poolmgr function and the executor keeps two specialized pods warm before any request arrives, so requests inside the floor never pay a cold start. + Repeatable `--provisioned-schedule` windows raise or lower the floor on a cron schedule — business hours, nightly batches — and the `executor.provisionedConcurrency.enabled` Helm gate turns the feature on. + See [Provisioned Concurrency](/docs/usage/function/provisioned-concurrency/). +- **Per-function environment variables.** + `--env-var` sets literal variables on a function, and `--env-from-secret` / `--env-from-configmap` project single keys (`name/key:ENV`) or whole objects from Secrets and ConfigMaps. + Function env wins over the Environment's pod spec, and platform-reserved names are rejected at admission. + Newdeploy and container executors only for now: poolmgr rejects the fields at admission until phase 2 lands ([fission/fission#3666](https://github.com/fission/fission/issues/3666)). + See [Secrets, ConfigMaps, and Environment Variables](/docs/usage/function/access-secret-cfgmap-in-function/#inject-environment-variables). +- **Smoother upgrades.** + `helm upgrade` now applies the matching CRDs through a pre-upgrade hook, and the router and webhook default to two replicas with surge rollouts and PodDisruptionBudgets, so warm function traffic keeps serving while the control plane rolls. + Zero downtime is the design goal, not yet a guarantee. + See [What happens during an upgrade](/docs/installation/upgrade/#what-happens-during-an-upgrade) for the per-component behavior and the drain-window tuning. +- **GitOps-grade YAML specs.** + `fission spec apply` is idempotent and scoped to a deployment ID: a no-op reapply writes nothing, archives dedupe by checksum, and a source change re-triggers the build. + Pruning is opt-in with `--delete`, `--wait` fails a pipeline on a failed build, `--commitlabel` records provenance, and `--dry-run` previews a merge from a pull request. + See [YAML Specs](/docs/usage/spec/). ## References @@ -48,6 +73,11 @@ Fission v1.28.0 is themed around **durable and asynchronous execution** — a sh - [Asynchronous invocation](/docs/usage/function/async-invocation/) - [Workflows](/docs/usage/workflows/) · [Concept](/docs/concepts/workflows/) · [Authoring](/docs/usage/workflows/authoring/) · [Examples](/docs/usage/workflows/examples/) - [Function versions and aliases](/docs/usage/function/versions-aliases/) · [Lifecycle and interactions](/docs/usage/function/versions-lifecycle/) +- [Statestore Eventing](/docs/usage/triggers/statestore-eventing/) +- [Provisioned Concurrency](/docs/usage/function/provisioned-concurrency/) +- [Secrets, ConfigMaps, and Environment Variables](/docs/usage/function/access-secret-cfgmap-in-function/) +- [Upgrade Guide](/docs/installation/upgrade/) +- [YAML Specs](/docs/usage/spec/) ## Changelog diff --git a/content/en/docs/usage/_index.en.md b/content/en/docs/usage/_index.en.md index bae37a7c..c1f495fc 100644 --- a/content/en/docs/usage/_index.en.md +++ b/content/en/docs/usage/_index.en.md @@ -20,6 +20,7 @@ Work through the function workflow in roughly this order: * [Package source code]({{% ref "function/package.en.md" %}}) — build functions from source archives or ship pre-built deployment packages. * [OCI image packages]({{% ref "function/oci-packages.md" %}}) — ship function code as an OCI image instead of an archive, with cache-friendly cold starts. * [Control function execution]({{% ref "function/executor.en.md" %}}) — choose an executor (poolmgr, newdeploy, or container) and tune scaling, concurrency, and cold starts. +* [Provisioned concurrency]({{% ref "function/provisioned-concurrency.md" %}}) — keep a floor of warm specialized pods, with cron-scheduled warming windows, so requests inside the floor never pay a cold start. * [Run a container as a function]({{% ref "function/container-functions.md" %}}) — turn any existing container image into a Fission function. * [Access secrets and ConfigMaps]({{% ref "function/access-secret-cfgmap-in-function.en.md" %}}) — read Kubernetes Secrets and ConfigMaps from inside a function. * [Access URL parameters]({{% ref "function/accessing-url-params.md" %}}) — read path parameters from REST-style routes. @@ -30,6 +31,7 @@ Work through the function workflow in roughly this order: Durable and asynchronous execution: * [Asynchronous invocation]({{% ref "function/async-invocation.md" %}}) — invoke a function fire-and-forget with a durable id, background retries, a dead-letter queue, and result destinations. +* [Statestore eventing]({{% ref "triggers/statestore-eventing.md" %}}) — publish events to durable built-in topics and subscribe functions with at-least-once delivery, with no external broker. * [Workflows]({{% ref "workflows/_index.md" %}}) — orchestrate several functions as one durable, resumable state machine with parallelism, retries, and durable waits. Operational and advanced topics: From 6cf17ba86194c866f9c4b0cad97bb2be83dca8a1 Mon Sep 17 00:00:00 2001 From: Sanket Sudake Date: Sat, 8 Aug 2026 13:31:16 +0530 Subject: [PATCH 19/26] docs: rebuild metrics reference from source metric definitions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds ~60 missing metrics (router hot-path, async invocation, eventing, statestore, provisioned concurrency, workflows). Marks the page as hand-maintained in the authoring resources — no generator exists. --- .claude/resources/page-patterns.md | 3 +- .claude/resources/seo.md | 2 +- .../en/docs/reference/metrics-reference.md | 72 +++++++++++++++++-- 3 files changed, 70 insertions(+), 7 deletions(-) diff --git a/.claude/resources/page-patterns.md b/.claude/resources/page-patterns.md index 67dd82dc..13a1e69d 100644 --- a/.claude/resources/page-patterns.md +++ b/.claude/resources/page-patterns.md @@ -22,7 +22,8 @@ New top-level sections must slot into this learning path, not append at the end. - Versions in prose: `{{< release-version >}}` / `{{< chart-version >}}` shortcodes, never literals (exceptions: historical rows in `installation/compatibility.md`, release-notes pages about themselves). - One sentence per line in Markdown (renders identically; diffs become per-sentence). - Every page needs a front-matter `description:` — see [seo.md](seo.md) for the SEO/LLM rules. -- Auto-generated pages are off-limits to hand edits: `docs/reference/fission-cli/*`, `crd-reference.md`, `metrics-reference.md`. +- Auto-generated pages are off-limits to hand edits: `docs/reference/fission-cli/*`, `crd-reference.md`. +- `metrics-reference.md` has no generator; update it by hand from the metric definitions in fission source (`pkg/**/metrics.go`). ## Catalog pages (environments, examples) diff --git a/.claude/resources/seo.md b/.claude/resources/seo.md index 0d6c59a4..39136023 100644 --- a/.claude/resources/seo.md +++ b/.claude/resources/seo.md @@ -7,7 +7,7 @@ Established in the SEO/LLM audit round (June 2026). - **Front matter `description:` is required** — one factual sentence (~70–155 chars), task-oriented. It becomes the meta description, og:description, and the page's entry in `/llms.txt` and the markdown mirror. Pages without it fall back to `.Summary` (first ~70 words) — sloppy in SERPs and AI indexes. -Only exception: auto-generated reference pages (`fission-cli/*`, `crd-reference.md`, `metrics-reference.md`). +Only exception: auto-generated reference pages (`fission-cli/*`, `crd-reference.md`). `metrics-reference.md` is hand-maintained from source metric definitions and keeps its description. - **One `

` per page.** Markdown pages get their h1 from the front-matter title — body headings start at `##`. HTML section pages (`_index.html` files) keep exactly one `

` (the hero); later section headings are `

` etc. — styling is class-based, so the tag level is free. - Release pages: `title: "vX.Y.Z Release Notes"` + `linkTitle: vX.Y.Z` (sidebar stays compact, ``/h1 get keywords). diff --git a/content/en/docs/reference/metrics-reference.md b/content/en/docs/reference/metrics-reference.md index 7559e637..af3f1753 100644 --- a/content/en/docs/reference/metrics-reference.md +++ b/content/en/docs/reference/metrics-reference.md @@ -5,7 +5,7 @@ description: > Fission Metrics - List of Prometheus metrics in Fission --- -**Fission exports Prometheus metrics for requests, cold starts, function calls, archive storage, and message-queue triggers, so you can monitor and alert on your deployment.** +**Fission exports Prometheus metrics for requests, cold starts, function calls, archive storage, message-queue triggers, eventing, async invocations, workflows, and the statestore, so you can monitor and alert on your deployment.** {{< notice info >}} To access these metrics, you'll need to install Fission 1.16 or higher. @@ -22,16 +22,78 @@ The table below lists every metric, the component that emits it, its labels, and | http_requests_total | General | path, method, code | Number of requests by path, method and status code | | http_requests_duration_seconds | General | path, method | Time taken to serve the request by path and method | | http_requests_in_flight | General | path, method | Number of requests currently being served by path and method | +| fission_error_span_export_failures_total | General | Nil | Error spans the error-biased exporter failed to send | +| fission_error_span_export_drops_total | General | Nil | Error spans dropped without export because the error-biased exporter was saturated | | fission_function_cold_starts_total | Executor | function_name, function_namespace | How many cold starts are made by function_name, function_namespace | | fission_function_running_seconds | Executor | function_name, function_namespace | The running time (last access - create) in seconds of the function | | fission_function_cold_start_errors_total | Executor | function_name, function_namespace | Count of Fission cold start errors | -| fission_function_calls_total | Router | function_namespace, function_name, path, method, code | Count of Fission function calls | -| fission_function_errors_total | Router | function_namespace, function_name, path, method, code | Count of Fission function errors | -| fission_function_overhead_seconds | Router | function_namespace, function_name, path, method, code | The function call delay caused by Fission. | -| fission_archives_total | StorageSvc | Nil | Number of archives stored | +| fission_executor_specializations_rejected_total | Executor | function_name, function_namespace | Specialization requests rejected at a capacity bound (concurrency cap or in-flight limit) | +| fission_executor_function_service_ensures_total | Executor | result | Count of per-function Service ensure operations by result (created, updated, exists, error) | +| fission_executor_oci_pools_reaped_total | Executor | Nil | Per-image (OCI) warm pools destroyed by the idle pool reaper | +| fission_executor_oci_pool_reap_failures_total | Executor | Nil | Idle-pool reap attempts whose deployment delete failed | +| fission_provisioned_target | Executor | function_name, function_namespace | Desired provisioned-concurrency warm-pod count | +| fission_provisioned_ready | Executor | function_name, function_namespace | Current provisioned-concurrency warm-pod count | +| fission_provisioned_eager_specializations_total | Executor | function_name, function_namespace, outcome | Provisioned eager specialization attempts by outcome (success, error) | +| fission_provisioned_window_transitions_total | Executor | function_name, function_namespace | Provisioned window transitions per function | +| fission_function_calls_total | Router | function_namespace, function_name, function_version, path, method, code | Count of Fission function calls | +| fission_function_errors_total | Router | function_namespace, function_name, function_version, path, method, code | Count of Fission function errors | +| fission_function_overhead_seconds | Router | function_namespace, function_name, function_version, path, method, code | The function call delay caused by Fission. | +| fission_invocation_failures_total | Router | component, reason | Count of failed function invocations attributed by component and reason | +| fission_router_sticky_requests_total | Router | function_namespace, function_name | Requests to sticky-routed functions that carried their sticky key | +| fission_router_sticky_key_missing_total | Router | function_namespace, function_name | Requests to sticky-routed functions missing their sticky key (default pick used) | +| fission_router_route_table_applies_total | Router | result | Route table applications by result (no_change, handler_swapped, shape_changed, rejected) | +| fission_router_mux_rebuilds_total | Router | listener, reason | Full mux rebuilds by listener and reason | +| fission_router_routes | Router | listener | Routes currently in the route table (public = HTTP triggers, internal = functions) | +| fission_router_route_resync_drift_total | Router | Nil | Routes the periodic resync had to correct; a nonzero value means a watch event was missed | +| fission_router_route_resync_failures_total | Router | Nil | Resync passes that failed; the drift guard could not verify the route table this tick | +| fission_router_mux_materialize_failures_total | Router | Nil | Mux materializations that failed before the swap; the served mux is stale until a retry succeeds | +| fission_router_tap_flush_errors_total | Router | Nil | Failed batched tap flushes from the router to the executor | +| fission_router_tap_flush_notfound_total | Router | Nil | Batched tap flushes the executor answered 404 (expired or unknown addresses) | +| fission_router_endpointcache_hits_total | Router | Nil | Requests served from the EndpointSlice endpoint index (no executor RPC) | +| fission_router_endpointcache_misses_total | Router | Nil | Requests with no ready endpoint in the EndpointSlice endpoint index | +| fission_router_endpointcache_endpointlb_picks_total | Router | Nil | Requests dialed directly to a pod IP by the endpoint-LB path (newdeploy/container) | +| fission_router_endpointcache_quarantines_total | Router | Nil | Endpoints quarantined from the index after a dial failure | +| fission_router_endpointcache_dial_timeout_strikes_total | Router | Nil | Soft dial failures (timeouts) recorded against endpoints | +| fission_router_endpointcache_fallbacks_total | Router | reason | Warm-path requests routed to the executor instead of the endpoint index, by reason | +| fission_router_endpointcache_mode | Router | requested, effective, endpoint_lb | Always 1; labels carry the requested and effective EndpointSlice cache modes | +| fission_router_endpointcache_size | Router | Nil | Number of functions with at least one EndpointSlice in the router's endpoint index | +| fission_router_endpointcache_informers | Router | Nil | Number of running per-namespace EndpointSlice informers | +| fission_async_deliveries_total | Router | condition | Count of async invocation delivery attempts, by response condition | +| fission_async_retries_total | Router | Nil | Count of async invocation deliveries requeued for a retry | +| fission_async_dlq_total | Router | reason | Count of async invocations dead-lettered, by reason | +| fission_async_destinations_total | Router | outcome | Count of async destination fires, by outcome | +| fission_async_depth_cap_total | Router | Nil | Count of async destination invocations dropped for exceeding the chain depth cap | +| fission_async_version_fallback_total | Router | Nil | Count of async deliveries that fell back to the bare function route after a 404 on a version-pinned route | +| fission_async_queue_depth | Router | Nil | Async invocation queue depth: visible messages awaiting delivery | +| fission_async_oldest_age_seconds | Router | Nil | Age in seconds of the oldest visible async invocation (0 when none) | +| fission_eventing_egress_queue_depth | Router | mqType | Broker egress queue depth: visible jobs awaiting publish | +| fission_eventing_egress_oldest_age_seconds | Router | mqType | Age in seconds of the oldest visible broker egress job (0 when none) | +| fission_archives | StorageSvc | Nil | Number of archives stored | | fission_archive_memory_bytes | StorageSvc | Nil | Amount of memory consumed by archives | +| fission_storagesvc_legacy_archive_access_total | StorageSvc | Nil | Accesses by a namespace-scoped caller to a legacy (unscoped) archive | | fission_mqt_subscriptions | MqTrigger | Nil | Total number of subscriptions to mq currently | | fission_mqt_messages_processed_total | MqTrigger | trigger_name, trigger_namespace | Total number of messages processed by trigger | | fission_mqt_message_lag | MqTrigger | trigger_name, trigger_namespace, topic, partition | Total number of messages lag per topic and partition | | fission_mqt_inprocess | MqTrigger | Nil | Total number of MQTs in active processing | | fission_mqt_status | MqTrigger | trigger_name, trigger_namespace | Status of an individual trigger 1 if processing otherwise 0 | +| fission_eventing_published_total | Router, MqTrigger | provider, outcome | Count of topic publishes by provider and outcome (published, error, invalid, capped, unsupported) | +| fission_eventing_delivered_total | MqTrigger | condition | Count of topic-event deliveries reaching terminal handling, by condition (success, exhausted) | +| fission_eventing_retries_total | MqTrigger | Nil | Count of topic-event delivery retries | +| fission_eventing_errortopic_total | MqTrigger | outcome | Count of exhausted events routed to the error topic, by outcome (published, error, dropped) | +| fission_eventing_trimmed_total | MqTrigger | reason | Count of topic events trimmed by retention, by reason (mincursor, age, size) | +| fission_eventing_responsetopic_total | MqTrigger | outcome | Count of response-topic publishes after successful deliveries, by outcome (published, error) | +| fission_eventing_gap_events_total | MqTrigger | Nil | Count of topic events a subscription found already trimmed when it resumed | +| fission_eventing_lag | MqTrigger | namespace, trigger | Per-trigger consumer lag (stream head minus committed cursor) | +| fission_eventing_egress_total | MqTrigger | outcome | Count of broker egress job outcomes (published, retry, malformed, settle_failed) | +| fission_statestore_ops_total | StateStore | capability, op | Statestore operations, by capability and op | +| fission_statestore_errors_total | StateStore | capability, op | Statestore operations that returned an error, by capability and op | +| fission_statestore_quota_rejections_total | StateStore | reason | Writes rejected by a scope quota, by reason | +| fission_statestore_conservation_scrape_errors_total | StateStore | Nil | Failures reading a driver's conservation stats; a nonzero value means the drift gauge is stale | +| fission_statestore_conservation_drift | StateStore | Nil | Queue conservation drift (enqueued - inflight - acked - dead); must be zero | +| fission_workflow_runs_total | Workflow | workflow, phase | Workflow runs reaching a terminal phase, by workflow and phase | +| fission_workflow_step_duration_seconds | Workflow | state, outcome | Task step attempt duration (invocation round trip), by workflow state and outcome | +| fission_workflow_active_runs | Workflow | Nil | Runs currently executing (started, not yet terminal) | +| fission_buildermgr_oci_publish_total | BuilderMgr | result | OCI package publish outcomes by result (published, degraded) | +| fission_autopublish_total | BuilderMgr | result | Auto-publish reconcile outcomes by result (created, unchanged, deferred) | +| fission_versiongc_deleted_total | BuilderMgr | Nil | Version retention GC: FunctionVersions deleted | +| fission_versiongc_skipped_total | BuilderMgr | reason | Version retention GC: FunctionVersion deletes skipped, by reason (referenced, forbidden) | From 3cf5bda42358d68d9a2d75d0b09682bce176f492 Mon Sep 17 00:00:00 2001 From: Sanket Sudake <sanketsudake@gmail.com> Date: Sat, 8 Aug 2026 13:31:16 +0530 Subject: [PATCH 20/26] docs: freshness pass on observability & dev-loop pages W3C-only propagators, metricsExporter values, describe VERSIONING output, run-local --secret-mount/--configmap-mount flags. --- content/en/docs/usage/function/debugging.md | 5 ++++ content/en/docs/usage/function/run-local.md | 2 ++ .../docs/usage/observability/opentelemetry.md | 28 +++++++------------ 3 files changed, 17 insertions(+), 18 deletions(-) diff --git a/content/en/docs/usage/function/debugging.md b/content/en/docs/usage/function/debugging.md index 96431354..7a608d55 100644 --- a/content/en/docs/usage/function/debugging.md +++ b/content/en/docs/usage/function/debugging.md @@ -35,8 +35,13 @@ PACKAGE: PODS: NAME READY STATUS AGE poolmgr-...-abcd 2/2 Running 5m + +VERSIONING: + Versioning: disabled ``` +For a function with [versioning]({{% ref "versions-aliases.md" %}}) enabled, the `VERSIONING` section lists the mode, the version count, and the aliases. + The **`Invocable`** line answers "can I call this right now?": | `Invocable` value | Meaning | diff --git a/content/en/docs/usage/function/run-local.md b/content/en/docs/usage/function/run-local.md index 07afa362..b4014c7e 100644 --- a/content/en/docs/usage/function/run-local.md +++ b/content/en/docs/usage/function/run-local.md @@ -169,6 +169,8 @@ Functions usually need configuration and secrets. * `--env-from <file>` — read environment variables from a file (one `KEY=VALUE` per line); `-e` overrides individual keys. * `--secret <name>` / `--configmap <name>` — materialize a cluster `Secret`/`ConfigMap` and mount it the way the cluster does, under `/secrets/<namespace>/<name>` and `/configs/<namespace>/<name>` (see [Accessing Secrets and ConfigMaps]({{% ref "access-secret-cfgmap-in-function.en.md" %}})). These require a reachable cluster to read the objects from. +* `--secret-mount <name>=<path>` / `--configmap-mount <name>=<path>` — mount the object at a custom path relative to `/secrets` or `/configs`, matching the function's `spec.secrets[].mountPath` / `spec.configmaps[].mountPath` in-cluster. + Repeatable; without it an object lands at the default `/secrets/<namespace>/<name>` layout. #### Attaching a debugger diff --git a/content/en/docs/usage/observability/opentelemetry.md b/content/en/docs/usage/observability/opentelemetry.md index 09290ff1..45d12657 100644 --- a/content/en/docs/usage/observability/opentelemetry.md +++ b/content/en/docs/usage/observability/opentelemetry.md @@ -33,8 +33,9 @@ The chart translates each value into a standard `OTEL_*` environment variable th | `openTelemetry.otlpHeaders` | `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated key-value pairs sent as headers on gRPC/HTTP export requests | | `openTelemetry.tracesSampler` | `OTEL_TRACES_SAMPLER` | Sampler for traces | | `openTelemetry.tracesSamplingRate` | `OTEL_TRACES_SAMPLER_ARG` | Argument for the sampler | -| `openTelemetry.propagators` | `OTEL_PROPAGATORS` | Propagator(s) used to generate and read the trace-id header | +| `openTelemetry.propagators` | `OTEL_PROPAGATORS` | Kept for chart compatibility. Fission components always propagate with W3C Trace Context + Baggage and do not honor other values — see [Trace propagation](#trace-propagation). | | `openTelemetry.logsEnabled` | `OTEL_LOGS_ENABLED` | `true`/`false` (default `false`). When enabled alongside a collector endpoint, control-plane components also push their structured logs (carrying `trace_id`) to the OTLP collector, not just traces. | +| `openTelemetry.metricsExporter` | `OTEL_METRICS_EXPORTER` | Metrics exporter selection (default `prometheus`). The Prometheus `/metrics` scrape always stays on; set `otlp` (or `prometheus,otlp`) to also push metrics over OTLP to the collector. | Without a configured collector endpoint, you won't be able to visualize traces. Depending on your sampler configuration, you can still observe `trace_id` in Fission component logs. @@ -57,34 +58,25 @@ Set `OTEL_TRACES_SAMPLER` to one of the following: | Sampler | Behavior | | ------- | -------- | -| `always_on` | Always samples spans, regardless of the parent span's sampling decision. | -| `always_off` | Never samples spans, regardless of the parent span's sampling decision. | +| `always_on` | Treated the same as `parentbased_always_on`. | +| `always_off` | Treated the same as `parentbased_always_off`. | | `traceidratio` | Samples probabilistically based on rate. | | `parentbased_always_on` | Respects the parent span's sampling decision, but otherwise always samples. Default if `OTEL_TRACES_SAMPLER` is empty. | | `parentbased_always_off` | Respects the parent span's sampling decision, but otherwise never samples. | | `parentbased_traceidratio` | Respects the parent span's sampling decision, but otherwise samples probabilistically based on rate. Default in the chart. | +An unknown sampler value falls back to `parentbased_always_on`. + #### Sampler arguments Only `traceidratio` and `parentbased_traceidratio` take an argument, set via `OTEL_TRACES_SAMPLER_ARG`: a sampling probability in the [0..1] range, e.g. `"0.1"`. Default is 0.1. -### Types of propagators - -The propagator type determines which header OpenTelemetry uses to generate and read the trace ID. -Set `OTEL_PROPAGATORS` to one of the following: - -| Propagator | Header | -| ---------- | ------ | -| `tracecontext` | W3C Trace Context | -| `baggage` | W3C Baggage | -| `b3` | B3 Single | -| `b3multi` | B3 Multi | -| `jaeger` | Jaeger `uber-trace-id` header | -| `xray` | AWS X-Ray (third party) | -| `ottrace` | OpenTracing Trace (third party) | +### Trace propagation -Change the propagator when you need a header other than W3C Trace Context — for example, set it to `jaeger` if you're integrating with OpenTracing/Jaeger. +Fission components propagate trace context with the W3C Trace Context and Baggage propagators. +Other propagator types (`b3`, `b3multi`, `jaeger`, `xray`, `ottrace`) are not honored; the non-W3C propagator modules were dropped to reduce the binary footprint. +The `openTelemetry.propagators` value still injects `OTEL_PROPAGATORS` into every pod, so a function that runs its own OpenTelemetry SDK can read it — but Fission's own components ignore it. ## Sample OTEL Collector From 1b133679c03bd70db62a17680aede975e8e5c25b Mon Sep 17 00:00:00 2001 From: Sanket Sudake <sanketsudake@gmail.com> Date: Sat, 8 Aug 2026 13:31:16 +0530 Subject: [PATCH 21/26] docs: refresh installation auth pages against pre-release hardening internal-auth: existingSecret/autoGenerate, fail-closed startup check, namespace replication, uninstall retention. authentication: secretKeyRef correction, existingSecret value, GitOps note. --- .../en/docs/installation/authentication.md | 12 ++++- content/en/docs/installation/internal-auth.md | 50 +++++++++++++++++-- 2 files changed, 56 insertions(+), 6 deletions(-) diff --git a/content/en/docs/installation/authentication.md b/content/en/docs/installation/authentication.md index 91574fc7..cb8d471f 100644 --- a/content/en/docs/installation/authentication.md +++ b/content/en/docs/installation/authentication.md @@ -2,7 +2,7 @@ title: "Authentication" weight: 40 description: > - Guide to set up basic authentication with Fission + Enable JWT authentication for Fission function invocations and generate tokens with the Fission CLI. --- ## Authentication for Fission Functions @@ -20,7 +20,7 @@ When enabled, a new endpoint for authentication will be registered in the router All the API calls to Fission functions will now be routed through function endpoints using authentication token. Fission also creates a Secret named `router` in the `fission` namespace with a default `username`, a randomly generated `password`, and a `jwtSigningKey`. -This Secret is mounted as a volume on the router pod. +The router reads these values through `secretKeyRef` environment variables. You first create an auth token by providing the `username` and `password`. The generated token must then be passed in the `Authorization` header of every subsequent function call. @@ -67,6 +67,11 @@ authentication: ## If left empty, the chart generates a random key on install. jwtSigningKey: + ## existingSecret names a pre-created Secret in the release namespace + ## with the keys username, password, and jwtSigningKey. + ## When set, the chart does not generate the "router" Secret. + existingSecret: + ## jwtExpiryTime is the JWT expiry time in seconds. ## default '120' jwtExpiryTime: @@ -76,6 +81,9 @@ authentication: jwtIssuer: fission ``` +On GitOps renderers (Argo CD, Flux), set `authentication.existingSecret` to a Secret you create yourself. +Those run `helm template`, where the chart cannot preserve the generated `password` and `jwtSigningKey` across syncs — each sync would mint fresh values and invalidate issued tokens. + Refer to the [installation guide]({{% ref "_index.en.md" %}}) if you are installing Fission for the first time, or to the [Upgrade Guide]({{% ref "upgrade.md" %}}) if you are upgrading from an older version. ## Generating Auth Token diff --git a/content/en/docs/installation/internal-auth.md b/content/en/docs/installation/internal-auth.md index ed005b4a..77fa2121 100644 --- a/content/en/docs/installation/internal-auth.md +++ b/content/en/docs/installation/internal-auth.md @@ -42,10 +42,19 @@ The public listener is unchanged for user `HTTPTrigger` traffic. helm install fission fission-charts/fission-all -n fission --create-namespace ``` -The chart materialises a `Secret/fission-internal-auth` with an auto-generated 32-byte master key. +The chart materializes a `Secret/fission-internal-auth` with an auto-generated 32-byte master key. The same value is preserved across `helm upgrade` runs. +Under static tenancy the chart replicates the Secret into `defaultNamespace` and each `additionalFissionNamespaces` entry, so dynamically created builder and function pods can mount it too. Every Fission control-plane component (storagesvc, executor, router, buildermgr, and the rest) and every dynamically-created builder/function pod mounts the master via environment variable; each signer/verifier pair derives its own per-service key. +### Fail-closed startup check + +Every binary — fission-bundle, fetcher, builder, and the CLI — validates the internal-auth environment at startup. +An absent `FISSION_INTERNAL_AUTH_SECRET` means internal auth is off; signers and verifiers pass through. +A present but blank value is refused: the process exits with an error that names the variable. +This closes the one misconfiguration that previously failed open — a Secret with an empty `secret` key silently disabled HMAC verification. +The same check covers the rotation variable `FISSION_INTERNAL_AUTH_SECRET_OLD`. + ## Bring your own master secret Pass an explicit master secret at install time to skip the auto-generated key: @@ -55,7 +64,37 @@ helm install fission fission-charts/fission-all -n fission \ --set internalAuth.secret="$(openssl rand -base64 32)" ``` -If `internalAuth.secret` is set, the chart honours it instead of auto-generating one. +If `internalAuth.secret` is set, the chart honors it instead of auto-generating one. + +## Use a pre-created Secret (`existingSecret`) + +Point the chart at a Secret you create and manage yourself: + +```bash +kubectl create secret generic fission-auth-master -n fission \ + --from-literal=secret="$(openssl rand -base64 32)" + +helm install fission fission-charts/fission-all -n fission \ + --set internalAuth.existingSecret=fission-auth-master +``` + +The Secret must hold the key `secret`, and during rotation the optional key `oldSecret`. +With `internalAuth.existingSecret` set, the chart renders no master Secret; every component reads yours. + +Create the Secret in every namespace where Fission runs pods: the release namespace, `defaultNamespace`, and each `additionalFissionNamespaces` entry. +kubelet cannot resolve a cross-namespace `secretKeyRef`, so a single copy in the release namespace leaves builder and function pods starting but returning 401 on every archive fetch and builder upload. +Under dynamic or cluster tenancy, only the release namespace needs the Secret. + +This is the recommended path for GitOps renderers (Argo CD, Flux). +Those run `helm template`, where the chart cannot preserve a generated value across syncs — each sync would mint a new master and break every running pod. +Switching an existing install to `existingSecret` is safe: a pre-upgrade hook marks the chart-generated Secret with `helm.sh/resource-policy=keep`, so Helm does not prune it. + +As an alternative for GitOps, `internalAuth.autoGenerate=true` (default `false`) moves generation into a pre-install/pre-upgrade hook that creates the master Secret in-cluster only if it is absent, so no renderer re-mints it. +The hook is admission-fenced by a `ValidatingAdmissionPolicy`: it can create only the master Secret, and only as a plain `Opaque` object. + +The CLI discovers the Secret name from the cluster it talks to. +The precedence is: an explicit `FISSION_INTERNAL_AUTH_SECRET_NAME` environment variable, then the name stamped on the executor Deployment, then the default `fission-internal-auth`. +If your CLI user cannot read Deployments and the install uses a non-default name, set `FISSION_INTERNAL_AUTH_SECRET_NAME` explicitly. ## Disable everywhere @@ -97,13 +136,16 @@ helm upgrade fission fission-charts/fission-all -n fission \ Because every per-service key is derived from the master via HKDF, this single sequence rotates the key for all five channels atomically. +`helm uninstall` no longer removes the master Secret: the chart marks it `helm.sh/resource-policy=keep`, and a reinstall reuses the surviving value. +To force a rotation after a suspected compromise, delete `Secret/fission-internal-auth` in every namespace it was replicated into, or set new values for `internalAuth.secret`. + ## Toggle interaction matrix The verifier (server) and signer (client) toggles are set independently per rollout, so mixed states are possible; this table shows the outcome of each combination: | Server (verifier) | Client (signer) | Outcome | |---|---|---| -| OFF | OFF | All requests pass through unsigned — identical to pre-v1.23 in-cluster behaviour | +| OFF | OFF | All requests pass through unsigned — identical to pre-v1.23 in-cluster behavior | | ON | ON | All signed and verified per-service (default) | | ON | OFF | Client request returns **401** | | OFF | ON | Client sends signed headers; server pass-through ignores them — works | @@ -126,7 +168,7 @@ Operators have two options until signing-aware KEDA images ship: Services that publish to the router internal listener (`kubewatcher`, `timer`, `mqt-fission-kafka`, `mqt-keda`) now read `ROUTER_INTERNAL_URL`. The chart sets it to `http://router-internal.<namespace>:<router.internalPort>` (port `8889` by default) using the dedicated `router-internal` Service. -If you customise the router `Service` name, namespace, or `router.internalPort`, set this env override accordingly. +If you customize the router `Service` name, namespace, or `router.internalPort`, set this env override accordingly. ## Reference From e0fa5fa6e7fb65464c9f9ee19d6694308bb39e13 Mon Sep 17 00:00:00 2001 From: Sanket Sudake <sanketsudake@gmail.com> Date: Sat, 8 Aug 2026 13:31:16 +0530 Subject: [PATCH 22/26] docs: streaming + MCP freshness fixes Idle-timeout is a router env var not a chart value; fission function tools real output columns; /mcp endpoint details. --- content/en/docs/usage/function/mcp-tools.md | 12 ++++++++---- content/en/docs/usage/function/streaming.md | 15 ++++++++++++--- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/content/en/docs/usage/function/mcp-tools.md b/content/en/docs/usage/function/mcp-tools.md index ebd0837e..959e8622 100644 --- a/content/en/docs/usage/function/mcp-tools.md +++ b/content/en/docs/usage/function/mcp-tools.md @@ -50,6 +50,7 @@ It listens on a `ClusterIP` Service on port `8890` by default (`mcp.port`). {{% notice warning %}} In production, leave `mcp.allowInsecure: false` and run with [authentication]({{% ref "/docs/installation/authentication.md" %}}) enabled. Agents then authenticate with a signed JWT whose `allowed_namespaces` claim scopes which functions they may see and call. +Enabling MCP with authentication off and `mcp.allowInsecure: false` fails the chart render. {{% /notice %}} ## Expose a function as a tool @@ -79,11 +80,12 @@ When omitted, the tool advertises an open object schema (`{"type":"object"}`). ```bash $ fission function tools -NAME FUNCTION NAMESPACE DESCRIPTION -default-weather weather default Return the current weather for a city +TOOL FUNCTION NAMESPACE DESCRIPTION EXPOSED +default-weather weather default Return the current weather for a city True ``` -Use `-o wide`, `-o json`, or `-o yaml` for more detail. +The `EXPOSED` column shows the function's `ToolExposed` status condition — `True` once the MCP server advertises the tool. +`-o wide` adds an `AGE` column; use `-o json` or `-o yaml` for full detail. ## Declarative spec @@ -115,7 +117,9 @@ spec: ## How agents reach the tools -Point an MCP-capable agent at the MCP server's endpoint (the `mcp` Service on port `8890`, exposed however you route in-cluster traffic — for example through an [HTTP trigger]({{% ref "/docs/usage/triggers/http-trigger.md" %}}) or your ingress/gateway). +Point an MCP-capable agent at the MCP server's Streamable HTTP endpoint: `http://mcp.<fission-namespace>:8890/mcp`. +The `mcp` Service is `ClusterIP`-only and never joins the router's public listener. +Expose it deliberately with an Ingress, a Gateway, or `kubectl port-forward`. With authentication enabled, the agent presents a bearer JWT and only sees tools in its `allowed_namespaces`. When the agent calls a tool, the MCP server invokes the underlying function through Fission's internal invocation path and returns the response. diff --git a/content/en/docs/usage/function/streaming.md b/content/en/docs/usage/function/streaming.md index fc1f3161..92ca9f5a 100644 --- a/content/en/docs/usage/function/streaming.md +++ b/content/en/docs/usage/function/streaming.md @@ -51,7 +51,7 @@ fission fn update --name chat --streaming=false | --- | --- | --- | | `--streaming` | off | Enable streaming responses for the function. Disable on update with `--streaming=false`. | | `--streamingprotocol` | `auto` | Streaming protocol: `auto`, `sse`, `chunked`, or `websocket`. `auto` covers all cases; `websocket` signals intent (the upgrade is detected from the request). | -| `--streamingidletimeout` | `60` | Abort the stream if no bytes flow from the function for this many seconds; reset on each chunk. Also bounds time-to-first-byte. | +| `--streamingidletimeout` | `60` | Abort the stream if no bytes flow from the function for this many seconds; reset on each chunk. Also bounds time-to-first-byte. Not applied after a WebSocket upgrade. | | `--streamingmaxduration` | `0` | Hard ceiling (seconds) on total stream lifetime; `0` means no ceiling. | ## How streaming changes timeouts @@ -97,6 +97,9 @@ wscat -c ws://<router>/ws WebSocket is now first-class for **every** environment, not just the Python GEVENT environment. The router upgrades the connection and holds the function pod for the socket's whole lifetime (a router-driven keepalive), and the `main(ws, clients)` programming model is unchanged. +After the `101` upgrade the router pipes bytes both ways and cannot observe idle time, so the idle timeout only bounds the time to upgrade. +Set `--streamingmaxduration` to bound the socket's total lifetime. + {{% notice warning %}} The legacy Python `socket_tracker.py` keepalive mechanism still works but is **deprecated in favor of the streaming approach** and is targeted for removal in a future release. New environment images should drop calls to the fetcher `/wsevent` endpoints and rely on the streaming WebSocket path. @@ -124,8 +127,14 @@ spec: ## Cluster default -The optional router environment variable `ROUTER_STREAM_IDLE_TIMEOUT` sets the cluster-wide default idle window, which per-function `idleTimeoutSeconds` overrides. -It is a router (Helm) setting; see [Customizing the chart](/docs/installation/upgrade/#configuration). +The optional router environment variable `ROUTER_STREAM_IDLE_TIMEOUT` sets the cluster-wide default idle window. +Per-function `idleTimeoutSeconds` overrides it. +The value is a Go duration string (for example `90s`) and must be positive — unlike the per-function flag, which takes integer seconds. +The Helm chart does not surface this variable; set it on the router deployment directly: + +```bash +kubectl set env deployment/router -n fission ROUTER_STREAM_IDLE_TIMEOUT=90s +``` ## Related From c4c7b9b8e97a3ddb26db7338a01754ada51dfc21 Mon Sep 17 00:00:00 2001 From: Sanket Sudake <sanketsudake@gmail.com> Date: Sat, 8 Aug 2026 13:31:16 +0530 Subject: [PATCH 23/26] docs: OCI packages + Gateway API freshness fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Image-volume delivery is default-on (auto-gated below K8s 1.33); drop the dead defaultParentRef flow — the CRD CEL rule requires explicit parentRefs. --- .../en/docs/usage/function/oci-packages.md | 28 +++++++++++-------- content/en/docs/usage/gateway-api/_index.md | 11 ++------ 2 files changed, 18 insertions(+), 21 deletions(-) diff --git a/content/en/docs/usage/function/oci-packages.md b/content/en/docs/usage/function/oci-packages.md index b75463f2..53b5a318 100644 --- a/content/en/docs/usage/function/oci-packages.md +++ b/content/en/docs/usage/function/oci-packages.md @@ -78,7 +78,7 @@ You can also build code images without a Docker daemon using [`crane`](https://g ```bash $ tar -cf code.tar hello.py -$ crane append --base scratch --new_layer code.tar \ +$ crane append --new_layer code.tar \ --new_tag registry.example.com/myteam/hello-code:v1 ``` @@ -183,8 +183,10 @@ Code-image pulls resolve credentials in this order: 3. **Anonymous** access. Both secret sources are resolved in the namespace the function pods run in. -For functions in the `default` namespace that is the configured function namespace (`fission-function` in many installs); for functions in other namespaces it is the function's own namespace. +By default that is the function's own namespace. +When your install sets the `functionNamespace` Helm value, functions in the `default` namespace run in that namespace instead. Confirm with `kubectl get pods -l environmentName=<env> -A` if unsure. +The examples below use `default`; substitute your function-pod namespace. ##### Step 1 — create a registry secret @@ -192,7 +194,7 @@ Create a standard `docker-registry` secret in the function-pod namespace (see th ```bash $ kubectl create secret docker-registry regcred \ - --namespace fission-function \ + --namespace default \ --docker-server=registry.example.com \ --docker-username=ci-bot \ --docker-password="$REGISTRY_TOKEN" @@ -204,7 +206,7 @@ Patch the `fission-fetcher` service account in the same namespace; every OCI pac ```bash $ kubectl patch serviceaccount fission-fetcher \ - --namespace fission-function \ + --namespace default \ -p '{"imagePullSecrets": [{"name": "regcred"}]}' ``` @@ -233,12 +235,12 @@ spec: Create a function on the package and invoke it; on a credential problem the function returns a 5xx and the fetcher log names the registry error: ```bash -$ kubectl logs <function-pod> -c fetcher -n fission-function | grep -i "error extracting OCI image" +$ kubectl logs <function-pod> -c fetcher -n default | grep -i "error extracting OCI image" ``` {{% notice warning %}} Fission does not validate that the referenced secrets exist or hold working credentials — a missing or wrong secret surfaces only at pull time. -With [image volumes](#optional-mount-code-with-kubernetes-image-volumes) enabled, the **kubelet** performs the pull using the same two secret sources (the pod inherits both), so the same setup keeps working — but pull errors then appear as pod events (`kubectl describe pod`, `ErrImagePull`) rather than fetcher logs. +With [image volumes](#kubernetes-image-volumes) active (the default on Kubernetes 1.33+), the **kubelet** performs the pull using the same two secret sources (the pod inherits both), so the same setup keeps working — but pull errors then appear as pod events (`kubectl describe pod`, `ErrImagePull`) rather than fetcher logs. {{% /notice %}} Runtime/environment images are pulled by the kubelet independently of package images; for those, see [Pull an Image From a Private Registry]({{% ref "/docs/usage/function/private-registry.md" %}}). @@ -256,23 +258,25 @@ fetcher: This is a comma-separated host allowlist, not a global switch — every other registry still requires TLS. Localhost and private (RFC-1918) IP addresses are implicitly trusted by the underlying client, matching Docker's behavior. -#### Optional: mount code with Kubernetes image volumes +#### Kubernetes image volumes -By default the per-pod fetcher pulls and extracts the image (this works on every supported Kubernetes version). -On Kubernetes **1.33+** you can instead let the **kubelet** mount the code image directly into function pods as an [image volume](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/), removing the fetch-and-extract step from the cold-start path entirely: +On Kubernetes **1.33+** the **kubelet** mounts the code image directly into function pods as an [image volume](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/), removing the fetch-and-extract step from the cold-start path entirely. +This is **on by default** (`executor.enableOCIImageVolume: true` in the Helm chart). +On clusters below 1.33 image volumes are detected as unsupported, and packages automatically use the per-pod fetcher, which pulls and extracts the image itself. +To force the fetcher path on every cluster, disable the setting: ```yaml executor: - enableOCIImageVolume: true + enableOCIImageVolume: false ``` -On clusters below 1.33 the setting is detected as unsupported and packages silently stay on the fetcher path. Be aware of the behavioral differences when image volumes are active: * **The kubelet pulls the image, not Fission.** Image references resolve with the node's DNS and containerd's registry configuration — a registry reachable only through cluster DNS (a ClusterIP `Service` name) will not resolve. Use a registry address that nodes can reach. -* Poolmgr functions that reference **Secrets or ConfigMaps**, and functions on **v1 environments**, automatically fall back to the fetcher path (those features need the fetcher inside the pod). +* Functions that reference **Secrets or ConfigMaps** still mount the code as an image volume; their pods keep the fetcher, which materializes those Secrets and ConfigMaps. +* Poolmgr functions on **v1 environments**, and those whose environment sets `allowedFunctionsPerContainer: infinite` or `keepArchive: true`, stay on the fetcher path. * The code mount is **read-only**. Runtimes that write next to the code (Python bytecode caches, JVM work files) should write elsewhere; the standard Fission environments handle this. * `subPath` must point to a **directory** inside the image (kubelets reject file sub-paths). diff --git a/content/en/docs/usage/gateway-api/_index.md b/content/en/docs/usage/gateway-api/_index.md index c26b803e..7f5c5631 100644 --- a/content/en/docs/usage/gateway-api/_index.md +++ b/content/en/docs/usage/gateway-api/_index.md @@ -42,7 +42,7 @@ flowchart TB When an HTTPTrigger sets `routeConfig.provider: gateway`, the router: - Creates an `HTTPRoute` named after the trigger, in the **router's own namespace** (`fission` by default). -- Sets the route's `parentRefs` to the Gateway(s) you specify (or a cluster-wide default Gateway). +- Sets the route's `parentRefs` to the Gateway(s) you specify. - Sets the route's `hostnames` and a `PathPrefix` match from your config. - Points the route's backend at the `router` Service on port 80 — the same backend the Ingress path used. - Labels the route with `triggerName`, `functionName`, and `triggerNamespace` so you can find it with `kubectl get httproute -l triggerName=<name> -n fission`. @@ -66,13 +66,6 @@ helm upgrade --install fission fission-charts/fission-all \ --set gatewayAPI.enabled=true ``` -Optionally configure a **default Gateway** that triggers attach to when they don't name their own. -The value is `name` or `namespace/name`: - -```bash - --set gatewayAPI.defaultParentRef=fission-gateways/shared-gw -``` - When `gatewayAPI.enabled=true`, the chart adds RBAC for the router to manage `httproutes` (and read `referencegrants`). If you request the `gateway` provider on a trigger while this is disabled, the router logs a warning and creates no route. @@ -186,7 +179,7 @@ spec: Notes: - `provider` is required. - When it is `gateway`, you must supply at least one `parentRef` **unless** the router is configured with a default Gateway (`gatewayAPI.defaultParentRef`). + When it is `gateway`, you must supply at least one `parentRef` — CRD validation rejects the trigger otherwise. - `tls` applies only to the ingress provider and is rejected by validation when `provider: gateway` (gateway TLS lives on the Gateway listener). - `routeConfig` takes precedence over the deprecated `createingress` + `ingressconfig` fields. From d254106724e57a8d984a0be19e17b3a78d05c9b3 Mon Sep 17 00:00:00 2001 From: Sanket Sudake <sanketsudake@gmail.com> Date: Sat, 8 Aug 2026 13:46:16 +0530 Subject: [PATCH 24/26] docs: Simplified Technical English + Tufte clarity sweep Sentence-splitting to ASD-STE100 caps, active voice, filler removal, one-sentence-per-line formatting across the 30 branch-touched pages. Verified per cluster: no command, flag, value, caveat, or link target changed; two meaning-drift edits caught and restored in verification. --- content/en/docs/architecture/_index.md | 13 ++-- content/en/docs/architecture/statestore.md | 12 ++-- content/en/docs/concepts/_index.md | 3 +- content/en/docs/concepts/workflows.md | 36 +++++++--- .../en/docs/installation/authentication.md | 41 +++++------ content/en/docs/installation/internal-auth.md | 30 +++++--- content/en/docs/installation/upgrade.md | 70 +++++++++++++------ content/en/docs/releases/v1.28.0.md | 45 ++++++++---- content/en/docs/usage/_index.en.md | 2 +- .../access-secret-cfgmap-in-function.en.md | 10 ++- .../docs/usage/function/async-invocation.md | 15 ++-- .../docs/usage/function/canary-deployments.md | 15 ++-- content/en/docs/usage/function/debugging.md | 27 ++++--- content/en/docs/usage/function/keyed-state.md | 44 ++++++++---- content/en/docs/usage/function/mcp-tools.md | 6 +- .../en/docs/usage/function/oci-packages.md | 60 ++++++++++------ .../usage/function/provisioned-concurrency.md | 18 +++-- content/en/docs/usage/function/run-local.md | 31 +++++--- content/en/docs/usage/function/streaming.md | 10 +-- .../docs/usage/function/versions-aliases.md | 48 +++++++++---- .../docs/usage/function/versions-lifecycle.md | 29 +++++--- content/en/docs/usage/gateway-api/_index.md | 10 +-- .../docs/usage/observability/opentelemetry.md | 56 ++++++++------- content/en/docs/usage/spec/_index.md | 18 +++-- content/en/docs/usage/triggers/_index.md | 7 +- .../usage/triggers/statestore-eventing.md | 6 +- content/en/docs/usage/workflows/_index.md | 14 ++-- content/en/docs/usage/workflows/authoring.md | 15 ++-- content/en/docs/usage/workflows/examples.md | 14 ++-- .../docs/usage/workflows/run-and-inspect.md | 9 ++- 30 files changed, 467 insertions(+), 247 deletions(-) diff --git a/content/en/docs/architecture/_index.md b/content/en/docs/architecture/_index.md index dd6f1be0..94c7d11e 100644 --- a/content/en/docs/architecture/_index.md +++ b/content/en/docs/architecture/_index.md @@ -6,7 +6,8 @@ description: > How Fission's components fit together to build, route, and run your functions on Kubernetes. --- -**This page maps how Fission's components fit together and how a request flows through them, so you know which ones to learn first.** +**This page maps how Fission's components fit together and how a request flows through them.** +**It shows which ones to learn first.** Fission is built from a set of small components that run inside your Kubernetes cluster. Together they turn a function's source code into a running pod and route requests to it on demand. @@ -17,8 +18,11 @@ It helps to split the components into two groups. ## Architecture overview -The diagram below shows how the components cooperate: blue boxes are Fission services, teal dashed boxes are the pods they manage, and the numbered arrows trace the build path (1–6) and the request path (7–10). -Conceptually the Executor, Builder Manager, and Admission Webhook form the **control plane** (they watch your Fission resources and reconcile the cluster toward them), while the Router, function pods, and StorageSvc form the **data plane** (they carry an actual request to your function). +The diagram below shows how the components cooperate. +Blue boxes are Fission services, and teal dashed boxes are the pods they manage. +Numbered arrows trace the build path (1–6) and the request path (7–10). +Conceptually, the Executor, Builder Manager, and Admission Webhook form the **control plane**: they watch your Fission resources and reconcile the cluster toward them. +The Router, function pods, and StorageSvc form the **data plane**: they carry an actual request to your function. ```mermaid flowchart TB @@ -107,7 +111,8 @@ A durable state substrate (key/value, event log, queue) that backs durable workf ### [Controller]({{% ref "controller.md" %}}) The old REST API server. -It was deprecated in Fission 1.18.0 and is no longer part of the default architecture — clients now talk directly to the Kubernetes API server and Fission CRDs. +It was deprecated in Fission 1.18.0 and is no longer part of the default architecture. +Clients now talk directly to the Kubernetes API server and Fission CRDs. See the [Controller page]({{% ref "controller.md" %}}) for migration guidance. ## Related diff --git a/content/en/docs/architecture/statestore.md b/content/en/docs/architecture/statestore.md index 0244859f..f8a1c3fe 100644 --- a/content/en/docs/architecture/statestore.md +++ b/content/en/docs/architecture/statestore.md @@ -8,7 +8,9 @@ description: > **The statestore is the durable substrate the control plane writes to when a feature needs state that outlives a single request or a single pod.** It exposes three capabilities behind one interface — a **key/value** store, an append-only **event log**, and a visibility-timeout **queue** — served by a pluggable driver. -Fission itself never deploys a database product: you either use the bundled embedded driver for development, or point the external driver at a database you already run. +Fission itself never deploys a database product. +For development, use the bundled embedded driver. +For production, point the external driver at a database you already run. The statestore is what makes Fission's newer durable features possible. Starting with Fission {{< release-version >}}, several subsystems build on it: @@ -18,7 +20,8 @@ Starting with Fission {{< release-version >}}, several subsystems build on it: - **[Function state]({{% ref "/docs/usage/function/keyed-state.md" %}})** gives a function a private keyspace of durable key/value entries — counters, sessions, carts, agent memory — with no external Redis or database. - **Eventing** uses the event log and queue as its zero-broker transport. -The statestore is off by default; a feature that needs it will tell you to enable it. +The statestore is off by default. +A feature that needs it tells you to enable it. ```mermaid flowchart TB @@ -52,7 +55,8 @@ flowchart TB ## Embedded vs external The driver is chosen with `statestore.mode`. -The two modes differ only in where the state lives; the interface the features use is identical. +The two modes differ only in where the state lives. +The interface the features use is identical. | Mode | Driver | Where state lives | Use it for | | --- | --- | --- | --- | @@ -99,8 +103,6 @@ helm upgrade --install fission fission-charts/fission-all \ | `statestore.embedded.size` | `1Gi` | Size of the PVC backing the embedded SQLite file. | | `statestore.external` | — | Name of the DSN Secret for external mode (defaults to `statestore-postgres`, key `dsn`). | -Fission runs no database of its own in either mode: embedded is a file on a volume, and external is a database you already operate. - ## Related - [Durable Workflows]({{% ref "/docs/usage/workflows/_index.md" %}}) — multi-step orchestration recorded in the event log. diff --git a/content/en/docs/concepts/_index.md b/content/en/docs/concepts/_index.md index c18264a7..50868466 100644 --- a/content/en/docs/concepts/_index.md +++ b/content/en/docs/concepts/_index.md @@ -21,7 +21,8 @@ Everything in Fission is built from four core objects, each backed by a Kubernet - A **Trigger** binds an event source (an HTTP request, a timer, a message-queue message, a Kubernetes event) to a function invocation. - A **Package** holds your code as archives and ties it to an environment, optionally building source into a runnable artifact. -The relationship is simple: a Trigger fires, the request reaches your Function, and your Function runs inside a pod created from its Environment, using the code stored in its Package. +A Trigger fires and the request reaches your Function. +Your Function runs inside a pod created from its Environment, using the code stored in its Package. ## How the objects relate diff --git a/content/en/docs/concepts/workflows.md b/content/en/docs/concepts/workflows.md index 35d355fd..9c716345 100644 --- a/content/en/docs/concepts/workflows.md +++ b/content/en/docs/concepts/workflows.md @@ -8,8 +8,14 @@ description: > **A workflow is a durable state machine that orchestrates several functions as one reliable unit of work.** A single function is the right tool for one step. -Real processes are usually several steps with logic between them — validate an order, screen it for fraud, charge the card, fulfill or reject — where some steps run in parallel, some are conditional, and some can fail transiently and must be retried. -You *can* wire that together by having functions call each other, but then the orchestration lives in your code, nothing records how far a given execution got, and a crash midway leaves you guessing. +Real processes are usually several steps with logic between them: validate an order, screen it for fraud, charge the card, then fulfill or reject it. +Some steps run in parallel. +Some are conditional. +Some fail transiently and need a retry. +You *can* wire that together by having functions call each other. +But then the orchestration lives in your code. +Nothing records how far an execution got. +A crash midway leaves you guessing. A workflow makes the orchestration a first-class, durable object instead. ## Definition and execution @@ -17,21 +23,30 @@ A workflow makes the orchestration a first-class, durable object instead. Workflows use two custom resources, mirroring the split between a program and a running process: - A **`Workflow`** is the *definition* — a named state machine that says which functions run, in what order, with what branching, retries, and error handling. -- A **`WorkflowRun`** is one *execution* of that definition against a specific input. You create a run each time you want the workflow to happen; each run has its own state and history. +- A **`WorkflowRun`** is one *execution* of that definition against a specific input. + You create a run each time you want the workflow to happen. + Each run has its own state and history. -The definition is authored once and reused; every invocation is a new run. +The definition is authored once and reused. +Every invocation is a new run. ## What makes it durable -Every step a run takes — scheduled, succeeded, failed, retried, a timer fired, branches joined — is appended to an event log in the [statestore]({{% ref "/docs/architecture/statestore.md" %}}) using compare-and-swap, so the log is the single source of truth for where a run is. +Every step a run takes — scheduled, succeeded, failed, retried, a timer fired, branches joined — is appended to an event log in the [statestore]({{% ref "/docs/architecture/statestore.md" %}}) using compare-and-swap. +The log is the single source of truth for where a run is. The engine's own state is derived: it rebuilds a run's position by folding its event log, then decides the next step. That design buys four things: -- **Restart survival.** If the controller restarts mid-run, it reads the log back and continues — nothing is re-run that already succeeded, and nothing is lost. -- **Resume exactly where it stopped.** A run picks up from its last recorded step, not from the beginning. -- **Retries with backoff.** A transient function failure (a 5xx) is retried automatically; a permanent one (a 4xx typed error) is not. -- **Typed-error routing.** A step can catch a named business error (`PaymentDeclined`) and route to a different state, separately from infrastructure retries. +- **Restart survival.** + If the controller restarts mid-run, it reads the log back and continues — nothing is re-run that already succeeded, and nothing is lost. +- **Resume exactly where it stopped.** + A run picks up from its last recorded step, not from the beginning. +- **Retries with backoff.** + A transient function failure (a 5xx) is retried automatically. + A permanent one (a 4xx typed error) is not. +- **Typed-error routing.** + A step can catch a named business error (`PaymentDeclined`) and route to a different state, separately from infrastructure retries. ```mermaid flowchart TB @@ -63,7 +78,8 @@ See [Authoring workflows]({{% ref "/docs/usage/workflows/authoring.md" %}}) for ## When to use a workflow -Reach for a workflow when an operation is **multiple steps that must complete reliably as a whole** — especially with parallelism, conditional routing, retries, durable waits, or a need to know afterward exactly what happened. +Reach for a workflow when an operation is **multiple steps that must complete reliably as a whole**. +Good signals include parallelism, conditional routing, retries, durable waits, or a need to know afterward exactly what happened. Prefer the simpler tools when they fit: diff --git a/content/en/docs/installation/authentication.md b/content/en/docs/installation/authentication.md index cb8d471f..0283a4ca 100644 --- a/content/en/docs/installation/authentication.md +++ b/content/en/docs/installation/authentication.md @@ -13,16 +13,13 @@ This feature instead protects direct calls to Fission's own function endpoints, ## How Authentication Works -Fission does so by enabling authentication for Fission Router. -This is an optional feature that can be enabled or disabled depending on your requirement. - -When enabled, a new endpoint for authentication will be registered in the router. -All the API calls to Fission functions will now be routed through function endpoints using authentication token. +Fission enables authentication on the Fission Router. +When enabled, the router registers a login endpoint, and every function call must include an authentication token. Fission also creates a Secret named `router` in the `fission` namespace with a default `username`, a randomly generated `password`, and a `jwtSigningKey`. The router reads these values through `secretKeyRef` environment variables. You first create an auth token by providing the `username` and `password`. -The generated token must then be passed in the `Authorization` header of every subsequent function call. +Pass the generated token in the `Authorization` header of every subsequent function call. The sequence below traces this end to end, from login to an authenticated function call: @@ -42,8 +39,7 @@ sequenceDiagram ## Enabling Authentication -To enable authentication, you need to set the key `authentication.enabled` to `true`. -This can be found in `charts/fission-all/values.yaml`. +To enable authentication, set `authentication.enabled` to `true` in `charts/fission-all/values.yaml`: ```bash --set authentication.enabled=true @@ -82,14 +78,15 @@ authentication: ``` On GitOps renderers (Argo CD, Flux), set `authentication.existingSecret` to a Secret you create yourself. -Those run `helm template`, where the chart cannot preserve the generated `password` and `jwtSigningKey` across syncs — each sync would mint fresh values and invalidate issued tokens. +Those run `helm template`, where the chart cannot preserve the generated `password` and `jwtSigningKey` across syncs. +Each sync would mint fresh values and invalidate issued tokens. -Refer to the [installation guide]({{% ref "_index.en.md" %}}) if you are installing Fission for the first time, or to the [Upgrade Guide]({{% ref "upgrade.md" %}}) if you are upgrading from an older version. +See the [installation guide]({{% ref "_index.en.md" %}}) if you install Fission for the first time. +See the [Upgrade Guide]({{% ref "upgrade.md" %}}) if you upgrade from an older version. ## Generating Auth Token -Once the installation is successful, you need to generate the `auth token`. -To do that, you will export the values and set up `$FISSION_USERNAME`, `$FISSION_PASSWORD` and `$FISSION_AUTH_TOKEN` env variables. +After installing Fission, generate an auth token by exporting `$FISSION_USERNAME`, `$FISSION_PASSWORD`, and `$FISSION_AUTH_TOKEN`: ```bash export FISSION_USERNAME=$(kubectl get secrets/router --template={{.data.username}} -n fission | base64 -d) @@ -97,10 +94,10 @@ export FISSION_PASSWORD=$(kubectl get secrets/router --template={{.data.password export FISSION_AUTH_TOKEN=$(fission token create --username $FISSION_USERNAME --password $FISSION_PASSWORD) ``` -To understand more about generating tokens, refer to the [`fission token create`]({{% ref "../reference/fission-cli/fission_token_create.md" %}}) reference. +See the [`fission token create`]({{% ref "../reference/fission-cli/fission_token_create.md" %}}) reference for more on generating tokens. -With this, all your API calls to Fission functions are now authenticated using the generated token. -If a malformed token is used, the API call fails and returns an error. +All API calls to Fission functions now use the generated token for authentication. +A malformed token causes the API call to fail with an error. {{% notice info %}} The auth token is valid for 120 seconds by default. @@ -116,21 +113,21 @@ Once authentication is enabled, you can use it in two ways: ### Fission Function `test` command -Make sure that the environment variables are set before you test your function. +Set the environment variables before you test your function. ```bash fission function test --name hello hello, world! ``` -If the environment variable is not set, you need to pass it using the `--header` flag: +If the environment variable is not set, pass the token with the `--header` flag: ```bash fission function test --name hello --header "Authorization: Bearer <token>" hello, world! ``` -If the `auth token` is not configured correctly or malformed, the function will not be invoked and instead will return an error. +If the auth token is missing or malformed, the function call fails and returns an error. ```bash fission fn test --name hello @@ -139,21 +136,19 @@ Error: Error calling function hello: 401; Please try again or fix the error: {"m ### Fission Function API call -To execute Fission functions over API calls, you need to first ensure that your fission function has an associated `route` created. - -Create a route for your Fission function: +To call a Fission function over the API, first create a route for it: ```bash fission route create --name sample --method GET --url /hello --function hello ``` -The next step is to forward the port: +Forward the port: ```bash kubectl port-forward svc/router 8888:80 -nfission ``` -Using `curl`, you can invoke the function by passing the `auth token` in the header: +Invoke the function with `curl`, passing the auth token in the header: ```bash curl http://localhost:8888/hello -H "Authorization: Bearer ${FISSION_AUTH_TOKEN}" diff --git a/content/en/docs/installation/internal-auth.md b/content/en/docs/installation/internal-auth.md index 77fa2121..9125ee6e 100644 --- a/content/en/docs/installation/internal-auth.md +++ b/content/en/docs/installation/internal-auth.md @@ -29,7 +29,9 @@ The router now binds **two listeners**: - **Public listener** (port `8888`) — serves user `HTTPTrigger` paths, `/router-healthz`, `/_version`, and (when enabled) the JWT-based [function-invocation auth]({{% ref "authentication.md" %}}). - **Internal listener** (port `8889`) — serves `/fission-function/<ns>/<name>` only, gated by `NetworkPolicy` plus HMAC verification. -**`/fission-function/<ns>/<name>` no longer exists on the public listener.** This closes [GHSA-3g33-6vg6-27m8](https://github.com/fission/fission/security/advisories/GHSA-3g33-6vg6-27m8) — previously anyone reachable to the public router URL (e.g. via Ingress) could invoke any function by guessing its name, bypassing all `HTTPTrigger` host/path/method gates. +**`/fission-function/<ns>/<name>` no longer exists on the public listener.** +This closes [GHSA-3g33-6vg6-27m8](https://github.com/fission/fission/security/advisories/GHSA-3g33-6vg6-27m8). +Previously, anyone reachable to the public router URL (e.g. via Ingress) could invoke any function by guessing its name, bypassing all `HTTPTrigger` host/path/method gates. Any external tooling that today curls `/fission-function/...` against the public router URL will receive **404** after upgrading. The public listener is unchanged for user `HTTPTrigger` traffic. @@ -45,14 +47,16 @@ helm install fission fission-charts/fission-all -n fission --create-namespace The chart materializes a `Secret/fission-internal-auth` with an auto-generated 32-byte master key. The same value is preserved across `helm upgrade` runs. Under static tenancy the chart replicates the Secret into `defaultNamespace` and each `additionalFissionNamespaces` entry, so dynamically created builder and function pods can mount it too. -Every Fission control-plane component (storagesvc, executor, router, buildermgr, and the rest) and every dynamically-created builder/function pod mounts the master via environment variable; each signer/verifier pair derives its own per-service key. +Every Fission control-plane component (storagesvc, executor, router, buildermgr, and the rest) and every dynamically-created builder/function pod mounts the master via environment variable. +Each signer/verifier pair derives its own per-service key. ### Fail-closed startup check Every binary — fission-bundle, fetcher, builder, and the CLI — validates the internal-auth environment at startup. An absent `FISSION_INTERNAL_AUTH_SECRET` means internal auth is off; signers and verifiers pass through. A present but blank value is refused: the process exits with an error that names the variable. -This closes the one misconfiguration that previously failed open — a Secret with an empty `secret` key silently disabled HMAC verification. +This closes the one misconfiguration that previously failed open. +A Secret with an empty `secret` key silently disabled HMAC verification. The same check covers the rotation variable `FISSION_INTERNAL_AUTH_SECRET_OLD`. ## Bring your own master secret @@ -82,14 +86,16 @@ The Secret must hold the key `secret`, and during rotation the optional key `old With `internalAuth.existingSecret` set, the chart renders no master Secret; every component reads yours. Create the Secret in every namespace where Fission runs pods: the release namespace, `defaultNamespace`, and each `additionalFissionNamespaces` entry. -kubelet cannot resolve a cross-namespace `secretKeyRef`, so a single copy in the release namespace leaves builder and function pods starting but returning 401 on every archive fetch and builder upload. +A single copy in the release namespace leaves builder and function pods starting but returning 401 on every archive fetch and builder upload, because kubelet cannot resolve a cross-namespace `secretKeyRef`. Under dynamic or cluster tenancy, only the release namespace needs the Secret. This is the recommended path for GitOps renderers (Argo CD, Flux). -Those run `helm template`, where the chart cannot preserve a generated value across syncs — each sync would mint a new master and break every running pod. +Those run `helm template`, where the chart cannot preserve a generated value across syncs. +Each sync would mint a new master and break every running pod. Switching an existing install to `existingSecret` is safe: a pre-upgrade hook marks the chart-generated Secret with `helm.sh/resource-policy=keep`, so Helm does not prune it. -As an alternative for GitOps, `internalAuth.autoGenerate=true` (default `false`) moves generation into a pre-install/pre-upgrade hook that creates the master Secret in-cluster only if it is absent, so no renderer re-mints it. +As an alternative for GitOps, `internalAuth.autoGenerate=true` (default `false`) moves generation into a pre-install/pre-upgrade hook. +The hook creates the master Secret in-cluster only if it is absent, so no renderer re-mints it. The hook is admission-fenced by a `ValidatingAdmissionPolicy`: it can create only the master Secret, and only as a plain `Opaque` object. The CLI discovers the Secret name from the cluster it talks to. @@ -111,7 +117,8 @@ Every signer/verifier short-circuits to pass-through — no signing, no verifica This is the **recommended setting if you rely on stock upstream KEDA connector images** (`ghcr.io/fission/keda-kafka-http-connector` and the other `keda-*-http-connector` images) — see [Caveats](#caveats) below. The router's two-listener split is independent of this toggle: `/fission-function/<ns>/<name>` remains on the internal listener regardless. -With `internalAuth.enabled=false` the internal listener still accepts unsigned requests; with `internalAuth.enabled=true` it requires signatures. +With `internalAuth.enabled=false` the internal listener still accepts unsigned requests. +With `internalAuth.enabled=true` it requires signatures. ## Master-secret rotation @@ -150,7 +157,8 @@ The verifier (server) and signer (client) toggles are set independently per roll | ON | OFF | Client request returns **401** | | OFF | ON | Client sends signed headers; server pass-through ignores them — works | -The chart applies the toggle wholesale, so the "ON / OFF" failure mode only surfaces during hand-edited deployments, in-flight `helm upgrade` rollouts where some pods haven't rolled yet, or external tooling that signed against an unconfigured CLI. +The chart applies the toggle wholesale. +The "ON / OFF" failure mode surfaces only during hand-edited deployments, in-flight `helm upgrade` rollouts where some pods haven't rolled yet, or external tooling that signed against an unconfigured CLI. ## Caveats @@ -161,8 +169,10 @@ With `internalAuth.enabled=true` (the default), KEDA-driven message-queue trigge Operators have two options until signing-aware KEDA images ship: -1. **Build signing-aware connector images** (recommended long-term). The signer primitive lives in `pkg/auth/hmac` in the Fission repo. -2. **Set `internalAuth.enabled=false`** and rely on `NetworkPolicy` alone for the KEDA traffic. The internal listener still hosts `/fission-function/<ns>/<name>` but does not enforce signatures. +1. **Build signing-aware connector images** (recommended long-term). + The signer primitive lives in `pkg/auth/hmac` in the Fission repo. +2. **Set `internalAuth.enabled=false`** and rely on `NetworkPolicy` alone for the KEDA traffic. + The internal listener still hosts `/fission-function/<ns>/<name>` but does not enforce signatures. ### `ROUTER_INTERNAL_URL` diff --git a/content/en/docs/installation/upgrade.md b/content/en/docs/installation/upgrade.md index 7fc7c431..ad53df59 100644 --- a/content/en/docs/installation/upgrade.md +++ b/content/en/docs/installation/upgrade.md @@ -14,7 +14,8 @@ Fission does not yet test or guarantee zero downtime for every request, so sched ## Upgrade to the latest Fission version **Every upgrade needs two steps, in order: update the CLI, then upgrade the chart.** -Starting with Fission {{< release-version >}}, `helm upgrade` applies the matching CRDs itself through a pre-upgrade hook, so a separate CRD step is needed only when you opt out. +Starting with Fission {{< release-version >}}, `helm upgrade` applies the matching CRDs itself through a pre-upgrade hook. +You need a separate CRD step only when you opt out. Check the version-specific sections below for anything extra your target release requires. ### Install the latest Fission CLI @@ -56,7 +57,6 @@ fission check ## What happens during an upgrade `helm upgrade` replaces the Fission control-plane pods, not your function pods. -This section describes what each component does while it rolls. ### Pre-upgrade checks @@ -73,7 +73,8 @@ If a check fails, the upgrade stops before any component rolls, and the existing The router runs two replicas by default and rolls surge-first (`maxSurge: 1`, `maxUnavailable: 0`), so the serving replica count never dips. A new router pod reports Ready only after it builds its route table and syncs its endpoint index. -A terminating router pod first sleeps for `router.preStopSleep` (default 5 seconds) so its removal from the Service propagates, then drains in-flight requests for up to `router.gracefulShutdownTimeout` (default `75s`). +A terminating router pod first sleeps for `router.preStopSleep` (default 5 seconds), so its removal from the Service propagates. +It then drains in-flight requests for up to `router.gracefulShutdownTimeout` (default `75s`). A PodDisruptionBudget (`minAvailable: 1`) protects the router during node drains. The chart renders the budget only when the router can satisfy it: two or more replicas, or an autoscaler with a floor of two. @@ -82,23 +83,28 @@ The chart renders the budget only when the router can satisfy it: two or more re Warm pods keep serving through the upgrade: - The restarted executor **adopts** existing function Deployments and pods (`executor.adoptExistingResources`, default `true`) instead of recreating them. -- **Specialized** poolmgr pods survive executor-side template changes, such as a new fetcher image; the pool controller recycles them only when their environment changes. +- **Specialized** poolmgr pods survive executor-side template changes, such as a new fetcher image. + The pool controller recycles them only when their environment changes. - **Generic** (not yet specialized) pool pods roll and pick up the new images. - Warm traffic does not need a live executor: the router serves warm requests directly from EndpointSlices. ### Executor -The executor is a single-writer control plane, so it rolls overlap-free (`maxSurge: 0`, `maxUnavailable: 1`): the old pod stops before the new one starts. +The executor is a single-writer control plane, so it rolls overlap-free (`maxSurge: 0`, `maxUnavailable: 1`). +The old pod stops before the new one starts. This gives a bounded executor-down window per roll. -Warm traffic keeps serving throughout; only cold starts wait for the new executor pod. +Warm traffic keeps serving throughout. +Only cold starts wait for the new executor pod. To shorten failover, run `executor.replicas: 2` with `executor.leaderElection.enabled: true` (active-passive HA). ### Webhook The validating webhook runs two replicas by default with a surge rollout and a PodDisruptionBudget, so Fission CR writes stay available while it rolls. -One caveat remains on the default certificate path: the chart mints a new serving certificate on every `helm upgrade`, so a short window can reject CR writes while old pods still serve the old certificate. +One caveat remains on the default certificate path: the chart mints a new serving certificate on every `helm upgrade`. +A short window can then reject CR writes while old pods still serve the old certificate. Set `webhook.certManager.enabled=true` to let cert-manager manage a stable certificate and close that window. -Function invocations are not affected; the webhook sits only on the CR write path. +Function invocations are not affected. +The webhook sits only on the CR write path. ### Embedded statestore @@ -114,14 +120,16 @@ New [asynchronous enqueues](/docs/usage/function/async-invocation/) during that ### Function pods: `terminationGracePeriod` Each environment sets how long its function pods drain before Kubernetes removes them: `spec.terminationGracePeriod`, default **90 seconds**. -A terminating function pod keeps serving for the whole window — the preStop hook sleeps through it, then the kubelet kills the pod. +A terminating function pod keeps serving for the whole window. +The preStop hook sleeps through it, then the kubelet kills the pod. Set the window above your longest function timeout, or the slowest in-flight requests end with a connection reset: ```sh fission env update --name node --graceperiod 180 ``` -The same window applies to every pod teardown — idle reap, environment update, upgrade, node drain — so a larger value makes each teardown take longer per pod. +The same window applies to every pod teardown: idle reap, environment update, upgrade, node drain. +A larger value makes each teardown take longer per pod. An explicit `0` disables draining and removes pods instantly. See the [`terminationGracePeriod` field reference](/docs/reference/crd-reference/#environmentspec). @@ -153,13 +161,18 @@ See the [v1.28.0 release notes](/docs/releases/v1.28.0/#upgrade-notes) for the f ## Upgrade to 1.27.x release v1.27.0 adds opt-in multi-namespace tenancy and a function-developer observability toolkit (invocation correlation, `fission function describe`, and local `run-local` development). -Tenancy is off by default — `tenancy.mode: static` renders byte-identical RBAC and keeps the existing auth model — so a single-namespace or `additionalFissionNamespaces` install upgrades with just the routine CRD/CLI/chart steps above, and the minimum Kubernetes version is unchanged at **1.32**. +Tenancy is off by default. +`tenancy.mode: static` renders byte-identical RBAC and keeps the existing auth model, so a single-namespace or `additionalFissionNamespaces` install upgrades with just the routine CRD/CLI/chart steps above. +The minimum Kubernetes version is unchanged at **1.32**. To onboard namespaces at runtime with `fission tenant enable` instead of editing `additionalFissionNamespaces`, see [Multi-namespace tenancy](/docs/usage/multi-namespace-tenancy/). Two runtime defaults change visibly and are worth reviewing first: -- The router now returns a structured JSON error body for attributed failures (status codes are unchanged). A client that parses the literal old plain-text body should read the JSON instead, or set `ROUTER_STRUCTURED_ERRORS=false` to restore it. -- Trace sampling now honors `OTEL_TRACES_SAMPLER`, so if you export traces over OTLP, successful-trace volume drops to the documented `0.1` ratio (all error traces are still kept). Set `OTEL_TRACES_SAMPLER=parentbased_always_on` to keep 100% export. +- The router now returns a structured JSON error body for attributed failures (status codes are unchanged). + A client that parses the literal old plain-text body should read the JSON instead, or set `ROUTER_STRUCTURED_ERRORS=false` to restore it. +- Trace sampling now honors `OTEL_TRACES_SAMPLER`. + If you export traces over OTLP, successful-trace volume drops to the documented `0.1` ratio (all error traces are still kept). + Set `OTEL_TRACES_SAMPLER=parentbased_always_on` to keep 100% export. See the [v1.27.0 release notes](/docs/releases/v1.27.0/#upgrade-notes) for the full list of behavioral changes and the action each one requires. @@ -170,8 +183,10 @@ There are no Kubernetes-version or admission changes from v1.25.0, so the routin Two behavioral defaults are worth reviewing before you upgrade: -- The router now serves warm traffic directly from EndpointSlices and accounts request concurrency **per router replica** by default. Functions that depend on global concurrency enforcement should set the `fission.io/concurrency-enforcement: strict` annotation. -- When a package registry is configured (`packageRegistry.enabled`), builds publish their deployment archive as a digest-pinned OCI image and functions cold-start from it. Leave `packageRegistry.enabled` unset to keep today's tarball behavior unchanged. +- The router now serves warm traffic directly from EndpointSlices and accounts request concurrency **per router replica** by default. + Functions that depend on global concurrency enforcement should set the `fission.io/concurrency-enforcement: strict` annotation. +- When a package registry is configured (`packageRegistry.enabled`), builds publish their deployment archive as a digest-pinned OCI image and functions cold-start from it. + Leave `packageRegistry.enabled` unset to keep today's tarball behavior unchanged. See the [v1.26.0 release notes](/docs/releases/v1.26.0/#upgrade-notes) for the full list of behavioral changes and the action each one requires. @@ -182,12 +197,23 @@ Before upgrading, confirm your cluster is on Kubernetes 1.32 or newer — the He Three breaking changes need attention: -1. **Kubernetes 1.32 minimum.** Clusters below 1.32 are rejected by the chart's `kubeVersion` constraint and fail the runtime `fission check` floor. The fluentbit `PodSecurityPolicy` manifest and the `logger.podSecurityPolicy` Helm value are removed (PSP no longer exists in Kubernetes 1.32); use Pod Security Admission instead. -2. **HTTPTrigger path validation at admission.** Empty paths, `..` traversal, root-only `/`, and paths that collide with router-owned routes (`/router-healthz`, `/readyz`, `/_version`, `/auth/login`) or shadow `/fission-function/<ns>/<name>` are now rejected. The `fission` CLI already enforced these; raw `kubectl apply` no longer bypasses them. Fix offending trigger paths before upgrading. -3. **PodSpec capabilities are an allowlist.** `Environment` and `Function` PodSpecs may only add `NET_BIND_SERVICE`; every container is forced to `drop: ["ALL"]`. Specs that added other capabilities are rejected, and workloads that silently relied on the OCI default cap set will see those caps stripped. +1. **Kubernetes 1.32 minimum.** + Clusters below 1.32 are rejected by the chart's `kubeVersion` constraint and fail the runtime `fission check` floor. + The fluentbit `PodSecurityPolicy` manifest and the `logger.podSecurityPolicy` Helm value are removed (PSP no longer exists in Kubernetes 1.32). + Use Pod Security Admission instead. +2. **HTTPTrigger path validation at admission.** + Empty paths, `..` traversal, root-only `/`, and paths that collide with router-owned routes (`/router-healthz`, `/readyz`, `/_version`, `/auth/login`) or shadow `/fission-function/<ns>/<name>` are now rejected. + The `fission` CLI already enforced these. + Raw `kubectl apply` no longer bypasses them. + Fix offending trigger paths before upgrading. +3. **PodSpec capabilities are an allowlist.** + `Environment` and `Function` PodSpecs may only add `NET_BIND_SERVICE`. + Every container is forced to `drop: ["ALL"]`. + Specs that added other capabilities are rejected, and workloads that silently relied on the OCI default cap set will see those caps stripped. The HTTPTrigger / TimeTrigger / CanaryConfig admission webhooks are also removed in favor of API-server CEL validation. -A side effect: a raw `kubectl apply` of an invalid cron schedule, CORS origin, or ingress path is now **admitted and flagged with a `…=False` status condition** (for example `Scheduled=False`, `RouteAdmitted=False`) rather than rejected at creation. +A side effect: a raw `kubectl apply` of an invalid cron schedule, CORS origin, or ingress path is now admitted rather than rejected at creation. +It is instead **flagged with a `…=False` status condition** (for example `Scheduled=False`, `RouteAdmitted=False`). The `fission` CLI still rejects these client-side, so the common path is unchanged. See the [v1.25.0 release notes](/docs/releases/v1.25.0/#upgrade-notes) for the full list of breaking changes and the action each one requires. @@ -195,7 +221,8 @@ See the [v1.25.0 release notes](/docs/releases/v1.25.0/#upgrade-notes) for the f ## Upgrade to 1.24.x release v1.24.0 is a security-hardening release. -The admission webhooks now reject cross-namespace references and dangerous PodSpec fields, deny cross-origin browser requests by default, and stop mounting the `fission-builder` ServiceAccount token into user builder containers. +The admission webhooks now reject cross-namespace references and dangerous PodSpec fields, and deny cross-origin browser requests by default. +They also stop mounting the `fission-builder` ServiceAccount token into user builder containers. Specs that rely on the rejected primitives will fail admission after upgrade, so review them first. See the [v1.24.0 release notes]({{% ref "../releases/v1.24.0.md" %}}#upgrade-notes) for the full list of breaking changes and the action each one requires. @@ -216,7 +243,8 @@ Audit before upgrading and migrate any such caller to use a proper `HTTPTrigger` ### KEDA message-queue triggers and the connector signing gap `internalAuth.enabled` defaults to `true` in v1.23.0. -Upstream `ghcr.io/fission/keda-kafka-http-connector` (and the other `keda-*-http-connector` images) do not yet sign their `/fission-function/...` invocations, so KEDA-driven message-queue triggers will receive `401` from the new router internal listener. +Upstream `ghcr.io/fission/keda-kafka-http-connector` (and the other `keda-*-http-connector` images) do not yet sign their `/fission-function/...` invocations. +KEDA-driven message-queue triggers therefore receive `401` from the new router internal listener. If your installation uses KEDA-backed `MessageQueueTrigger` resources, **set `internalAuth.enabled=false` at upgrade time** until signing-aware KEDA connector images ship: diff --git a/content/en/docs/releases/v1.28.0.md b/content/en/docs/releases/v1.28.0.md index 9093d1d2..6feacd47 100644 --- a/content/en/docs/releases/v1.28.0.md +++ b/content/en/docs/releases/v1.28.0.md @@ -17,40 +17,54 @@ Version numbers, upgrade notes, and the changelog are finalized when v1.28.0 shi <!-- Finalized at release cut: minimum Kubernetes version, chart/CRD changes, upgrade steps. --> All headline features are **opt-in** and off by default, so a routine upgrade changes nothing for an existing install until you enable them. -One set of chart defaults does change: the router and webhook now run two replicas with surge rollouts, and `helm upgrade` applies the CRDs itself through a pre-upgrade hook. +One set of chart defaults does change: the router and webhook now run two replicas with surge rollouts. +`helm upgrade` applies the CRDs itself through a pre-upgrade hook. See [Upgrade to 1.28.x release](/docs/installation/upgrade/#upgrade-to-128x-release) for the details and the opt-outs. For the general upgrade steps (CRDs, CLI, Helm chart), see the [Upgrade Guide](/docs/installation/upgrade/). ## Highlights -Fission v1.28.0 is themed around **durable and asynchronous execution** — a shared durable substrate and the features that build on it — plus first-class **function versioning** for safe rollouts and instant rollbacks. +Fission v1.28.0 is themed around **durable and asynchronous execution** — a shared durable substrate and the features that build on it. +It also adds first-class **function versioning** for safe rollouts and instant rollbacks. A second group of improvements covers day-2 operation: provisioned warm capacity, per-function environment variables, smoother upgrades, and GitOps-grade specs. - **Statestore — a durable state substrate.** - A single interface exposing key/value, an append-only event log, and a visibility-timeout queue, served by a pluggable driver: **embedded** SQLite on a PVC for development, or an **external** Postgres DSN for production and HA. + A single interface exposing key/value, an append-only event log, and a visibility-timeout queue, served by a pluggable driver. + Choices are **embedded** SQLite on a PVC for development, or an **external** Postgres DSN for production and HA. Fission deploys no database product of its own. It is the foundation that asynchronous invocation, eventing, and workflows build on. See [Statestore](/docs/architecture/statestore/). - **Asynchronous invocation — fire-and-forget with durability.** - Send `X-Fission-Invoke-Mode: async` (or `fission fn test --async`) and the router enqueues the call, returns a durable invocation id with `202 Accepted`, and delivers it in the background with retries. - Per-function delivery config sets the attempt budget and max age; a **dead-letter queue** (`fission function dlq`) captures what cannot be delivered; result **destinations** route the outcome to another function; and an opt-in KEDA `ScaledObject` autoscales the workers on the backlog. + Send `X-Fission-Invoke-Mode: async` (or `fission fn test --async`) and the router enqueues the call. + It returns a durable invocation id with `202 Accepted` and delivers the call in the background with retries. + Per-function delivery config sets the attempt budget and max age. + A **dead-letter queue** (`fission function dlq`) captures what cannot be delivered. + Result **destinations** route the outcome to another function. + An opt-in KEDA `ScaledObject` autoscales the workers on the backlog. See [Asynchronous invocation](/docs/usage/function/async-invocation/). - **Statestore eventing — durable pub/sub topics with no external broker.** - A topic is a durable, replayable stream on the statestore: `fission topic publish` appends events, and a message queue trigger with `--mqtkind fission --mqtype statestore` subscribes a function. + A topic is a durable, replayable stream on the statestore. + `fission topic publish` appends events, and a message queue trigger with `--mqtkind fission --mqtype statestore` subscribes a function. Delivery is at-least-once with retries, an error topic for events that keep failing, and an optional response topic. Async invocations can fan their results out to a topic with `--async-on-success-topic`. See [Statestore Eventing](/docs/usage/triggers/statestore-eventing/). - **Function versions and aliases — publish, promote, roll back.** - Every runtime-affecting update can be published as an immutable `FunctionVersion` snapshot (automatically with `spec.versioning.mode: auto`, or explicitly via `fission fn publish`); movable `FunctionAlias` pointers like `prod` and `staging` are what triggers reference; and `fission fn rollback` repoints an alias atomically with no pod churn and no cold start. + Every runtime-affecting update can be published as an immutable `FunctionVersion` snapshot, automatically with `spec.versioning.mode: auto` or explicitly via `fission fn publish`. + Movable `FunctionAlias` pointers like `prod` and `staging` are what triggers reference. + `fission fn rollback` repoints an alias atomically, with no pod churn and no cold start. Weighted aliases split traffic between two versions, canary configs can drive the split automatically, and digest pinning makes aliases GitOps-friendly. Bare function names keep meaning "the live function", so nothing changes until you opt in. See [Function versions and aliases](/docs/usage/function/versions-aliases/). - **Durable Workflows — orchestrate functions as a resumable state machine.** - A `Workflow` custom resource is a state machine over your functions; each execution is a `WorkflowRun` recorded step by step in the statestore event log, so a run survives controller restarts, resumes exactly where it stopped, retries transient failures with backoff, and routes typed business errors. - States cover `Task`, `Choice`, `Parallel`, `Map`, `Wait`, and `Succeed`/`Fail`, with a `fission workflow` CLI that includes a local day/night graph viewer and a per-run status overlay. + A `Workflow` custom resource is a state machine over your functions. + Each execution is a `WorkflowRun` recorded step by step in the statestore event log. + A run survives controller restarts, resumes exactly where it stopped, retries transient failures with backoff, and routes typed business errors. + States cover `Task`, `Choice`, `Parallel`, `Map`, `Wait`, and `Succeed`/`Fail`. + A `fission workflow` CLI includes a local day/night graph viewer and a per-run status overlay. See [Workflows](/docs/usage/workflows/). - **Provisioned concurrency — warm capacity on a schedule.** - Set `--provisioned-concurrency 2` on a poolmgr function and the executor keeps two specialized pods warm before any request arrives, so requests inside the floor never pay a cold start. + Set `--provisioned-concurrency 2` on a poolmgr function and the executor keeps two specialized pods warm before any request arrives. + Requests inside the floor never pay a cold start. Repeatable `--provisioned-schedule` windows raise or lower the floor on a cron schedule — business hours, nightly batches — and the `executor.provisionedConcurrency.enabled` Helm gate turns the feature on. See [Provisioned Concurrency](/docs/usage/function/provisioned-concurrency/). - **Per-function environment variables.** @@ -59,12 +73,17 @@ A second group of improvements covers day-2 operation: provisioned warm capacity Newdeploy and container executors only for now: poolmgr rejects the fields at admission until phase 2 lands ([fission/fission#3666](https://github.com/fission/fission/issues/3666)). See [Secrets, ConfigMaps, and Environment Variables](/docs/usage/function/access-secret-cfgmap-in-function/#inject-environment-variables). - **Smoother upgrades.** - `helm upgrade` now applies the matching CRDs through a pre-upgrade hook, and the router and webhook default to two replicas with surge rollouts and PodDisruptionBudgets, so warm function traffic keeps serving while the control plane rolls. + `helm upgrade` now applies the matching CRDs through a pre-upgrade hook. + The router and webhook default to two replicas with surge rollouts and PodDisruptionBudgets, so warm function traffic keeps serving while the control plane rolls. Zero downtime is the design goal, not yet a guarantee. See [What happens during an upgrade](/docs/installation/upgrade/#what-happens-during-an-upgrade) for the per-component behavior and the drain-window tuning. - **GitOps-grade YAML specs.** - `fission spec apply` is idempotent and scoped to a deployment ID: a no-op reapply writes nothing, archives dedupe by checksum, and a source change re-triggers the build. - Pruning is opt-in with `--delete`, `--wait` fails a pipeline on a failed build, `--commitlabel` records provenance, and `--dry-run` previews a merge from a pull request. + `fission spec apply` is idempotent and scoped to a deployment ID. + A no-op reapply writes nothing, archives dedupe by checksum, and a source change re-triggers the build. + Pruning is opt-in with `--delete`. + `--wait` fails a pipeline on a failed build. + `--commitlabel` records provenance. + `--dry-run` previews a merge from a pull request. See [YAML Specs](/docs/usage/spec/). ## References diff --git a/content/en/docs/usage/_index.en.md b/content/en/docs/usage/_index.en.md index c1f495fc..82743d18 100644 --- a/content/en/docs/usage/_index.en.md +++ b/content/en/docs/usage/_index.en.md @@ -6,7 +6,7 @@ description: > --- This section is the hands-on guide to using Fission once it is installed on your cluster. -Each page is task-oriented: it states what you will accomplish, lists the commands to run, and shows the output to expect. +Each page states what you will accomplish, lists the commands to run, and shows the output to expect. If you have not installed Fission yet, start with the [Installation guide]({{% ref "/docs/installation/_index.en.md" %}}). For the concepts behind these tasks, see [Concepts]({{% ref "/docs/concepts/_index.md" %}}). diff --git a/content/en/docs/usage/function/access-secret-cfgmap-in-function.en.md b/content/en/docs/usage/function/access-secret-cfgmap-in-function.en.md index 7fda9122..62f77665 100644 --- a/content/en/docs/usage/function/access-secret-cfgmap-in-function.en.md +++ b/content/en/docs/usage/function/access-secret-cfgmap-in-function.en.md @@ -6,7 +6,9 @@ description: > Mount Kubernetes Secrets and ConfigMaps into a Fission function as files, or inject them and literal values as per-function environment variables. --- -**Fission functions read configuration through two channels: [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) and [ConfigMaps](https://kubernetes.io/docs/concepts/storage/volumes/#configmap) mounted as files, and — starting with Fission {{< release-version >}} — per-function environment variables that can also project Secret and ConfigMap values.** +**Fission functions read configuration through two channels.** +The first channel is [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) and [ConfigMaps](https://kubernetes.io/docs/concepts/storage/volumes/#configmap) mounted as files. +The second channel, starting with Fission {{< release-version >}}, is per-function environment variables, which can also project Secret and ConfigMap values. Use Secrets for sensitive values such as API keys and tokens. Use ConfigMaps for configuration that is not secret. Use environment variables for 12-factor configuration such as `DATABASE_URL` or `LOG_LEVEL`. @@ -129,7 +131,8 @@ See the [executor support matrix](#executor-support) below. By default an object's files land under `/secrets/<namespace>/<name>` or `/configs/<namespace>/<name>`. Set `mountPath` on the reference in the function spec to redirect them. -There is no `fn create` / `fn update` flag for it; edit the spec YAML (the `fission spec` workflow or `kubectl`): +There is no `fn create` / `fn update` flag for it. +Edit the spec YAML instead (the `fission spec` workflow or `kubectl`): ```yaml # in the Function spec @@ -239,7 +242,8 @@ $ fission fn update --name env-reader \ --env-from-configmap app-config ``` -If you pass only some of the three flags, the variables set through the omitted flags are removed; the CLI prints a warning when that happens. +Passing only some of the three flags removes the variables set through the omitted flags. +The CLI prints a warning when that happens. An env change is a runtime-affecting update: the function's pods roll and new pods see the new values. ### Precedence and reserved names diff --git a/content/en/docs/usage/function/async-invocation.md b/content/en/docs/usage/function/async-invocation.md index 5b118fe9..7ba19b47 100644 --- a/content/en/docs/usage/function/async-invocation.md +++ b/content/en/docs/usage/function/async-invocation.md @@ -9,11 +9,13 @@ description: > **Invoke a function fire-and-forget: the router accepts the call, returns a durable invocation id immediately, and delivers it in the background with retries — so the caller never waits for the work to finish.** A normal invocation is synchronous: the caller holds the connection open until the function returns a response. -That is wrong for work that is slow, spiky, or must not be lost if a caller disconnects — sending email, processing an upload, calling a rate-limited third party. +That is wrong for work that is slow, spiky, or must not be lost if a caller disconnects. +Examples: sending email, processing an upload, calling a rate-limited third party. Starting with Fission {{< release-version >}}, an asynchronous invocation hands that work to Fission and returns right away. The caller sends `X-Fission-Invoke-Mode: async` (or uses `fission fn test --async`). -The router **enqueues** the call on the [statestore]({{% ref "/docs/architecture/statestore.md" %}}) queue, returns **`202 Accepted`** with a durable invocation id, and a background worker delivers it — retrying transient failures, dead-lettering what it cannot deliver, and optionally invoking a destination function with the result. +The router **enqueues** the call on the [statestore]({{% ref "/docs/architecture/statestore.md" %}}) queue and returns **`202 Accepted`** with a durable invocation id. +A background worker then delivers it — retrying transient failures, dead-lettering what it cannot deliver, and optionally invoking a destination function with the result. ```mermaid flowchart TB @@ -90,7 +92,8 @@ fission fn update --name resize-image \ | `--async-max-age` | Maximum age of an invocation before dead-lettering, regardless of attempts. | {{% notice info %}} -When the function is invoked through a [function alias]({{% ref "versions-aliases.md" %}}), the invocation is pinned to the version resolved at enqueue time — retries re-run that same version even if the alias moves or is rolled back in between, so retries stay deterministic. +When the function is invoked through a [function alias]({{% ref "versions-aliases.md" %}}), the invocation is pinned to the version resolved at enqueue time. +Retries re-run that same version even if the alias moves or is rolled back in between, so retries stay deterministic. {{% /notice %}} ## Result destinations @@ -108,7 +111,8 @@ fission fn update --name resize-image \ | `--async-on-success` | Same-namespace function invoked with the result when delivery succeeds. | | `--async-on-failure` | Same-namespace function invoked when the invocation is dead-lettered. | -To fan the result out to an event topic instead of a single function, use the `--async-on-success-topic` / `--async-on-failure-topic` variants, which publish the result to a Fission eventing topic that any number of functions can subscribe to. +To fan the result out to an event topic instead of a single function, use the `--async-on-success-topic` / `--async-on-failure-topic` variants. +These publish the result to a Fission eventing topic that any number of functions can subscribe to. ## Dead-letter queue @@ -140,7 +144,8 @@ A re-driven invocation starts with a fresh attempt budget. ## Autoscaling -An opt-in KEDA `ScaledObject` scales the async workers on the queue backlog, so a burst of enqueued work spins up more delivery capacity and idles back down when the queue drains. +An opt-in KEDA `ScaledObject` scales the async workers on the queue backlog. +A burst of enqueued work spins up more delivery capacity, then idles back down when the queue drains. {{% notice warning %}} Autoscaling requires `statestore.mode=external` (Postgres). diff --git a/content/en/docs/usage/function/canary-deployments.md b/content/en/docs/usage/function/canary-deployments.md index 3280215b..29f6bf32 100644 --- a/content/en/docs/usage/function/canary-deployments.md +++ b/content/en/docs/usage/function/canary-deployments.md @@ -39,8 +39,7 @@ A Canary Config has the following parameters: | `failureType` | How the health of the new version is checked. The only supported type is `status-code` (the HTTP status code), so a function that returns a status code other than 200 is considered unhealthy. Set in the CanaryConfig spec — the CLI does not expose a flag for it. | For example, suppose the current stable version of a function is `fn-a-v1` and the new version is `fn-a-v2`. -We want to increment traffic towards the new version in steps of 30% every 1m, with a failure threshold of 10%. -The sample canary config below captures this. +This example increments traffic toward the new version in steps of 30% every 1m, with a failure threshold of 10%. ```yaml apiVersion: fission.io/v1 @@ -58,9 +57,9 @@ spec: weightincrement: 30 ``` -Every 1m, the percentage of failed requests to `fn-a-v2` is calculated from Prometheus metrics. -If it is under the configured failure threshold of 10%, the traffic to `fn-a-v2` is incremented by 30%. -This cycle repeats until either the failure threshold is reached (the deployment is rolled back) or `fn-a-v2` is receiving 100% of user traffic. +Every 1m, Fission calculates the percentage of failed requests to `fn-a-v2` from Prometheus metrics. +If it is under the 10% failure threshold, Fission increments traffic to `fn-a-v2` by 30%. +This cycle repeats until the failure rate crosses the threshold, which triggers a rollback, or `fn-a-v2` receives 100% of user traffic. #### Steps to setup a canary config @@ -113,6 +112,6 @@ The status is one of: #### Running canaries faster than the default scrape interval The `scrape_interval` for Prometheus server is 1m by default. -If the "duration" parameter needs to be less than 1m, the `scrape_interval` parameter needs to configured to a much lower value. -This can be done by updating the config map for prometheus server. -Updating the config map is enough; the prometheus server does not need to be restarted. +If the "duration" parameter needs to be less than 1m, the `scrape_interval` parameter needs to be configured to a much lower value. +Update the config map for the Prometheus server to do this. +Updating the config map is enough — you do not need to restart the Prometheus server. diff --git a/content/en/docs/usage/function/debugging.md b/content/en/docs/usage/function/debugging.md index 7a608d55..a3997001 100644 --- a/content/en/docs/usage/function/debugging.md +++ b/content/en/docs/usage/function/debugging.md @@ -7,8 +7,12 @@ description: > --- **Diagnose a failing function down to the component and the exact invocation, without reading server logs.** -When a function misbehaves, the question is usually *where* it broke — the function code, the build, the executor, or a timeout — and *which* call it was. -Fission answers both: `fission function describe` shows a function's health in one view, `fission function test` attributes a failure to a component and hands you a request id, and `fission function logs --request-id` pulls that one invocation's logs. +When a function misbehaves, the question is usually *where* it broke: the function code, the build, the executor, or a timeout. +The other question is *which* call it was. +Fission answers both. +`fission function describe` shows a function's health in one view. +`fission function test` attributes a failure to a component and hands you a request id. +`fission function logs --request-id` pulls that one invocation's logs. #### See a function's health at a glance @@ -67,7 +71,8 @@ PACKAGE: #### Read the failure attribution `fission function test` invokes a function and, on failure, tells you which component failed and why instead of just printing a status code. -Every run echoes the invocation's request id; a failure renders the structured attribution: +Every run echoes the invocation's request id. +A failure renders the structured attribution: ```bash $ fission function test --name broken @@ -75,12 +80,15 @@ Request ID: 6f1c2a9e-1c2b-4f0a-9d2e-7b3c2a1d4e5f ✗ function "broken" failed in executor (specialization_failed) — status 500, request 6f1c2a9e-... ``` -Now you know it failed during **specialization** in the **executor** (not in your code, not a timeout), and you have the request id to find its logs. +Now you know it failed during **specialization** in the **executor** — not in your code, not a timeout. +You also have the request id to find its logs. Against an older cluster that does not send structured errors, `test` falls back to printing the raw response body. #### The failure-attribution contract -Every response — success or failure — carries the request id, and failures add the component, so callers and tooling can attribute a failure without reading server logs: +Every response — success or failure — carries the request id. +A failure also adds the component. +Callers and tooling can then attribute a failure without reading server logs: | Header | Meaning | | --- | --- | @@ -112,10 +120,12 @@ The **reason** is a stable value you can match on: | `stream_idle` / `stream_max_duration` | A [streaming]({{% ref "streaming.md" %}}) response hit its idle or max-duration limit. | The body never includes raw internal error text by default. -To get verbose detail for a single call, send `X-Fission-Debug: true`; the router fills in a `message` field only when it is running in debug mode. +To get verbose detail for a single call, send `X-Fission-Debug: true`. +The router fills in a `message` field only when it is running in debug mode. {{% notice info %}} -**Operators:** structured error bodies are on by default and can be turned off with `ROUTER_STRUCTURED_ERRORS=false` on the router, which restores the legacy plain-text error body. +**Operators:** structured error bodies are on by default. +Set `ROUTER_STRUCTURED_ERRORS=false` on the router to turn them off and restore the legacy plain-text error body. Status codes are unchanged either way. {{% /notice %}} @@ -127,5 +137,6 @@ With the request id from `test` (or from a caller's `X-Fission-Request-ID` respo $ fission function logs --name hello --dbtype loki --request-id 6f1c2a9e-1c2b-4f0a-9d2e-7b3c2a1d4e5f ``` -`--request-id`, `--trace-id`, and `--level` are applied by the `loki` log database and are ignored by the default `kubernetes` driver. +The `loki` log database applies `--request-id`, `--trace-id`, and `--level`. +The default `kubernetes` driver ignores them. See [Logs with Loki]({{% ref "/docs/usage/observability/loki.md" %}}) for setup and the full query workflow, and [Local development with run-local]({{% ref "run-local.md" %}}) to reproduce and fix the failure locally without a redeploy. diff --git a/content/en/docs/usage/function/keyed-state.md b/content/en/docs/usage/function/keyed-state.md index 966f709b..55ccf248 100644 --- a/content/en/docs/usage/function/keyed-state.md +++ b/content/en/docs/usage/function/keyed-state.md @@ -7,11 +7,14 @@ description: > --- **Give a function durable key/value state without bringing your own Redis or database.** -A Fission function is normally stateless: nothing it writes to memory survives the request, and two requests may land on two different pods. -Anything that needs to remember something between requests — a per-user counter, a shopping cart, a login session, a rate limit, an AI agent's conversation history — usually means standing up Redis or a database, wiring its connection string into every environment image, and re-implementing tenancy and quotas per team. +A Fission function is normally stateless. +Nothing it writes to memory survives the request, and two requests may land on two different pods. +Many things must persist between requests: a per-user counter, a shopping cart, a login session, a rate limit, an AI agent's conversation history. +Each usually means standing up Redis or a database, wiring its connection string into every environment image, and re-implementing tenancy and quotas per team. Starting with Fission {{< release-version >}}, a function can opt into a **keyed state API** instead. -It gets a private keyspace of versioned key/value entries, reached over a local HTTP endpoint that Fission injects into the pod along with a scoped token. +It gets a private keyspace of versioned key/value entries. +Fission injects a local HTTP endpoint into the pod, along with a scoped token, so the function can reach it. Your code shrinks to `get` / `set` / `delete` / `list` against `localhost`-speed HTTP — portable across environments, with no client library and no secret to manage. State is **opt-in per function** and additive: functions that don't ask for it behave exactly as before. @@ -157,7 +160,10 @@ def state_client(): ### A per-user counter The simplest useful pattern: increment a value keyed by user id. -Because two requests for the same user can race, use the version returned by `get` as a **compare-and-swap** token on the `set` — the write only lands if nobody changed the value in between, and you retry on a conflict. +Two requests for the same user can race. +Use the version returned by `get` as a **compare-and-swap** token on the `set`. +The write only lands if nobody changed the value in between. +You retry on a conflict. No lost increments, no locks. ```javascript @@ -175,7 +181,8 @@ module.exports = async function (context) { }; ``` -The same shape covers **rate limiting** (increment a counter keyed by `client-ip`, reject past a threshold, let it expire with a TTL) and any other read-modify-write on a single key. +The same shape covers **rate limiting**: increment a counter keyed by `client-ip`, reject past a threshold, and let it expire with a TTL. +It also covers any other read-modify-write on a single key. ### A login session @@ -193,7 +200,9 @@ Set `--state-ttl 30m` on the function and stale sessions clean themselves up — ### A shopping cart -A cart is a value keyed by cart id; add-item is a read-modify-write with the same compare-and-swap retry as the counter, so two tabs adding items at once never clobber each other: +A cart is a value keyed by cart id. +Add-item is a read-modify-write, with the same compare-and-swap retry as the counter. +Two tabs adding items at once never clobber each other: ```javascript const cur = await state.get(cartId); @@ -205,7 +214,9 @@ const code = await state.set(cartId, JSON.stringify(cart), { ifVersion: cur ? cu ### AI agent conversation memory -Give an agent function a durable memory keyed by conversation id — append each turn and read the history back on the next call, so the agent remembers across requests without a vector store or database for the transcript itself. +Give an agent function a durable memory keyed by conversation id. +Append each turn and read the history back on the next call. +The agent then remembers across requests, without a vector store or database for the transcript itself. ```javascript const key = `conv:${conversationId}`; @@ -219,7 +230,8 @@ await state.set(key, JSON.stringify(history), { ifVersion: cur ? cur.version : 0 ## Keep an in-memory cache coherent with sticky routing Everything above is durable and correct no matter which pod serves a request. -If your function also keeps an **in-memory cache** on top of that durable state — to avoid a round trip on hot keys — you want all requests for one key to keep landing on the same pod so that cache stays warm and coherent. +Your function may also keep an **in-memory cache** on top of that durable state, to avoid a round trip on hot keys. +In that case, you want all requests for one key to land on the same pod, so the cache stays warm and coherent. Turn on **sticky routing** by telling Fission where the key lives in the request: ```bash @@ -228,16 +240,19 @@ fission function create --name game-room --env nodejs --code room.js --state \ --state-sticky-name X-Room-Id ``` -Now requests carrying the same `X-Room-Id` are consistent-hashed onto the same ready pod while the pod set is stable. +Fission now consistent-hashes requests carrying the same `X-Room-Id` onto the same ready pod while the pod set is stable. Sources can be a `header` or a `queryparam`. -Sticky routing is a **performance optimization, not a correctness guarantee**: on a scale event or pod replacement a key may move to another pod, and its in-memory cache warms up again from the state API. +Sticky routing is a **performance optimization, not a correctness guarantee**. +On a scale event or pod replacement, a key may move to another pod. +Its in-memory cache then warms up again from the state API. The durable truth always lives in the state API, so a request that lands on a different pod is never wrong — only, briefly, colder. Requests that don't carry the key fall back to normal routing. ## Inspect and manage state from the CLI -`fission function state` reaches the same keyspace as an operator, useful for debugging and cleanup (it needs the cluster's internal auth secret, so it fails closed if that is not configured): +`fission function state` reaches the same keyspace as an operator, useful for debugging and cleanup. +It needs the cluster's internal auth secret, so it fails closed if that is not configured: ```bash fission function state set --name cart --key demo-cart --value '{"items":[]}' @@ -249,13 +264,16 @@ fission function state delete --name cart --key demo-cart ## Lifecycle, limits, and cleanup - **State is shared across [function versions]({{% ref "versions-aliases.md" %}}).** - The keyspace belongs to the function, not to any one published version, so repointing or rolling back an alias rolls back code — never data — and both sides of a weighted split read and write the same keyspace. + The keyspace belongs to the function, not to any one published version. + Repointing or rolling back an alias rolls back code — never data. + Both sides of a weighted split read and write the same keyspace. - **Deleting a function purges its keyspace** by default, so state doesn't leak after the function is gone. Annotate the function with `fission.io/state-retain: "true"` to keep the data (for example to re-attach a replacement function to the same keyspace). - **Quotas are enforced for you.** A value larger than `--state-max-value-bytes` is rejected; creating a key past `--state-max-keys` is rejected — atomically, so concurrent writers can't overshoot the budget. - **This is key/value, not a database.** - There are no cross-key transactions, no secondary indexes, and values are capped (256 KiB by default) — large blobs belong in object storage, relational data in a real database. + There are no cross-key transactions, no secondary indexes, and values are capped (256 KiB by default). + Large blobs belong in object storage, relational data in a real database. It is exactly the right tool for the "remember a small thing per key" workloads above. - **Executor type.** State works with the `poolmgr` (default) and `newdeploy` executors. diff --git a/content/en/docs/usage/function/mcp-tools.md b/content/en/docs/usage/function/mcp-tools.md index 959e8622..093ce705 100644 --- a/content/en/docs/usage/function/mcp-tools.md +++ b/content/en/docs/usage/function/mcp-tools.md @@ -8,7 +8,8 @@ description: > **Expose a Fission function as an MCP tool so any LLM agent that speaks MCP can discover and invoke it, with no hand-written adapter code.** The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open protocol that lets LLM agents discover and call external tools. -Starting with Fission {{< release-version >}}, an agent that speaks MCP (for example Claude) can list an advertised function and invoke it over Fission's existing internal invocation path. +Starting with Fission {{< release-version >}}, an agent that speaks MCP (for example Claude) can list an advertised function. +It can then invoke the function over Fission's existing internal invocation path. Exposing a function as a tool is **opt-in per function** and additive — functions you don't mark stay private. @@ -64,7 +65,8 @@ fission fn create --name weather --env nodejs --code weather.js \ --tool-input-schema weather-schema.json ``` -`--tool-input-schema` points at a JSON Schema (draft 2020-12) file describing the tool's arguments; it is advertised verbatim as the MCP tool `inputSchema`. +`--tool-input-schema` points at a JSON Schema (draft 2020-12) file describing the tool's arguments. +Fission advertises it verbatim as the MCP tool `inputSchema`. When omitted, the tool advertises an open object schema (`{"type":"object"}`). | Flag | Meaning | diff --git a/content/en/docs/usage/function/oci-packages.md b/content/en/docs/usage/function/oci-packages.md index 53b5a318..fc8bfa74 100644 --- a/content/en/docs/usage/function/oci-packages.md +++ b/content/en/docs/usage/function/oci-packages.md @@ -6,7 +6,8 @@ description: > Ship Fission function code as an OCI image instead of an archive: build a code-only image, create a package with --oci, and pin digests for fast cold starts. --- -**Ship Fission function code as an OCI image instead of a zip archive: build a code-only image, push it to any OCI registry, and reference it when creating the package.** +**Ship Fission function code as an OCI image instead of a zip archive.** +**Build a code-only image, push it to any OCI registry, and reference it when creating the package.** Available starting with Fission v1.26.0. Create the package with `--oci`: @@ -32,7 +33,8 @@ flowchart TB #### Why deliver code as an image? -* **Faster, cache-friendly cold starts**: nodes and registries cache image layers, so repeated fetches of the same code are cheap, and there is no zip download + extract step from Fission's internal storage. +* **Faster, cache-friendly cold starts**: nodes and registries cache image layers, so repeated fetches of the same code are cheap. + There is no zip download + extract step from Fission's internal storage. * **Standard supply-chain tooling**: code images can be signed (`cosign`), scanned, replicated, and promoted with the same tooling you already use for runtime images. * **Registry-native workflows**: CI pipelines that already push images need no extra upload step to Fission's storage service. @@ -41,8 +43,10 @@ With neither configured, archive-based packages remain the default and are unaff #### Building a compatible code image -The image's filesystem must contain exactly what an *extracted deployment archive* would contain — your code files at the image root (or under a sub-path, see below). -The environment's runtime still comes from the environment image; the code image carries **only your code**. +The image's filesystem must contain exactly what an *extracted deployment archive* would contain. +That means your code files at the image root, or under a sub-path (see below). +The environment's runtime still comes from the environment image. +The code image carries **only your code**. For a Python function with a `main` entry point in `hello.py`: @@ -88,9 +92,12 @@ $ crane append --new_layer code.tar \ The code image is never executed as a container — Fission only reads its filesystem — so it needs no shell, libc, or OS layer. A scratch-based code image is a few kilobytes, pulls fast, and has no CVE surface. * Do **not** base the code image on the environment/runtime image. - The runtime is supplied by the environment; duplicating it in the code image wastes pull time and storage and changes nothing at runtime. -* If your build pipeline cannot produce `FROM scratch` images, any minimal base works — Fission extracts the *merged* filesystem, so whatever the image contains beyond your code is extracted too. - Keep it small and put code under a dedicated directory combined with `subPath` (below) so OS files are excluded. + The environment supplies the runtime. + Duplicating it in the code image wastes pull time and storage and changes nothing at runtime. +* If your build pipeline cannot produce `FROM scratch` images, any minimal base works. + Fission extracts the *merged* filesystem, so it also extracts anything in the image beyond your code. + Keep it small, and put code under a dedicated directory. + Combine this with `subPath` (below) to exclude OS files. #### Creating packages and functions @@ -105,7 +112,9 @@ $ curl http://$FISSION_ROUTER/hello Hello, world! ``` -`fission fn create --oci <ref>` is a shortcut that creates the package and the function in one step, and `fission package update --name hello --oci <ref:v2>` switches a package to a new image (followed by `fn update` to roll running functions, exactly like archive updates). +`fission fn create --oci <ref>` is a shortcut that creates the package and the function in one step. +`fission package update --name hello --oci <ref:v2>` switches a package to a new image. +Follow it with `fn update` to roll running functions, exactly like archive updates. The package spec exposes a few more fields than the CLI flag; use spec files for these: @@ -132,14 +141,17 @@ spec: {{% notice info %}} **Pin digests in production.** -A package references an image; re-pushing the same tag with different content is **not** detected automatically (functions roll only on package update). +A package references an image. +Re-pushing the same tag with different content is **not** detected automatically (functions roll only on package update). Setting `digest` makes the reference immutable and the pull verifiable. {{% /notice %}} #### Automatic OCI delivery for built packages The `--oci` flow above is **per package** — you build and push the image yourself. -You can also have Fission do this for **every** build cluster-wide: configure a **package registry** and each successful build publishes its deployment archive as a digest-pinned OCI image, and functions cold-start by pulling it instead of downloading a tarball from the storage service. +You can also have Fission do this for **every** build cluster-wide: configure a **package registry**. +Each successful build then publishes its deployment archive as a digest-pinned OCI image. +Functions cold-start by pulling it instead of downloading a tarball from the storage service. Enable it with Helm: @@ -202,7 +214,8 @@ $ kubectl create secret docker-registry regcred \ ##### Step 2a — cluster-wide: attach the secret to the fetcher service account -Patch the `fission-fetcher` service account in the same namespace; every OCI package pull then uses it without any per-package configuration: +Patch the `fission-fetcher` service account in the same namespace. +Every OCI package pull then uses it without any per-package configuration: ```bash $ kubectl patch serviceaccount fission-fetcher \ @@ -232,7 +245,8 @@ spec: ##### Verifying -Create a function on the package and invoke it; on a credential problem the function returns a 5xx and the fetcher log names the registry error: +Create a function on the package and invoke it. +On a credential problem, the function returns a 5xx and the fetcher log names the registry error: ```bash $ kubectl logs <function-pod> -c fetcher -n default | grep -i "error extracting OCI image" @@ -240,10 +254,12 @@ $ kubectl logs <function-pod> -c fetcher -n default | grep -i "error extracting {{% notice warning %}} Fission does not validate that the referenced secrets exist or hold working credentials — a missing or wrong secret surfaces only at pull time. -With [image volumes](#kubernetes-image-volumes) active (the default on Kubernetes 1.33+), the **kubelet** performs the pull using the same two secret sources (the pod inherits both), so the same setup keeps working — but pull errors then appear as pod events (`kubectl describe pod`, `ErrImagePull`) rather than fetcher logs. +With [image volumes](#kubernetes-image-volumes) active (the default on Kubernetes 1.33+), the **kubelet** performs the pull using the same two secret sources (the pod inherits both), so the same setup keeps working. +Pull errors then appear as pod events (`kubectl describe pod`, `ErrImagePull`) rather than fetcher logs. {{% /notice %}} -Runtime/environment images are pulled by the kubelet independently of package images; for those, see [Pull an Image From a Private Registry]({{% ref "/docs/usage/function/private-registry.md" %}}). +The kubelet pulls runtime/environment images independently of package images. +For those, see [Pull an Image From a Private Registry]({{% ref "/docs/usage/function/private-registry.md" %}}). #### Insecure (plain-HTTP) registries @@ -256,13 +272,15 @@ fetcher: ``` This is a comma-separated host allowlist, not a global switch — every other registry still requires TLS. -Localhost and private (RFC-1918) IP addresses are implicitly trusted by the underlying client, matching Docker's behavior. +The underlying client implicitly trusts localhost and private (RFC-1918) IP addresses, matching Docker's behavior. #### Kubernetes image volumes -On Kubernetes **1.33+** the **kubelet** mounts the code image directly into function pods as an [image volume](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/), removing the fetch-and-extract step from the cold-start path entirely. +On Kubernetes **1.33+** the **kubelet** mounts the code image directly into function pods as an [image volume](https://kubernetes.io/docs/tasks/configure-pod-container/image-volumes/). +This removes the fetch-and-extract step from the cold-start path entirely. This is **on by default** (`executor.enableOCIImageVolume: true` in the Helm chart). -On clusters below 1.33 image volumes are detected as unsupported, and packages automatically use the per-pod fetcher, which pulls and extracts the image itself. +On clusters below 1.33, Fission detects image volumes as unsupported. +Packages then automatically use the per-pod fetcher, which pulls and extracts the image itself. To force the fetcher path on every cluster, disable the setting: ```yaml @@ -273,14 +291,16 @@ executor: Be aware of the behavioral differences when image volumes are active: * **The kubelet pulls the image, not Fission.** - Image references resolve with the node's DNS and containerd's registry configuration — a registry reachable only through cluster DNS (a ClusterIP `Service` name) will not resolve. + Image references resolve with the node's DNS and containerd's registry configuration. + A registry reachable only through cluster DNS (a ClusterIP `Service` name) will not resolve. Use a registry address that nodes can reach. -* Functions that reference **Secrets or ConfigMaps** still mount the code as an image volume; their pods keep the fetcher, which materializes those Secrets and ConfigMaps. +* Functions that reference **Secrets or ConfigMaps** still mount the code as an image volume. + Their pods keep the fetcher, which materializes those Secrets and ConfigMaps. * Poolmgr functions on **v1 environments**, and those whose environment sets `allowedFunctionsPerContainer: infinite` or `keepArchive: true`, stay on the fetcher path. * The code mount is **read-only**. Runtimes that write next to the code (Python bytecode caches, JVM work files) should write elsewhere; the standard Fission environments handle this. * `subPath` must point to a **directory** inside the image (kubelets reject file sub-paths). -* The `digest` pin is enforced by the kubelet through the volume's image reference. +* The kubelet enforces the `digest` pin through the volume's image reference. #### Limitations diff --git a/content/en/docs/usage/function/provisioned-concurrency.md b/content/en/docs/usage/function/provisioned-concurrency.md index bd523bde..35424c7f 100644 --- a/content/en/docs/usage/function/provisioned-concurrency.md +++ b/content/en/docs/usage/function/provisioned-concurrency.md @@ -6,12 +6,15 @@ description: > Keep a floor of warm specialized pods for a poolmgr function, with cron-scheduled warming windows, so requests inside the floor never pay a cold start. --- -**Declare a floor of always-warm capacity: the executor keeps N specialized pods ready before any request arrives, and cron-scheduled windows raise or lower that floor for known traffic patterns.** +**Declare a floor of always-warm capacity: the executor keeps N specialized pods ready before any request arrives.** +Cron-scheduled windows raise or lower that floor for known traffic patterns. The poolmgr warm pool is generic: pods idle without your code loaded. -The first request per pod pays package fetch and load, and the idle reaper un-warms quiet functions, so off-hours traffic pays it again. +The first request per pod pays package fetch and load. +The idle reaper un-warms quiet functions, so off-hours traffic pays that cold start again. Starting with Fission {{< release-version >}}, provisioned concurrency removes that cold start for opted-in functions. -The executor specializes pods eagerly, exempts them from the idle reaper, and publishes them to the router, so requests within the floor always hit a warm pod. +The executor specializes pods eagerly, exempts them from the idle reaper, and publishes them to the router. +Requests within the floor always hit a warm pod. Requests beyond the floor behave exactly as before: they pay a normal on-demand cold start. ```mermaid @@ -59,7 +62,8 @@ function 'checkout' created The executor's provisioner reconciles every 30 seconds (Helm: `executor.provisionedConcurrency.reconcileInterval`). On each pass it counts ready warm pods for the function. -If the count is below the target, it specializes more pods from the generic pool — the same code path a cold start uses, so the pods are identical. +If the count is below the target, it specializes more pods from the generic pool. +This is the same code path a cold start uses, so the pods are identical. If the count is above the target, it removes the exemption label from the excess pods and lets the idle reaper retire them. Warming is paced, not instant. @@ -140,7 +144,8 @@ Warm pods carry the `fission.io/provisioned=true` label: kubectl get pods -A -l fission.io/provisioned=true ``` -`fission fn pods --name checkout` lists the same pods, but its columns do not show the provisioned label — use the kubectl label filter to tell warm floor pods apart. +`fission fn pods --name checkout` lists the same pods, but its columns do not show the provisioned label. +Use the kubectl label filter to tell warm floor pods apart. The executor also exports metrics: `fission_provisioned_target`, `fission_provisioned_ready`, `fission_provisioned_eager_specializations_total` (by outcome), and `fission_provisioned_window_transitions_total`. @@ -155,7 +160,8 @@ A clamped function shows `provisionedSpecTarget > provisionedTarget` and reason Eager specialization consumes generic pool pods. If the pool cannot supply them, warming stalls until the pool refills — raise the environment `--poolsize` to absorb the largest window target. - **Warm-up bursts can slow other functions' worst-case cold starts.** -While one function eagerly warms a large burst, on-demand cold starts of other functions in the same environment pool can be several times slower at the tail; the median stays bounded. +While one function eagerly warms a large burst, on-demand cold starts of other functions in the same environment pool can be several times slower at the tail. +The median stays bounded. The in-flight limit and a larger pool reduce the effect. - **Latest generation only.** After a function update, the provisioner warms the new generation and lets old-generation pods drain. diff --git a/content/en/docs/usage/function/run-local.md b/content/en/docs/usage/function/run-local.md index b4014c7e..63d0b23e 100644 --- a/content/en/docs/usage/function/run-local.md +++ b/content/en/docs/usage/function/run-local.md @@ -6,10 +6,13 @@ description: > Run a Fission function locally in Docker against its real environment image — no cluster round-trip — with hot reload, a builder pass, and config mounts. --- -`fission function run-local` runs a single function on your laptop in Docker, against the **same environment runtime image** the cluster uses, so you can iterate without a build-and-deploy round-trip. -A normal edit → deploy → test cycle goes through a package build and a specialization on the cluster and takes tens of seconds to a couple of minutes; `run-local` collapses that to a local pull-once, then sub-second re-runs on each edit. +`fission function run-local` runs a single function on your laptop in Docker, against the **same environment runtime image** the cluster uses. +You iterate without a build-and-deploy round-trip. +A normal edit → deploy → test cycle goes through a package build and a specialization on the cluster and takes tens of seconds to a couple of minutes. +`run-local` collapses that to a local pull-once, then sub-second re-runs on each edit. -It reproduces the cluster's behavior faithfully — the runtime image, the specialize contract, and the invocation headers all match — so a function that works under `run-local` works the same way once deployed. +It reproduces the cluster's behavior faithfully: the runtime image, the specialize contract, and the invocation headers all match. +A function that works under `run-local` works the same way once deployed. {{% notice info %}} `run-local` is an **alpha** command; its flags and output may change. @@ -27,7 +30,7 @@ flowchart LR classDef user fill:#ffffff,stroke:#94a3b8,color:#1f2a43 classDef fission fill:#e8f0fe,stroke:#2d70de,color:#1f2a43 classDef pod fill:#e6f7f1,stroke:#11a37f,color:#1f2a43,stroke-dasharray:5 3 - classDef store fill:#fff7e0,stroke:#dba514,color:#1f2a43 + classDef store fill:#fff7e0,stroke:#dba514,color:#1f2a43,stroke-dasharray:5 3 ``` #### Prerequisites @@ -53,11 +56,13 @@ Specializing function ... Hello, world! ``` -`run-local` pulls the image (showing layer progress), starts the container, replays the specialize contract over your code, invokes the function once, prints the response, and tears the container down. +`run-local` pulls the image (showing layer progress), starts the container, and replays the specialize contract over your code. +Then it invokes the function once, prints the response, and tears the container down. Status lines are color-coded on a terminal — cyan for progress, green for milestones, red for failures, dim for container logs — and plain when the output is piped or `NO_COLOR` is set. The function is published on `127.0.0.1` at an auto-selected port (shown in the output). -`--port` sets the port the application **inside** the container listens on (default `8888`, the Fission environment contract port); change it only for a `container` function whose image listens elsewhere. +`--port` sets the port the application **inside** the container listens on (default `8888`, the Fission environment contract port). +Change it only for a `container` function whose image listens elsewhere. #### Running against a cluster environment @@ -67,12 +72,13 @@ If you have a cluster, resolve the runtime (and builder) image from an existing $ fission function run-local --env nodejs --code hello.js ``` -`--env` reads the `Environment` CRD for its runtime image; pass `--namespace` to resolve an environment outside `default`. +`--env` reads the `Environment` CRD for its runtime image. +Pass `--namespace` to resolve an environment outside `default`. Use `--image` instead when you want to stay fully offline or pin a specific image tag. #### Invoking the function -`run-local` reuses the same invocation flags as [`fission function test`]({{% ref "functions.en.md" %}}), so the request is built exactly as the cluster builds it: +`run-local` reuses the same invocation flags as [`fission function test`]({{% ref "functions.en.md" %}}), so it builds the request exactly as the cluster does: ```bash $ fission function run-local --image ghcr.io/fission/python-env --code hello.py \ @@ -95,12 +101,14 @@ Specializing function ... Serving local at http://127.0.0.1:63048 — watching hello.js for changes (Ctrl-C to stop) ``` -Edit and save `hello.js`, and `run-local` reloads it; `curl http://127.0.0.1:63048` then returns the new response. +Edit and save `hello.js`, and `run-local` reloads it. +`curl http://127.0.0.1:63048` then returns the new response. The watch scope follows the source: * A single `--code` file watches that one file. -* A directory source — `--deploy <dir>`, or a builder project (Go, Java, …) — watches the **whole tree**, so editing any file inside it triggers a reload. +* A directory source — `--deploy <dir>`, or a builder project (Go, Java, …) — watches the **whole tree**. + Editing any file inside it triggers a reload. Version-control and dependency/build directories (`.git`, `node_modules`, `vendor`, `target`, `.next`, `__pycache__`) and editor swap files are ignored. A reload **restarts** the container rather than re-specializing in place, because published environment runtimes reject a second specialization on an already-specialized process. @@ -142,7 +150,8 @@ For an app that is more than one file — a multi-module project, or a pre-built $ fission function run-local --image ghcr.io/fission/node-env --deploy ./app --entrypoint server ``` -The directory is bind-mounted directly into the container (large dependency trees are not copied), and a `.zip` source is extracted automatically before mounting. +`run-local` bind-mounts the directory directly into the container, so it does not copy large dependency trees. +It extracts a `.zip` source automatically before mounting. #### Executor types diff --git a/content/en/docs/usage/function/streaming.md b/content/en/docs/usage/function/streaming.md index 92ca9f5a..3b311318 100644 --- a/content/en/docs/usage/function/streaming.md +++ b/content/en/docs/usage/function/streaming.md @@ -6,8 +6,8 @@ description: > Stream a Fission function's response incrementally over Server-Sent Events, HTTP chunked transfer, or WebSocket — for LLM tokens, chat, and long-running calls. --- -**Starting with Fission {{< release-version >}}, a function can stream its response incrementally — over Server-Sent Events (SSE), HTTP chunked transfer, or a WebSocket upgrade — instead of buffering the whole response behind `functionTimeout`.** -The response is flushed to the client as it is produced and is **not** bound by `functionTimeout`. +**Starting with Fission {{< release-version >}}, a function can stream its response incrementally — over Server-Sent Events (SSE), HTTP chunked transfer, or a WebSocket upgrade.** +The response flushes to the client as it is produced and is **not** bound by `functionTimeout`. By default, though, a function still buffers its full response and the router cuts the request off at that limit. Streaming is **per-function and opt-in**: omit the `spec.streaming` object (or the `--streaming` flag) and the function keeps the existing buffered behavior exactly. @@ -65,7 +65,8 @@ See the [function timeout concept]({{% ref "/docs/concepts/functions.md" %}}) fo ## Protocols -`auto` (the default) handles every case; set a specific protocol only to signal intent. +`auto` (the default) handles every case. +Set a specific protocol only to signal intent. Streaming works on both the public HTTPTrigger route and the internal `/fission-function/<ns>/<name>` invocation path. {{< tabs >}} @@ -95,7 +96,8 @@ wscat -c ws://<router>/ws ## WebSocket WebSocket is now first-class for **every** environment, not just the Python GEVENT environment. -The router upgrades the connection and holds the function pod for the socket's whole lifetime (a router-driven keepalive), and the `main(ws, clients)` programming model is unchanged. +The router upgrades the connection and holds the function pod for the socket's whole lifetime (a router-driven keepalive). +The `main(ws, clients)` programming model is unchanged. After the `101` upgrade the router pipes bytes both ways and cannot observe idle time, so the idle timeout only bounds the time to upgrade. Set `--streamingmaxduration` to bound the socket's total lifetime. diff --git a/content/en/docs/usage/function/versions-aliases.md b/content/en/docs/usage/function/versions-aliases.md index f629c83c..4b0cff51 100644 --- a/content/en/docs/usage/function/versions-aliases.md +++ b/content/en/docs/usage/function/versions-aliases.md @@ -8,7 +8,8 @@ description: > **Publish a function as immutable versions, point named aliases like `prod` and `staging` at them, and roll back a bad deploy in seconds — without editing a single trigger and without a cold start.** -A plain `fission fn update` changes the live function in place: every trigger that names the function immediately serves the new code, and the only way back is another update. +A plain `fission fn update` changes the live function in place. +Every trigger that names the function immediately serves the new code, and the only way back is another update. Starting with Fission {{< release-version >}}, a function can also have **versions** and **aliases**: - A **version** (`FunctionVersion`, `kubectl get fnver`) is an immutable snapshot of the function's spec and package content at publish time, named `<function>-v<sequence>` (for example `orders-v3`). @@ -29,7 +30,8 @@ flowchart LR ``` This is fully backward compatible. -A trigger that references a bare function name keeps meaning "the live function", exactly as before — nothing changes until you publish a version and point something at it. +A trigger that references a bare function name keeps meaning "the live function", exactly as before. +Nothing changes until you publish a version and point something at it. ## Publish a version @@ -72,8 +74,12 @@ orders-v2 2 sha256:60303ae22b99 2026-07-17T16:41:55Z - 7d orders-v3 3 sha256:fd61a03af4f7 2026-07-24T08:03:11Z prod 2m ``` -The `DIGEST` column pins the exact package content of each version, and `ALIASED-BY` shows which aliases currently reference it — a `-` means the version is unreferenced and eligible for [retention GC]({{% ref "versions-lifecycle.md#retention" %}}). -The table truncates digests; `-o wide` prints them in full and adds an `ENVDRIFT` column showing whether the version was published under an older generation of its environment (see [environment updates and drift]({{% ref "versions-lifecycle.md#environment-updates-and-drift" %}})), plus the `DESCRIPTION` recorded at publish time. +The `DIGEST` column pins the exact package content of each version. +`ALIASED-BY` shows which aliases currently reference it — a `-` means the version is unreferenced and eligible for [retention GC]({{% ref "versions-lifecycle.md#retention" %}}). +The table truncates digests. +`-o wide` prints digests in full. +It adds an `ENVDRIFT` column showing whether the version predates the environment's current generation (see [environment updates and drift]({{% ref "versions-lifecycle.md#environment-updates-and-drift" %}})). +It also adds the `DESCRIPTION` recorded at publish time. `-o name` prints one version name per line, for scripting; `-o json` / `-o yaml` print the full objects. To read a version rather than list them, `fission fn get --version` prints the exact source snapshot the version froze: @@ -101,7 +107,8 @@ staging orders orders-v4 <none> orders-v4 `--wait` blocks until the alias's `Resolved` condition confirms the target — the same flag `alias update` takes, so a CI job can gate on either. Without it, creation returns immediately and resolution completes asynchronously. -`fission alias get --name prod` shows the same row plus the alias's status conditions and — once the alias has been repointed at least once — a `HISTORY` block listing its previous targets, most recent last: +`fission alias get --name prod` shows the same row, plus the alias's status conditions. +Once the alias has been repointed at least once, it also shows a `HISTORY` block listing its previous targets, most recent last: ```bash $ fission alias get --name prod @@ -119,13 +126,15 @@ orders-v2 2d orders-v3 8s ``` -The last history entry is what a bare `fission fn rollback` returns to, so `alias get` is the fastest way to see where a rollback would land. +The last history entry is what a bare `fission fn rollback` returns to. +`alias get` is therefore the fastest way to see where a rollback would land. `fission alias delete --name prod` removes the alias. An alias lives in the same namespace as its function, and one function can have any number of aliases. ## Testing an alias or version -`fission fn test` takes `--alias` and `--version` so you can smoke-test one alias or one pinned version directly, without touching a trigger and without waiting for the alias to actually see traffic: +`fission fn test` takes `--alias` and `--version`, so you can smoke-test one alias or one pinned version directly. +It needs no trigger, and no wait for the alias to see traffic: ```bash $ fission fn test --name orders --alias prod @@ -136,7 +145,8 @@ $ fission fn test --name orders --version orders-v3 ``` `--alias` and `--version` are mutually exclusive. -Each is checked against the function before the request is sent, so a typo'd name fails immediately with a clear error instead of an opaque router 404: +Each is checked against the function before the request is sent. +A typo'd name fails immediately with a clear error, instead of an opaque router 404: ```bash $ fission fn test --name orders --alias staging @@ -144,11 +154,13 @@ Error: alias "staging" not found for function "orders": functionaliases.fission. ``` `--async` works with either flag too. -The invocation is enqueued against the resolved alias/version route, so it stays pinned to that target even if the alias moves before the function actually runs. +Fission enqueues the invocation against the resolved alias/version route. +It stays pinned to that target even if the alias moves before the function actually runs. ## Inspecting versions, aliases, and their pods -`fission fn describe` on a versioned function ends with a `VERSIONING` section — the versioning mode, the version count, and one row per alias — and its `PODS` table gains a `VERSION` column showing which version each specialized pod is serving: +`fission fn describe` on a versioned function ends with a `VERSIONING` section: the versioning mode, the version count, and one row per alias. +Its `PODS` table also gains a `VERSION` column, showing which version each specialized pod serves: ```bash $ fission fn describe --name orders @@ -166,7 +178,8 @@ prod orders-v3 <none> False staging orders-v4 <none> False ``` -Add `--version` to describe one version instead of the function — an inspector over the immutable snapshot, including its digest, publish-time description, the environment generation it was published under, and which aliases reference it: +Add `--version` to describe one version instead of the function. +This inspects the immutable snapshot: its digest, publish-time description, the environment generation it was published under, and which aliases reference it: ```bash $ fission fn describe --name orders --version orders-v3 @@ -188,7 +201,8 @@ NAME TARGET WEIGHT ENVDRIFT prod orders-v3 <none> False ``` -The same per-target filtering works on `fission fn pods` and `fission fn logs`: `--version` narrows to pods serving one pinned version, `--alias` follows an alias to whatever it currently resolves to. +The same per-target filtering works on `fission fn pods` and `fission fn logs`. +`--version` narrows to pods serving one pinned version; `--alias` follows an alias to whatever it currently resolves to. During a weighted split or an incident, that is the difference between reading interleaved logs from two versions and reading exactly the one you care about: ```bash @@ -216,7 +230,8 @@ trigger 'orders-api' created ``` `--function-alias` requires exactly one `--function` and is mutually exclusive with `--function-version` and with weighted multi-function routing. -The same flag works on `fission route update`, with one wrinkle: pass `--function` again alongside it — `route update` does not infer the target function from the existing route. +The same flag works on `fission route update`, with one wrinkle. +Pass `--function` again alongside it — `route update` does not infer the target function from the existing route. For GitOps pipelines, the same field is settable declaratively — write the trigger with `--spec` and edit the generated file, or apply YAML directly: @@ -251,7 +266,8 @@ functionref: alias: staging ``` -To pin a route permanently to one immutable snapshot instead, pass `--function-version orders-v3` (or set `functionref.version: orders-v3` in YAML) — unlike an alias, a version pin never moves. +To pin a route permanently to one immutable snapshot instead, pass `--function-version orders-v3` (or set `functionref.version: orders-v3` in YAML). +Unlike an alias, a version pin never moves. `alias` and `version` are mutually exclusive, and both are valid on every trigger kind that embeds a function reference (HTTP, message queue, timer, Kubernetes watch). ## Deploy by moving the alias @@ -382,7 +398,9 @@ $ fission alias wait --name prod --for condition=Resolved --timeout 120s ``` `version` and `packageDigest` are mutually exclusive — exactly one must be set. -Promotion between environments is then just two aliases converging: point `staging` at a new version, test through the staging route, and promote by repointing `prod` at the **same** version — the identical immutable snapshot, not a rebuild. +Promotion between environments is then just two aliases converging. +Point `staging` at a new version and test through the staging route. +Promote by repointing `prod` at the **same** version — the identical immutable snapshot, not a rebuild. Versions themselves are deliberately **not** spec-managed: the cluster mints them, and Git references them by name or digest. diff --git a/content/en/docs/usage/function/versions-lifecycle.md b/content/en/docs/usage/function/versions-lifecycle.md index 6951e907..fbb9270a 100644 --- a/content/en/docs/usage/function/versions-lifecycle.md +++ b/content/en/docs/usage/function/versions-lifecycle.md @@ -24,8 +24,10 @@ Function 'orders' updated ``` `--versioning` takes `auto` (the default once versioning is enabled), `manual`, or `off`. -`off` is only meaningful on `fn update` — it clears the versioning config; on `fn create` there is nothing to clear yet, so omitting `--versioning` and passing `--versioning off` are equivalent. -`--retain-versions` sets the retention floor (see below) and requires versioning to already be enabled — pass `--versioning` in the same command, or add `--retain-versions` on its own once the function already carries a `versioning` block. +`off` is only meaningful on `fn update`, where it clears the versioning config. +On `fn create` there is nothing to clear yet, so omitting `--versioning` and passing `--versioning off` are equivalent. +`--retain-versions` sets the retention floor (see below), and requires versioning to already be enabled. +Pass `--versioning` in the same command, or add `--retain-versions` on its own once the function already carries a `versioning` block. `--retain-versions` is distinct from `--retainpods`, which controls how many specialized pods stay warm — not how many function versions are kept. The same fields are also settable directly on the function's spec — in a [spec file]({{% ref "/docs/usage/spec/_index.md" %}}) or with `kubectl patch`, if you'd rather manage it that way: @@ -46,7 +48,8 @@ spec: $ kubectl patch function orders --type merge -p '{"spec":{"versioning":{"mode":"auto","retain":10}}}' ``` -In `auto` mode, Fission publishes a new version after every **runtime-affecting** update — a change to what actually runs or is observable by an invocation, such as new code, a changed entry point, or changed resources. +In `auto` mode, Fission publishes a new version after every **runtime-affecting** update. +That means a change to what runs, or what an invocation can observe — new code, a changed entry point, or changed resources. Cosmetic edits (labels, annotations) do not mint versions. The CLI reminds you that the mint is pending after every such update: @@ -60,7 +63,8 @@ versioning=auto: a new version is minted once the build succeeds (fission fn ver The version is minted only **after the referenced package build succeeds**, so a broken build never becomes a version an alias could point at. If a build is in flight when you update, the version appears when the build completes. -Set `--versioning manual` (or `mode: manual` in the spec) to keep versioning opted in (retention GC, alias support) but mint versions only on explicit `fission fn publish`. +Set `--versioning manual` (or `mode: manual` in the spec) to keep versioning opted in — retention GC and alias support both still apply. +Versions are then minted only on explicit `fission fn publish`. `fission fn publish` itself works on any function, whether or not `spec.versioning` is set. ## Retention @@ -85,7 +89,8 @@ The `ALIASED-BY` column of `fission fn versions` shows exactly which alias prote ### Deleting the function Deleting a versioned function cascades: its versions and aliases go with it. -`fission fn delete` says so before doing it, and calls out any triggers that route through the doomed aliases — those triggers are **not** deleted, but they stop resolving: +`fission fn delete` warns before doing it, and calls out any triggers that route through the doomed aliases. +Those triggers are **not** deleted, but they stop resolving: ```bash $ fission fn delete --name orders @@ -96,7 +101,8 @@ function 'orders' deleted ## Environment updates and drift Versions snapshot the function's **code and configuration** — not the environment's runtime image. -An environment update (say, bumping `node` to a new image) recycles pods under **every** version of every function using it; it sits outside the version boundary entirely. +An environment update (say, bumping `node` to a new image) recycles pods under **every** version of every function using it. +It sits outside the version boundary entirely. That has one operational consequence worth internalizing: {{% notice warning %}} @@ -127,8 +133,12 @@ orders staging orders-v3 5 5 False reports <none> <none> <none> 5 <none> ``` -`DRIFT` is `True` (published under an older environment generation), `False` (current), `OtherEnv` (the version was published when the function still used a different environment), or `<none>` (no alias or not assessable). -`fission fn versions --name orders -o wide` shows the same verdict per version in its `ENVDRIFT` column, and the per-version inspector (`fission fn describe --name orders --version orders-v2`) spells it out in full — the environment generation the version was published under, the live runtime image, and an `Env Drift` verdict. +`DRIFT` is `True` when the version was published under an older environment generation, or `False` when it's current. +It is `OtherEnv` when the version was published under a different environment. +It is `<none>` when there is no alias, or drift cannot be assessed. +`fission fn versions --name orders -o wide` shows the same verdict per version, in its `ENVDRIFT` column. +The per-version inspector (`fission fn describe --name orders --version orders-v2`) spells it out in full. +It shows the environment generation the version was published under, the live runtime image, and an `Env Drift` verdict. ## How other invocation paths behave @@ -162,7 +172,8 @@ The canary controller then steps the alias's weight toward `orders-v4`, watching On success it promotes: the alias is repointed fully at the new version. On failure it rolls back: traffic returns to `orders-v3` — which is still warm, because the alias never stopped referencing it. -Prefer this over the classic two-function canary pattern (deploying `orders-v2` as a separate function next to `orders`): with versions there is nothing to duplicate, the history stays on one function, and cleanup is automatic via retention. +Prefer this over the classic two-function canary pattern (deploying `orders-v2` as a separate function next to `orders`). +With versions there is nothing to duplicate, the history stays on one function, and cleanup is automatic via retention. The classic pattern keeps working unchanged. ## Related diff --git a/content/en/docs/usage/gateway-api/_index.md b/content/en/docs/usage/gateway-api/_index.md index 7f5c5631..b8491d4f 100644 --- a/content/en/docs/usage/gateway-api/_index.md +++ b/content/en/docs/usage/gateway-api/_index.md @@ -47,7 +47,8 @@ When an HTTPTrigger sets `routeConfig.provider: gateway`, the router: - Points the route's backend at the `router` Service on port 80 — the same backend the Ingress path used. - Labels the route with `triggerName`, `functionName`, and `triggerNamespace` so you can find it with `kubectl get httproute -l triggerName=<name> -n fission`. -The route is reconciled level-based: it is created when missing, updated when the trigger changes, and deleted when the trigger is deleted or switched to a different provider. +The route is reconciled level-based. +Fission creates it when missing, updates it when the trigger changes, and deletes it when the trigger is deleted or switched to a different provider. ## Prerequisites @@ -93,8 +94,9 @@ spec: ``` {{% alert title="Cross-namespace attachment" color="info" %}} -Whether an `HTTPRoute` in the `fission` namespace may attach to a `Gateway` in another namespace is controlled by the **Gateway listener's `allowedRoutes.namespaces`** (`Same`, `All`, or a label `Selector`) — not by a `ReferenceGrant`. -No `ReferenceGrant` is needed for the route's backend, because Fission's generated `HTTPRoute` and its backend (the `router` Service) always live in the same namespace. +The **Gateway listener's `allowedRoutes.namespaces`** setting (`Same`, `All`, or a label `Selector`) controls whether an `HTTPRoute` in the `fission` namespace may attach to a `Gateway` in another namespace. +A `ReferenceGrant` does not control this. +The route's backend needs no `ReferenceGrant`, because Fission's generated `HTTPRoute` and its backend (the `router` Service) always live in the same namespace. {{% /alert %}} ## Expose a function @@ -304,7 +306,7 @@ fission route create --name hello --function hello --url /hello \ Existing HTTPTriggers created with `--createingress` keep working unchanged after an upgrade. Fission does **not** auto-convert them to the Gateway API, because doing so would break clusters that have no Gateway API installed. -Migration is opt-in and can be done per trigger, with no downtime for the others. +Migration is opt-in: migrate one trigger at a time, with no downtime for the others. ### Map the old flags to the new ones diff --git a/content/en/docs/usage/observability/opentelemetry.md b/content/en/docs/usage/observability/opentelemetry.md index 45d12657..9f5cb010 100644 --- a/content/en/docs/usage/observability/opentelemetry.md +++ b/content/en/docs/usage/observability/opentelemetry.md @@ -10,13 +10,14 @@ description: > **Tracing gives you a request-level view of how a call flows through Fission's components** — router, executor, function pod — and how long each step takes. Fission instruments its components with [OpenTelemetry](https://opentelemetry.io/) and exports spans over OTLP to any compatible backend. -Earlier releases used OpenTracing/Jaeger directly; that path has been replaced by OpenTelemetry, which is the only tracing system Fission ships today. +Earlier releases used OpenTracing/Jaeger directly. +OpenTelemetry has replaced that path and is the only tracing system Fission ships today. Because OpenTelemetry speaks OTLP, you can still send traces to Jaeger (shown below) or to any vendor that accepts OTLP. ## OpenTelemetry -OpenTelemetry is a set of APIs, SDKs, tooling and integrations that are designed for the creation and management of telemetry data such as traces, metrics, and logs. -The project provides a vendor-agnostic implementation that can be configured to send telemetry data to the backend(s) of your choice. +OpenTelemetry is a set of APIs, SDKs, and integrations for creating and managing telemetry data — traces, metrics, and logs. +The project provides a vendor-agnostic implementation you can configure to send telemetry data to the backend(s) of your choice. It supports a variety of popular open-source projects including Jaeger and Prometheus. ## Fission OpenTelemetry Integration @@ -24,7 +25,8 @@ It supports a variety of popular open-source projects including Jaeger and Prome If you have OpenTelemetry installed, you can use it to collect traces and metrics from Fission. The `openTelemetry` section in the Helm chart configures the OpenTelemetry SDK used by the Fission components. -The chart translates each value into a standard `OTEL_*` environment variable that is injected into every component pod, and these variables are propagated to function pods as well. +The chart translates each value into a standard `OTEL_*` environment variable and injects it into every component pod. +These variables also propagate to function pods. | Helm value | Environment variable | Description | | ---------- | -------------------- | ----------- | @@ -37,20 +39,20 @@ The chart translates each value into a standard `OTEL_*` environment variable th | `openTelemetry.logsEnabled` | `OTEL_LOGS_ENABLED` | `true`/`false` (default `false`). When enabled alongside a collector endpoint, control-plane components also push their structured logs (carrying `trace_id`) to the OTLP collector, not just traces. | | `openTelemetry.metricsExporter` | `OTEL_METRICS_EXPORTER` | Metrics exporter selection (default `prometheus`). The Prometheus `/metrics` scrape always stays on; set `otlp` (or `prometheus,otlp`) to also push metrics over OTLP to the collector. | -Without a configured collector endpoint, you won't be able to visualize traces. +Without a configured collector endpoint, you cannot visualize traces. Depending on your sampler configuration, you can still observe `trace_id` in Fission component logs. -Search by `trace_id` across Fission service logs to debug or troubleshoot a specific request. +Search by `trace_id` across Fission service logs to debug a specific request. {{% notice info %}} -Since v1.27.0 the head sampler is taken from `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG` (these were previously ignored). -Spans for failed invocations are always exported regardless of the sampler decision, so error traces are never dropped. +Since v1.27.0 the head sampler comes from `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG` (these were previously ignored). +Fission always exports spans for failed invocations regardless of the sampler decision, so error traces are never dropped. With the chart default (`parentbased_traceidratio` at `0.1`), successful-trace export drops to 10% while every error trace is kept; set `OTEL_TRACES_SAMPLER=parentbased_always_on` to export 100%. {{% /notice %}} Many observability platforms — DataDog, Dynatrace, Honeycomb, Lightstep, New Relic, Signoz, Splunk, and others — support OpenTelemetry out of the box. Use `otlpHeaders` to configure the headers those platforms require, and you can send traces to them directly without standing up an OpenTelemetry Collector yourself. -If none of the above options are adequate, feel free to raise an issue or open a pull request. +If none of the above options work, open an issue or a pull request. ### Types of samplers @@ -75,13 +77,15 @@ Default is 0.1. ### Trace propagation Fission components propagate trace context with the W3C Trace Context and Baggage propagators. -Other propagator types (`b3`, `b3multi`, `jaeger`, `xray`, `ottrace`) are not honored; the non-W3C propagator modules were dropped to reduce the binary footprint. -The `openTelemetry.propagators` value still injects `OTEL_PROPAGATORS` into every pod, so a function that runs its own OpenTelemetry SDK can read it — but Fission's own components ignore it. +Fission does not honor other propagator types (`b3`, `b3multi`, `jaeger`, `xray`, `ottrace`). +It dropped the non-W3C propagator modules to reduce the binary footprint. +The `openTelemetry.propagators` value still injects `OTEL_PROPAGATORS` into every pod, so a function running its own OpenTelemetry SDK can read it. +Fission's own components ignore it, though. ## Sample OTEL Collector This example uses the [OpenTelemetry Operator for Kubernetes](https://github.com/open-telemetry/opentelemetry-operator) to set up the OTEL collector. -To install the operator in an existing cluster, `cert-manager` is required. +Installing the operator in an existing cluster requires `cert-manager`. Use the following commands to install `cert-manager` and the operator: @@ -93,9 +97,10 @@ kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/downlo kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml ``` -Once the `opentelemetry-operator` deployment is ready, we need to create an OpenTelemetry Collector instance. +Once the `opentelemetry-operator` deployment is ready, create an OpenTelemetry Collector instance. -The following configuration provides a good starting point; change it as needed: +The following configuration is a good starting point. +Change it as needed: ```sh kubectl apply -f - <<EOF @@ -234,7 +239,7 @@ spec: EOF ``` -Note: The above configuration is borrowed from the [OpenTelemetry Collector traces example](https://github.com/open-telemetry/opentelemetry-go/tree/main/example/otel-collector), with some minor changes. +Note: the configuration above adapts the [OpenTelemetry Collector traces example](https://github.com/open-telemetry/opentelemetry-go/tree/main/example/otel-collector), with minor changes. ### Jaeger @@ -246,7 +251,7 @@ kubectl create namespace observability kubectl create -n observability -f https://github.com/jaegertracing/jaeger-operator/releases/download/v1.39.0/jaeger-operator.yaml ``` -Note that you'll need to download and customize the Role Bindings if you are using a namespace other than observability. +If you use a namespace other than observability, download and customize the Role Bindings. Once the jaeger-operator deployment in the observability namespace is ready, create a Jaeger instance: @@ -259,7 +264,7 @@ metadata: EOF ``` -Check that the `otel-collector` and `jaeger-query` services have been created: +Check that the `otel-collector` and `jaeger-query` services exist: ```sh kubectl get svc --all-namespaces @@ -279,13 +284,13 @@ opentelemetry-operator-system opentelemetry-operator-webhook-service opentelemetry-operator-system otel-collector NodePort 10.96.107.99 <none> 4317:30080/TCP,8889:30898/TCP 2m22s ``` -Now, set up a port forward to the `jaeger-query` service: +Set up a port forward to the `jaeger-query` service: ```sh kubectl port-forward service/jaeger-query -n observability 8080:16686 & ``` -You should now be able to access Jaeger at [http://localhost:8080/](http://localhost:8080/). +Access Jaeger at [http://localhost:8080/](http://localhost:8080/). ### Installing Fission @@ -302,7 +307,7 @@ helm install --namespace $FISSION_NAMESPACE \ --set openTelemetry.tracesSamplingRate="1" ``` -Note: You may have to change the `openTelemetry.otlpCollectorEndpoint` value as per your setup. +Change `openTelemetry.otlpCollectorEndpoint` to match your setup. ## Testing @@ -326,20 +331,21 @@ hello, world! ### Traces with Jaeger -If you have been following along, you should be able to access Jaeger at [http://localhost:8080/](http://localhost:8080/). -Refresh the page and you should see multiple services listed in the `Service` dropdown. +If you followed along, access Jaeger at [http://localhost:8080/](http://localhost:8080/). +Refresh the page. +Multiple services appear in the `Service` dropdown. Select the `Fission-Router` and click the `Find Traces` button. -You should see the spans created for the function request we just tested. +The spans for the function request you just tested appear. Select the trace and on the next page expand the spans. -You should be able to see the request flow similar to the one below: +The request flow looks similar to the one below: ![Fission OpenTelemetry](../assets/fission-otel.png) If you enable OpenTelemetry tracing within your function, you can capture spans and events for the function request. -The following are a few samples of spans and events captured by invoking a Go-based function: +These are sample spans and events from invoking a Go-based function: ![Fission Spans](../assets/fission-go-func-trace.png) diff --git a/content/en/docs/usage/spec/_index.md b/content/en/docs/usage/spec/_index.md index 013ac2e1..9463bcfe 100644 --- a/content/en/docs/usage/spec/_index.md +++ b/content/en/docs/usage/spec/_index.md @@ -328,13 +328,17 @@ fission spec validate fission spec apply --delete --wait ``` -* **Safe to re-apply.** A sync with no spec change writes nothing: no rebuilds, no pod restarts, no new function versions. -* **`--delete` completes the loop.** Removing a spec file from Git removes the resource from the cluster on the next apply. +* **Safe to re-apply.** + A sync with no spec change writes nothing: no rebuilds, no pod restarts, no new function versions. +* **`--delete` completes the loop.** + Removing a spec file from Git removes the resource from the cluster on the next apply. Without it, deletions in Git never reach the cluster. * **`--wait` fails the pipeline on a failed build**, instead of reporting success while the package is broken. -* **`--commitlabel` records provenance.** Each resource gets a `commit` label with the Git commit hash of its spec file, so you can trace any cluster object back to the commit that produced it. +* **`--commitlabel` records provenance.** + Each resource gets a `commit` label with the Git commit hash of its spec file, so you can trace any cluster object back to the commit that produced it. * **Apply warns on a dirty work tree**, so uncommitted local changes do not silently ship from a workstation. -* **Preview in pull requests.** Run `fission spec apply --dry-run` in the PR pipeline to post what a merge would change. +* **Preview in pull requests.** + Run `fission spec apply --dry-run` in the PR pipeline to post what a merge would change. ### Specs with OCI image packages @@ -348,8 +352,10 @@ $ fission function create --spec --name hello --env go \ The generated package spec carries only the image reference. Nothing is uploaded at apply time, and the digest pins exactly what runs. -Your CI builds and pushes the image, then bumps the digest in the spec file; the same spec promotes unchanged across dev, QA, and production. -Because such specs contain only plain Kubernetes resources, a GitOps controller such as Argo CD or Flux can also apply them directly, without the `fission` CLI in the loop. +Your CI builds and pushes the image, then bumps the digest in the spec file. +The same spec promotes unchanged across dev, QA, and production. +Such specs contain only plain Kubernetes resources. +A GitOps controller such as Argo CD or Flux can therefore apply them directly, without the `fission` CLI in the loop. One exclusion applies: `fission-deployment-config.yaml` is CLI metadata, not a cluster resource, so point the sync at the resource YAMLs only. ## A bit about how this works diff --git a/content/en/docs/usage/triggers/_index.md b/content/en/docs/usage/triggers/_index.md index fc17a8a8..d491a5b5 100644 --- a/content/en/docs/usage/triggers/_index.md +++ b/content/en/docs/usage/triggers/_index.md @@ -6,7 +6,9 @@ description: > --- A **trigger binds an event source to a function**, so that the function runs whenever the event occurs. -Every function in Fission is ultimately invoked over HTTP: the router exposes functions internally, and each trigger type turns its event into an HTTP request to that function. +Fission ultimately invokes every function over HTTP. +The router exposes functions internally. +Each trigger type turns its event into an HTTP request to that function. Fission ships several trigger types, one per kind of event source. Pick the trigger that matches where your events come from. @@ -30,7 +32,8 @@ See [Message Queue Trigger: KEDA]({{% ref "message-queue-trigger-kind-keda/_inde ## How triggers reach a function All trigger types converge on the same internal path: each one issues an HTTP request to the router, which routes it to a function pod. -HTTP triggers are served directly by the router; the other trigger types run a dedicated component that watches its event source and calls the router on your behalf. +The router serves HTTP triggers directly. +The other trigger types run a dedicated component; it watches the event source and calls the router on your behalf. ```mermaid flowchart LR diff --git a/content/en/docs/usage/triggers/statestore-eventing.md b/content/en/docs/usage/triggers/statestore-eventing.md index fa63bee9..e0b9336d 100644 --- a/content/en/docs/usage/triggers/statestore-eventing.md +++ b/content/en/docs/usage/triggers/statestore-eventing.md @@ -159,9 +159,11 @@ A reaper in the statestore MQ consumer trims each subscribed topic once per minu A subscriber that resumes after a backstop trim logs the gap and counts it in the `fission_eventing_gap_events_total` metric. A topic with **no** statestore trigger is not trimmed at all — the orphan-stream age sweep is not implemented yet. -Instead, a per-topic backlog cap of 10,000 events bounds the growth: publishes to a capped topic fail with `topic backlog cap reached` instead of dropping silently. +Instead, a per-topic backlog cap of 10,000 events bounds the growth. +Publishes to a capped topic fail with `topic backlog cap reached` instead of dropping silently. To recover a capped orphan topic, create a statestore trigger on it. -The trigger's cursor starts at the head, so the reaper trims the old backlog within about a minute and publishes flow again; the trimmed backlog is not delivered. +The trigger's cursor starts at the head, so the reaper trims the old backlog within about a minute and publish flow resumes. +The trimmed backlog is not delivered. ## Limits diff --git a/content/en/docs/usage/workflows/_index.md b/content/en/docs/usage/workflows/_index.md index 99af26d6..98bc7fcb 100644 --- a/content/en/docs/usage/workflows/_index.md +++ b/content/en/docs/usage/workflows/_index.md @@ -5,10 +5,15 @@ description: > Orchestrate several functions as one durable, resumable state machine — with parallel branches, data-driven routing, retries, durable waits, and typed-error handling. --- -**A workflow orchestrates several functions as one durable state machine: it survives controller restarts, resumes exactly where it stopped, retries transient failures, and routes typed business errors — all recorded step by step in the statestore.** +**A workflow orchestrates several functions as one durable state machine. +It survives controller restarts and resumes exactly where it stopped. +It retries transient failures and routes typed business errors. +Every step is recorded in the statestore.** -Starting with Fission {{< release-version >}}, you define a `Workflow` as a state machine over your functions and start a `WorkflowRun` each time you want it to execute. -For the mental model behind the two resources and the durability guarantees, read the [Workflows concept]({{% ref "/docs/concepts/workflows.md" %}}); this guide is how to enable, author, run, and inspect them. +Starting with Fission {{< release-version >}}, you define a `Workflow` as a state machine over your functions. +You start a `WorkflowRun` each time you want it to execute. +For the mental model behind the two resources and the durability guarantees, read the [Workflows concept]({{% ref "/docs/concepts/workflows.md" %}}). +This guide covers how to enable, author, run, and inspect them. ## Prerequisites @@ -53,7 +58,8 @@ stateDiagram-v2 reject --> [*] ``` -`fission workflow graph --name <workflow>` renders this diagram from a workflow's definition, and `--open` serves it in a local day/night viewer. +`fission workflow graph --name <workflow>` renders this diagram from a workflow's definition. +`--open` serves it in a local day/night viewer. ## In this section diff --git a/content/en/docs/usage/workflows/authoring.md b/content/en/docs/usage/workflows/authoring.md index 1cc13bf0..9235d15a 100644 --- a/content/en/docs/usage/workflows/authoring.md +++ b/content/en/docs/usage/workflows/authoring.md @@ -5,10 +5,12 @@ description: > The full YAML reference for a Workflow — every state type, JSONPath I/O shaping, retries and backoff, and the built-in error model. --- -**A `Workflow` is a YAML state machine: a `startAt` state and a map of named states, each of which invokes a function, branches on data, waits, or terminates.** +**A `Workflow` is a YAML state machine: a `startAt` state and a map of named states. +Each state invokes a function, branches on data, waits, or terminates.** This page is the field reference. -For the concepts, see [Workflows]({{% ref "/docs/concepts/workflows.md" %}}); to run and inspect what you author, see [Run and inspect]({{% ref "run-and-inspect.md" %}}). +For the concepts, see [Workflows]({{% ref "/docs/concepts/workflows.md" %}}). +To run and inspect what you author, see [Run and inspect]({{% ref "run-and-inspect.md" %}}). ## Manifest skeleton @@ -89,7 +91,8 @@ Three optional JSONPath fields shape how a state reads from and writes to it: - **`outputPath`** selects what is passed on to the next state. `resultPath` is the one to be deliberate about. -Setting `resultPath: $.charge` merges the function's result under `$.charge`, **keeping** the rest of the document; omitting it **replaces** the whole document with the result. +Setting `resultPath: $.charge` merges the function's result under `$.charge`, **keeping** the rest of the document. +Omitting it **replaces** the whole document with the result. The same applies to a caught error — merge it so the recovery step still sees the original input: ```yaml @@ -174,7 +177,8 @@ grace-period: ## Succeed and Fail Terminal states. -`Succeed` ends the run successfully; `Fail` ends it as failed. +`Succeed` ends the run successfully. +`Fail` ends it as failed. A Task with `end: true` also terminates the run. ```yaml @@ -194,7 +198,8 @@ Fission classifies every step failure into a built-in error class that `catch.er | `Fission.BranchFailed` | A `Parallel`/`Map` branch failed terminally. | — (route with `catch`). | | `Fission.All` | Matches any error class in a `catch` route. | — | -A function can also return its own **typed** business error by responding with a `{"errorType": "PaymentDeclined", ...}` body; `catch` routes on that name directly, so business recovery is separate from infrastructure retries. +A function can also return its own **typed** business error by responding with a `{"errorType": "PaymentDeclined", ...}` body. +`catch` routes on that name directly, so business recovery is separate from infrastructure retries. ## Validate before applying diff --git a/content/en/docs/usage/workflows/examples.md b/content/en/docs/usage/workflows/examples.md index 3afec805..c06ec410 100644 --- a/content/en/docs/usage/workflows/examples.md +++ b/content/en/docs/usage/workflows/examples.md @@ -12,7 +12,10 @@ Read them alongside the [authoring reference]({{% ref "authoring.md" %}}). ## Order pipeline — Parallel, Choice, retry, catch -An e-commerce checkout: validate an order, screen it for fraud and stock **in parallel**, route on the results with a `Choice`, charge the card with **retry and a catch for declines**, then converge every failure onto one rejection path. +An e-commerce checkout: validate an order, then screen it for fraud and stock **in parallel**. +A `Choice` routes on the results. +Charging the card includes **retry and a catch for declines**. +Every failure converges onto one rejection path. It is the flagship example — the one the [`stateDiagram`]({{% ref "_index.md" %}}#state-types) on the overview page is drawn from. - **Shows:** `Parallel` with an ordered join, data-driven `Choice`, `Task` `retry` for transient gateway errors, and `catch` on a typed `PaymentDeclined` error. @@ -21,8 +24,10 @@ It is the flagship example — the one the [`stateDiagram`]({{% ref "_index.md" ## Batch enrichment — Map fan-out -Enrich a batch of CRM leads: a `Map` state invokes a single-record scoring function once per element of `$.leads`, at most three concurrently, and the ordered join array feeds a summary step. -The function stays simple; the workflow owns the fan-out, throttling, retries, and ordering. +Enrich a batch of CRM leads: a `Map` state invokes a single-record scoring function once per element of `$.leads`, at most three concurrently. +The ordered join array feeds a summary step. +The function stays simple. +The workflow owns the fan-out, throttling, retries, and ordering. - **Shows:** `Map` with `itemsPath` and `maxConcurrency`, and an ordered join feeding the next `Task`. - **Inputs:** `leads` — the array the Map iterates. @@ -30,7 +35,8 @@ The function stays simple; the workflow owns the fan-out, throttling, retries, a ## Payment dunning — durable Wait timers -Subscription renewal with a grace period: if a charge is declined, the run **waits out a grace period on a durable timer** and tries once more before canceling. +Subscription renewal with a grace period: if a charge is declined, the run **waits out a grace period on a durable timer**. +It tries once more before canceling. The run consumes no pod, memory, or connection while waiting — the timer lives in the statestore and survives controller restarts. - **Shows:** `Wait` as a durable delay, and a `catch` route that changes behavior on the second attempt. diff --git a/content/en/docs/usage/workflows/run-and-inspect.md b/content/en/docs/usage/workflows/run-and-inspect.md index 1ea1fbb9..64f6d9cf 100644 --- a/content/en/docs/usage/workflows/run-and-inspect.md +++ b/content/en/docs/usage/workflows/run-and-inspect.md @@ -11,7 +11,8 @@ This page assumes you have a manifest — see [Authoring workflows]({{% ref "aut ## Manage the definition -`fission workflow` is the definition lifecycle; it mirrors the other Fission resources: +`fission workflow` is the definition lifecycle. +It mirrors the other Fission resources: ```bash fission workflow create -f workflow.yaml @@ -30,7 +31,8 @@ $ fission workflow run --name order-pipeline --input @inputs/happy.json Run started: order-pipeline-7k2p9 ``` -Each `run` is an independent execution with its own state and history; the definition is unchanged. +Each `run` is an independent execution with its own state and history. +The definition is unchanged. ## Inspect runs @@ -70,7 +72,8 @@ fission workflow graph -f workflow.yaml fission workflow graph --name order-pipeline --open ``` -`workflow runs graph --name <run>` draws the same diagram but overlays a specific run's status — each state colored by what that run actually did, so the picture *is* the answer to "where did this run stop": +`workflow runs graph --name <run>` draws the same diagram but overlays a specific run's status. +Each state is colored by what that run actually did, so the picture *is* the answer to "where did this run stop": ```bash fission workflow runs graph --name order-pipeline-7k2p9 --open From 48fbfc869e2ac39d89b751b1be0893df5b1ef98a Mon Sep 17 00:00:00 2001 From: Sanket Sudake <sanketsudake@gmail.com> Date: Sat, 8 Aug 2026 13:47:37 +0530 Subject: [PATCH 25/26] config: raise sidebar_menu_truncate for the grown CLI reference --- config.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/config.toml b/config.toml index 4b695257..b45f81af 100644 --- a/config.toml +++ b/config.toml @@ -231,6 +231,8 @@ navbar_logo = true navbar_translucent_over_cover_disable = false # Enable to show the side bar menu in its compact state. sidebar_menu_compact = true +# CLI reference now has 128 pages; default truncate (100) drops entries. +sidebar_menu_truncate = 150 # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) sidebar_search_disable = true From ba93cf90f5b9c0d13a0af6702076444b5b52e665 Mon Sep 17 00:00:00 2001 From: Sanket Sudake <sanketsudake@gmail.com> Date: Sat, 8 Aug 2026 14:08:23 +0530 Subject: [PATCH 26/26] docs: working OTEL collector walkthrough Replace the 0.6.0 image, removed --mem-ballast-size-mib flag, and dead jaeger exporter with collector 0.158.0, GOMEMLIMIT, and an otlp/jaeger exporter to Jaeger's native OTLP ingest; health_check bound to pod IP; memory_limiter+batch processors added. --- .../docs/usage/observability/opentelemetry.md | 77 ++++++++++--------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/content/en/docs/usage/observability/opentelemetry.md b/content/en/docs/usage/observability/opentelemetry.md index 9f5cb010..6f61ee17 100644 --- a/content/en/docs/usage/observability/opentelemetry.md +++ b/content/en/docs/usage/observability/opentelemetry.md @@ -115,36 +115,38 @@ metadata: data: otel-collector-config: | receivers: - # Make sure to add the otlp receiver. - # This will open up the receiver on port 4317 + # Add the otlp receiver. + # This opens the receiver on port 4317. otlp: protocols: grpc: endpoint: "0.0.0.0:4317" processors: + memory_limiter: + check_interval: 5s + limit_mib: 1500 + spike_limit_mib: 512 + batch: {} extensions: - health_check: {} + health_check: + endpoint: "0.0.0.0:13133" exporters: - jaeger: - endpoint: "jaeger-collector.observability.svc.cluster.local:14250" - insecure: true - prometheus: - endpoint: 0.0.0.0:8889 - namespace: "testapp" - logging: + # Jaeger accepts OTLP natively since v1.35, so export over OTLP + # instead of the old jaeger exporter, which current collector + # builds no longer ship. + otlp/jaeger: + endpoint: "jaeger-collector.observability.svc.cluster.local:4317" + tls: + insecure: true + debug: {} service: extensions: [health_check] pipelines: traces: receivers: [otlp] - processors: [] - exporters: [jaeger] - - metrics: - receivers: [otlp] - processors: [] - exporters: [prometheus, logging] + processors: [memory_limiter, batch] + exporters: [otlp/jaeger, debug] --- apiVersion: v1 kind: Service @@ -156,15 +158,11 @@ metadata: component: otel-collector spec: ports: - - name: otlp # Default endpoint for otlp receiver. + - name: otlp # Default endpoint for the otlp receiver. port: 4317 protocol: TCP targetPort: 4317 nodePort: 30080 - - name: metrics # Default endpoint for metrics. - port: 8889 - protocol: TCP - targetPort: 8889 selector: component: otel-collector type: NodePort @@ -187,10 +185,6 @@ spec: replicas: 1 # increase for higher trace throughput or collector high availability template: metadata: - annotations: - prometheus.io/path: "/metrics" - prometheus.io/port: "8889" - prometheus.io/scrape: "true" labels: app: opentelemetry component: otel-collector @@ -199,12 +193,13 @@ spec: - command: - "/otelcol" - "--config=/conf/otel-collector-config.yaml" - # Memory Ballast size should be max 1/3 to 1/2 of memory. - - "--mem-ballast-size-mib=683" env: - - name: GOGC - value: "80" - image: otel/opentelemetry-collector:0.6.0 + # GOMEMLIMIT replaces the old --mem-ballast-size-mib flag, + # which current collector builds no longer accept. + # Set it to about 80% of the memory limit below. + - name: GOMEMLIMIT + value: "1600MiB" + image: otel/opentelemetry-collector:0.158.0 name: otel-collector resources: limits: @@ -214,8 +209,7 @@ spec: cpu: 200m memory: 400Mi ports: - - containerPort: 4317 # Default endpoint for otlp receiver. - - containerPort: 8889 # Default endpoint for querying metrics. + - containerPort: 4317 # Default endpoint for the otlp receiver. volumeMounts: - name: otel-collector-config-vol mountPath: /conf @@ -239,7 +233,13 @@ spec: EOF ``` -Note: the configuration above adapts the [OpenTelemetry Collector traces example](https://github.com/open-telemetry/opentelemetry-go/tree/main/example/otel-collector), with minor changes. +The image tag above (`0.158.0`) was current at the time of writing. +Check the [available tags](https://hub.docker.com/r/otel/opentelemetry-collector/tags) for a newer release before you deploy. + +This example uses the core `otel/opentelemetry-collector` image, which already includes the OTLP receiver, OTLP exporter, and health-check extension this pipeline needs. +Use the `-contrib` image only if you add components it does not ship, such as vendor-specific receivers or exporters. + +Note: the configuration above adapts the [OpenTelemetry Collector Kubernetes example](https://github.com/open-telemetry/opentelemetry-collector/blob/main/examples/k8s/otel-config.yaml), with minor changes. ### Jaeger @@ -264,6 +264,9 @@ metadata: EOF ``` +The jaeger-operator enables the collector's OTLP receiver by default. +No extra flag is needed for `jaeger-collector` to accept the OTLP traffic from the OTEL collector on ports 4317 (gRPC) and 4318 (HTTP). + Check that the `otel-collector` and `jaeger-query` services exist: ```sh @@ -275,13 +278,13 @@ cert-manager cert-manager-webhook default kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 9m35s kube-system kube-dns ClusterIP 10.96.0.10 <none> 53/UDP,53/TCP,9153/TCP 9m33s observability jaeger-agent ClusterIP None <none> 5775/UDP,5778/TCP,6831/UDP,6832/UDP 3s -observability jaeger-collector ClusterIP 10.96.48.27 <none> 9411/TCP,14250/TCP,14267/TCP,14268/TCP 3s -observability jaeger-collector-headless ClusterIP None <none> 9411/TCP,14250/TCP,14267/TCP,14268/TCP 3s +observability jaeger-collector ClusterIP 10.96.48.27 <none> 9411/TCP,14250/TCP,14267/TCP,14268/TCP,4317/TCP,4318/TCP 3s +observability jaeger-collector-headless ClusterIP None <none> 9411/TCP,14250/TCP,14267/TCP,14268/TCP,4317/TCP,4318/TCP 3s observability jaeger-operator-metrics ClusterIP 10.96.164.206 <none> 8383/TCP,8686/TCP 61s observability jaeger-query ClusterIP 10.96.186.29 <none> 16686/TCP,16685/TCP 3s opentelemetry-operator-system opentelemetry-operator-controller-manager-metrics-service ClusterIP 10.96.29.83 <none> 8443/TCP 6m11s opentelemetry-operator-system opentelemetry-operator-webhook-service ClusterIP 10.96.74.0 <none> 443/TCP 6m11s -opentelemetry-operator-system otel-collector NodePort 10.96.107.99 <none> 4317:30080/TCP,8889:30898/TCP 2m22s +opentelemetry-operator-system otel-collector NodePort 10.96.107.99 <none> 4317:30080/TCP 2m22s ``` Set up a port forward to the `jaeger-query` service: