delonix stack

Aplica um manifesto inteiro (delonix-manifest.yaml) — todos os Kinds, por ordem.

Applies a whole manifest (delonix-manifest.yaml) — every Kind, in dependency order.

O equivalente declarativo do compose, ao estilo Kubernetes: um YAML multi-documento (apiVersion: delonix.io/v1) aplicado por ordem de dependência. Converge em onze dos doze Kinds — muda-se um campo no manifesto e o apply aplica-o, a quente e sem mudar o PID quando é possível. Só o Secret continua garante-presente (o estado são valores cifrados, e um plano não os decifra para comparar), e o plan marca-o com ! em vez de o esconder. A lista exacta sai de delonix stack plan --fields. Continua fail-fast e sem rollback: o que já foi aplicado fica, e é o plan seguinte que mostra o que faltou. Guia completo de CI e deriva em GitOps e CI.

The declarative, Kubernetes-style counterpart to compose: a multi-document YAML (apiVersion: delonix.io/v1) applied in dependency order. It converges for Container, Pod, Volume and Network — change a field in the manifest and apply applies it, live and without changing the PID where that is possible; the remaining Kinds stay ensure-present and plan marks them ! rather than hiding them. Still fail-fast and without rollback: whatever was applied stays, and the next plan is what shows the rest. Full CI and drift guide in GitOps & CI.

📄 Implementação real em Rust: cmd/stack.rs

Usage: delonix stack [OPTIONS] <COMMAND>

Commands:
  apply     Applies all the manifest Kinds (Network → Volume → Image → Vm → Container)
  destroy   Removes everything this stack owns (by the `delonix.io/stack` label)
  wait      Blocks until every declared resource is present and, where it has one, healthy
  init      Initializes a COMPLETE project: Delonixfile + manifest + cluster + README
  describe  Stack detail in `kubectl describe` style
  history   What this stack applied, and when (ADR-0019)
  ls        List the structure the manifest composes, and whether each resource exists
  plan      Shows what an `apply` WOULD change, without changing anything
  validate  Validates the manifest WITHOUT touching anything (dry-run)
  rollback  Re-apply a recorded revision (ADR-0019)
  prune     Remove what this stack owns and the manifest no longer declares
  help      Print this message or the help of the given subcommand(s)

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

COMMAND MAP:
  Lifecycle    apply · destroy · wait
  Create       init
  Inspect      plan · ls · describe · validate · history
  Declarative  rollback
  Maintenance  prune

EXAMPLES:
  # everything a manifest declares, in dependency order
  delonix stack apply -f delonix-manifest.yaml

  # what would change, before anything changes
  delonix stack plan -f prod.yaml

  # a complete project, files already filled in
  delonix stack init -t python

SEE ALSO:
  delonix container apply · delonix compose up · delonix cluster apply ·
  delonix manifest schema

  delonix › stack

Exemplo de manifesto

apiVersion: delonix.io/v1
kind: Network
metadata: { name: backend }
---
apiVersion: delonix.io/v1
kind: Volume
metadata: { name: dados }
---
apiVersion: delonix.io/v1
kind: Container
metadata: { name: db }
spec:
  image: postgres:16-alpine
  network: backend
  volumes: [ "dados:/var/lib/postgresql/data" ]
  ports: [ "5432:5432" ]
  env: [ "POSTGRES_PASSWORD=segredo" ]

`stack validate`

Validates the manifest WITHOUT touching anything (dry-run).

Resolves the cross-references (Container.network/.volumes, Vm.network, Ingress/Egress.target) against what the manifest declares PLUS what already exists in the stores. Exits with an error if any reference is left unresolved — it is the safety net against an apply that would only fail halfway through (fail-fast, no rollback).

Usage: delonix stack validate [OPTIONS]

Options:
  -f, --file <FILE>
          

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --strict
          Fail (exit != 0) when a field was ignored, instead of only warning about it — for CI

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # resolve every cross-reference before an apply that has no rollback
  delonix stack validate -f prod.yaml

  # the manifest in this directory, as a pre-commit check
  delonix stack validate

