# theforeman/foremanctl architecture

> Architecture diagram of the GitHub repository theforeman/foremanctl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theforeman/foremanctl
- Repository: https://github.com/theforeman/foremanctl

## Overview

foremanctl is a production CLI for deploying and managing Foreman/Katello as Podman Quadlet services under systemd, with Ansible playbooks executed through Obsah. Its principal workflow is an operator invoking the CLI, which runs deployment automation to configure the services. The repository also provides operational playbooks for checks, health, backup/restore, migration, and proxy deployment, plus feature metadata and Ansible extensions. The README establishes the CLI-to-playbook relationship; sampled source shows filter and migration behavior, but not their callers or the internal playbook orchestration, so those links are omitted.

Main entry points: [`foremanctl`](https://github.com/theforeman/foremanctl/blob/master/foremanctl) (foremanctl CLI), [`src/playbooks/deploy/deploy.yaml`](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/deploy/deploy.yaml) (Deployment playbooks), [`forge`](https://github.com/theforeman/foremanctl/blob/master/forge) (forge CLI), [`src/plugins/modules/foremanctl_announce_to_sources.py`](https://github.com/theforeman/foremanctl/blob/master/src/plugins/modules/foremanctl_announce_to_sources.py) (Sources registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_foremanctl["foremanctl CLI"]
  node_forge["forge CLI"]
end

subgraph group_orchestration["Deployment orchestration"]
  node_playbooks["Deployment playbooks<br/>[deploy.yaml]"]
  node_features["Feature metadata<br/>[features.yaml]"]
  node_roles["Service roles"]
  node_proxy["Proxy deployment<br/>[deploy-proxy.yaml]"]
end

subgraph group_operations["Operations"]
  node_checks["Preflight checks<br/>[checks.yaml]"]
  node_health["Health checks<br/>[health.yaml]"]
  node_backup["Backup<br/>[backup.yaml]"]
  node_restore["Restore<br/>[restore.yaml]"]
  node_migration["Migration<br/>[migrate.yaml]"]
  node_image_pull["Pull images<br/>[pull-images.yaml]"]
  node_auth_bundle["Auth bundles<br/>[auth-bundle.yaml]"]
end

subgraph group_extensions["Ansible extensions"]
  node_feature_filters["Feature filters<br/>[foremanctl.py]"]
  node_answer_migration["Answer migration<br/>[migrate_answers.py]"]
  node_callback["Output callback<br/>[foremanctl.py]"]
  node_sources_module["Sources registration"]
end

node_operator(("Operator"))
node_podman["Podman Quadlets"]
node_systemd["systemd"]
node_foreman_api["Foreman API"]

node_operator -->|"invokes"| node_foremanctl
node_foremanctl -->|"runs playbooks"| node_playbooks
node_playbooks -.->|"configures services"| node_podman
node_podman -->|"generates units"| node_systemd
node_foremanctl -.->|"manages proxy"| node_proxy
node_foremanctl -.->|"runs checks"| node_checks
node_foremanctl -.->|"runs checks"| node_health
node_foremanctl -.->|"runs playbooks"| node_backup
node_foremanctl -.->|"runs playbooks"| node_restore
node_foremanctl -.->|"runs playbooks"| node_migration
node_foremanctl -.->|"runs playbooks"| node_image_pull
node_foremanctl -.->|"runs playbooks"| node_auth_bundle
node_sources_module -->|"calls API"| node_foreman_api
node_forge -->|"supports development"| node_operator

click node_foremanctl "https://github.com/theforeman/foremanctl/blob/master/foremanctl"
click node_playbooks "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/deploy/deploy.yaml"
click node_features "https://github.com/theforeman/foremanctl/blob/master/src/features.yaml"
click node_roles "https://github.com/theforeman/foremanctl/tree/master/src/roles"
click node_proxy "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/deploy-proxy/deploy-proxy.yaml"
click node_checks "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/checks/checks.yaml"
click node_health "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/health/health.yaml"
click node_backup "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/backup/backup.yaml"
click node_restore "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/restore/restore.yaml"
click node_migration "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/migrate/migrate.yaml"
click node_image_pull "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/pull-images/pull-images.yaml"
click node_auth_bundle "https://github.com/theforeman/foremanctl/blob/master/src/playbooks/auth-bundle/auth-bundle.yaml"
click node_feature_filters "https://github.com/theforeman/foremanctl/blob/master/src/filter_plugins/foremanctl.py"
click node_answer_migration "https://github.com/theforeman/foremanctl/blob/master/src/plugins/modules/migrate_answers.py"
click node_callback "https://github.com/theforeman/foremanctl/blob/master/src/callback_plugins/foremanctl.py"
click node_sources_module "https://github.com/theforeman/foremanctl/blob/master/src/plugins/modules/foremanctl_announce_to_sources.py"
click node_forge "https://github.com/theforeman/foremanctl/blob/master/forge"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_foremanctl,node_forge toneBlue
class node_playbooks,node_features,node_roles,node_proxy toneAmber
class node_checks,node_health,node_backup,node_restore,node_migration,node_image_pull,node_auth_bundle,node_foreman_api toneMint
class node_feature_filters,node_answer_migration,node_callback,node_sources_module toneRose
class node_operator,node_podman,node_systemd toneIndigo
```

## Components

### Entry points

- [foremanctl CLI](https://github.com/theforeman/foremanctl/blob/master/foremanctl): `foremanctl`
- [forge CLI](https://github.com/theforeman/foremanctl/blob/master/forge): `forge`

### Deployment orchestration

- [Deployment playbooks](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/deploy/deploy.yaml): `src/playbooks/deploy/deploy.yaml`
- [Feature metadata](https://github.com/theforeman/foremanctl/blob/master/src/features.yaml): `src/features.yaml`
- [Service roles](https://github.com/theforeman/foremanctl/tree/master/src/roles): `src/roles`
- [Proxy deployment](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/deploy-proxy/deploy-proxy.yaml): `src/playbooks/deploy-proxy/deploy-proxy.yaml`

### Operations

- [Preflight checks](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/checks/checks.yaml): `src/playbooks/checks/checks.yaml`
- [Health checks](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/health/health.yaml): `src/playbooks/health/health.yaml`
- [Backup](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/backup/backup.yaml): `src/playbooks/backup/backup.yaml`
- [Restore](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/restore/restore.yaml): `src/playbooks/restore/restore.yaml`
- [Migration](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/migrate/migrate.yaml): `src/playbooks/migrate/migrate.yaml`
- [Pull images](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/pull-images/pull-images.yaml): `src/playbooks/pull-images/pull-images.yaml`
- [Auth bundles](https://github.com/theforeman/foremanctl/blob/master/src/playbooks/auth-bundle/auth-bundle.yaml): `src/playbooks/auth-bundle/auth-bundle.yaml`

### Ansible extensions

- [Feature filters](https://github.com/theforeman/foremanctl/blob/master/src/filter_plugins/foremanctl.py): `src/filter_plugins/foremanctl.py`
- [Answer migration](https://github.com/theforeman/foremanctl/blob/master/src/plugins/modules/migrate_answers.py): `src/plugins/modules/migrate_answers.py`
- [Output callback](https://github.com/theforeman/foremanctl/blob/master/src/callback_plugins/foremanctl.py): `src/callback_plugins/foremanctl.py`
- [Sources registration](https://github.com/theforeman/foremanctl/blob/master/src/plugins/modules/foremanctl_announce_to_sources.py): `src/plugins/modules/foremanctl_announce_to_sources.py`

### Other components

- **Operator**
- **Podman Quadlets**
- **systemd**
- **Foreman API**

## Connections

- Operator → foremanctl CLI: invokes (evidence: `README.md`)
- foremanctl CLI → Deployment playbooks: runs playbooks (evidence: `README.md`)
- Deployment playbooks → Podman Quadlets: configures services
- Podman Quadlets → systemd: generates units (evidence: `README.md`)
- foremanctl CLI → Proxy deployment: manages proxy
- foremanctl CLI → Preflight checks: runs checks
- foremanctl CLI → Health checks: runs checks
- foremanctl CLI → Backup: runs playbooks
- foremanctl CLI → Restore: runs playbooks
- foremanctl CLI → Migration: runs playbooks
- foremanctl CLI → Pull images: runs playbooks
- foremanctl CLI → Auth bundles: runs playbooks
- Sources registration → Foreman API: calls API (evidence: `src/plugins/modules/foremanctl_announce_to_sources.py`)
- forge CLI → Operator: supports development (evidence: `README.md`)