Operations grimoire/Operations repository/FAQ

General Questions

What is the rOPS repository?

rOPS (repository OPS) is the Nasqueron operations repository. It contains the configuration of our infrastructure servers and follows the principle of Infrastructure as Code to offer documentation, reproducibility, transparency and to allow external contributions.

The repository is available at https://devcentral.nasqueron.org/diffusion/OPS/

What does this repository contain?

The repository contains:

• Server configuration
• Deployment information for our applications and services

Combined with NetBox, it constitutes an exhaustive inventory and source of truth for our infrastructure.

What technology does Nasqueron use for infrastructure management?

We mainly rely on Salt (SaltStack) for deployment and automation. The repository also includes utilities for humans and Terraform provisioning.

What is the minimum Salt version required?

The minimum Salt version is 3006.

What servers are in scope for this repository?

Both Nasqueron servers and side projects we manage are in scope. For example, the Eglide service is configured through roles/core (common to every server) and roles/shellserver (specific).

Repository Structure

How is the repository organized?

The repository is organized into seven main areas:

A. Services

Configuration organized in roles and units

B. Structured data

Pillar data for configuration

C. SaltStack modules

Python modules for complex logic

D. UNIX resources assignments

UIDs, GIDs, and port assignments

E. Tests

Unit and integration tests

F. Resources

Templates and resources for automated tasks

G. Utilities

Scripts for operations team members

What are roles and units?

Roles are full high-level services (e.g., mailserver, paas-docker). They represent the goal a server accomplishes.

Units are components needed to achieve the service's goals (e.g., a userland software collection, a nginx server).

Directory structure follows roles/<role>/<unit>.

What are states and formulas?

States (also called formulas) are the configuration files in the roles/ directory. They are generally written in YAML with Jinja2 templating.

The top.sls file defines which states are loaded by server, while the services.sls describes service configurations that aren't server-specific.

What is pillar?

Pillar is structured data stored in the pillar/ directory. This data is structured cleanly and queried from states, directly or through functions. Each pillar .sls file is written in YAML.

The top.sls file defines which pillar files are loaded by server, while the tower.sls file acts similarly and allows more flexibility.

What is the map.jinja file for?

The map.jinja file provides "Omni-OS" configuration. Since we deploy onto several Linux distributions (Debian, Rocky) and FreeBSD, we need to provide a way to map packages and directories across different operating systems.

Where are configuration files stored?

If configuration files for a unit should be stored, a subfolder files/ is created at unit level within the role/unit structure.

What are SaltStack modules?

While states offer powerful templating capabilities, they can become too complex when evolving from declarations to full programs. Salt modules express more complex logic in Python. The Python functions can be called directly from states.

Modules are stored in:

• _modules/ for execution modules
• _states/ for states modules

What is the hotfixes directory for?

If anything escapes the role and unit logic organization, like CVE hotfixes, the hotfixes/ directory is used.

Where are UIDs, GIDs, and ports documented?

This repository is the source of truth for service accounts, groups and ports:

• UIDs document unique usernames and the UIDs for system accounts
• GIDs document the same information for groups
• PORTS contain the list of reserved application ports

When a service needs any of those resources, they are assigned in those files.

How do I test my changes?

Unit and integration tests are stored in _tests/

You can test the correctness of several repository aspects:

• Salt configuration files in _tests/config/
• Salt execution modules in _tests/modules/
• Salt pillar in _tests/pillar/
• Scripts deployed within this repository in _tests/scripts/

If you add a new directory, you should add a corresponding entry in Makefile.

What are resources and utilities?

Resources (_resources/) are used by automated tasks to generate repository files, such as templates for new services.

Utilities (utils/) are scripts and other utilities to be run by Nasqueron Operations SIG members.

Contributing

How can I contribute?

Contributions are welcome, especially if you wish to:

1. Improve our infrastructure
2. Install or configure something on a Nasqueron server
3. Install or configure something on a project we manage (like Eglide)
4. Automate deployment of one of your Nasqueron projects

Follow the contributor guide to send a commit for review. This procedure is open to everyone.

Where can I report issues?

Issues can be reported on the #Servers component on DevCentral, the Nasqueron Phabricator instance.

Where can I find more documentation?

Documentation about the repository and tips for IDEs are available on Agora: https://agora.nasqueron.org/Operations_grimoire/Operations_repository

Where can I get help?

Support for contributors is provided on our IRC channel: #nasqueron-ops on Libera.

Terminology

What terminology does Nasqueron use?

The repository uses inclusive terminology:

Salt primary server

A server that issues commands to other servers or itself

Node

A server, baremetal or VM configured by Salt

Nasqueron follows the inclusive language conventions to ensure that our community is welcoming to everyone.

Why doesn't the repository use master/slave terminology?

Nasqueron follows inclusive language conventions. Instead of "master," we use "Salt primary server" to describe the server that issues commands.

Licensing

What is the license for this repository?

A lot of configuration as code is trivial, and so ineligible for copyright per threshold of originality.

When this is not the case, the code is licensed under BSD-2-Clause if not otherwise specified.

Getting Started

I'm new to the repository. Where should I start?

1. Read this FAQ and the main README
2. Check the Operations grimoire for detailed documentation
3. Join our IRC channel #nasqueron-ops on Libera for support
4. Browse the roles/ directory to see how services are structured
5. Look at existing commits on DevCentral to understand the contribution workflow

What background knowledge do I need?

Helpful knowledge includes:

• YAML syntax
• SaltStack basics
• Jinja2 templating
• Python (for writing modules)
• UNIX / Linux system administration

However, you can start contributing with basic YAML knowledge and learn as you go!