maqpna config bundle

Build, verify, inspect and push signed configuration bundles

Operate-o json | yaml

Synopsis#

maqpna config bundle build DIR --key URI --out FILE [--revision N] [--issuer S] [--expires DUR] [--not-before T]
maqpna config bundle verify FILE (--pubkey PEM | --jwks FILE|URL | --allow-unpinned) [--issuer S] [--current-revision N]
maqpna config bundle inspect FILE
maqpna config bundle push FILE [--gateway URL]

Description#

From the help of maqpna config:

Checks, offline:

  - JSON syntax and the core gateway rules shared with the gateway (listen and
    adminListen, upstream names and URLs, policyFile, auditPath, identity keys,
    auditFailurePolicy, modelPolicy, tokenExchangeURL, sessionBudgetUSD);
  - unknown top-level keys (a warning; an error with --strict);
  - referenced files (policyFile, identity.publicKeyFiles, pricingFile,
    sovereigntyPolicyFile, upstreamCAFile, ...), resolved against --base-dir
    (default: the current directory, as the gateway resolves them against
    its working directory). A missing file is a warning, because
    in-cluster paths such as /etc/maqpna/... rarely exist locally; with
    --strict it is an error;
  - the policyFile compiles, when it exists;
  - every upstream URL complies with sovereigntyPolicyFile, when it exists;
  - adminAuth: static-token-only admin access is a warning.

--gateway-binary (env MAQPNA_GATEWAY_BIN) also runs "maqpna-gateway -check-config FILE", which applies every gateway rule.

Exit status: 0 valid (warnings allowed), 3 errors (or warnings with --strict).

A configuration bundle is the gateway's rendered files (policies.json, models.json, upstreams.json, ..., upstream-credentials/) as one signed .tar.gz: a manifest with a revision, the issuer, the creation time, an optional validity window and every file's SHA-256, signed as a detached JWS (Ed25519, P-256, RSA or ML-DSA; file, KMS or HSM keys; --pq-key adds an ML-DSA signature next to the classical one). Gateways with a configBundle block apply it when it is pushed, pulled or dropped into a directory, after checking the signature against their pinned keys and that the revision is above theirs.

  build DIR     sign the files under DIR (maqpna-operator render -out DIR)
  verify FILE   check signature, files, issuer, validity and revision (exit 3 when not)
  inspect FILE  print the manifest (signature checked against the embedded key only)
  push FILE     POST it to the gateway's /v1/admin/config:bundle (admin)

Bundles carry credentials in clear: keep them 0600 and on trusted media.

Subcommands#

Examples#

$ maqpna config bundle build ./rendered --key file:///etc/maqpna/bundle.key --out edge.tar.gz --expires 168h
$ maqpna config bundle verify edge.tar.gz --pubkey bundle.pub --current-revision 41
$ maqpna config bundle inspect edge.tar.gz -o json
$ maqpna config bundle push edge.tar.gz --gateway https://edge-7.example:8443

What happens when you run it#

• Prints a table by default; -o json or -o yaml print the data, and --jq EXPR filters the JSON.

Exit codes#

Related commands#

• maqpna configValidate a gateway configuration file offline; sign and push configuration bundles
• maqpna config validateValidate a gateway configuration file offline
• maqpna config get-contextsList contexts (kubectl config get-contexts; = maqpna context list)
• maqpna config current-contextPrint the current context (= maqpna context current)
• maqpna config use-contextSwitch to a context (= maqpna context use)
• maqpna config set-contextCreate or update a context (= maqpna context set)
• maqpna config delete-contextDelete a context (= maqpna context delete)
• maqpna config viewPrint the CLI config file: contexts, no secrets
• maqpna config bundle buildBuild and sign a configuration bundle from a directory
• maqpna config bundle verifyCheck a configuration bundle's signature, files, issuer, validity and revision