SEE ALSO:
  delonix stack plan · delonix stack apply · delonix manifest schema · delonix
  explain

  delonix › stack › validate

ExemplosExamples

Validar o manifesto SEM aplicar nada

Validate the manifest WITHOUT applying anything

delonix stack validate -f delonix-manifest.yaml

`stack describe`

Stack detail in kubectl describe style.

Each resource DECLARED in the manifest and whether or not it is present on the machine.

The stack has no state of its own — there is no registry of "stacks", only a manifest and the resources it creates. That is why this describe always starts from the file and goes to confirm each resource against the respective store, instead of inventing a new registry that would drift out of sync (the same reason cluster ls derives its state from the container labels).

The column that matters is PRESENCE: an apply is fail-fast and without rollback, so a half-applied stack is a normal state and this is exactly what it shows.

Usage: delonix stack describe [OPTIONS]

Options:
  -f, --file <FILE>
          

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # each declared resource in kubectl-describe style, confirmed against its
  # store
  delonix stack describe -f prod.yaml

  # after an apply that died halfway, see exactly what did get created
  delonix stack describe

SEE ALSO:
  delonix stack ls · delonix stack plan · delonix container describe

  delonix › stack › describe

ExemplosExamples

Estado recurso a recurso, confrontado com o manifesto

Resource-by-resource state, checked against the manifest

delonix stack describe

`stack ls`

List the structure the manifest composes, and whether each resource exists.

Containers, volumes, networks, ... — the tabular summary of describe.

Usage: delonix stack ls [OPTIONS]

Options:
  -f, --file <FILE>
          

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # every resource the manifest composes, and whether it exists yet
  delonix stack ls -f prod.yaml

  # the manifest in this directory
  delonix stack ls

SEE ALSO:
  delonix stack describe · delonix stack plan · delonix stack wait

  delonix › stack › ls

ExemplosExamples

Que recursos do manifesto existem de facto neste host

Which manifest resources actually exist on this host

delonix stack ls

`stack init`

Initializes a COMPLETE project: Delonixfile + manifest + cluster + README.

Files ALREADY FILLED IN (images included), ready to use without editing anything.

ADOPTS an existing, non-empty project instead: only the Delonix/CI glue (Delonixfile, manifest, CI/CD, SonarQube, CONTRIBUTING.md) is written, the project's own code is never touched — a warning follows, since the Delonixfile still assumes the template's own file layout.

Usage: delonix stack init [OPTIONS] [DIR]

Arguments:
  [DIR]
          Project directory (default: the current one)
          
          [default: .]

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --name <NAME>
          Project name (default: the directory name)

      --image <IMAGE>
          Image to use. Omit = fills in with the default image

      --force
          Overwrites already existing files

  -t, --template <TEMPLATE>
          Generates a complete PROJECT for a stack (e.g. `python`) with best practices, instead of the generic scaffold. `--template list` shows the available ones

  -v, --template-version <TEMPLATE_VERSION>
          Version parameter some templates read — an image tag, a framework version, or a toolchain version, depending on the template; the exact accepted form is documented in that template's own README. Refused with a clear error on a template that has none

      --up
          After generating, builds the image, starts it and waits for it to become healthy

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # a complete Python project — Delonixfile, manifest and README, runnable
  # without editing anything
  delonix stack init -t python

  # which templates exist
  delonix stack init --template list

  # scaffold into a directory of its own, with the name and image you want
  delonix stack init ./api --name api --image nginx:alpine

  # generate, build and wait until it answers healthy
  delonix stack init -t go --up

  # pin a Django project to an exact major.minor line
  delonix stack init -t django -v 5.2

  # pin a Laravel project to a framework major
  delonix stack init -t laravel -v 12.5

  # pin the Go toolchain a template builds against
  delonix stack init -t go -v 1.22

SEE ALSO:
  delonix stack apply · delonix stack plan · delonix init · delonix cluster
  init

  delonix › stack › init

