Skip to main content

Infrable

Infrable is a simple Infrastructure and Configuration as Code tool written in Python. It lets you manage hosts, services, configuration, deployments, and more — all from a single Python file named infra.py.

PyPI version

  1. Prerequisites
  2. Installation and Project Setup
  3. Defining Hosts and Services
  4. Working with Templates
  5. Deploying and Recovering Files
    1. Deploy Workflow
    2. Recover Workflow
  6. Running Remote Commands, Tasks, and Workflows
    1. Running Remote Commands
    2. Creating Tasks
    3. Creating Workflows
  7. Using Environments and Switches
  8. Managing Meta and Secrets
  9. Extending Infrable with Custom Modules
  10. Security Model and Limitations

Prerequisites

  • Python 3.12 or newer, on Linux or macOS (Windows is not supported)
  • The ssh client, and key-based access to your hosts
  • Passwordless sudo for the admin user on the managed hosts
  • Basic Python, Jinja2 and Shell scripting knowledge

Installation and Project Setup

Install Infrable:

pip install -U infrable

Bootstrap a New Project:

infrable init

This command creates the basic project structure you’ll need.


Defining Hosts and Services

In Infrable, you describe your infrastructure in a single file (named infra.py). Here you define all your hosts and the services running on them.

Example infra.py:

from infrable import Host, Service

# Define your hosts
dev_host = Host(fqdn="dev.example.com", ip="127.0.0.1")
beta_host = Host(fqdn="beta.example.com", ip="127.0.0.1")
prod_host = Host(fqdn="prod.example.com", ip="127.0.0.1")

# Define services on the hosts
dev_web = Service(host=dev_host, port=8080)
beta_web = Service(host=beta_host, port=8080)
prod_web = Service(host=prod_host, port=8080)

dev_nginx = Service(host=dev_host, port=80)
beta_nginx = Service(host=beta_host, port=80)
prod_nginx = Service(host=prod_host, port=80)

View your hosts and services:

infrable hosts
infrable services

Working with Templates

Templates let you manage configuration files dynamically. You write these using Jinja2 syntax and include metadata (like file paths and permissions) as header comments.

Add a template prefix in infra.py:

template_prefix = "https://github.com/username/repository/blob/main"

Example: Nginx configuration template (templates/nginx/web.j2):

# ---
# src: {{ template_prefix }}/{{ _template.src }}
# dest:
#   - {{ dev_nginx.host }}:/etc/nginx/sites-enabled/web
#   - {{ beta_nginx.host }}:/etc/nginx/sites-enabled/web
#   - {{ prod_nginx.host }}:/etc/nginx/sites-enabled/web
# chmod: 644
# chown: root:root
# ---

server {
    listen {{ dev_nginx.port }};
    listen [::]:{{ dev_nginx.port }};

    server_name {{ dev_nginx.host.fqdn }} www.{{ dev_nginx.host.fqdn }};

    location / {
        proxy_pass http://127.0.0.1:{{ dev_web.port }};
        include proxy_params;
    }

    location /robots.txt {
        root /var/www/html;
    }
}

Notes:

  • The template_prefix and *_nginx variables are defined in infra.py.
  • The _template.src variable is automatically available in all templates.
  • The dest metadata field specifies the target path on the host.
  • The chmod and chown metadata fields set file permissions and ownership.
  • There are other metadata fields you can use, like execute and skip.
  • You can also declare multiple destinations with different chmod, chown values and context variables using yaml list syntax.

Example: A template script with destination as list (templates/nginx/robots.txt.sh.j2):

#!/usr/bin/env bash

# ---
# src: {{ template_prefix }}/{{ _template.src }}
# dest:
#   - loc: {{ dev_nginx.host }}:/root/init/robots.txt.sh
#     ctx:
#       disallow: "/"
#   - loc: {{ beta_nginx.host }}:/root/init/robots.txt.sh
#     ctx:
#       disallow: "/"
#   - loc: {{ prod_nginx.host }}:/root/init/robots.txt.sh
#     ctx:
#       disallow: ""
# execute: true
# ---

set -euxo pipefail

if [ ! -d /var/www/html ]; then
    mkdir -p /var/www/html
fi

chown root:www-data /var/www/html

cat > /var/www/html/robots.txt <<EOF
User-agent: *
Disallow: {{ disallow }}
EOF

chown root:www-data /var/www/html/robots.txt

Deploying and Recovering Files

Before pushing configuration changes, Infrable compares your new files with those currently deployed. This helps you catch unintended changes. It also keeps a backup of the current configuration, so you can roll back if needed.

Deploy Workflow

Deploy your files:

infrable files deploy [path]

## Same as
# infrable files gen [path]
# infrable files pull
# infrable files backup
# infrable files push

This command performs several steps:

  • Generates new files from your templates.
  • Pulls the current files from the server.
  • Backs up the current configuration.
  • Compares the new and old versions.
  • Prompts you to push changes if differences are found.

