dekube-manager

Documentation

dekube-manager is a lightweight package manager for the dekube ecosystem. It downloads distribution scripts and extensions from GitHub releases. Python 3, stdlib only — no dependencies.

Installation

Download from the dekube-manager repo (rolling release — always latest):

Usage

Info mode

--info displays registry information about extensions without downloading anything:

If no extension names are given and dekube.yaml has a depends: list, info is shown for those extensions.

Output

dekube-manager creates the following directory structure:

Run mode

run is a shortcut to invoke helmfile2compose with sensible defaults:

By default, run re-downloads the distribution and all extensions before every invocation, overwriting cached files. Versions follow normal resolution: latest release, or the pinned version from dekube.yaml / CLI flags. If you change a pin in the yaml, the next run picks it up.

Use --no-reinstall to skip downloads for files already present in .dekube/ (missing files are still fetched). There is no version tracking: a cached file is either kept as-is or replaced with whatever version resolves. No in-between.

Defaults: --helmfile-dir ., --extensions-dir .dekube/extensions (if it exists), --output-dir .. Any explicit flag overrides the default. All extra arguments are passed through to helmfile2compose.

In run mode, extensions are resolved from dekube.yaml depends: (or CLI extension args if provided). Extension names passed before the run keyword are ignored — only depends: and post-run flags matter.

Version resolution

Distribution

• No flag: latest GitHub release of dekubeio/helmfile2compose
• --distribution-version v3.1.0: exact tag. The v prefix is added automatically if missing.

Extensions

• Bare name (keycloak): latest GitHub release
• Pinned (keycloak==0.4.0): exact version. The v prefix is added automatically if missing.

No version ranges. Just latest and ==exact.

Dependency resolution

Extensions can declare dependencies in the registry. For example, trust-manager depends on cert-manager:

Dependencies are resolved one level deep (no transitive chains). Duplicates are deduplicated.

Incompatibility checking

Some extensions are fundamentally incompatible (e.g. cert-manager generates certificates with FQDN SANs that flatten-internal-urls would strip). The registry declares these conflicts via "incompatible" in extensions.json, and dekube-manager blocks the combination before downloading anything:

The check is bidirectional — if A declares incompatibility with B, installing both A+B or B+A triggers the error.

To override (you know what you're doing):

Python dependency checking

Some extensions require Python packages (e.g. cert-manager requires cryptography). dekube-manager checks if they're installed and prints an aggregated warning:

This is a warning, not a fatal error — the extension file is still downloaded. Install the dependency before running helmfile2compose with that extension.

Extension registry

The registry lives at dekubeio/dekube-manager as extensions.json. It maps extension names to GitHub repos:

{
  "schema_version": 1,
  "extensions": {
    "keycloak": {
      "repo": "dekubeio/dekube-provider-keycloak",
      "description": "Keycloak and KeycloakRealmImport CRDs",
      "file": "keycloak.py",
      "depends": [],
      "incompatible": []
    }
  }
}

Available versions are whatever tags/releases exist on each repo. The registry doesn't list versions — GitHub is the source of truth.

To add an extension to the registry, see Writing extensions — publishing.

Declarative dependencies

If dekube.yaml exists, dekube-manager reads distribution, distribution_version, and depends from it:

# dekube.yaml
distribution: helmfile2compose
distribution_version: v3.1.0
depends:
  - keycloak
  - cert-manager==0.3.0
  - trust-manager

The distribution key selects which distribution to install. Available distributions are listed in the distributions.json registry. Use core for the bare engine (dekube.py) or omit the key for the default full distribution.

CLI flags override the yaml: --distribution-version overrides distribution_version, explicit extension args override depends. This keeps behavior predictable: either the yaml drives it, or you drive it.

core_version is accepted as a backwards-compatible alias for distribution_version. The v prefix is added automatically if missing (3.0.0 → v3.0.0).

dekube-manager also checks that pyyaml is installed (required by helmfile2compose) and warns alongside any extension-specific missing dependencies.

Integration with generate-compose.sh

Projects that ship a generate-compose.sh wrapper can use dekube-manager as the bootstrap:

#!/bin/bash
set -euo pipefail

DEKUBE_MANAGER_URL="https://raw.githubusercontent.com/dekubeio/dekube-manager/main/dekube-manager.py"
curl -fsSL "$DEKUBE_MANAGER_URL" -o dekube-manager.py
python3 dekube-manager.py run -e compose