Skip to main content

Ansible Collection - republic.infra

The republic.infra Ansible Galaxy collection provides a set of roles to configure core infrastructure components for servers. This collection is currently in early production, with limited but stable roles tested for real-world use. It offers foundational tools for configuring system settings, improving performance, and managing essential services on a variety of systems.

Available Roles​

The current roles available in the republic.infra collection are:

  • republic.infra.hostname – Set the system hostname.
  • republic.infra.ntp – Configure Network Time Protocol (NTP) to synchronize time.
  • republic.infra.iptables – Configure iptables firewall rules.
  • republic.infra.fail2ban – Install and configure Fail2ban for intrusion prevention.
  • republic.infra.cron – Install and manage cron jobs for automated task scheduling.
  • republic.infra.logrotate – Configure log rotation to manage system logs.
  • republic.infra.golang – Install the Go programming language (Golang).
  • republic.infra.sysctl_net – Adjust sysctl settings for increased UDP throughput.
  • republic.infra.cpu_governor – Set the CPU governor power management scheme.
  • republic.infra.sysstat – Install Sysstat to track system performance and resource usage.
  • republic.infra.otelcol – Set up OpenTelemetry Collector for gathering metrics.
  • republic.infra.yaml_merge – Merge and update YAML configuration files.

More roles are coming soon, providing even more tools for system configuration and management.

Installation​

You can install the republic.infra collection from Ansible Galaxy using the following command:

ansible-galaxy collection install republic.infra

This command downloads and installs the latest version of the collection and makes the roles available for use in your playbooks.

Example Usage​

Here’s a simple example of how to use a role from the republic.infra collection to configure NTP on a set of hosts:

# playbook.yml
---
- hosts: all
  become: true
  roles:
    - role: republic.infra.ntp

This playbook applies the republic.infra.ntp role to synchronize the system’s time using NTP on all targeted hosts.

Concept​

The roles within the republic.infra collection generally follow these phases (though not all roles will use each phase):

  1. Load variables: Initialize role-specific variables.
  2. Install binaries: Install necessary packages or dependencies.
  3. Set configuration: Apply system or service configurations.
  4. Optimize settings: Adjust performance or security settings (e.g., sysctl, iptables).
  5. Enable services: Ensure services (e.g., NTP, Fail2ban) are enabled and running.

Contributing​

If you would like to contribute to the republic.infra collection or report any issues, the best way is to open an issue on the GitHub repository. Contributions are welcome, whether they are new roles, bug fixes, or enhancements to existing roles.

Adding a New Role​

To add a new role, the easiest way is to use PowerShell and the provided new-role.ps1 script:

./new-role.ps1 -Author null-ref-ex -Name new_role_name

This will generate a skeleton for your new role, including a documentation file under the docs/ folder. You can then customize the role and its documentation to meet your needs.

Molecule Testing Framework​

Roles in this collection are tested using Molecule with the Vagrant driver. Molecule ensures that each role works as expected across various environments.

To set the Vagrant provider and box, use the following environment variables:

export VAGRANT_DEFAULT_PROVIDER=provider_name
export MOLECULE_PROVIDER=provider_name
export MOLECULE_BOX=box_name

This can be added to your environment for persistent configuration. For development, it’s recommended to work inside a virtual environment:

virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt
ansible-galaxy install -r requirements.yml

Build Ansible Galaxy Locally​

To build the collection locally, use the following command:

ansible-galaxy collection build --force

This will create the republic-infra-x.x.x.tar.gz file in the root of the project. You can then install the collection locally for testing:

ansible-galaxy collection install republic-infra-0.x.x.tar.gz --force

Documentation​

All new roles should have a corresponding documentation file under the root docs/ folder, named {{ role_name }}_role.md, where role_name is the name of your new role.

For example, a new role called new_thing should have a document called new_thing_role.md. This document should then be linked as the README.md in the role directory:

cd ./roles/new_role
ln -s ../../docs/new_role_role.md README.md

This ensures that documentation is always available directly within the role directory.

By using the republic.infra collection, you can easily manage essential system configurations and services across your infrastructure with reusable and well-tested roles. This collection aims to provide a solid foundation for system administrators and developers to streamline server setup and maintenance tasks.