Secrets

Secrets provide a secure way to inject sensitive values — passwords, API keys, tokens — into generator configs without storing them in plain text. Values are kept in an encrypted keyring file and referenced in configs with ${secrets.name} tokens.

How it works

Secrets follow the same substitution model as parameters, but the values come from an encrypted file instead of startup.yml or the --params CLI flag:

output:
  - opensearch:
      hosts:
        - ${params.opensearch_host}
      username: ${params.opensearch_user}
      password: ${secrets.opensearch_password}   # from the keyring

When Eventum loads the config, it extracts all ${secrets.*} tokens, looks up each name in the encrypted keyring, decrypts the values, and substitutes them into the config before YAML parsing.

The keyring and cryptfile

Secrets are stored in an encrypted file called the cryptfile, managed by the keyrings.cryptfile library. The cryptfile is AES-encrypted and protected by a password.

Keyring password

The keyring password is read from the EVENTUM_KEYRING_PASSWORD environment variable. If the variable is not set, Eventum falls back to the default password eventum and logs a warning.

For production use, always set a custom password:

export EVENTUM_KEYRING_PASSWORD="your-strong-password"

Cryptfile location

The cryptfile path depends on how you run Eventum:

Managing secrets with eventum-keyring

The eventum-keyring CLI tool lets you add, read, and remove secrets from the cryptfile.

Set a secret

# Provide the value inline
eventum-keyring set db_password "s3cret"

# Or omit the value to be prompted interactively (input is hidden)
eventum-keyring set db_password
# Enter password of `db_password`: ********

Get a secret

eventum-keyring get db_password
# s3cret

Remove a secret

eventum-keyring remove db_password

Custom cryptfile location

Every subcommand accepts a --cryptfile flag to work with a specific file instead of the system default:

eventum-keyring set api_key "tok_abc123" --cryptfile ./my-project/cryptfile.cfg
eventum-keyring get api_key --cryptfile ./my-project/cryptfile.cfg

This is the same file referenced by path.keyring_cryptfile in eventum.yml or --cryptfile on eventum generate.

Using secrets in configs

Reference secrets with ${secrets.name} anywhere in generator.yml:

output:
  - http:
      url: https://api.example.com/ingest
      headers:
        Authorization: "Bearer ${secrets.api_token}"

  - opensearch:
      hosts:
        - https://opensearch.prod:9200
      username: admin
      password: ${secrets.opensearch_password}

  - clickhouse:
      host: clickhouse.prod
      username: ${secrets.ch_user}
      password: ${secrets.ch_password}

Missing secrets

If a config references ${secrets.name} but the secret is not in the keyring, Eventum raises an error at load time and the generator does not start:

Error: Failed to obtain secrets used in configuration
Reason: Cannot obtain secret `api_token`: Secret is missing

This prevents generators from running with empty credentials.

When to use secrets

Credentials and sensitive data — passwords for OpenSearch, ClickHouse; API keys and tokens for authentication to HTTP endpoints or any other output destination:

eventum-keyring set opensearch_password "prod-password-here"
eventum-keyring set ch_password "clickhouse-secret"
eventum-keyring set api_token "tok_abc123xyz"

output:
  - opensearch:
      password: ${secrets.opensearch_password}
  - clickhouse:
      password: ${secrets.ch_password}
  - http:
      url: https://api.example.com/events
      headers:
        Authorization: "Bearer ${secrets.api_token}"

Secrets vs parameters

For the full CLI reference see $ eventum-keyring command page.