Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLI
Assigneesstack72

Relationships

#1530 Load grants from external source on swamp serve startup

Opened by stack72 · 8/5/2026· Shipped 8/5/2026

Problem

In a Kubernetes deployment, access grants are managed externally — defined in a ConfigMap, Helm values, or a GitOps repo — and mounted into the container at startup. Today, swamp serve reads grants from model definitions in the repo's models/ directory. There's no clean way to inject grants from outside the repo at container init time.

Operators working in a k8s ecosystem want to:

  1. Define grants in their Helm chart or ConfigMap
  2. Mount the grants file into the container
  3. Have swamp serve read it on startup

Today this requires either:

  • Copying the grants file into the repo's models/ directory during init (fragile, pollutes the repo)
  • Running swamp commands to create grant definitions before starting serve (extra init steps, race conditions)
  • Baking grants into the container image (can't change without rebuild)

Desired Outcome

swamp serve reads grants from a configurable external path on startup, in addition to the repo's built-in grant definitions. The external grants are loaded and reconciled before serve starts accepting traffic.

Design

CLI flag

swamp serve --grants-file /etc/swamp/grants.yaml

Or via serve config file (serve.yaml):

grants-file: /etc/swamp/grants.yaml

Or via environment variable:

SWAMP_GRANTS_FILE=/etc/swamp/grants.yaml

Grants file format

The file should use the same format as grant model definitions — the operator shouldn't need to learn a new schema:

grants:
  - subject: "user:deploy-bot"
    action: run
    resource: "workflow:*"
  - subject: "idp-group:engineering"
    action: run
    resource: "model:*"
  - subject: "idp-group:platform"
    action: admin
    resource: "*"
  - subject: "user:readonly"
    action: read
    resource: "*"

Startup behavior

  1. Serve starts, loads grant definitions from the repo (existing behavior)
  2. If --grants-file is specified, read and parse the external file
  3. Reconcile external grants alongside repo grants — they are additive (external grants don't replace repo grants, they extend them)
  4. If the file doesn't exist or can't be parsed, fail startup with a clear error (not a silent fallback — the operator explicitly asked for this file)
  5. If the file is empty, that's fine — no external grants added

Kubernetes use case

Deployment manifest:

containers:
  - name: swamp
    command: ["swamp", "serve"]
    volumeMounts:
      - name: grants
        mountPath: /etc/swamp/grants.yaml
        subPath: grants.yaml
volumes:
  - name: grants
    configMap:
      name: swamp-grants

ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: swamp-grants
data:
  grants.yaml: |
    grants:
      - subject: "idp-group:engineering"
        action: run
        resource: "workflow:*"

Reload on SIGHUP (optional, nice to have)

If --hot-reload is active, a SIGHUP could also reload the grants file alongside the extension reload. This allows updating grants via ConfigMap rollout without restarting serve. But this is a stretch goal — the primary value is loading at startup.

What this does NOT include

  • Grant management via API (create/delete grants via WebSocket protocol)
  • Grant priority or conflict resolution between external and repo grants
  • Grant templating or variable substitution
  • Multiple grants files

Files to modify

  • src/cli/commands/serve.ts — new --grants-file flag, load and parse on startup
  • src/domain/access/grant_file.ts or similar — parsing the external grants format
  • Possibly src/domain/access/grant_file_reconciler.ts — reconciling external grants

Testing

  1. Serve starts with --grants-file, grants are active
  2. Serve starts with --grants-file pointing to missing file, startup fails with clear error
  3. Serve starts without --grants-file, existing behavior unchanged
  4. External grants are additive to repo grants
  5. Invalid grants file format produces clear error
  6. Empty grants file is accepted (no external grants)
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 4 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

8/5/2026, 5:20:51 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack728/5/2026, 1:56:55 PM

Sign in to post a ripple.