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 expiration. 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 expiration. Set issuer/subject to the identity the registry expects, and expiration to the desired lifetime (here ~1 year). With no credential.username, the signed JWT is stored as a bearer registrytoken:

# config.yaml
apiVersion: mirror.plugin.fluxcd.io/v1beta2
kind: Config
hosts:
  - host: registry.example.com
    credential:
      jwkPath: ./keys/registry/privkey.json
      issuer: https://my-issuer.example
      subject: ci-pusher
      # audiences:                   # optional, defaults to the host
      #   - registry.example.com
      expiration: 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 the configured expiration 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 the configured subject until the public key is rotated out.