// Benutzung · Grundlagen
Credentials
Fleeger stores the secrets it needs to reach infrastructure — Proxmox API tokens, iDRAC logins, kubeconfigs. This is the reference for how those credentials are modelled, secured, shared, and cleaned up.
For how a credential's secret is encrypted at rest (AES-256-GCM with a service-held master key), see the security model. This document is about the credential entity and its lifecycle.
First-class, per-location, shareable
A credential is a standalone entity, not a property owned 1:1 by one resource:
- Named — a human label ("Proxmox homelab token") shown in the manager.
- Per-location — a credential belongs to a location and may only attach to
resources in that same location. This preserves Fleeger's location-isolation
boundary: a homelab credential can never be used against a datacenter box.
Attaching one from another location, by
credential_idon resource create or onPUT /resources/{id}/credential, gets the same404and message as an id that does not exist, so a caller scoped to one location cannot probe for credential ids elsewhere. - Shareable — one credential can be attached to many resources at once
(
resource.credential_ref→ the credential). Rotate the secret once and every resource using it is updated. - Independently-lifecycled — a credential survives the deletion of a resource that used it, becoming an orphan rather than being destroyed.
- Bound to where it is used — sharing stays at the addresses a credential is used at now. See below.
Bound to the addresses it is used at
Attaching an existing credential sends its secret to the resource's address,
so a credential is attached by id (credential_id on resource create, or
PUT /resources/{id}/credential) only where a resource using it now
already points: the same endpoint, meaning
- for a URL, the same scheme, host and port, the scheme's default port filled
in:
https://pve:8006/api2andhttps://PVE:8006are one endpoint,https://pveandhttps://pve:443too, whilehttp://pve:8006is another (the token must not be downgraded to cleartext) and so ishttps://pve:8007; - for the bare
host[:port]of the non-URL kinds (e.g. a TCP check), that host and port as written; no scheme and no default port are assumed, sodb:5432anddbdiffer. A URL and a bare address never match, and an address with no readable host matches nothing.
Anywhere else needs resource.edit on all locations (a global grant), and
so does attaching a credential no resource uses (one saved in the manager, or
one left over after its resources were detached or deleted): it is attached at
no endpoint now. Everyone else enters the secret again on the resource, which
saves a new credential. A refusal is 403, and nothing is written. Nothing is
remembered about where a credential was used before: an address it has left
is like any other.
The editing rule is the same comparison: the address of a resource holding a
credential cannot be changed to another endpoint (a 400; detach first), and
a checkpoint rollback that would do so is refused. Detaching, re-pointing and
attaching again does not get round it either: once detached, no resource uses
the credential at the new address.
The attach is checked against a resource using the credential at that endpoint, and its transaction commits only while that resource still uses it at the address it was checked with; if it was detached or re-pointed meanwhile, the attach is checked again.
Whether the caller holds resource.edit globally is the gateway's answer: on
these two routes it sets X-Fleeger-Credential-Any-Host: 1 for such a caller,
after dropping any copy the client sent, and inventory-svc reads a missing
header as "no". The manager listing shows each credential's endpoints (those
of the resources using it); the resource form and the manager's "Attach"
picker grey out a credential that cannot be attached at the chosen address,
and say why.
A stored credential and certificate checks off (allow_invalid_certs) go
together only for a user holding resource.allow_invalid_certs at the
resource's location (see RBAC & per-location access): with the checks off
the agent accepts any certificate, so a man in the middle at the site would
read the secret. Turning the flag on for a resource that carries a credential,
attaching an existing credential where it is on, and a rollback that would
turn it on for a resource keeping its credential need it. A secret the user
enters itself may go with the checks off: on an existing resource, detach the
credential (on the credentials page), turn the checks off, then enter the
secret again. Without the permission the resource form does not offer the
combination: the checkbox stays off for a resource with a credential, and a
saved credential cannot be picked while it is ticked, each saying why; the
credentials page's Attach does not offer resources with the checks off.
Orphans
Because a credential outlives its attachments, a credential that no resource
references is an orphan. Orphans are surfaced distinctly in the manager as
cleanup candidates — an otherwise-invisible dangling secret becomes a visible,
one-click-deletable thing. When a credential becomes orphaned (its last
attachment is removed or deleted), it's stamped with last_attached_to — a
breadcrumb of what it was on, so you can still recognise it.
Orphan detection is a reverse query, not a stored counter: "which resources
reference this credential" (resource_by_credential index). Zero rows → orphan.
Lifecycle
stateDiagram-v2
[*] --> Orphaned: created standalone
[*] --> Attached: created inline with a resource
Orphaned --> Attached: attach to a resource
Attached --> Attached: attach to / detach from another (still used)
Attached --> Orphaned: last attachment removed (stamps last_attached_to)
Orphaned --> [*]: deleted (allowed only when orphaned)- Create — standalone in the manager, or inline when creating a resource.
- Attach — from the resource form ("use existing"), or from the manager's "Attach" picker. Attaching points a resource at the credential, where a resource using it already points (see above).
- Detach / replace — removes one resource's use of it; the credential survives (it may be shared). Replacing a resource's credential detaches the old one the same way.
- Delete — refused while any resource still uses it (
409 Conflict); detach everywhere first. Deleting a location removes all of its credentials (they're location-scoped and can't be used elsewhere).
Relationship to rollback
Config rollback (see Config revisions, checkpoints & rollback) never touches credential attachments or secrets — snapshots don't contain secrets, and a rollback restores config fields only. A resource recreated by a rollback comes back without a credential, and a rollback that would move the address of a resource holding one to another host is refused, as the edit is. So a rollback never sends a credential somewhere new. The credential manager is the place to fix up attachments after a rollback if needed.