Licensing

Install a MAQPNA licence, check its status and entitlements, and see how billable nodes are counted. A licence never blocks agent traffic.

flowchart LR
  L[Licence file<br/>signed JWS] --> V[maqpna license verify<br/>offline]
  V --> I[maqpna license install<br/>Secret maqpna-license]
  I --> G[Gateway and operator<br/>re-read within about a minute]
  G --> E[Paid features on<br/>agent traffic unchanged]
  O[Operator samples nodes<br/>with sandbox pods] --> C[ConfigMap<br/>maqpna-usage-nodes]
  C --> S[maqpna license status<br/>billable nodes vs limit]
  G --> S

Goal#

Install the licence you received, confirm which paid features it enables, and check billable nodes against your licence limit.

Editions#

A licence names one edition (enterprise, sovereign or operator) and lists the paid features it enables. The feature names are:

* enables every feature.

Prerequisites#

• The licence file from MAQPNA (a compact JWS, for example licence.jws).
• maqpna from a release whose built-in keys include the key that signed your licence. Licences verify offline against public keys compiled into the binary; there is no call home and no runtime override.
• For install and status: a kubeconfig context for the cluster, and RBAC to create or update Secrets in the MAQPNA namespace (default maqpna-system).

Steps#

1. Verify the licence offline#

maqpna license verify licence.jws

A valid licence prints its claims. This is the output format, from a local run with a test licence verified against a test key (--pubkey):

state:     valid
id:        lic_test_0001
customer:  Example GmbH
edition:   operator
features:  usage-reports
limits:    nodes=12 tenants=20 sandboxHours/month=0 (0 = unlimited)
valid:     2026-10-03 .. 2027-10-03 (364 days left)
signed by: 9FHvKLplpeVjzWvxxFWPh1ehLcgi_pTY8-7Q7coiPjE
verified with keys/checkpoint.pub

With the built-in keys the last line reads verified with built-in keys. verify exits 3 when the licence is invalid or expired. A binary whose build has no trusted licence key prints:

state:     invalid
error:     license: no trusted licence keys in this build
verified with built-in keys

--pubkey PEM checks a licence against other public keys (Ed25519 or EC P-256). A licence that verifies only with --pubkey enables nothing in a real installation.

2. Install it in the cluster#

maqpna license install licence.jws -n maqpna-system

This creates or updates the licence Secret: the one the gateway and operator mount (Helm license.secretRef, default maqpna-license, key license). Override with --secret and --key, and pick a cluster with --kube-context. The command prints where it wrote the licence and that the gateway and operator pick it up within about a minute (kubelet Secret sync plus a 30 s poll). No restart is needed.

The chart values:

license:
  secretRef:
    name: maqpna-license   # empty: no licence is mounted (Community)
    key: license

3. Check status and entitlements#

maqpna license status -n maqpna-system

status reads the Secret, evaluates the licence with the binary's keys and prints lines of this form (format taken from cmd/maqpna/license.go):

licence:   valid (operator edition), customer Example GmbH, licence lic_2026_0001, expires 2027-10-03 (364 days left)
secret:    maqpna-system/maqpna-license key license (installed)
features:  usage-reports
entitled:  usage-reports
billable nodes this month: 7 (licence limit 12)

Without a licence the entitled line reads none (paid features off; agent traffic is never affected) and the limit reads none: Community. A limit of 0 is shown as unlimited. status exits 3 when the licence is invalid or expired; -o json gives the same data for scripts. maqpna status and maqpna doctor (checks license and license-node-limit) include the licence too, and the gateway serves it at GET /v1/license to the auditor and admin roles.

4. Understand node counting#

A billable node is a node that runs at least one MAQPNA sandbox pod (a pod labelled maqpna.com/session, scheduled and not finished). The operator samples the number of such nodes every minute and keeps the highest count per UTC day and per UTC month (the high-water mark) in the ConfigMap maqpna-usage-nodes in its namespace:

kubectl -n maqpna-system get configmap maqpna-usage-nodes -o yaml

Its data keys are day.2026-10-02 and month.2026-10 (the marks) and updatedAt (the last sample). It keeps the last 62 days and 25 months. maqpna license status and maqpna usage report read the month's mark from it.

The limits in a licence (nodes, tenants, sandboxHours per month; 0 means unlimited) are contracted ceilings. MAQPNA reports them; it does not enforce them on agent traffic.

5. Plan for expiry#

An expired licence keeps its features for a 30-day grace period (state grace), then falls back to Community (state expired). Agent traffic is unaffected in every state. The chart's alerts warn before expiry from the metric maqpna_license_days_left (licenseExpiryWarnDays, default 30, and licenseExpiryCriticalDays, default 7). Install the renewed licence with step 2.

Verify#

• maqpna license verify licence.jws exits 0 and shows your customer name and edition.
• maqpna license status shows licence: valid and the features you bought under entitled.
• billable nodes this month shows a number, not not recorded yet, once agents have run.

Troubleshooting#

Next steps#

• Usage metering and billing: signed usage reports carry your licence ID.
• Multi-tenant setup for service providers.
• Monitoring and alerts: the licence-expiry alert.
• Command reference: maqpna license install, maqpna license status, maqpna license verify.