Configuration

Spage can be configured through a configuration file or environment variables. The configuration file (spage.yaml by default) should be placed in your current working directory.

Quick Start

Create a spage.yaml file in your project root:

execution_mode: parallel
logging:
  level: info
revert: true

Ansible Migration

If you're coming from Ansible, here's how Spage configuration maps to ansible.cfg:

Ansible Setting	Spage Equivalent	Example
[defaults] host_key_checking	host_key_checking	host_key_checking: false
[defaults] roles_path	roles_path	roles_path: "./roles:/usr/share/ansible/roles"
[defaults] inventory	inventory	inventory: "./inventory.yaml"
[defaults] timeout	timeout	timeout: 3600
[defaults] retry_files_enabled	revert	revert: true
[ssh_connection] ssh_args	ssh.options	ssh.options.ssh_args: "-o ControlMaster=auto"
[ssh_connection] jump_host	ssh.jump_host	ssh.jump_host: "bastion.example.com"
[privilege_escalation] become_flags	privilege_escalation.become_flags	become_flags: "-E"
[privilege_escalation] use_interactive	privilege_escalation.use_interactive	use_interactive: false

Configuration Options

Core Execution

Option	Default	Description
execution_mode	sequential	Task execution mode: sequential or parallel
executor	local	Execution engine: local or temporal
connection	""	Connection type override (e.g., "local" to run tasks locally)
revert	false	Enable automatic task reversion on failure
limit	""	Host limit pattern for execution

Logging

Option	Default	Description
logging.level	info	Log level: debug, info, warn, error
logging.format	plain	Output format: json, yaml, or plain
logging.file	""	Log file path (empty for stdout)
logging.timestamps	true	Include timestamps in log output

Temporal Integration

These options come into effect when the executor is set to temporal.

Option	Default	Description
temporal.address	""	Temporal server address (defaults to localhost:7233)
temporal.task_queue	SPAGE_DEFAULT_TASK_QUEUE	Temporal task queue name
temporal.workflow_id_prefix	spage-workflow	Prefix for workflow IDs
temporal.trigger	false	Enable Temporal trigger mode

API Configuration

API configuration is used for uploading bundles to the Spage API. These options are not affecting any run-time behavior.

Option	Default	Description
api.http_base	https://api.spage.dev	Base URL for Spage API HTTP server
api_token	""	Bearer token for CLI auth against spage-api

Daemon Configuration

This daemon is used for remotely starting/monitoring Spage processes and reporting play execution status to the Spage API.

Option	Default	Description
daemon.enabled	false	Enable daemon communication
daemon.endpoint	localhost:9091	Daemon endpoint address
daemon.play_id	""	Play ID for daemon reporting
daemon.timeout	3s	Daemon communication timeout

Inventory and Roles

These options are used for loading the inventory and roles by default. You can override these options through the command line parameters.

Option	Default	Description
inventory	""	Colon-delimited paths to search for inventory files
inventory_plugins	""	Colon-delimited paths to search for inventory plugins
enable_plugins	[]	List of enabled plugin names/patterns
roles_path	""	Colon-delimited paths to search for roles

SSH Configuration

Option	Default	Description
ssh.use_password_fallback	false	Enable interactive password authentication as fallback
ssh.jump_host	""	SSH jump host (ProxyJump equivalent), use "none" to disable
ssh.jump_user	""	Username for jump host
ssh.jump_port	22	Port for jump host
host_key_checking	true	Enable SSH host key checking

SSH Authentication

Option	Default	Description
ssh.auth.methods	["publickey", "password"]	Ordered list of auth methods to try
ssh.auth.public_keys	[]	Paths to specific public key files
ssh.auth.password	true	Enable password authentication
ssh.auth.keyboard	false	Enable keyboard-interactive authentication
ssh.auth.gssapi	false	Enable GSSAPI authentication
ssh.auth.none	false	Enable "none" authentication method
ssh.auth.preferred	publickey	Preferred authentication method
ssh.auth.identities_only	false	Only use explicitly configured identities
ssh.auth.password_prompt	""	Custom password prompt
ssh.auth.agent_forwarding	false	Enable SSH agent forwarding
ssh.options	{}	Advanced SSH options (ssh_config style)

