Skip to content

Installation

Everything you need to stand up IOLake — from a one-binary demo on a laptop to a production Kubernetes install.

Start here

Path Walkthrough Best for
🚀 Fastest demo quickstart.md One binary, <60 s to aws s3 ls
🐧 Bare-metal Linux linux.md Production servers, systemd, raw disks
🍏 macOS macos.md Dev laptops (AIO only — not a production target)
🐳 Docker docker.md The container image, CI, single-host appliances
☸ Kubernetes kubernetes.md Helm chart, Kind demo, StatefulSet layout

Platform support: Linux (amd64, arm64), natively and in containers, and macOS for development. Releases publish iolake-aio for Linux amd64 and arm64 and macOS arm64; Intel Macs build from source. IOLake is POSIX-only; there is no native Windows build.

Deeper references

  • hardware-sizing.md — from a capacity and throughput requirement to a bill of quantities, with a calculator.
  • topologies.md — single-node vs rack-aware vs multi-DC; how many disks, nodes, and meta replicas you need for a given EC profile.
  • deployment-options.md — the detailed version: worked scenarios (1, 3, 6+ nodes), EC vs replication, configuration examples, capacity planning.
  • configuration.md — authoritative flag / env / TOML reference for every binary.

Minimum requirements

For a production cluster, size from the requirement with Hardware design and sizing and its calculator. To run IOLake at all:

Component Minimum Production
CPU 2 cores sizing: about one core per drive, plus the gateway's share
RAM 4 GB sizing: about 1.5 GB per drive, plus 8 GB
Disk 1 × any block device or file NVMe with power-loss protection, one OSD per drive
Network 1 Gbps sizing: two ports per host, 25 GbE or faster
Linux kernel 4.19+ 5.15+ (io_uring)
macOS 12+ — (AIO dev only)
Docker 24+ Buildx enabled for multi-arch
Kubernetes 1.26+ With a WaitForFirstConsumer StorageClass

Cluster sizing at a glance

EC profile Min OSDs Recommended OSDs Meta replicas Survives
4+2 6 7 (+1 spare) 3 2 disk / node failures
8+4 12 14 3 or 5 4 failures
LRC 10+2+2 14 15 5 2 failures; more by where they fall; one lost shard repaired from its group
replication=3 3 5 3 2 failures (3× overhead)

Meta is a Raft cluster: use 1 pod for dev, 3 for prod, 5 for larger / geo-distributed clusters. Always odd.

Default ports (cluster convention)

Port Service Reachable from
9000 Gateway — S3, Iceberg REST, Delta Sharing, /_console/, /_admin/ clients
9100 Meta gRPC + Raft RPC meta, OSDs, gateways, block gateways
9101 Meta Prometheus /metrics IOLake's nodes, monitoring
9102 Meta admin (Raft bootstrap / membership, /status, the probes /health and /ready; HTTPS under mTLS) the Raft bootstrap (Helm Job, iolake-install cluster init), operators, kubelet
9200 OSD gRPC meta, gateways, block gateways
9201 OSD Prometheus /metrics IOLake's nodes, monitoring
9300 Block gateway gRPC (volume admin) operators (iolakectl volume, snapshot)
9301 Block gateway Prometheus /metrics monitoring
10809 Block gateway NBD target the machines that attach volumes, nothing else

Every port but 9000 is internal. Without mTLS nothing on them is authenticated: anyone who reaches meta's gRPC port can read every user's secret key, anyone who reaches an OSD's can overwrite or delete shards, and anyone who reaches 9102 can add a Raft member and be sent the whole metadata log. Run without mTLS only on a network that IOLake's own nodes alone can reach. NBD (10809) has no authentication even with mTLS: it must be reachable only from the machines that attach volumes.

See configuration.md for the code defaults (which differ for meta and OSD) and how to override them.

Security checklist (production)

  • [ ] TLS terminated in front of the gateway (ingress / LB / reverse-proxy).
  • [ ] Authentication enabled (--no-auth not set).
  • [ ] OIDC configured for the console + Iceberg JWTs, if applicable.
  • [ ] SSE master key present (gateway.sse.enabled: true in Helm).
  • [ ] mTLS between the services (tls.enabled in Helm), with a certificate per role.
  • [ ] Firewall / NetworkPolicy keeping every internal port to the peers in the table above: 9100, 9101, 9102, 9200, 9201, 9300, 9301 and
  • On Kubernetes the chart's NetworkPolicies do it (networkPolicy.enabled, on by default; your network plugin must enforce NetworkPolicies): the internal ports take only IOLake's own pods and its bootstrap Job, the metrics ports every pod of the release (its Prometheus), and networkPolicy.adminFrom, metricsFrom, gatewayFrom and blockGatewayFrom add peers (Kubernetes). Elsewhere, a host firewall.
  • [ ] Non-root objectio service user with CAP_SYS_RAWIO (not full root) on OSD nodes.
  • [ ] --trusted-proxies set to the ingress / load balancer network if TLS ends there and policies use aws:SecureTransport or aws:SourceIp.

Next steps

  1. Pick a deployment path above.
  2. Once running, see the Operations tree for monitoring, metrics, and failure recovery.
  3. And Administration for the admin API surface — users, buckets, warehouses, policies.