--template <nome> gera um projecto real e funcional de uma linguagem/framework, com boas práticas (multi-stage não-root, healthcheck, testes, dotfiles) e já delonix-native (Delonixfile + manifesto). Sem --template, o init gera o scaffold genérico. Os tokens __NAME__/__MODULE__ são substituídos pelo nome do projecto.

--template <name> generates a real, functional project for a language/framework, with best practices (non-root multi-stage, healthcheck, tests, dotfiles) and already delonix-native (Delonixfile + manifest). Without --template, init generates the generic scaffold. The __NAME__/__MODULE__ tokens get replaced with the project name.

ExemplosExamples

Projecto COMPLETO de uma stack (FastAPI): código + Delonixfile + manifesto + testes

COMPLETE stack project (FastAPI): code + Delonixfile + manifest + tests

delonix stack init myapi --template python

Ver os templates disponíveis

See the available templates

delonix stack init --template list

`stack apply`

Applies all the manifest Kinds (Network → Volume → Image → Vm → Container)

Usage: delonix stack apply [OPTIONS]

Options:
      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --name <NAME>
          Stack name (the owner stamped on every resource). Default: a `kind: Stack`'s name, else the manifest's directory

  -f, --file <FILE>
          

      --dry-run
          Don't apply anything — print the full manifest with every default filled in (like `kubectl apply --dry-run=client -o yaml`). Stacks are expanded and Kinds canonicalized, so you see exactly what WOULD run

      --replace <KIND/NAME>
          Authorize DESTROYING and recreating a resource whose change does not converge live: `--replace <Kind>/<name>` (repeatable), or `--replace all`. Without it, `apply` refuses and changes nothing

      --prune
          Also REMOVE what this stack owns and the manifest no longer declares. Never happens without this flag

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # converge the machine onto the manifest — creates what is missing and
  # updates what drifted
  delonix stack apply -f delonix-manifest.yaml

  # the full manifest with every default filled in, applying nothing
  delonix stack apply -f prod.yaml --dry-run

  # authorize the one recreation the plan asked for — a cold field cannot
  # converge live
  delonix stack apply -f prod.yaml --replace Container/web

  # also remove what this stack owns and the file no longer declares
  delonix stack apply -f prod.yaml --prune

SEE ALSO:
  delonix stack plan · delonix stack wait · delonix stack destroy · delonix
  stack validate

  delonix › stack › apply

Uma alteração que não converge a quente (imagem, entrypoint, capabilities, driver de um volume) é RECUSADA sem --replace, e nada é alterado — recriar significa downtime e, num volume, perder os dados. O plan nomeia sempre o campo que a obriga.

O --prune nunca acontece sozinho, e só toca no que esta stack possui (label delonix.io/stack): um recurso criado à mão é invisível para ele.

ExemplosExamples

Aplicar o manifesto por omissão (./delonix-manifest.yaml)

Apply the default manifest (./delonix-manifest.yaml)

delonix stack apply

Manifesto explícito

Explicit manifest

delonix stack apply -f infra/stack.yaml

Autorizar a recriação de um recurso que não converge a quente

Authorize recreating a resource that does not converge live

delonix stack apply --replace Container/api

Aplicar E remover o que saiu do manifesto

Apply AND remove whatever left the manifest

delonix stack apply --prune

`stack plan`

Shows what an apply WOULD change, without changing anything.

Compares the manifest against the machine and against the last spec this stack applied (a three-way diff, so a field a human set by hand is left alone while a field removed from the manifest is reverted). With the manifest unchanged, whatever it prints IS drift.

Usage: delonix stack plan [OPTIONS]

