Docker secrets as templates

[hazzuk]

Description

Docker secrets are now defined using templates (instead of convoluted defaults variables).

See hazzuk/karo-custom#23 for a reference implementation.

Changes

• The 'deploy' tasks have been moved to up.yml. Simplifying the role, and allowing for secrets to be templated.
• New karo_compose_secrets_path variable, set dynamically at runtime per stack.
• Secrets created using templates, and each end of file newline is automatically removed.

Notes

Secrets as templates have some large advantages:

• The compose. dictionary variable can now be used to reference a stack variable.
• Avoids the need for long-winded variable definitions.
• Much more visually representative of how secrets are passed to compose stacks.
• Secrets can now be left undefined, and instead rely on the stack defaults variables.

Checklist

• Written documentation
• [n/a] Linked relevant issues

[hazzuk]

Secrets documentation changes complete: https://docs.karolabs.dev/dev/compose/secrets/

@mosslocker changes have been made since yesterday, which should further help to clarify how secrets work.

[mosslocker]

What's the problem?

After a conversation on 10-08-2026

• Having these individual stack secret .j2 templates, with only one variable inside, seems un-intuative.
• Template suggest a framework, where as a single file for a single variable isn't much of a framework
• Too "annoying" to maintain for custom stack creators, adds yet another directory/set of directories

Can we instead...

• Use "lookups" to tell Ansible which variables should be rendered as secrets, through predictable naming conventions in the vault itself. Examples below:

Current format:

hazzuk_core_pocketid_enabled: false

hazzuk_core_pocketid_stack_defaults:
  pocketid:
    image: ghcr.io/pocket-id/pocket-id
    version: v2.6.2@sha256:1cc51e5b36fa7ec31368d3efb24ba362be6dce20f3cc0a2852843527bd5110f0
    log_level: info # debug, info, warn, error
    encryption_key: "" # `openssl rand -base64 32`
    maxmind_license_key: ""

Example 1

hazzuk_core_pocketid_enabled: false

hazzuk_core_pocketid_stack_defaults:
  pocketid:
    image: ghcr.io/pocket-id/pocket-id
    version: v2.6.2@sha256:1cc51e5b36fa7ec31368d3efb24ba362be6dce20f3cc0a2852843527bd5110f0
    log_level: info # debug, info, warn, error
    encryption_key_secret: "" # `openssl rand -base64 32`
    maxmind_license_key_secret: ""

Example 2

hazzuk_core_pocketid_enabled: false

hazzuk_core_pocketid_stack_defaults:
  pocketid:
    image: ghcr.io/pocket-id/pocket-id
    version: v2.6.2@sha256:1cc51e5b36fa7ec31368d3efb24ba362be6dce20f3cc0a2852843527bd5110f0
    log_level: info # debug, info, warn, error
    secrets:
      encryption_key: "" # `openssl rand -base64 32`
      maxmind_license_key: ""

Example 2 is my personal favourite, as it reduces word repetition in the individual variable names