harmony/docs/guides/getting-started.md

Getting Started Guide

This guide walks you through deploying your first application with Harmony — a PostgreSQL cluster on a local Kubernetes cluster (K3D). By the end, you'll understand the core workflow: compile a Score, run it through the Harmony CLI, and verify the result.

What you'll deploy

A fully functional PostgreSQL cluster running in a local K3D cluster, managed by the CloudNativePG operator. This demonstrates the full Harmony pattern:

1. Provision a local Kubernetes cluster (K3D)
2. Install the required operator (CloudNativePG)
3. Create a PostgreSQL cluster
4. Expose it as a Kubernetes Service

Prerequisites

Before you begin, install the following tools:

• Rust & Cargo: Install Rust (edition 2024)
• Docker: Install Docker (required for the local K3D cluster)
• kubectl: Install kubectl (optional, for inspecting the cluster)

Step 1: Clone and build

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

# Build the project (this may take a few minutes on first run)
cargo build --release

Step 2: Run the PostgreSQL example

cargo run -p example-postgresql

Harmony will output its progress as it:

1. Creates a K3D cluster named harmony-postgres-example (first run only)
2. Installs the CloudNativePG operator into the cluster
3. Creates a PostgreSQL cluster with 1 instance and 1 GiB of storage
4. Prints connection details for your new database

Expected output (abbreviated):

[+] Cluster created
[+] Installing CloudNativePG operator
[+] Creating PostgreSQL cluster
[+] PostgreSQL cluster is ready
    Namespace: harmony-postgres-example
    Service: harmony-postgres-example-rw
    Username: postgres
    Password: <stored in secret harmony-postgres-example-db-user>

Step 3: Verify the deployment

Check that the PostgreSQL pods are running:

kubectl get pods -n harmony-postgres-example

You should see something like:

NAME                                    READY   STATUS    RESTARTS   AGE
harmony-postgres-example-1              1/1     Running   0          2m

Get the database password:

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

Step 4: Connect to the database

Forward the PostgreSQL port to your local machine:

kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 5432:5432

In another terminal, connect with psql:

psql -h localhost -p 5432 -U postgres
# Enter the password from Step 4 when prompted

Try a simple query:

SELECT version();

Step 5: Clean up

To delete the PostgreSQL cluster and the local K3D cluster:

k3d cluster delete harmony-postgres-example

Alternatively, just delete the PostgreSQL cluster without removing K3D:

kubectl delete namespace harmony-postgres-example

How it works

The example code (examples/postgresql/src/main.rs) is straightforward:

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();
}

• Inventory::autoload() discovers the local environment (or uses an existing inventory)
• K8sAnywhereTopology::from_env() connects to K3D if HARMONY_AUTOINSTALL=true (the default), or to any Kubernetes cluster via KUBECONFIG
• harmony_cli::run(...) executes the Score against the Topology, managing the full lifecycle

Connecting to an existing cluster

By default, Harmony provisions a local K3D cluster. To use an existing Kubernetes cluster instead:

export KUBECONFIG=/path/to/your/kubeconfig
export HARMONY_USE_LOCAL_K3D=false
export HARMONY_AUTOINSTALL=false

cargo run -p example-postgresql

Troubleshooting

Docker is not running

Error: could not create cluster: docker is not running

Start Docker and try again.

K3D cluster creation fails

Error: failed to create k3d cluster

Ensure you have at least 2 CPU cores and 4 GiB of RAM available for Docker.

kubectl cannot connect to the cluster

error: unable to connect to a kubernetes cluster

After Harmony creates the cluster, it writes the kubeconfig to ~/.kube/config or to the path in KUBECONFIG. Verify:

kubectl cluster-info --context k3d-harmony-postgres-example

Port forward fails

error: unable to forward port

Make sure no other process is using port 5432, or use a different local port:

kubectl port-forward -n harmony-postgres-example svc/harmony-postgres-example-rw 15432:5432
psql -h localhost -p 15432 -U postgres

Next steps

• Explore the Scores Catalog: See what other Scores are available
• Explore the Topologies Catalog: See what infrastructure Topologies are supported
• Read the Core Concepts: Understand the Score / Topology / Interpret pattern in depth
• OKD on Bare Metal: See a complete bare-metal deployment example

Advanced examples

Once you're comfortable with the basics, these examples demonstrate more advanced use cases. Note that some require specific infrastructure (existing Kubernetes clusters, bare-metal hardware, or multi-cluster environments):

Example	Description	Prerequisites
monitoring	Deploy Prometheus alerting with Discord webhooks	Existing K8s cluster
ntfy	Deploy ntfy notification server	Existing K8s cluster
tenant	Create a multi-tenant namespace with quotas	Existing K8s cluster
cert_manager	Provision TLS certificates	Existing K8s cluster
validate_ceph_cluster_health	Check Ceph cluster health	Existing Rook/Ceph cluster
okd_pxe / okd_installation	Provision OKD on bare metal	HAClusterTopology, bare-metal hardware

To run any example:

cargo run -p example-<example_name>