harmony/README.md

# Harmony

**Infrastructure orchestration that treats your platform like first-class code.**

Harmony is an open-source framework that brings the rigor of software engineering to infrastructure management. Write Rust code to define what you want, and Harmony handles the rest — from local development to production clusters.

_By [NationTech](https://nationtech.io)_

[![Build](https://git.nationtech.io/NationTech/harmony/actions/workflows/check.yml/badge.svg)](https://git.nationtech.io/NationTech/harmony)
[![License](https://img.shields.io/badge/license-AGPLv3-blue?style=flat-square)](LICENSE)

---

## The Problem Harmony Solves

Modern infrastructure is messy. Your Kubernetes cluster needs monitoring. Your bare-metal servers need provisioning. Your applications need deployments. Each comes with its own tooling, its own configuration format, and its own failure modes.

**What if you could describe your entire platform in one consistent language?**

That's Harmony. It unifies project scaffolding, infrastructure provisioning, application deployment, and day-2 operations into a single strongly-typed Rust codebase.

---

## Three Principles That Make the Difference

| Principle | What It Means |
|-----------|---------------|
| **Infrastructure as Resilient Code** | Stop fighting with YAML and bash. Write type-safe Rust that you can test, version, and refactor like any other code. |
| **Prove It Works Before You Deploy** | Harmony verifies at _compile time_ that your application can actually run on your target infrastructure. No more "the config looks right but it doesn't work" surprises. |
| **One Unified Model** | Software and infrastructure are one system. Deploy from laptop to production cluster without switching contexts or tools. |

---

## How It Works: The Core Concepts

Harmony is built around three concepts that work together:

### Score — "What You Want"

A `Score` is a declarative description of desired state. Think of it as a "recipe" that says _what_ you want without specifying _how_ to get there.

```rust
// "I want a PostgreSQL cluster running with default settings"
let postgres = PostgreSQLScore {
    config: PostgreSQLConfig {
        cluster_name: "harmony-postgres-example".to_string(),
        namespace: "harmony-postgres-example".to_string(),
        ..Default::default()
    },
};
```

### Topology — "Where It Goes"

A `Topology` represents your infrastructure environment and its capabilities. It answers the question: "What can this environment actually do?"

```rust
// Deploy to a local K3D cluster, or any Kubernetes cluster via environment variables
K8sAnywhereTopology::from_env()
```

### Interpret — "How It Happens"

An `Interpret` is the execution logic that connects your `Score` to your `Topology`. It translates "what you want" into "what the infrastructure does."

**The Compile-Time Check:** Before your code ever runs, Harmony verifies that your `Score` is compatible with your `Topology`. If your application needs a feature your infrastructure doesn't provide, you get a compile error — not a runtime failure.

---

## What You Can Deploy

Harmony ships with ready-made Scores for:

**Data Services**
- PostgreSQL clusters (via CloudNativePG operator)
- Multi-site PostgreSQL with failover

**Kubernetes**
- Namespaces, Deployments, Ingress
- Helm charts
- cert-manager for TLS
- Monitoring (Prometheus, alerting, ntfy)

**Bare Metal / Infrastructure**
- OKD clusters from scratch
- OPNsense firewalls
- Network services (DNS, DHCP, TFTP)
- Brocade switch configuration

**And more:** Application deployment, tenant management, load balancing, and more.

---

## Quick Start: Deploy a PostgreSQL Cluster

This example provisions a local Kubernetes cluster (K3D) and deploys a PostgreSQL cluster on it — no external infrastructure required.

```rust
use harmony::{
    inventory::Inventory,
    modules::postgresql::{PostgreSQLScore, capability::PostgreSQLConfig},
    topology::K8sAnywhereTopology,
};

#[tokio::main]
async fn main() {
    let postgres = PostgreSQLScore {
        config: PostgreSQLConfig {
            cluster_name: "harmony-postgres-example".to_string(),
            namespace: "harmony-postgres-example".to_string(),
            ..Default::default()
        },
    };

    harmony_cli::run(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(),
        vec![Box::new(postgres)],
        None,
    )
    .await
    .unwrap();
}
```

### What this actually does

When you compile and run this program:

1. **Compiles** the Harmony Score into an executable
2. **Connects** to `K8sAnywhereTopology` — which auto-provisions a local K3D cluster if none exists
3. **Installs** the CloudNativePG operator into the cluster (one-time setup)
4. **Creates** a PostgreSQL cluster with 1 instance and 1 GiB of storage
5. **Exposes** the PostgreSQL instance as a Kubernetes Service

### Prerequisites

- [Rust](https://rust-lang.org/tools/install) (edition 2024)
- [Docker](https://docs.docker.com/get-docker/) (for the local K3D cluster)
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (optional, for inspecting the cluster)

### Run it

```bash
# Clone the repository
git clone https://git.nationtech.io/nationtech/harmony
cd harmony

# Build the project
cargo build --release

# Run the example
cargo run -p example-postgresql
```

Harmony will print its progress as it sets up the cluster and deploys PostgreSQL. When complete, you can inspect the deployment:

```bash
kubectl get pods -n harmony-postgres-example
kubectl get secret -n harmony-postgres-example harmony-postgres-example-db-user -o jsonpath='{.data.password}' | base64 -d
```

To connect to the database, forward the port:
```bash
kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 5432:5432
psql -h localhost -p 5432 -U postgres
```

To clean up, delete the K3D cluster:
```bash
k3d cluster delete harmony-postgres-example
```

---

## Environment Variables

`K8sAnywhereTopology::from_env()` reads the following environment variables to determine where and how to connect:

| Variable | Default | Description |
|----------|---------|-------------|
| `KUBECONFIG` | `~/.kube/config` | Path to your kubeconfig file |
| `HARMONY_AUTOINSTALL` | `true` | Auto-provision a local K3D cluster if none found |
| `HARMONY_USE_LOCAL_K3D` | `true` | Always prefer local K3D over remote clusters |
| `HARMONY_PROFILE` | `dev` | Deployment profile: `dev`, `staging`, or `prod` |
| `HARMONY_K8S_CONTEXT` | _none_ | Use a specific kubeconfig context |
| `HARMONY_PUBLIC_DOMAIN` | _none_ | Public domain for ingress endpoints |

To connect to an existing Kubernetes cluster instead of provisioning K3D:

```bash
# Point to your kubeconfig
export KUBECONFIG=/path/to/your/kubeconfig
export HARMONY_USE_LOCAL_K3D=false
export HARMONY_AUTOINSTALL=false

# Then run
cargo run -p example-postgresql
```

---

## Documentation

| I want to... | Start here |
|--------------|------------|
| Understand the core concepts | [Core Concepts](./docs/concepts.md) |
| Deploy my first application | [Getting Started Guide](./docs/guides/getting-started.md) |
| Explore available components | [Scores Catalog](./docs/catalogs/scores.md) · [Topologies Catalog](./docs/catalogs/topologies.md) |
| See a complete bare-metal deployment | [OKD on Bare Metal](./docs/use-cases/okd-on-bare-metal.md) |
| Build my own Score or Topology | [Developer Guide](./docs/guides/developer-guide.md) |

---

## Why Rust?

We chose Rust for the same reason you might: **reliability through type safety**.

Infrastructure code runs in production. It needs to be correct. Rust's ownership model and type system let us build a framework where:

- Invalid configurations fail at compile time, not at 3 AM
- Refactoring infrastructure is as safe as refactoring application code
- The compiler verifies that your platform can actually fulfill your requirements

See [ADR-001 · Why Rust](./adr/001-rust.md) for our full rationale.

---

## Architecture Decisions

Harmony's design is documented through Architecture Decision Records (ADRs):

- [ADR-001 · Why Rust](./adr/001-rust.md)
- [ADR-003 · Infrastructure Abstractions](./adr/003-infrastructure-abstractions.md)
- [ADR-006 · Secret Management](./adr/006-secret-management.md)
- [ADR-011 · Multi-Tenant Cluster](./adr/011-multi-tenant-cluster.md)

---

## License

Harmony is released under the **GNU AGPL v3**.

> We choose a strong copyleft license to ensure the project—and every improvement to it—remains open and benefits the entire community.

See [LICENSE](LICENSE) for the full text.

---

_Made with ❤️ & 🦀 by NationTech and the Harmony community_