Flux Mirror Keygen Command

The flux mirror keygen command generates an EdDSA (Ed25519) JSON Web Key pair for JWK-based registry auth. The output files plug directly into the hosts[].credential.jwkPath config field, which sync and login use to sign JWTs.

Synopsis

flux mirror keygen [flags]

It writes the key pair into a directory as two JWK sets:

Both files use the standard JWK set shape {"keys":[...]}. The two keys share a UUIDv6 kid so a signature made with the private key can be matched against the public set.

Flags

Behavior

• The output directory is created (mkdir -p) if it does not exist.
• The command refuses to overwrite either file if it already exists. Delete them or point at a fresh directory to rotate.
• The private file is written with mode 0600. If the public write fails, the private file is rolled back, so a partial run never leaves a stray key behind.

# Write a key pair into the current directory.
flux mirror keygen

# Write a key pair into ./keys/registry (created if missing).
flux mirror keygen -o ./keys/registry

Output:

✔ private key set written to: ./keys/registry/privkey.json
✔ public key set written to: ./keys/registry/pubkey.json

Example: mint a long-lived login token

Unlike provider/value credentials — whose lifetime is fixed by an external issuer — a jwkPath credential is signed locally, so you control its lifetime through exp. This makes a key pair plus login a convenient way to mint a single, long-lived bearer token (for example, a year-long token for a CI system or an air-gapped agent).

1. Generate the key pair.

flux mirror keygen -o ./keys/registry

2. Reference the private key from a host credential, with a long exp. Set iss/sub to the identity the registry expects, and exp to the desired lifetime (here ~1 year). With no username, the signed JWT is stored as a bearer registrytoken:

# config.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta1
kind: Config
hosts:
  - host: registry.example.com
    credential:
      jwkPath: ./keys/registry/privkey.json
      iss: https://my-issuer.example
      sub: ci-pusher
      # aud: registry.example.com   # optional, defaults to the host
      exp: 8760h                     # ~1 year

3. Log in once to mint and store the token.

flux mirror login -f ./config.yaml

login signs one JWT valid for exp and writes it to the Docker config, so tools like flux push artifact authenticate as that identity until it expires.

4. Grant access on the registry side. Share pubkey.json with the registry operator, or publish it at an HTTPS URL the registry can fetch as JWKS, so the registry can verify tokens signed by the matching private key (matched by kid).

Re-run login to mint a fresh token before the current one expires. Treat privkey.json as a secret: anyone holding it can mint tokens for sub until the public key is rotated out.