Skip to main content

Concepts

The concepts described in this document are fundamental to understanding how Spage works. Each subject has a short description, and you can find more thorough documentation on each subject throughout the rest of the documentation.

Core concepts​

These are the core concepts of Spage, and are inherited from Ansible.

Task​

A task is a unit of work that can be executed. It is the smallest unit of work in Spage.

playbook.yaml
- name: task 1
  command: echo "task 1"
  when: previous_task.stdout == "success"

Playbook​

A playbook is a collection of plays that are executed on a set of hosts. It always has a play, and can optionally define the target hosts, variables, and other options.

playbook.yaml
- hosts: all
  vars:
    my_var: "Playbook variable!"
  tasks:
    - name: task 1
      command: echo "{{ my_var }}"

Play​

A play is a list of tasks that are executed on a set of hosts. A play is defined in a playbook, and is typically run in the context of an inventory.

playbook.yaml
- name: task 1
  command: echo "task 1"

- name: task 2
  command: echo "task 2"

Inventory​

An inventory defines a collection of hosts and groups that can be targeted by a play. It is typically a YAML file, but can also be a plugin. You can define variables on a host and/or group level, and these variables are available to all tasks in the play.

inventory.yaml
all:
  hosts:
    localhost:
      host: 127.0.0.1
      my_var: "Host specific variable!"

Variable​

A variable is a run-time value that can be used in a playbook. It is typically defined in a playbook, and is used in a task.

playbook.yaml
- name: task 1
  command: echo "{{ my_var }}"

Host​

Hosts are the targets of a play. They are defined in an inventory where they can be referenced by name. The inventory gives them host-specific variables, but hosts can also inherit variables from the groups they are a member of.

inventory.yaml
all:
  hosts:
    localhost:
      host: 127.0.0.1
      my_var: "Host specific variable!"

Group​

Groups are a collection of hosts that can be targeted by a play. They are defined in an inventory where they can be referenced by name.

inventory.yaml
all:
  hosts:
    localhost:
      host: 127.0.0.1
      my_var: "Host specific variable!"
my_group:
  hosts:
    localhost:
  vars:
    my_group_var: "Group specific variable!"
playbook.yaml
- hosts: my_group
  tasks:
    - name: task 1
      command: echo "{{ my_var }}"
    - name: task 2
      command: echo "{{ my_group_var }}"

Configuration​

Spage can be configured through either a configuration file (by default spage.yaml in the current working directory) or through environment variables. Refer to the configuration reference for more information.

spage.yaml
execution_mode: parallel
Environment variables

$ SPAGE_EXECUTION_MODE=parallel spage run playbook.yaml

Execution mode​

Spage takes a different approach to execution than Ansible. Instead of only allowing sequential execution, Spage also allows for parallel execution of tasks.

Next to this, you can offload the execution of tasks to a different execution engine. This is useful when you want to define your tasks in a playbook but still utilize external runners, such as Temporal.

Sequential execution​

Sequential execution is the default execution mode. In this mode, tasks are executed one after the other, in the order they appear in the playbook.

Sequential mode can be explicitly set by setting execution_mode: sequential in the configuration.

For more information, see the execution modes documentation.

Parallel execution​

Parallel execution is an execution mode that allows for the execution of tasks in parallel.

For more information, see the execution modes documentation.

Execution engines​

Spage supports different execution engines for executing tasks. By default, Spage uses the local execution engine, which executes tasks locally (just like Ansible).

However, Spage also supports the temporal execution engine, which allows for the execution of tasks on a Temporal worker.

Local execution engine​

The local execution engine is the default execution engine. It executes tasks locally, just like Ansible.

Temporal execution engine​

The Temporal execution engine allows for the execution of tasks on a Temporal worker. Instead of running tasks from the executing machine, the tasks are loaded into a Temporal worker. This is especially useful if you want to have a durable execution environment for running your playbooks. You can read up on Temporal's sales pitch here.

The play is converted into a Temporal workflow, and the tasks are converted into Temporal activities.

Revert mode​

Spage supports a revert mode. This mode allows for the reversion of a task, where the state of the host is reverted to the state before the task was executed. This logic is defined per task, and can be found on the module definition.

playbook.yaml
- name: task 1
  command: echo "task 1"