Features
Performance Infrastructure Flexibility Data Isolation Developer Experience
Docs
Overview Installation Custom Resource Monitoring Future Plans
FAQ
Get Started

Step-by-Step Installation

Table of Contents

🗂️ Create database topology config file

HariKube determines data locality using the object key structure and applies routing based on configurable policies, such as matching by resource type, namespace, key prefix, or custom resource definition.

Routing configurations are evaluated in order from top to bottom, and the first matching rule determines the data’s target database. Once a match is found, subsequent rules are ignored for that resource.

Routing policies must be carefully designed, as adding or changing a policy for resource types that already have stored data can result in the existing records becoming inaccessible. HariKube does not migrate previously stored resources to the new target automatically, so any change in routing may lead to apparent data loss unless handled manually.

topology.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

backends:
- endpoint: http://127.0.0.1:2579
  regexp:
    name: rbac
    prefix: (clusterrolebindings|clusterroles|rolebindings|roles|serviceaccounts)
    key: (clusterrolebindings|clusterroles|rolebindings|roles|serviceaccounts)
- endpoint: mysql://root:passwd@tcp(127.0.0.1:3306)/kube_system
  namespace:
    name: kube-system
    namespace: kube-system
- endpoint: postgres://postgres:passwd@127.0.0.1:5432/pods
  prefix:
    name: pods
    prefix: pods
- endpoint: sqlite://./db/shirts.db?_journal=WAL&cache=shared&_busy_timeout=30000&_txlock=immediate
  customresource:
    name: shirts
    group: stable.example.com
    kind: shirts

Routing Configuration Explained

  • ETCD with regular expression routing: Routes Kubernetes RBAC resources to an ETCD store.

  • MySQL endpoint with namespace matching: All objects in the kube-system namespace are routed to a MySQL backend.

    Only built-in core resource types are supported, for custom resource you have to create a separate policy.

  • PostgreSQL endpoint with prefix matching: All pods resources - except pods in kube-system namespace - are routed to a PostgreSQL backend.

  • SQLite endpoint for specific custom resources: Routes all resources of type shirts in the group stable.example.com to a lightweight embedded SQLite database.

  • Rest of the objects are stored in the default database.

Advanced Configuration Options

📘 Metadata Store Configuration

HariKube includes an internal metadata store that maintains mapping information about the underlying databases. It keeps track of which database is responsible for each data segment, ensuring consistency and fast lookups without querying every backend directly. The metadata store is central to HariKube’s ability to provide dynamic data placement, multi-database support, and high-performance routing across flat or hierarchical topologies. To configure metadata store you have to set environment variable(s) for the middleware. Default Metadata store is sqlite.

  • REVISION_MAPPER_HISTORY: Defines how long metadata revisions are retained in the system. After this period, older revisions are treated as compacted and are no longer accessible for historical lookups. This helps manage storage usage by limiting how long old revision data is preserved. If 0, the compaction is disabled. Default 4h
  • REVISION_MAPPER_CACHE_CAPACITY: Capacity of the in-memory cache. Default 10000, 1000000 for In-memory
  • REVISION_MAPPER_SKIP_VERIFY: Skip TLS verification. Default false

HariKube mappers are optimized for high-throughput environments, and some persist metadata asynchronously; in worst-case scenarios where metadata is lost, restarting services that rely on historical revisions will safely reinitialize a fresh revision history—allowing the system to continue operating, even if older state is no longer available.

🔌 Start Middleware

Images are not public, please ask for registry user via info@inspirnation.eu.

1
2
3
4
5
6
7

docker run -d \
  -e TOPOLOGY_CONFIG=/topology.yaml \
  -v $(pwd)/topology.yaml:/topology.yaml \
  -v harikube_db:/db \
  -p 2379:2379 \
  registry.mhmxs.duckdns.org/harikube/middleware:beta-v1.0.0 \
  --listen-address=0.0.0.0:2379 --endpoint=multi://http://<default.database.server:2379>

Mounting of harikube_db volume isn’t mandatory, if all databases and the metada store are pointing to external target.

🚀 Setup and start Kubernetes

Kubernetes Configuration

HariKube requires specific Kubernetes configuration to enable custom resource routing and external data store integration

MandatoryCategoryOptionDescription
✅Feature GateCustomResourceFieldSelectors=trueEnables CR field selectors
✅Feature GateWatchList=trueEnables watch list support
✅Feature GateWatchListClient=trueEnables watch list client feature
✅API Server Flag--encryption-provider-config=""Encryption not supported
✅API Server Flag--storage-media-type=application/jsonSets storage format to JSON
✅API Server Flag--watch-cache=falseDisables watch cache (recommended for large data)
✅API Server Flag--etcd-servers=http(s)://middleware.service:2379Sets the middleware as the ETCD backend
➖API Server Flag--max-mutating-requests-inflight=400Increases concurrency for mutating requests
➖API Server Flag--max-requests-inflight=800Increases concurrency for all requests

Kubernetes is compatible with HariKube by default. However, due to architectural constraints in ETCD—its underlying storage system—it is not optimized for handling very large datasets. To enable support for high-volume data workloads, modifications to specific Kubernetes components (such as the API server) are required.

You can use our pre-built images, pre-built versions are:

  • v1.32 [amd64, arm64, ppc64le, s390x]
    • v1.32.0, v1.32.1, v1.32.2, v1.32.3
1
2

docker pull registry.mhmxs.duckdns.org/harikube/kube-apiserver-amd64:v1.32.0
docker pull registry.mhmxs.duckdns.org/harikube/kube-controller-manager-amd64:v1.32.0

Comipiling Kubernetes From Source Code (optional)

For detailed information about how to build Kubernetes please follow official documentation. But here are some simple steps to compile it.

1
2
3

git clone https://github.com/kubernetes/kubernetes.git
cd kubernetes
git checkout v1.32.0

Download kubernetes-v1.32.0.patch and apply.

1

git apply kubernetes-v1.32.0.patch

Building Options

<– Overview | Custom Resource –>