A cross-repository OpenShift topology analysis tool. It reads one or more GitOps-managed OpenShift configuration and application repositories, synthesises a topology summary, and produces human-readable reports and draw.io architecture diagrams.
Audience: Platform engineers, SREs, and architects who manage OpenShift clusters via GitOps repositories and want a machine-generated view of what is deployed, where, by whom, and how it is exposed or secured.
- Repository Structure
- Module Map
- Prerequisites
- Installation
- High-Level Usage Flow
- Input Data Files
- Output Files
- Running the Tests
- Contributing
- Author
- License
ocp-topology-tool/
├── data/ # Static input data used to enrich the diagram
│ ├── external-services.json # External service definitions and data-flow connections
│ ├── user-access-profiles.json # Per-cluster user role/type definitions
│ └── oc_csv.out # Optional: raw 'oc get csv' output for runtime version injection
│
├── src/
│ └── ocp_topology_tool/ # Main Python package (see Module Map below)
│
├── tests/
│ └── test_apps_repo.py # Unit tests for apps repository parsing helpers
│
├── out/ # Generated output (gitignored; contents accumulate at runtime)
│
├── pyproject.toml # Package metadata, build config, and CLI entry point
├── README.md # This file
├── USER_DOCS.md # Step-by-step guide for first-time users
└── LICENSE # Creative Commons BY-NC-SA 4.0
| File | Purpose |
|---|---|
pyproject.toml |
Declares the ocp-topology CLI entry point and Python ≥ 3.11 requirement. No external runtime dependencies. |
data/external-services.json |
Defines external provider swimlanes (e.g. AWS, GitHub) and the data-flow arrows that connect them to clusters in the draw.io diagram. |
data/user-access-profiles.json |
Maps user roles and access types (privileged / non-privileged) to clusters so the diagram can render user-stack annotations. |
data/oc_csv.out |
Optional snapshot of oc get csv -A output used to inject live operator version strings into the diagram. |
out/ |
Runtime output directory. Topology JSON summaries, draw.io XML files, encryption reports, and network reports are written here. No source-controlled content should be placed here. |
All source code lives under src/ocp_topology_tool/.
| Module | Purpose |
|---|---|
__init__.py |
Package initialiser; declares the package description. |
__main__.py |
Entry point for python -m ocp_topology_tool; delegates immediately to cli.main(). |
cli.py |
Argument parsing (build_parser), cluster filtering helpers, and the main() orchestration function that calls all report builders. |
models.py |
Core dataclasses: ApplicationRef, ClusterTopology, and TopologySummary. |
apps_repo.py |
Parses the apps GitOps repository: discovers cluster directories, reads kustomization resource lists, extracts Argo CD Application manifests, and normalises application names. |
config_repo.py |
Parses the config GitOps repository: builds indexed lookups for operator families, namespaces, subscription versions, overlay-to-cluster mappings, and RBAC group bindings. |
topology.py |
Synthesises a TopologySummary from the apps repo, config repo, and any optional supplementary repos (nerc-k8s-operators, mss-keycloak). Handles namespace inference from kustomize files. |
drawio.py |
Generates draw.io XML from a TopologySummary. Implements the swimlane layout engine, colour scheme, legend, ingress-chain rendering, external-service overlays, and user-stack annotations. Also produces the version mapping report. |
encryption_report.py |
Scans config repo YAML files for TLS Route, Service CA, Service Mesh, and cert-manager evidence; produces a per-component encryption coverage report. |
network_report.py |
Scans config repo YAML files for OpenShift Route and NetworkPolicy resources; produces a per-component exposure and isolation report. |
- Python 3.11 or later
- The following GitOps repositories cloned locally (see USER_DOCS.md for detail):
- A config repo structured like
nerc-ocp-config(cluster-scope overlays, operator subscriptions, RBAC bindings) - An apps repo structured like
nerc-ocp-apps(per-cluster kustomization files and Argo CD Application manifests)
- A config repo structured like
- (Optional) A k8s-operators repo structured like
nerc-k8s-operatorsfor additional shift-cluster operator coverage - (Optional) An mss-keycloak repo for Keycloak/client application coverage
- (Optional) draw.io desktop or app.diagrams.net to view generated
.drawiofiles
The tool has zero external runtime Python dependencies — only the standard library is used.
# Clone the repository
git clone https://github.com/<your-org>/ocp-topology-tool.git
cd ocp-topology-tool
# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install the package in editable mode
pip install -e .After installation the ocp-topology command is available on PATH. You can also invoke the tool directly without installation:
PYTHONPATH=src python3 -m ocp_topology_tool [options]config repo ─────┐
apps repo ────────┤
k8s-operators ───┤──► topology.build_topology_summary()
mss-keycloak ────┘ │
▼
TopologySummary (JSON)
│
┌──────────────┼──────────────┐
▼ ▼ ▼
drawio.py encryption_report network_report
(diagram) (TLS evidence) (route/netpol)
build_topology_summary()reads all input repositories and produces aTopologySummaryJSON file.- Optional reports (draw.io diagram, encryption report, network report, version report) are generated from that summary.
- All outputs are written to the
out/directory by default.
See USER_DOCS.md for concrete CLI commands and option descriptions.
Defines external provider swimlanes rendered above the data-centre boundary in the draw.io diagram, and the directed data-flow arrows that connect them to clusters or components. Each entry in services carries display geometry and colour; each entry in flows references source and target nodes by a ref string. See USER_DOCS.md for the schema.
Maps user roles (e.g. SysAdmin, Developer, Student, Researcher) and access types (privileged or non-privileged) to the clusters they access. Privileged user stacks are rendered to the left of external services in the diagram; non-privileged stacks to the right.
A plain-text snapshot of oc get csv -A captured from a live cluster. When supplied via --csv-versions, the tool parses operator package names and version strings from this file and overlays them on diagram nodes. The file is not required for a valid run.
All outputs land in the directory specified by --out (JSON summary) and --drawio-out (diagram). The tool auto-increments output filenames (e.g. topology-1.json, topology-2.json) when a file is already open or exists, so repeated runs do not silently overwrite previous results.
| File pattern | Produced by flag | Description |
|---|---|---|
topology-summary.json |
--out |
Full machine-readable topology summary |
topology.drawio |
--drawio-out |
draw.io architecture diagram |
encryption-report.json |
--encryption-report-out |
TLS/cert evidence per component |
network-report.json |
--network-report-out |
Route/NetworkPolicy evidence per component |
version-mapping-report.json |
--version-report-out |
Operator version resolution details |
unmatched-versions.txt |
--unmatched-versions-out |
Names that could not be version-matched |
cd ocp-topology-tool
source .venv/bin/activate
PYTHONPATH=src pytest -qTests live in tests/. The current suite covers the apps repository parsing helpers.
- Fork the repository and create a feature branch.
- Keep changes focused on scope — this tool intentionally has no external runtime dependencies; please don't add any.
- Add or update tests in
tests/for any logic changes in theapps_repoortopologymodules. - Run
PYTHONPATH=src pytest -qbefore submitting a pull request. - Open a pull request with a clear description of what changes and why.
Bug reports and feature requests are welcome via GitHub Issues.
Scott Yockel — scott.yockel@gmail.com
This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) license.
You are free to share and adapt this material for non-commercial purposes, provided you give appropriate credit, indicate if changes were made, and distribute any derivative works under the same license.
See the LICENSE file for the full license text, or visit:
https://creativecommons.org/licenses/by-nc-sa/4.0/
© 2026 Scott Yockel