Aerospike#

An L2 adapter backed by the native C++ Aerospike connector (the same ConnectorBase worker-pool harness used by fs_native), wrapped with NativeConnectorL2Adapter. KV objects are stored under a meta record plus optional payload segments so values larger than the server record cap are transparently sharded.

Prerequisites – Building with Aerospike support:

The Aerospike extension is not built by default. Install the Aerospike C client, then build with BUILD_AEROSPIKE=1 (or set AEROSPIKE_INCLUDE_DIR):

BUILD_AEROSPIKE=1 pip install -e .

See Adding Native Backends (section “Built-in Aerospike backend”) for installing the C client into .deps/ and the aerospike-client-c.env example.

Required fields:

  • hosts: Seed hosts as host:port[,host:port...].

Optional fields:

  • namespace (str, default "lmcache"): Aerospike namespace. Must exist on the server and have nsup-period > 0 if you rely on TTL expiry.

  • set_name / set (str, default "kv_chunks"): Aerospike set name.

  • num_workers (int, default 8, > 0): C++ worker threads for I/O. This is the real I/O queue depth – raise it to push throughput.

  • read_timeout_ms (int, default 1000): Client read timeout.

  • write_timeout_ms (int, default 2000): Client write timeout.

  • default_ttl_seconds (int, default 86400): Record TTL. 0 uses the namespace default TTL.

  • target_segment_bytes (int, default 0): Target shard size. 0 uses the discovered server record cap.

  • max_record_bytes (int, default 0): Override the server record cap. 0 discovers it at construction time.

  • username / password (str, default ""): Optional Enterprise Edition authentication.

  • max_capacity_gb (float, default 0): Maximum L2 capacity in GB for client-side usage tracking / eviction. 0 disables tracking.

Environment variable fallbacks. When the corresponding config value is empty, these environment variables are used: LMCACHE_AEROSPIKE_HOSTS, LMCACHE_AEROSPIKE_NAMESPACE, LMCACHE_AEROSPIKE_SET, LMCACHE_AEROSPIKE_USERNAME, LMCACHE_AEROSPIKE_PASSWORD.

Configuration examples:

# Basic single-node Community Edition
--l2-adapter '{"type": "aerospike", "hosts": "127.0.0.1:3000", "namespace": "lmcache", "set_name": "kv_chunks", "num_workers": 8}'

# Multi-node seed list with capacity tracking for eviction
--l2-adapter '{"type": "aerospike", "hosts": "10.0.0.1:3000,10.0.0.2:3000", "namespace": "lmcache", "num_workers": 16, "max_capacity_gb": 512}'

# Enterprise Edition with authentication
--l2-adapter '{"type": "aerospike", "hosts": "as.internal:3000", "namespace": "lmcache", "username": "lmcache", "password": "secret"}'