You can run the same workflow in Python:

import infrable.files

infrable.files.deploy(path)

## Same as
# infrable.files.gen(path)
# infrable.files.pull()
# infrable.files.backup()
# infrable.files.push()

A simplified flowchart of the process:

flowchart TD;
    A[Generate new files] --> B[Pull current files];
    B --> C[Backup current files];
    C --> D[Compare new vs. current];
    D --> E{Differences?};
    E -- Yes --> F[Show diff & confirm push];
    E -- No --> G[Clean up temporary files];
    F --> H[Push changes];

Recover Workflow

If you need to roll back changes, use the recover workflow:

infrable files recover [path]

## Same as
# infrable files revert [path]
# infrable files push

Or in Python:

import infrable.files

infrable.files.recover(path)

## Same as
# infrable.files.revert(path)
# infrable.files.push()

Running Remote Commands, Tasks, and Workflows

Infrable allows you to execute commands remotely on your defined hosts.

Running Remote Commands

Run a command on a specific host:

infrable remote dev_host "sudo systemctl reload nginx"

Run on a service:

infrable remote dev_nginx "sudo systemctl reload nginx"

Run on all hosts affected by a file change:

infrable remote affected-hosts "sudo systemctl reload nginx"

Or combine with file diff:

infrable files affected-hosts | infrable remote - "sudo systemctl reload nginx"

Creating Tasks

Tasks are groups of commands that simplify repeated actions. Define them in infra.py.

Example Task:

import typer

# Add a task group for the dev_nginx service
dev_nginx.typer = typer.Typer(help="Tasks for dev_nginx.")


@dev_nginx.typer.command(name="reload")
def reload_dev_nginx():
    """Test configuration and reload the Nginx service."""

    assert dev_nginx.host, "Service must have a host to reload"

    # Run: sudo nginx -t
    dev_nginx.host.remote().sudo.nginx("-t")

    # Run: sudo systemctl reload nginx
    dev_nginx.host.remote().sudo.systemctl.reload.nginx()

Run the task:

infrable dev-nginx reload

Creating Workflows

Workflows let you combine tasks into a complete deployment process.

Example Workflow:

from infrable import files, concurrentcontext, paths, retryable

deploy = typer.Typer(help="Deployment workflows.")


@deploy.command(name="dev-nginx")
def deploy_dev_nginx():
    """Deploy dev_nginx configuration."""

    # Deploy the Nginx configuration files
    files.deploy(paths.templates / "nginx")

    # Test the Nginx configuration and reload the service concurrently
    cmd = "sudo nginx -t && sudo systemctl reload nginx && echo success || echo failed"
    fn = lambda host: (host, host.remote().sudo(cmd))
    with concurrentcontext(retryable(fn), files.affected_hosts()) as results:
        for host, result in results:
            print(f"{host}: {result}")

Run the workflow:

infrable deploy dev-nginx

Using Environments and Switches

Environments (like dev, beta, prod) let you use the same templates and tasks for different deployment targets.

Define environments and a switch in infra.py:

from infrable import Switch, Host, Service

# Define environment names
dev = "dev"
beta = "beta"
prod = "prod"
environments = {dev, beta, prod}

# Create a switch for environments (default is dev)
env = Switch(environments, init=dev)
current_env = env()

# Define hosts for each environment
dev_host = Host(fqdn="dev.example.com", ip="127.0.0.1")
beta_host = Host(fqdn="beta.example.com", ip="127.0.0.2")
prod_host = Host(fqdn="prod.example.com", ip="127.0.0.3")

# Use the switch to select hosts based on environment
managed_hosts = env(
    dev=[dev_host],
    beta=[beta_host],
    prod=[prod_host],
)

# Define a service using a strict switch to choose the host
web = Service(
    host=env.strict(
        dev=dev_host,
        beta=beta_host,
        prod=prod_host,
    ),
    port=8080,
)

Update Templates to Use Environment-Specific Values:

For example, in templates/nginx/proxy_params.j2:

# ---
# src: {{ template_prefix }}/{{ _template.src }}
# dest:
# {% for host in managed_hosts %}
#   - {{ host }}:/etc/nginx/proxy_params
# {% endfor %}
# chmod: 644
# chown: root:root
# ---
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

Note: Yes, you can use loops in template headers!

Managing the Environment Switch:

# Switch to a specific environment
infrable switch env [dev|beta|prod]

# Check the current environment
infrable switch env

# List available environments
infrable switch env --options

# Shortcut alias (if switch is named "env")
infrable env [dev|beta|prod]

# List all switches
infrable switches

Managing Meta and Secrets

Keep sensitive information (like secret keys) out of your version control by storing them in separate files inside an git-ignored directory.

printf '%s\n' /secrets/ /.infrable/ >> .gitignore

Example in infra.py:

from infrable import Meta, readfile

# Read a secret key from a file
common_secret_key = readfile("secrets/common/secret_key")

