progfiguration documentation

progfiguration is programatic configuration for your infrastructure. It’s infrastructure as code, but like, actual code.

Note

This project is currently extremely alpha. It’s subject to change, even more than most software. And, as we know, all change is loss. Rely on this project and imperil not just your infrastructure, but your emotional wellbeing.

Where other configuration management tools require learning a new abstraction on top of the configuration changes you want to make, progfiguration lets you just write Python to configure your infrastructure. It provides:

• A way to write code to configure your infrastructure.

• A simple standard library for functions like writing to files idempotently.

• Judicious use of dependencies: remote deployments typically use SSH, the default secret storage mechanism uses Age, and building/development use well supported third party Python libraries.

• A command-line interface for running your configuration.

• A nice package building experience that assembles your code into a single executable.

The whole point of progfiguration is that your configuration is just Python code. You can use any Python library you want, and you can use any Python code you want.

And you don’t have to fight the declarative model when all you want to do is set an intermediate value to a variable or write a loop.

Do you…

• …wish you could write a real program, even multiple lines, instead of toiling in the YAML mines?

• …hate running widely available stable software supported by well-funded corporations and large communities?

progfiguration is for you!

Availability

• Source code on GitHub at mrled/progfiguration.

• Releases on PyPI as progfiguration.

• Licensed under MIT.

• Written by Micah R Ledbetter.

Patches and bug reports are welcome! If you use progfiguration for your own infrastructure, I’d love to hear about it, and you’re welcome to add yourself to the list of users.

A guided tour of the documentation

Read Getting started first. It will walk you through installing progfiguration and building out your site, which is the directory (usually in a Git repository) that contains your inventory. When you’re exploring, you might be interested in some basic concepts, the command help reference, and the progfigsite API that lists your site package must implement. You might also want to read progfiguration for Ansible users, if you’re familiar with Ansible. See Why use progfiguration? for some scenarios that progfiguration was designed to handle well, and Progfiguration design to read about design principles and hypotheses.

Table of Contents

Contents:

• Getting started
  • Creating a New Progfiguration Site
  • Creating your first node
  • Creating your first role
  • Build and deploy
• User Reference
  • Important concepts
  • Why use progfiguration?
  • Commands
  • progfigsite packages
  • Example progfigsite packages
  • Packaging process
  • Versioning
• Developer Reference
  • Progfiguration design
  • Entrypoints
• Appendix
  • Real world progfigsites
  • To do
  • Changelog
  • progfiguration for Ansible users
  • Advanced topics
  • Experiments
  • Sphinx and progfiguration
  • pyproject.toml edge cases
• API Reference
  • example_site
  • progfiguration
  • nnss_progfigsite

Indices

• Module index, containing documentation for every Python module

• Complete index, containing a flat list of every function, variable, class, module, etc on a single page