Skip to content
Karakoram

Apache-2.0 · Self-hosted

Self-hosted MongoDB orchestration for Zerops.

Karakoram provisions and operates Percona Server for MongoDB and Percona Backup for MongoDB inside your own Zerops project: a Go control plane with a REST API, the karactl CLI and a web UI. No Kubernetes, no hosted coordinator.

Read the docsInstall on ZeropsView on GitHub

What it is, and what it is not

Karakoram is

  • A control plane you run in your own Zerops project, with your own token.
  • A coordinator for Percona's PSMDB and PBM: replica sets, sharded clusters, backups, point-in-time recovery, restores.
  • Yours to operate. You own the infrastructure, credentials, data and recovery procedures. Zerops is the infrastructure backend, not the operator of your databases.

Karakoram is not

  • A managed or hosted service. Nobody runs it for you.
  • A Kubernetes operator. It talks to the Zerops REST API directly.
  • A guarantee of physical-host anti-affinity or independent failure domains. Healthy voters do not prove that.
  • Highly available itself: the control plane has one replica and Local Storage is single-host.

Read the limitations before production use

What it operates

Each capability maps to a user-guide page that describes exactly what is supported.

  • Replica sets

    1, 3, 5 or 7 members, initial-sync-aware scaling and replacement, quorum-aware removal, retained-volume suspend and resume.

  • Sharded clusters

    Config-server and shard replica sets, mongos routers, shard addition and balancer controls.

  • Backups, PITR, restore and clone

    S3-compatible PBM logical and physical backups, UTC schedules with count retention, point-in-time recovery, in-place restore and clone.

  • Resources and rolling upgrades

    CPU and RAM configuration, persistent disk growth, rolling binary upgrades and restarts, explicit FCV promotion.

  • Users, TLS and access

    Database users and roles, independently rotatable system accounts, keyfile authentication, generated or supplied TLS certificates, opt-in public TCP access.

  • Monitoring, auth and RBAC

    Per-member monitoring, authenticated Prometheus output, events and logs, local accounts, OIDC, RBAC and owner-scoped API tokens.

    See also RBAC and authentication

REST APIGenerated, strict HTTP contract; every authenticated operation carries explicit authorization metadata.karactl CLIGenerated client for the same API, with saved connection contexts.Web UIEmbedded React SPA served by the control plane.

How it runs

Everything lives in your Zerops project

Karakoram deployment topology on ZeropsInside your Zerops project: the karakoram control-plane service with its karakoramdata Local Storage volume holding SQLite state, a mongos router service for sharded clusters, and database member services that each run mongod, a node agent and a PBM agent on their own Local Storage volume. Browsers and karactl reach the control plane over HTTPS; the control plane calls the Zerops REST API with a project-scoped token and talks to agents over TLS. PBM agents write backups to S3-compatible object storage outside the members.Browser · karactlweb UI, REST API, CLIZerops REST APIservices, volumes, routingYour Zerops projectkarakoramcontrol plane · web UI · APIkarakoramdata · SQLite statemongos routersharded clusters · no data volumeagent TLS · MongoDB wire protocolmemberUbuntu runtime · mongodnode agent · PBM agentLocal Storage volumememberUbuntu runtime · mongodnode agent · PBM agentLocal Storage volumememberUbuntu runtime · mongodnode agent · PBM agentLocal Storage volumeHTTPSproject-scoped tokenPBM backups · PITR oplogS3-compatible object storageoutside the members, per-cluster prefixes
Control plane
One karakoram runtime service with a karakoramdata Local Storage volume for its SQLite state. Browsers and karactl reach it over HTTPS; it provisions services through the Zerops REST API with a project-scoped token.
Database members
One Ubuntu runtime per mongod, including config servers, each with its own Local Storage volume. A node agent supervises mongod and the PBM agent and talks to the control plane over TLS with pinned trust roots.
Routers
A stateless mongos service per sharded cluster, with no data volume.
Backups
PBM agents write logical and physical backups and the PITR oplog to S3-compatible object storage outside the members.

Architecture and trust boundaries

Quick start

Import into an existing Zerops project

The import below creates the control plane service and its volume. You need an existing project and a project-scoped Full access integration token.

deploy/zerops/import.yaml
#yamlPreprocessor=on
# SPDX-License-Identifier: Apache-2.0
# Copyright 2026 The Karakoram Authors
# Set buildFromGit to your fork's public URL when deploying a fork.
# To deploy a local checkout, use import-local.yaml and install.sh.
services:
  - hostname: karakoramdata
    type: local-storage:single@1
    verticalAutoscaling:
      minDisk: 5
      maxDisk: 5
  - hostname: karakoram
    type: ubuntu@24.04
    minContainers: 1
    maxContainers: 1
    enableSubdomainAccess: true
    buildFromGit: https://github.com/KarakoramDev/Karakoram
    zeropsSetup: karakoram
    envSecrets:
      KARAKORAM_MASTER_KEY: <@generateRandomString(<48>)>
      KARAKORAM_ADMIN_PASSWORD: <@generateRandomString(<24>)>
      # Replace before import, or set in the service GUI and restart after import.
      # Zerops reserves ZEROPS_* for system variables.
      KARAKORAM_ZEROPS_TOKEN: ""
    verticalAutoscaling:
      cpuMode: SHARED
      minCpu: 1
      maxCpu: 1
      minRam: 0.5
      maxRam: 1
      minDisk: 1
      maxDisk: 2
  1. Import the services. In your project's dashboard choose Import services and paste the YAML, or run zcli project service-import import.yaml -P "$PROJECT_ID".
  2. Set the token. On the karakoram service, set the secret KARAKORAM_ZEROPS_TOKEN to your project-scoped Full access integration token. Never commit it. Keep the generated KARAKORAM_MASTER_KEY andKARAKORAM_ADMIN_PASSWORD.
  3. Wait for build and deploy. The Git build and deploy processes must finish; the import response alone is not enough. If the token was empty at import, set it and restart or redeploy.
  4. Sign in. Open the service's HTTPS subdomain, sign in as admin with the generated KARAKORAM_ADMIN_PASSWORD, change the password, then sign in again.

Full installation guideCovers prerequisites, secret handling, installing from a local checkout with zcli, custom domains and CLI login.

Built on Percona's work, inspired by OpenEverest

Percona

Thank you to Percona for Percona Server for MongoDB andPercona Backup for MongoDB. Karakoram installs both from Percona's official package repositories at repo.percona.com. The database engine, replication, backups and point-in-time recovery come from their open-source work; Karakoram coordinates those capabilities rather than reinventing them.

OpenEverest

OpenEverest is the inspiration for this project. Originally Percona Everest, it is an Apache-2.0 CNCF Sandbox project whose model of self-hosted, provider-based database orchestration shaped Karakoram: Provider and Instance concepts, version bundles, topology schemas, backup storages, PITR and restore flows, and RBAC. Karakoram brings that idea to Zerops rather than Kubernetes. It is an independent implementation; no OpenEverest code or UI is copied.

The name

Everest is the highest peak. Karakoram is the range that holds K2 and other giants.

The name is a nod to OpenEverest and to growing beyond a single peak, with room for more engines and backends in the future. That is a direction, not a claim that they exist today: only the PSMDB provider and the Zerops backend are implemented.

Contributions are welcome

Open an issue first for anything beyond a small fix, keep each pull request to one logical change, and sign off every commit under the Developer Certificate of Origin (git commit -s). A human submits every contribution.