Inventory, variables and secrets

Automax keeps operational data outside the source tree. Jobs, inventories, variables and secrets are passed by path from the CLI:

automax run \
  --job /srv/automax/jobs/deploy.yaml \
  --inventory /srv/automax/inventory/prod.yaml \
  --vars /srv/automax/vars/prod.yaml \
  --secrets /srv/automax/secrets/prod.yaml

Inventory

Inventory can be static YAML or dynamic provider output. Static inventory defines target servers, groups, host variables and SSH connection data:

servers:
  web01:
    host: 10.0.0.11
    port: 22
    groups: [web, production]
    vars:
      role: frontend
    ssh:
      user: "{{ secrets.ssh_user }}"
      key_file: "{{ secrets.ssh_key_file }}"
      known_hosts: ~/.ssh/known_hosts
      missing_host_key_policy: reject

Supported SSH fields are read into the target model or passed through the ssh mapping for the SSH manager. Use missing_host_key_policy: reject for real environments. Lab-only policies should be explicit in the inventory.

Dynamic inventory providers are also supported when the target list is generated by another local tool or inventory service:

inventory:
  provider: command
  command: ["./scripts/list-hosts.py", "--env", "prod"]
  format: yaml
  timeout: 30

Supported providers are file, command and http. See Dynamic inventory for provider-specific examples and safety notes.

Variable precedence

The current precedence is:

CLI --var overrides
> job vars
> external vars file

Target variables are merged at execution time and override the global variable view for that target:

target.vars > merged global vars

Example variables file:

vars:
  app_name: myapp
  version: 1.2.3
  environment: production

CLI overrides:

automax run --job job.yaml --inventory inventory.yaml --var version=1.2.4

Secrets

Secrets support env, file, command, vault, aws_secrets_manager, azure_key_vault, gcp_secret_manager and onepassword providers. External secret manager providers run their vendor CLI on the Automax controller and keep resolved values in memory only.

secrets:
  ssh_user:
    provider: env
    name: AUTOMAX_SSH_USER

  ssh_key_file:
    provider: file
    path: ~/.ssh/automax-key-path

  deploy_token:
    provider: vault
    path: secret/prod/app
    field: deploy_token

  db_password:
    provider: aws_secrets_manager
    secret_id: prod/db
    json_key: password
    region: eu-west-1

Shorthand forms are also supported:

secrets:
  ssh_user:
    env: AUTOMAX_SSH_USER
  ssh_key_file:
    file: ~/.ssh/automax-key-path
  deploy_token:
    command: ["pass", "show", "prod/automax/deploy-token"]

A plain string is accepted as an already-resolved secret value, but this should be reserved for local labs and examples. See Command secrets for command-provider and external secret-manager guidance.

Template context

Rendered job values and plugin parameters can use:

job
 task
 step
 substep
 server / target
 vars
 secrets
 outputs
 step_state

fs.file.template adds one extra namespace: values, taken from fs.file.template.with.values.

SSH security options

Automax defaults to conservative SSH behavior:

servers:
  app01:
    host: app01.example.com
    ssh:
      user: deploy
      key_file: ~/.ssh/id_ed25519
      known_hosts: ~/.ssh/known_hosts
      missing_host_key_policy: reject
      allow_agent: false
      look_for_keys: false
      strict_key_permissions: true

Unknown host keys are always rejected. Bootstrap lab hosts by collecting their host key into a dedicated known_hosts file first, then keep missing_host_key_policy: reject.

Private key files are checked by default and must not be accessible by group or other users. Use chmod 600 on private keys instead of disabling the check.

Secrets resolved from env or file are masked before stdout, stderr, messages and plugin result data are persisted to the SQLite run state.

Job-scoped variable rendering

Use automax vars render to inspect the final target-specific variable context used by a selected job plan. The command applies the same --limit, --exclude, --tags, --skip-tags, --vars, --secrets and --var inputs as automax run, and masks secret values before printing text or JSON output.

automax vars render --job jobs/deploy.yaml --inventory inventory/prod.yaml --vars vars/prod.yaml --secrets secrets/prod.yaml --limit web01