Harmony

Open Infrastructure Orchestration for Enterprise

Harmony is an open-source orchestrator designed to unify the entire software lifecycle within a single, coherent codebase. It seamlessly integrates project creation, infrastructure provisioning, and application deployment across all your environments—from a local mini-cluster to a full-scale production setup.

Built on the principles of Infrastructure as Code (IaC) and Platform Engineering, Harmony leverages the full power of a real programming language (Rust) to provide a robust, type-safe, and unified developer experience.

The Harmony Philosophy

Infrastructure is a requirement for nearly all software, but it isn't your core business. It's ours. Harmony provides an expert-designed foundation for your applications, allowing you to focus on the features that matter to your customers.

Principle 1: Infrastructure as Resilient Code, Not Fragile Configuration.

• The Problem: Traditional infrastructure is managed with static files (like YAML) and brittle scripts. These are error-prone, hard to test, and don't scale with complexity.
• The Harmony Way: We treat infrastructure with the same seriousness as application code. By using a powerful, type-safe programming language (Rust), we define infrastructure as living code that can be tested, reused, and reasoned about, making it fundamentally more robust.

Principle 2: From "Hope It Works" to "Prove It Works".

• The Problem: With conventional tools, you only discover if a deployment plan is valid when you run it—often in a staging or production environment.
• The Harmony Way: We believe correctness should be a guarantee, not a hope. Harmony uses the compiler to prove that your application's needs are compatible with your infrastructure's capabilities before deployment. This eliminates entire classes of configuration errors at the earliest possible stage.

Principle 3: A Unified Model for a Unified Reality.

• The Problem: In reality, software and infrastructure are a single, interdependent system. Yet, we manage them with separate, disjointed tools, creating a gap where errors and inconsistencies thrive.
• The Harmony Way: We model the system as it truly is: a single entity. Harmony creates a unified codebase where application and infrastructure logic live together, enabling deep integration and holistic management of your entire platform, from bare-metal hardware to the final application.

If you like metaphors, see this one : cyborg-metaphor

Quick Start: Deploying a Full LAMP Stack

The following example demonstrates how to define and deploy a complete, production-grade LAMP stack. Harmony will handle everything: setting up a local Kubernetes cluster, building a containerized PHP application, deploying a MariaDB database, and configuring monitoring.

main.rs

use harmony::{
    data::Version,
    inventory::Inventory,
    maestro::Maestro,
    modules::{
        lamp::{LAMPConfig, LAMPScore},
        monitoring::monitoring_alerting::MonitoringAlertingStackScore,
    },
    topology::{K8sAnywhereTopology, Url},
};

#[tokio::main]
async fn main() {
    // This here is the whole configuration to:
    // - Setup a local K3D cluster (if not already running)
    // - Build a docker image with the PHP project and production-grade settings
    // - Deploy a MariaDB database using a production-grade Helm chart
    // - Deploy the new container using a Kubernetes Deployment
    // - Configure networking between the PHP container and the database
    // - Provision a public route and an SSL certificate automatically on production environments
    //
    // Enjoy :)
    let lamp_stack = LAMPScore {
        name: "harmony-lamp-demo".to_string(),
        domain: Url::Url(url::Url::parse("https://lampdemo.harmony.nationtech.io").unwrap()),
        php_version: Version::from("8.4.4").unwrap(),
        // This config can be extended as needed for more complicated configurations
        config: LAMPConfig {
            project_root: "./php".into(),
            database_size: "4Gi".into(),
            ..Default::default()
        },
    };

    // You can choose the type of Topology you want. We suggest starting with the
    // K8sAnywhereTopology, as it is the most automatic one. It enables you to easily deploy
    // locally, to a development environment from a CI, to staging, and to production
    // with settings that automatically adapt to each environment grade.
    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(),
    )
    .await
    .unwrap();

    // Attach additional features like a full monitoring and alerting stack
    let mut monitoring_stack_score = MonitoringAlertingStackScore::new();
    monitoring_stack_score.namespace = Some(lamp_stack.config.namespace.clone());

    maestro.register_all(vec![Box::new(lamp_stack), Box::new(monitoring_stack_score)]);

    // Here we bootstrap the CLI, which provides useful interactive features.
    harmony_cli::init(maestro, None).await.unwrap();
}

// That's it. The end of your Infrastructure as Code.

Running the Example

To launch the orchestrator, simply run the project:

cargo run

This will start Harmony, which will analyze the code, determine the required state, and apply the necessary changes to match your definition. It will present you with an interactive TUI to review and approve the execution plan.

Core Concepts

Harmony is built around a few key architectural concepts:

• Scores: A Score is a declarative, high-level definition of a resource or application you want to exist (e.g., LAMPScore, PostgresClusterScore). It defines what you want, not how to achieve it.
• Interprets: An Interpret contains the imperative logic that brings a Score to life. It's the "how" that translates the declarative goal into concrete actions, like running kubectl commands or calling a cloud provider API.
• Topology: A Topology defines where your infrastructure runs. It's an abstraction over your target environment, whether it's a local k3d cluster, a bare-metal server, or a public cloud provider. K8sAnywhereTopology is a powerful default that adapts to any Kubernetes environment.
• Maestro: The Maestro is the central orchestrator. It loads the inventory, initializes the Topology, and executes the Interprets for all registered Scores.

Contributing & Deeper Dive

Contributions are welcome! Whether it's improving the core, adding a new Score, or enhancing the documentation, we'd love to have your help.

For a deeper understanding of our design decisions, please see our Architectural Decision Records (ADRs):

• [ADR-001: Rust as the Primary Language]
• [ADR-003: Infrastructure Abstractions]
• [ADR-006: Secret Management]
• [ADR-011: Multi Tenant Cluster]
• ... and more in the /adr directory.

Detailed technical guides, such as how to extend Harmony to support new hardware (e.g., OPNsense), can be found in the /docs section of this repository.

License

This project is licensed under the AGLP License. See the LICENSE file for details.

Why AGPL ? Because we believe a strong copyleft license is what enables and empowers all use cases founded in good will, aiming at bringing forward our world towards a better place by leveraging humanity's greatest strenght : collaboration.

We are totally fine with companies forking harmony and beating us at our own game of creating the best infrastructure orchestration tool. But this has been built for the community and must stay open, so we're forcing copyleft terms upon this project to make sure they are not allowed to keep it just for them.