Options:
  -f, --file <FILE>
          

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --name <NAME>
          Stack name (owner of the resources). Default: a `kind: Stack`'s name, else the manifest's directory

  -o, --output <OUTPUT>
          Output format: `table` (default) or `json` (ADR-0005)
          
          [default: table]
          [possible values: table, json]

      --detailed-exitcode
          Exit 2 when there are changes (0 = none, 1 = error) — the `terraform plan -detailed-exitcode` contract, for a CI drift gate

      --fields
          Print WHICH fields the plan compares, per Kind, and exit. Answers "why is my change not showing up?" without reading the source

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # what an apply would change — the machine is not touched
  delonix stack plan -f prod.yaml

  # a drift gate in CI: exit 2 means the machine no longer matches the file
  delonix stack plan -f prod.yaml --detailed-exitcode

  # machine-readable, for a bot to comment on a pull request
  delonix stack plan -f prod.yaml -o json

  # which fields the plan compares, per Kind, and which it does not — answers
  # why a change is not showing up
  delonix stack plan --fields

SEE ALSO:
  delonix stack apply · delonix stack validate · delonix stack describe ·
  delonix stack destroy

  delonix › stack › plan

Compara TRÊS coisas: o manifesto, a máquina, e o último spec que esta stack aplicou. É esse terceiro lado que distingue «tiraste este campo do ficheiro» (reverte) de «alguém pôs isto à mão com container update» (não mexe). Com o manifesto inalterado, o que ele imprimir É deriva.

Símbolos: + criar · +~ adoptar (existe e não é de stack nenhuma) · ~ actualizar a quente · -/+ recriar · - remover · = sem alteração · ✗ conflito (é de outra stack) · ! Kind não convergente.

ExemplosExamples

O que um apply mudaria — sem mudar nada

What an apply would change — without changing anything

delonix stack plan

Gate de deriva em CI (sai 2 quando há alterações)

Drift gate in CI (exits 2 when there are changes)

delonix stack plan --detailed-exitcode

Para alimentar outra ferramenta

To feed another tool

delonix stack plan -o json

Que campos são comparados, e quais não são e porquê

Which fields are compared, and which are not and why

delonix stack plan --fields

`stack destroy`

Removes everything this stack owns (by the delonix.io/stack label).

A resource created by hand, or belonging to another stack, is never touched. Removal happens in the REVERSE of the creation order, so a network is not pulled from under the containers still attached to it.

Usage: delonix stack destroy [OPTIONS]

Options:
  -f, --file <FILE>
          

      --l18n <en|pt>
          Output language: `en` (default) or `pt` (Portuguese, pt_AO). Also settable via `$DELONIX_L18N`. Global — works before any subcommand

      --name <NAME>
          Stack name. Default: a `kind: Stack`'s name, else the manifest's directory

      --dry-run
          List what would be removed, and remove nothing

  -h, --help
          Print help (see a summary with '-h')

EXAMPLES:
  # remove everything this stack owns, in the reverse of the creation order
  delonix stack destroy -f prod.yaml

  # read the list first — nothing is removed
  delonix stack destroy -f prod.yaml --dry-run

  # when the file declares no Stack, say whose resources these are
  delonix stack destroy -f prod.yaml --name shop

SEE ALSO:
  delonix stack apply · delonix stack plan · delonix stack ls · delonix
  compose down

  delonix › stack › destroy

Remove pela ordem INVERSA da de criação, para não arrancar uma rede debaixo dos containers ainda ligados a ela. Só toca no que tem a label delonix.io/stack; é idempotente (destruir uma stack já destruída devolve 0).

ExemplosExamples

Ver o que seria removido

See what would be removed

delonix stack destroy --dry-run

Remover tudo o que esta stack possui

Remove everything this stack owns

delonix stack destroy

LaboratórioLab

Gera um projecto COMPLETO já pronto (código + Delonixfile + manifesto) a partir de um template, e aplica-o.

delonix stack init minha-api --template python
cd minha-api
delonix stack apply

Generate a COMPLETE, ready-to-run project (code + Delonixfile + manifest) from a template, and apply it.

delonix stack init my-api --template python
cd my-api
delonix stack apply

DesafioChallenge

Corre stack apply --dry-run e compara o YAML impresso (com todos os defaults preenchidos) com o teu delonix-manifest.yaml original — que campos é que o motor preencheu por ti?

Run stack apply --dry-run and compare the printed YAML (every default filled in) against your original delonix-manifest.yaml — which fields did the engine fill in for you?