Workflow Endpoints

When a workflow service exposes network endpoints (configured via the network section in your workflow definition), the fuzzball workflow endpoints command and its subcommands let you list the live endpoints you have access to, inspect a single endpoint, mint an access token for a non-public endpoint, or print the URL(s) derived from a workflow specification.

fuzzball workflow endpoints list returns the workflow service endpoints currently alive on the cluster that you have access to. Access is scoped to the groups (accounts) you belong to and to your organization.

$ fuzzball workflow endpoints list

ENDPOINT ID         WORKFLOW ID   SERVICE     ENDPOINT   TYPE        SCOPE   URL
endpoint-1a2b3c4d    <workflow>    jupyter     web        path        user    https://endpoints.example.com/endpoints/...
endpoint-5e6f7a8b    <workflow>    api-server  grpc       subdomain   group   https://api-server.<workflow>.<account>.example.com/

Flags:

Use -o json or -o yaml for scripting; the structured output includes additional fields such as the owning account and organization.

$ fuzzball workflow endpoints list -o json

fuzzball workflow endpoints get shows the details of one endpoint by its ID, including its URL:

$ fuzzball workflow endpoints get ENDPOINT_ID

Endpoints whose scope is not public require a bearer token. fuzzball workflow endpoints generate-token mints a token bound to the endpoint and carrying your identity:

$ fuzzball workflow endpoints generate-token ENDPOINT_ID

Present the returned token to the endpoint using the Authorization or FB-Authorization HTTP header.

The --expiration flag sets the token lifetime. It accepts the units understood by Go durations (s, m, h) plus day, week, month, and year units — 7d, 2w, 1mo, 1y (and long forms like 7days). When omitted, the server default lifetime is used:

# Valid for 24 hours
$ fuzzball workflow endpoints generate-token ENDPOINT_ID --expiration 24h

# Valid for 7 days
$ fuzzball workflow endpoints generate-token ENDPOINT_ID --expiration 7d

# Valid for 1 month
$ fuzzball workflow endpoints generate-token ENDPOINT_ID --expiration 1mo

Invoked with a workflow ID (and optional service and endpoint names), fuzzball workflow endpoints prints the endpoint URL(s) derived from that workflow’s specification:

$ fuzzball workflow endpoints WORKFLOW_ID [SERVICE_NAME] [ENDPOINT_NAME]

Arguments:

Get all endpoints for a workflow:

$ fuzzball workflow endpoints <workflow_id>

SERVICE       ENDPOINT   URL
jupyter       web        https://endpoints.example.com/endpoints/accounts/.../jupyter/web/
api-server    grpc       https://endpoints.example.com/endpoints/accounts/.../api-server/grpc/

Get all endpoints for a specific service, or a specific endpoint by name:

$ fuzzball workflow endpoints <workflow_id> jupyter
$ fuzzball workflow endpoints <workflow_id> jupyter web

Output the results as JSON (useful for scripting):

$ fuzzball workflow endpoints <workflow_id> -o json

Endpoints are declared in the network section of a service definition. For example, a Jupyter service that exposes a web endpoint:

services:
  jupyter:
    image:
      uri: docker://jupyter/base-notebook:latest
    script: |
      #!/bin/bash
      jupyter lab --ip=0.0.0.0 --no-browser
    resource:
      cpu:
        cores: 2
      memory:
        size: 4GB
    network:
      ports:
        - name: web
          port: 8888
          protocol: tcp
      endpoints:
        - name: web
          port-name: web
          protocol: https
          type: path
          scope: user

See the workflow syntax reference for full details on the network configuration options.

When a workflow service runs, Fuzzball automatically injects environment variables for each configured endpoint. These variables allow your service code to discover the public URLs assigned to its endpoints.

For each endpoint, two environment variables are provided:

• FB_ENDPOINT_PATH_<ENDPOINT_NAME> — the full URL path to the endpoint
• FB_ENDPOINT_URL_<ENDPOINT_NAME> — the complete URL including protocol and host

The <ENDPOINT_NAME> suffix is derived from the endpoint’s name field by:

1. Converting the name to uppercase
2. Replacing any character that is not a letter, digit, or underscore with an underscore (_)

This transformation ensures that the generated environment variable names are valid POSIX shell identifiers and compatible with all container runtimes.

Examples:

Simple alphanumeric endpoint names (containing only letters, digits, and underscores) are unaffected by this transformation beyond being converted to uppercase.

You can reference these environment variables in your service’s startup script to configure applications dynamically:

services:
  web-app:
    image:
      uri: docker://myapp:latest
    script: |
      #!/bin/bash
      echo "Service available at: $FB_ENDPOINT_URL_WEB"
      ./myapp --public-url="$FB_ENDPOINT_URL_WEB"
    network:
      ports:
        - name: http
          port: 8080
          protocol: tcp
      endpoints:
        - name: web
          port-name: http
          protocol: https
          type: path
          scope: user

For an endpoint named jupyter-notebook, you would reference the sanitized variable names:

echo "Notebook URL: $FB_ENDPOINT_URL_JUPYTER_NOTEBOOK"