Jean-Gabriel Gill-Couture
6554ac5341
- Fixed network topology diagram in pair README: 192.168.10.x -> 192.168.1.x to match the actual code (OPNsense boots on .1 of 192.168.1.0/24) - Added explanation of NIC juggling to the diagram section - Updated single-VM "What's next" to link to pair example (was "in progress") - Added opnsense_pair_integration to examples/README.md table and category
132 lines
6.4 KiB
Markdown
132 lines
6.4 KiB
Markdown
# Examples
|
|
|
|
This directory contains runnable examples demonstrating Harmony's capabilities. Each example is a self-contained program that can be run with `cargo run -p example-<name>`.
|
|
|
|
## Quick Reference
|
|
|
|
| Example | Description | Local K3D | Existing Cluster | Hardware Needed |
|
|
|---------|-------------|:---------:|:----------------:|:---------------:|
|
|
| `postgresql` | Deploy a PostgreSQL cluster | ✅ | ✅ | — |
|
|
| `ntfy` | Deploy ntfy notification server | ✅ | ✅ | — |
|
|
| `tenant` | Create a multi-tenant namespace | ✅ | ✅ | — |
|
|
| `cert_manager` | Provision TLS certificates | ✅ | ✅ | — |
|
|
| `node_health` | Check Kubernetes node health | ✅ | ✅ | — |
|
|
| `monitoring` | Deploy Prometheus alerting | ✅ | ✅ | — |
|
|
| `monitoring_with_tenant` | Monitoring + tenant isolation | ✅ | ✅ | — |
|
|
| `operatorhub_catalog` | Install OperatorHub catalog | ✅ | ✅ | — |
|
|
| `validate_ceph_cluster_health` | Verify Ceph cluster health | — | ✅ | Rook/Ceph |
|
|
| `remove_rook_osd` | Remove a Rook OSD | — | ✅ | Rook/Ceph |
|
|
| `brocade_snmp_server` | Configure Brocade switch SNMP | — | ✅ | Brocade switch |
|
|
| `opnsense_node_exporter` | Node exporter on OPNsense | — | ✅ | OPNsense firewall |
|
|
| `opnsense_vm_integration` | Full OPNsense firewall automation (11 Scores) | ✅ | — | KVM/libvirt |
|
|
| `opnsense_pair_integration` | OPNsense HA pair with CARP failover | ✅ | — | KVM/libvirt |
|
|
| `okd_pxe` | PXE boot configuration for OKD | — | — | ✅ |
|
|
| `okd_installation` | Full OKD bare-metal install | — | — | ✅ |
|
|
| `okd_cluster_alerts` | OKD cluster monitoring alerts | — | ✅ | OKD cluster |
|
|
| `multisite_postgres` | Multi-site PostgreSQL failover | — | ✅ | Multi-cluster |
|
|
| `nats` | Deploy NATS messaging | — | ✅ | Multi-cluster |
|
|
| `nats-supercluster` | NATS supercluster across sites | — | ✅ | Multi-cluster |
|
|
| `lamp` | LAMP stack deployment | ✅ | ✅ | — |
|
|
| `openbao` | Deploy OpenBao vault | ✅ | ✅ | — |
|
|
| `zitadel` | Deploy Zitadel identity provider | ✅ | ✅ | — |
|
|
| `try_rust_webapp` | Rust webapp with packaging | ✅ | ✅ | Submodule |
|
|
| `rust` | Rust webapp with full monitoring | ✅ | ✅ | — |
|
|
| `rhob_application_monitoring` | RHOB monitoring setup | ✅ | ✅ | — |
|
|
| `sttest` | Full OKD stack test | — | — | ✅ |
|
|
| `application_monitoring_with_tenant` | App monitoring + tenant | — | ✅ | OKD cluster |
|
|
| `kube-rs` | Direct kube-rs client usage | ✅ | ✅ | — |
|
|
| `k8s_drain_node` | Drain a Kubernetes node | ✅ | ✅ | — |
|
|
| `k8s_write_file_on_node` | Write files to K8s nodes | ✅ | ✅ | — |
|
|
| `harmony_inventory_builder` | Discover hosts via subnet scan | ✅ | — | — |
|
|
| `cli` | CLI tool with inventory discovery | ✅ | — | — |
|
|
| `tui` | Terminal UI demonstration | ✅ | — | — |
|
|
|
|
## Status Legend
|
|
|
|
| Symbol | Meaning |
|
|
|--------|---------|
|
|
| ✅ | Works out-of-the-box |
|
|
| — | Not applicable or requires specific setup |
|
|
|
|
## By Category
|
|
|
|
### Data Services
|
|
- **`postgresql`** — Deploy a PostgreSQL cluster via CloudNativePG
|
|
- **`multisite_postgres`** — Multi-site PostgreSQL with failover
|
|
- **`public_postgres`** — Public-facing PostgreSQL (⚠️ uses NationTech DNS)
|
|
|
|
### Kubernetes Utilities
|
|
- **`node_health`** — Check node health in a cluster
|
|
- **`k8s_drain_node`** — Drain and reboot a node
|
|
- **`k8s_write_file_on_node`** — Write files to nodes
|
|
- **`validate_ceph_cluster_health`** — Verify Ceph/Rook cluster health
|
|
- **`remove_rook_osd`** — Remove an OSD from Rook/Ceph
|
|
- **`kube-rs`** — Direct Kubernetes client usage demo
|
|
|
|
### Monitoring & Alerting
|
|
- **`monitoring`** — Deploy Prometheus alerting with Discord webhooks
|
|
- **`monitoring_with_tenant`** — Monitoring with tenant isolation
|
|
- **`ntfy`** — Deploy ntfy notification server
|
|
- **`okd_cluster_alerts`** — OKD-specific cluster alerts
|
|
|
|
### Application Deployment
|
|
- **`try_rust_webapp`** — Deploy a Rust webapp with packaging (⚠️ requires `tryrust.org` submodule)
|
|
- **`rust`** — Rust webapp with full monitoring features
|
|
- **`rhob_application_monitoring`** — Red Hat Observability Stack monitoring
|
|
- **`lamp`** — LAMP stack deployment (⚠️ uses NationTech DNS)
|
|
- **`application_monitoring_with_tenant`** — App monitoring with tenant isolation
|
|
|
|
### Infrastructure & Bare Metal
|
|
- **`opnsense_vm_integration`** — **Recommended demo.** Boot an OPNsense VM and configure it with 11 Scores (load balancer, DHCP, TFTP, VLANs, firewall rules, NAT, VIPs, LAGG). Fully automated, requires only KVM. See the [detailed guide](../docs/use-cases/opnsense-vm-integration.md).
|
|
- **`opnsense_pair_integration`** — Boot two OPNsense VMs and configure a CARP HA firewall pair with `FirewallPairTopology` and `CarpVipScore`. Demonstrates NIC link control for sequential bootstrap.
|
|
- **`okd_installation`** — Full OKD cluster from scratch
|
|
- **`okd_pxe`** — PXE boot configuration for OKD
|
|
- **`sttest`** — Full OKD stack test with specific hardware
|
|
- **`brocade_snmp_server`** — Configure Brocade switch via SNMP
|
|
- **`opnsense_node_exporter`** — Node exporter on OPNsense firewall
|
|
|
|
### Multi-Cluster
|
|
- **`nats`** — NATS deployment on a cluster
|
|
- **`nats-supercluster`** — NATS supercluster across multiple sites
|
|
- **`multisite_postgres`** — PostgreSQL with multi-site failover
|
|
|
|
### Identity & Secrets
|
|
- **`openbao`** — Deploy OpenBao vault (⚠️ uses NationTech DNS)
|
|
- **`zitadel`** — Deploy Zitadel identity provider (⚠️ uses NationTech DNS)
|
|
|
|
### Cluster Services
|
|
- **`cert_manager`** — Provision TLS certificates
|
|
- **`tenant`** — Create a multi-tenant namespace
|
|
- **`operatorhub_catalog`** — Install OperatorHub catalog sources
|
|
|
|
### Development & Testing
|
|
- **`cli`** — CLI tool with inventory discovery
|
|
- **`tui`** — Terminal UI demonstration
|
|
- **`harmony_inventory_builder`** — Host discovery via subnet scan
|
|
|
|
## Running Examples
|
|
|
|
```bash
|
|
# Build first
|
|
cargo build --release
|
|
|
|
# Run any example
|
|
cargo run -p example-postgresql
|
|
cargo run -p example-ntfy
|
|
cargo run -p example-tenant
|
|
```
|
|
|
|
For examples that need an existing Kubernetes cluster:
|
|
|
|
```bash
|
|
export KUBECONFIG=/path/to/your/kubeconfig
|
|
export HARMONY_USE_LOCAL_K3D=false
|
|
export HARMONY_AUTOINSTALL=false
|
|
|
|
cargo run -p example-monitoring
|
|
```
|
|
|
|
## Notes on Private Infrastructure
|
|
|
|
Some examples use NationTech-hosted infrastructure by default (DNS domains like `*.nationtech.io`, `*.harmony.mcd`). These are not suitable for public use without modification. See the [Getting Started Guide](../docs/guides/getting-started.md) for the recommended public examples.
|