Privilege Escalation

Option	Default	Description
privilege_escalation.use_interactive	false	Use -Su (interactive) vs -u (non-interactive)
privilege_escalation.become_flags	""	Additional flags to pass to become

Tags & Filtering

Option	Default	Description
tags.tags	[]	Only run tasks with these tags
tags.skip_tags	[]	Skip tasks with these tags

Ansible Vault

Ansible Vault is used for decrypting vaulted variables/files. Spage supports the same options as Ansible.

Option	Default	Description
ansible_vault.password_file	""	Vault password file path
ansible_vault.identity	""	Colon-delimited paths to vault identity files
ansible_vault.password_prompt	""	Vault password prompt
ansible_vault.ask_vault_pass	false	Ask for vault password
ansible_vault.ask_vault_pass_on_diff	false	Ask for vault password when doing a diff
ansible_vault.timeout	30	Vault timeout in seconds
ansible_vault.retry_count	3	Vault retry count
ansible_vault.retry_delay	5	Vault retry delay in seconds

Facts & Variables

Option	Default	Description
facts	{}	Global facts/variables available to all tasks

Environment Variables

All configuration options can be set via environment variables. They take precedence over the config file:

# Core execution
export SPAGE_EXECUTION_MODE=parallel
export SPAGE_EXECUTOR=temporal

# Logging
export SPAGE_LOGGING_LEVEL=debug
export SPAGE_LOGGING_FORMAT=json

# SSH
export SPAGE_SSH_JUMP_HOST=jump.example.com
export SPAGE_SSH_AUTH_METHODS="publickey,password"

# Temporal
export SPAGE_TEMPORAL_ADDRESS=temporal.example.com:7233
export SPAGE_TEMPORAL_TASK_QUEUE=my-queue

# API
export SPAGE_API_TOKEN=your-token-here
export SPAGE_API_HTTP_BASE=https://api.example.com

Examples

Production Configuration

# High-performance parallel execution
execution_mode: parallel
executor: local
revert: true

# Structured logging
logging:
  level: info
  format: json
  file: /var/log/spage.log
  timestamps: true

# SSH configuration
ssh:
  jump_host: bastion.example.com
  jump_user: admin
  auth:
    methods: ["publickey"]
    identities_only: true

# Inventory and roles
inventory: "./inventory/production.yaml"
roles_path: "./roles:/usr/share/ansible/roles"

# Tags
tags:
  tags: ["deploy", "production"]
  skip_tags: ["test", "debug"]

Development Configuration

# Debug-friendly settings
execution_mode: sequential
logging:
  level: debug
  format: plain
  timestamps: true

# Local development
connection: local
inventory: "./inventory/local.yaml"
roles_path: "./roles"

# Development features
revert: false
tags:
  tags: ["dev", "test"]

Temporal Workflow Configuration

# Use Temporal for execution
executor: temporal
temporal:
  address: temporal.example.com:7233
  task_queue: spage-prod
  workflow_id_prefix: spage-deploy
  trigger: false

# High-performance settings
execution_mode: parallel
revert: true

# Monitoring
daemon:
  enabled: true
  endpoint: localhost:9091
  timeout: 10s

SSH Jump Host Configuration

# SSH through jump host
ssh:
  jump_host: bastion.example.com
  jump_user: admin
  jump_port: 2222
  auth:
    methods: ["publickey", "password"]
    public_keys: ["~/.ssh/id_rsa", "~/.ssh/id_ed25519"]
    password: true
    identities_only: false

# Security settings
host_key_checking: true
privilege_escalation:
  use_interactive: false
  become_flags: "-E"

Configuration Precedence

Configuration values are resolved in this order (highest to lowest priority):

1. Command line flags (if supported)
2. Environment variables
3. Configuration file (spage.yaml)
4. Built-in defaults