openstack-janitor

A CLI that audits an OpenStack cloud for orphaned and wasteful resources.

Status: early development. Seven detectors and a clean command are working — see Detectors and Cleaning; more detectors and safety rails are coming — see Roadmap.

Install

Requires Python 3.9+. On older interpreters, pip automatically selects a compatible older version of openstacksdk.

From PyPI:

pipx install openstack-janitor   # recommended for CLI use
# or
pip install openstack-janitor

Standalone Linux binary — no Python needed at all. Built against glibc 2.28, so it runs on RHEL 8-era hosts whose system Python is too old for the package:

curl -LO https://github.com/mabunemeh/openstack-janitor/releases/latest/download/janitor-linux-x86_64
chmod +x janitor-linux-x86_64
./janitor-linux-x86_64 audit --cloud my-cloud

From source:

git clone https://github.com/mabunemeh/openstack-janitor
cd openstack-janitor
pip install -e .

Old distro pip (e.g. Ubuntu 22.04's pip 22.0): source installs can fail with No module named 'packaging.licenses' — the distro-patched pip leaks the system's old packaging into the build environment. Installing from PyPI is unaffected. For source installs, use a fresh venv with an upgraded pip: python3 -m venv .venv && .venv/bin/pip install -U pip.

Usage

janitor detectors
janitor audit
janitor audit -c my-cloud
janitor audit -d unattached-volumes -d orphaned-ports
janitor audit -f json > findings.json
janitor audit -f html > report.html

Short options: -c / --cloud, -d / --detector, -f / --format, -h / --help.

janitor detectors lists every registered detector (name and description) without connecting to a cloud. Use the names it prints with audit --detector.

--format table (the default) prints a rich table; json and html write machine-readable / shareable reports to stdout.

Example output when orphaned volumes are found:

$ janitor audit --cloud my-cloud
              openstack-janitor findings
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Type          ┃ ID        ┃ Name    ┃ Project ┃ Reason                       ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ volume        │ a1b2c3d4… │ old-db  │ proj-1  │ volume is unattached         │
│               │           │         │         │ (status=available)           │
└───────────────┴───────────┴─────────┴─────────┴──────────────────────────────┘
$ echo $?
1

janitor audit exits 0 when nothing is found, 1 when findings were reported (so it's safe to wire into a cron job or CI check), 2 if an unknown --detector name is given, and 3 if connecting to the cloud fails.

Cleaning

janitor clean -d unattached-volumes                   # dry run: preview only, deletes nothing
janitor clean -d unattached-volumes --yes             # delete what that detector flags
janitor clean -d unattached-volumes -e vol-0001 --yes # keep specific resource IDs

janitor clean is dry run by default — it re-runs the detectors and shows what it would delete, but touches nothing. Pass --yes to actually delete. Deletes are real and irreversible: once a volume, snapshot, floating IP, port, security group, instance, or image is gone, it is gone.

--detector is required. clean refuses to act on every detector at once, so a single command can never delete across all seven resource types.

Read this before using --yes:

• Some detectors have no age threshold. orphaned-ports and unused-security-groups flag by state alone, so a port or group created seconds ago — mid-provisioning, mid-CI-run — is a finding and will be deleted. Until tag/age rails land, keep --detector narrow.
• The preview does not bind the execution. Dry run and --yes are two independent detection passes. A resource created in between is deleted without ever having appeared in the table you reviewed.
• Cleaning can create new findings. Deleting a shutoff instance leaves its volumes unattached; deleting snapshots orphans the images built from them. The next run will flag those. Re-read each dry run rather than looping --yes blindly.
• --exclude takes resource IDs, not names. An --exclude value that matches no finding aborts the run rather than being ignored, so a typo cannot silently delete what it was meant to protect.
• Deletes are asynchronous. A successful call means the delete was accepted; verify with janitor audit afterwards.

Tag/age safety rails (e.g. a janitor:keep marker) are on the roadmap but not implemented yet.

janitor clean exits 0 on a successful dry run or execute, 1 if any resource was not deleted during --yes — either the deletion failed or the detector does not support cleaning (other resources are still processed; failures are isolated per resource) — 2 for a missing or unknown --detector or an --exclude ID that matched nothing, and 3 if connecting to the cloud or scanning it fails.

Detectors

Detection is always read-only — janitor audit never modifies anything. The same detectors also know how to delete what they flag, but only janitor clean --yes ever does so.

Resources without a parseable timestamp are never flagged by the age-based detectors. Note that orphaned-ports and unused-security-groups have no age threshold at all, so they can flag a resource created seconds ago — see the warning under Cleaning. Thresholds become configurable once janitor.toml support lands (see Roadmap).

Authentication

openstack-janitor uses openstacksdk for authentication, so anything openstacksdk understands works here too:

• A named cloud from clouds.yaml via --cloud my-cloud (or the OS_CLOUD environment variable).
• The standard OS_* environment variables (OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME, etc.) if no cloud is specified.

See the openstacksdk configuration documentation for the full resolution order and file locations.

Roadmap

• janitor.toml for per-cloud configuration (which detectors run, age thresholds, exclusions).
• Safety rails: a janitor:keep tag (or similar) so resources can be marked "do not touch" before clean ever deletes anything, beyond today's --exclude flag and dry-run review.