Offline licensing
LoadoutHQ uses a vendor-issued offline license file. The cluster does not contact a licensing service.
Treat the license as a Secret. Do not commit it to Git, place it in Helm values, print it in logs, or attach it to support requests.
Runtime states
| State | Meaning | Product behavior |
|---|---|---|
valid | The license is accepted | Normal operation |
expiring | 30 days or fewer remain | Normal operation with an administrator warning |
missing | No license is installed | Activation and health remain available; capabilities return HTTP 423 |
invalid | The license file was rejected | Capabilities return HTTP 423 |
not_yet_valid | The validity window has not started | Capabilities return HTTP 423 |
expired | The validity window has ended | Capabilities return HTTP 423 |
Activate through GitOps
Store the vendor-issued .lhq-license file in the customer's approved secret manager. Use the
existing external-secret or sealed-secret workflow to materialize a Kubernetes Secret named
loadouthq-license with the key license.lhq-license.
Reference that Secret in values.production.yaml:
license:
existingSecret: loadouthq-license
secretKey: license.lhq-license
Commit only the Secret reference and values change. Let the GitOps controller reconcile the release,
then confirm /api/v1/license/status. A mounted license is authoritative; if it is rejected or
expired, LoadoutHQ fails closed and does not fall back to an uploaded license.
Activate in the application
When no mounted license is configured, open /license, sign in as a platform administrator, and
upload the vendor-issued file. The raw license is never returned by the API and must not be logged.
Check /api/v1/license/status for state, dates, customer, license ID, and key ID.
Renew
Obtain the replacement license through the agreed LoadoutHQ delivery channel. Update the file in the customer's secret manager, let GitOps reconcile the affected Secret and workload, and verify the new state before removing the previous recovery copy.
Recover from rejection
- Inspect the status endpoint and API logs for the error code; never paste the raw license into a ticket.
- Confirm cluster time and the mounted key name
license.lhq-license. - Verify the customer, validity dates, and license ID against the delivery record.
- Replace the file through the approved secret workflow and let GitOps reconcile the workload.