SemaphoreUI Playbook Demo

Based on previous work: cbugk/ansible-postgresql-demo.

This repository provides a template for SemaphoreUI application, which is a web application to centrally execute for Ansible/Bash/Terraform scripts and allows for simpler user/secret management.

Ansible will be the focus here, as project is an AWX competitor.

1. Setup

Follow SemaphoreUI installation guide and/or take a look at docs/Installation for spinning up an instance.

Note that, a local instance can be spun up and used for bootstrapping another instance for taking advantage of playbooks for security, logging, etc.

2. Editing the configuration

Files and directories

Prioritized and redacted list:

.
├── .ansible
│   └── [...]
│
├── .yamllint
├── .ansible-lint
├── .pre-commit-config.yaml
│
├── ansible.cfg
│
├── inventory
│   ├── group_vars
│   │   ├── all
│   │   │   └── ansible_ssh.yml
│   │   ├── gitlab_runner
│   │   │   ├── params.yml
│   │   │   └── systemd.yml
│   │   ├── podman
│   │   │   └── systemd.yml
│   │   └── security
│   │       ├── geerlingguy.firewall.yml
│   │       └── geerlingguy.security.yml
│   ├── hosts.yml
│   └── host_vars
│       ├── test1
│       │   ├── ansible_ssh.yml
│       │   └── gitlab-runner.yml
│       └── test2
│           ├── ansible_ssh.yml
│           └── gitlab-runner.yml
│
├── requirements.yml
├── playbooks
│   └── [...]
├── tasks
│   └── [...]
│
├── static
│   └── [...]
├── templates
│   └── [...]
│
└──  docs
    └── [...]

Explanation:

• .ansible: Generated by ansible-lint, is gitignored.
• .yamllint and .ansible-lint: are used by pre-commit checks
• ansible.cfg; Standard INI configuration file. Specifies non-standard inventory file.
• inventory: Directory to hold any configuration regarding groups and hosts. Set in ansible.cfg
• inventory/hosts.yml: Standard file which holds groups and hosts in YAML format. Note that, this path should be provided to SemaphoreUI inventory setting, with this repository as source.
• inventory/group_vars/foo/: any YAML file under this directory defines variables of group foo.
• inventory/host_vars/bar/: any YAML file under this directory defines variables of host bar. Note that, host variables overwrite group variables.
• requirements.yml: Standard requirements file, where lists of collections and roles are specified.
• playbooks/: Directory containing all playbooks. Note that, playbook to be executed needs to be provided in Semaphore template settings.
• tasks/: Directory to separate tasks into files. They can be called via an ansible.builtin.include_tasks or ansible.builtin.import_tasks task. Their variables can be provided by those include/import tasks, or implicitly inherited from the playbook/inventory. This is useful for keeping playbooks manageable in size and provides organization of related operations.
• static/: Constant files referred in playbooks. Their content does not depend on variables.
• templates/: Dynamic files referred in playbooks. They are Jinja2 templates to be expended with use of playbook variables.
• docs/: Playbook/Task Group documentations. Simple notes to clarify intension, tricks used, or links for details should be stored there. This provides a self-contained repository, and should not inhibit more comprehensive docs from being hosted elsewhere.

Parameters

Group-wide default parameters, and host-specific parameters should be stored in their respective file. For instance:

• systemd related variables of podman group should be placed at ./inventory/group_vars/podman/systemd.yml.
• gitlab-runner related variables of test1 host should be placed at ./inventory/host_vars/test1/gitlab-runner.yml.

Hosts

Example hosts are given non-existing IP addresses on purpose. They should be disabled and proper host configurations be added to the repository.

Alternatively, inventory can be hosted elsewhere. However, that would render ansible-lint useless, as most violations would need to be disabled.

Task Inclusion

Conventions

It is suggested that all hosts be stored under ./inventory and all playbooks be stored under ./playbooks with C++ include guards-esque when clauses to ensure group memberships and host naming schemes.

Relative Paths

Import/include paths are relative to playbook's YAML file itself. With above convention, their working directory is ./playbooks, and ./tasks/ would be ../tasks in relation. This is against ansible-lint's default rules, so an exception is added.

Task Guards for Related Groups

Following is an example of ensuring security tasks being called upon security group only. This is checked even when hosts: security is explicitly provided on the playbook YAML as a way to make tasks modular.

- name: Security Related Tasks (OS agnostic)
  when: ('security' in group_names)
  become: true
  ansible.builtin.import_tasks: ../tasks/security.yml

Requirements YAML

See official docs for installing collections and roles.

3. Pre-commit hooks

Create a venv and install pre-commit via pip. Thereon, pre-commit run --all-files can be used to check compliance without committing changes on the filesystem.

./.pre-commit-config.yaml has been set up via pre-commit install in aforementioned ven environment to take effect.