# Or declare a group of secrets
secrets = Meta(
    secret_key=readfile("secrets/common/secret_key"),
    db_password=readfile("secrets/common/db_password"),
    api_token=readfile("secrets/common/api_token"),
)

# Attach secret metadata to a service
web = Service(
    meta=Meta(secret_key=common_secret_key),
    host=env(dev=dev_host, beta=beta_host, prod=prod_host),
    port=8080,
)

Extending Infrable with Custom Modules

You can add custom Python modules to extend Infrable’s functionality.

Example module (modules/mycloud.py):

from dataclasses import dataclass
from typer import Typer
from infrable import Host, infra


@dataclass
class MyCloud:
    """Custom module for MyCloud operations."""

    secret_api_key: str
    typer: Typer | None = None

    def provision_ubuntu_host(self, fqdn: str):
        ip = self.api.create_ubuntu_host(fqdn)
        return MyCloudUbuntuHost(fqdn=fqdn, ip=ip)


@dataclass
class MyCloudUbuntuHost(Host):
    """Customized Ubuntu host for MyCloud."""

    def setup(self):
        self.install_mycloud_agent()

    def install_mycloud_agent(self):
        raise NotImplementedError


workflows = Typer()


@workflows.command()
def provision_ubuntu_host(fqdn: str, setup: bool = True):
    """Provision an Ubuntu host."""

    # Get the MyCloud instance from infra.py
    cloud = next(iter(infra.item_types[MyCloud].values()))
    host = cloud.provision_ubuntu_host(fqdn)
    if setup:
        host.setup()
    name = fqdn.split(".")[0].replace("-", "_")

    print("Add the host to the infra.py file.")
    print(f"{name} = {repr(host)}")

Plug the module into your infra.py:

from modules import mycloud

# Integrate the custom module with Infrable
cloud = mycloud.MyCloud(secret_api_key=readfile("secrets/mycloud/secret_api_key"))
cloud.typer = mycloud.workflows

Run the module workflow:

infrable cloud --help

Security Model and Limitations

Infrable pushes files to your servers and runs commands there as root, so read this before using it on anything important.

  • infra.py is code, and it is executed. Every infrable command imports infra.py (and the modules/ it uses) from the current directory. Only run Infrable in directories you trust, just like you would with a Makefile or fabfile.py. Templates are code too: they're rendered with full access to your infra.py, and a template with execute: true is run as root on the host.
  • SSH host keys. Infrable uses StrictHostKeyChecking=accept-new: a host's key is trusted on first use, and a changed key is refused. To verify keys yourself beforehand, set INFRABLE_STRICT_HOST_KEY_CHECKING=yes (other accepted values are ask, no, off and accept-new). Don't use no or off on untrusted networks.
  • Remote writes. Files are streamed over SSH into a private temporary file created with mktemp, given their chown/chmod (644 unless you set one), and then moved into place with sudo. Set chmod explicitly for anything sensitive.
  • Retries. Only SSH connection failures are retried (up to 5 attempts). A command or script that fails on the host is not run again. The retryable helper you can use in your own workflows retries on any error, so only wrap idempotent code with it.
  • Local state. .infrable/ and the files created by readfile are readable by the owner only, but they're plaintext. Keep them out of version control and out of backups that you don't trust.
  • Format strings. The --format option renders a Jinja template in a sandbox, but you should still treat it as input from the person running the command.
  • Other limitations. IPv6 addresses can't be used as the host part of a template's dest (host:/path), as the first : is the separator. Use an FQDN or a host name.

Found a vulnerability? See SECURITY.md.

Metadata

Release files for infrable 0.1.51

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for infrable 0.1.51
File Size Uploaded Provenance Actions
infrable-0.1.51.tar.gz 128.1 kB Without provenance Details for infrable-0.1.51.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for infrable 0.1.51
File Interpreter ABI Platform Actions
infrable-0.1.51-py3-none-any.whl Python 3 none any Details for infrable-0.1.51-py3-none-any.whl

Total release size: 162.1 kB

Release files / infrable-0.1.51.tar.gz

Download URL infrable-0.1.51.tar.gz
Size 128.1 kB
Tags Source
SHA-256 checksum
How to use checksums
ab9b754cdec9fa53d285d4f7ad9b7a439b8337e272e161f925225b6dfb12fe97
BLAKE2b-256 checksum
How to use checksums
c2f6f1552e8daaadbe8317e5704a5f262e073c72d73ad1300842cb931d8e2edc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"NixOS","version":"26.05","id":"yarara","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / infrable-0.1.51-py3-none-any.whl

Download URL infrable-0.1.51-py3-none-any.whl
Size 34.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7fc08f76e63939e3efd7fbf93af263e6764caddf2cc1e38aa431c58276f98db4
BLAKE2b-256 checksum
How to use checksums
b4f269767bed72a8a21e798bb3db0a71782758b3ca65d026585afb10cd1cdc98
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"NixOS","version":"26.05","id":"yarara","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for infrable 0.1.51

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.51 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page