ADR-0212accepted

AIStor as Local S3 Runtime

Status

Accepted

Context and Problem Statement

ADR-0208 selected MinIO OSS as the local S3-compatible runtime. Upstream MinIO OSS moved to source-only maintenance mode and then no-longer-maintained + archived state. Relying on an archived runtime as a core storage contract creates avoidable supply-chain and patching risk.

We still need a local S3-compatible runtime for joelclaw workloads and for ADR-0209 S3-first migration phases.

Decision

Adopt AIStor as the maintained local S3 runtime, deployed on Kubernetes via Helm, while keeping legacy MinIO online during transition.

Runtime topology

  • Legacy (rollback path): joelclaw/minio + joelclaw/minio-nodeport (30900/30901)
  • Active migration target: aistor namespace
    • Operator release: aistor
    • ObjectStore release: aistor-primary
    • API service: aistor-s3-api (NodePort 31000, TLS)
    • Console service: aistor-s3-console (NodePort 31001, TLS)

Deployment contract

  • Canonical deploy command:
~/Code/joelhooks/joelclaw/k8s/reconcile-aistor.sh
  • License key source: secrets key aistor_key
  • ObjectStore namespace stays isolated (aistor) until explicit cutover.

Non-Goals

  • Immediate deletion of legacy MinIO.
  • Immediate migration of all existing buckets/objects.
  • Rewriting ADR-0209 scope; this ADR updates only the local runtime implementation choice.

Implementation Plan

Required skills preflight

  • k8s — Helm + k8s operator/objectstore deployment behavior.
  • system-architecture — namespace/service topology and exposure map.
  • adr-skill — supersession hygiene and index updates.

Phase 1 — Parallel runtime (done)

  • Deploy AIStor operator and objectstore in aistor namespace.
  • Keep legacy MinIO in joelclaw namespace.
  • Validate both runtime paths with Restate smoke tests.

Phase 2 — Consumer cutover (next)

  • For each S3 consumer, switch endpoint from joelclaw/minio to aistor/aistor-s3-api.
  • Require explicit TLS setting (MINIO_USE_SSL=true) where applicable.
  • Validate read/write path after each consumer migration.

Phase 3 — Legacy retirement (gated)

  • Confirm no active consumers depend on joelclaw/minio.
  • Snapshot/export required historical objects.
  • Remove legacy MinIO StatefulSet/services.

Verification

  • AIStor operator pods are healthy in namespace aistor.
  • AIStor objectstore pod aistor-s3-pool-0-0 is Running.
  • AIStor services aistor-s3-api and aistor-s3-console are present.
  • Legacy MinIO remains available in joelclaw for rollback.
  • Restate smoke test passes against legacy MinIO.
  • Restate smoke test passes against AIStor.

Consequences

Positive

  • Local S3 runtime is back on maintained bits.
  • Migration can proceed incrementally with rollback.
  • ADR-0209 remains valid with updated local runtime implementation.

Negative

  • Temporary dual-runtime operational overhead.
  • TLS handling complexity for clients migrating to AIStor.

Related

  • ADR-0208 (superseded): MinIO S3 API on NAS-backed storage.
  • ADR-0209: S3-first storage migration.
  • ADR-0088: NAS-backed storage tiering.