Skip to main content

LOAD EXTERNAL GRANTS AT STARTUP

This guide shows you how to load authorization grants from YAML files outside the repository when starting swamp serve.

Write the grants file

Create a YAML file with a top-level grants key. The format is the same as files in the grants/ directory:

# /etc/swamp/grants.yaml
grants:
  - subject: user:deploy-bot
    effect: allow
    actions: [run]
    resource: workflow:@acme/deploy
  - subject: idp-group:platform-eng
    effect: allow
    actions: [run, read]
    resource: behavior:*

Start the server with the grants file

Pass the file path with --grants-file:

swamp serve --auth-mode token --admins 'user:admin-id' \
  --grants-file /etc/swamp/grants.yaml

Or set the SWAMP_GRANTS_FILE environment variable:

export SWAMP_GRANTS_FILE=/etc/swamp/grants.yaml
swamp serve --auth-mode token --admins 'user:admin-id'

The server loads grants from this file at startup. If the file does not exist or contains invalid YAML, the server refuses to start.

Load a directory of grants files

To load several files, put them in one directory and pass it with --grants-dir, or set SWAMP_GRANTS_DIR. The directory is read alongside the repository's grants/ directory:

swamp serve --auth-mode token --admins 'user:admin-id' \
  --grants-dir /etc/swamp/grants

Verify the grants loaded

List active grants to confirm:

swamp access grant list --server wss://localhost:9090

Grants from the external file appear alongside any grants from the grants/ directory and CLI-created grants. The SOURCE column names where each came from, not the path it was loaded from. You will see output like:

ID                                    SUBJECT                       EFFECT  ACTIONS               RESOURCE                      METHODS           CONDITION             SOURCE
49e45c77-287e-4dfa-8646-fa5e7cc9c0f6  user:deploy-bot               allow   run                   workflow:@acme/deploy         *                                       file:grants-file
d05ef220-436d-4352-964c-1eb01ce4f67f  user:admin-id                 allow   admin                 access:*                      *                                       config
8ed647cf-2d22-410d-bd21-18e169a9e6cb  user:bob                      allow   read                  data:*                        *                                       file:team.yaml
ce759846-9ac2-4ac7-8bdf-911b1600ae54  user:alice                    deny    run                   workflow:@acme/prod-*         *                                       file:grants-dir/deny.yaml

Run several instances on one datastore

Give every swamp serve instance that shares a datastore the same grant files. The mount path can differ between instances: /etc/swamp/grants on one and /srv/grants on another store the same file:grants-dir/<filename> sources.

An instance started without the --grants-dir, or with different files in it, revokes the other instances' file:grants-dir/ grants when it reconciles.

Upgrading from path-based sources

Earlier releases stored --grants-dir and --grants-file grants with the file's absolute path as their source, such as file:/etc/swamp/grants/deny.yaml. After you upgrade:

  • The first reconcile revokes each grant stored under an absolute path and creates the same grant under file:grants-dir/<filename> or file:grants-file, with a new grant ID. Audit entries that name the old ID refer to the revoked copy. Later starts change nothing. On a shared datastore, another instance can briefly see the revoke before the create.
  • swamp access grant list and swamp access reload results show the new source names. Update scripts that match on the old path.
  • Instances on a shared datastore that still run an earlier release keep storing and revoking grants by absolute path. Upgrade every instance that shares the datastore.
← PreviousUse a Config FileNext →Monitor Server Health