artifact-store/docs/minio-compatibility-landscape-2026-06-27.md

# MinIO Compatibility Landscape - 2026-06-27

## Purpose

This note closes `ARTIFACT-STORE-WP-0007-T001` by recording the dated
object-store landscape that should guide artifact-store's S3-compatible backend
and any future MaxIO decision.

## Decision

Do not start a direct MaxIO server fork from artifact-store. Treat the near-term
work as a compatibility-profile lane:

- Keep Ceph RGW as the preferred Railiance production target because it has a
  mature S3 compatibility matrix, multipart support, STS-related docs, and fits
  existing cluster storage ownership.
- Keep upstream MinIO only as an opt-in compatibility target for development and
  migration testing, pinned by source tag or an operator-provided image whose
  provenance is documented.
- Treat OpenMaxIO as a console/UI signal, not a full object-store fork candidate
  for artifact-store yet.
- Keep RustFS, Garage, and SeaweedFS as evaluation targets for later harness runs
  if Ceph RGW or MinIO compatibility uncovers a gap.
- Do not adopt any "Pigsty MinIO fork" until a primary source repository,
  license, release process, and security update path are verified.

## Source Status

- `minio/minio` was archived on GitHub on 2026-04-25 and is read-only. The tags
  page shows `RELEASE.2025-10-15T17-29-55Z` as the newest visible tag on
  2026-06-27, with a commit note pointing documentation toward source-only
  releases.
- MinIO AIStor documentation still documents STS. It states STS can generate
  temporary credentials and convert external identity-provider credentials into
  AWS Signature V4-compatible credentials.
- `AssumeRoleWithWebIdentity` remains the relevant OIDC shape for future
  short-lived object-store credentials, returning access key, secret key,
  expiration, and session token fields.

## Candidate Comparison

| Candidate | Fit | Risks / notes | Current call |
| --- | --- | --- | --- |
| Upstream MinIO source tag | Strong S3 behavior baseline; familiar endpoint for development smoke tests. | Archived/read-only repository, AGPLv3 obligations, source-only release posture, and unclear long-term community patch path. | Use only as a pinned compatibility target, not the production platform default. |
| OpenMaxIO UI pieces | Active public UI fork signal; useful for console affordance research. | Repository is the object browser/console, not a full server fork. It is AGPLv3 and claims broader goals than the repo currently proves. | Do not treat as the object-store backend. Track only as UI/reference material. |
| Pigsty MinIO fork | Mentioned in the workplan as a candidate to compare. | No primary source repository was verified in this assessment pass. | Not pursued until provenance is clear. |
| Garage | Small, self-hostable object store with documented S3 API workflow, Docker quick start, single-node mode, and binary/source install paths. | Not a drop-in S3 clone; compatibility and operations profile differ from MinIO/RGW. | Good later compatibility target for lightweight deployments, not first production target. |
| RustFS | Apache-2.0, S3-compatible object-store project with MinIO/Ceph migration positioning, OIDC support notes, and Docker quick start. | Project maturity and feature status need live evaluation; some distributed/KMS features are marked under testing. | Worth an opt-in harness target after MinIO/RGW path is stable. |
| SeaweedFS S3 gateway | Mature file/object system with explicit S3 gateway, documented supported bucket/object/multipart APIs, and STS/OIDC/IAM API references. | Different storage model and bucket/collection semantics; may be more platform than artifact-store needs. | Evaluate only if large-scale filer/backup needs make it attractive. |
| Ceph RGW | Existing production-aligned target. Ceph documents S3 API compatibility, supported core bucket/object operations, multipart uploads, storage classes, STS, and Keycloak/OIDC references. | Needs cluster/operator storage ownership and explicit credential custody. | Preferred production target for Railiance. |

## Harness Implications

The compatibility harness should stay backend-agnostic and run against an
operator-provided S3 endpoint. For MinIO today, the repo now provides an opt-in
pytest module that:

- skips unless explicit `ARTIFACTSTORE_MINIO_*` environment variables are set;
- performs a small put/get/range/head/delete round trip;
- performs a multipart upload with a 5 MiB part size so MinIO-compatible servers
  see realistic multipart behavior;
- avoids storing any secret values in Git, State Hub, test output, or docs.

The same shape can be reused later for Ceph RGW, RustFS, Garage, or SeaweedFS by
renaming the environment variables or parameterizing the fixture.

## STS Follow-Up

STS credential vending remains `ARTIFACT-STORE-WP-0007-T003`/`T004` work. The
source assessment confirms the shape to test, but implementation ownership still
belongs to identity/platform routing:

- issuer: KeyCape/local-identity or another approved OIDC issuer;
- custody: OpenBao/operator path for any long-lived bootstrap secret;
- consumer: artifact-store S3 backend can consume temporary access key, secret
  key, and session token once the config supports session tokens or an external
  refresher injects standard SDK credentials;
- audit: State Hub records only non-secret request metadata and evidence ids.

## Sources Checked

- https://github.com/minio/minio/tags
- https://docs.min.io/aistor/developers/security-token-service/
- https://docs.min.io/aistor/developers/security-token-service/assumerolewithwebidentity/
- https://github.com/OpenMaxIO/openmaxio-object-browser
- https://garagehq.deuxfleurs.fr/documentation/quick-start/
- https://github.com/rustfs/rustfs
- https://github.com/seaweedfs/seaweedfs/wiki/Amazon-S3-API
- https://docs.ceph.com/en/latest/radosgw/s3/