Environment:Treeverse LakeFS S3 Gateway Test Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Integration_Testing |
| Last Updated | 2026-02-08 10:00 GMT |
Overview
Integration test environment with MinIO S3-compatible storage, lakeFS server, and Go test runner for S3 gateway compatibility testing.
Description
The lakeFS S3 gateway integration tests (esti test suite) verify that lakeFS correctly implements the S3 protocol. Tests run against a Docker Compose stack that includes a lakeFS server, a MinIO instance (or real S3), and a PostgreSQL database. The test runner uses both the MinIO Go SDK and the AWS Go SDK v2 to exercise the S3 gateway from different client perspectives. Tests are gated by the `ESTI_BLOCKSTORE_TYPE` environment variable and some tests are skipped when not running against real S3.
Usage
Use this environment for running S3 gateway integration tests, verifying S3 compatibility, or developing new S3 gateway features. It is required for all implementations in the S3 Gateway Integration workflow (WF4).
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux (Docker host) | Docker Compose required |
| Hardware | 4+ CPU cores, 8GB+ RAM | For running lakeFS + MinIO + PostgreSQL concurrently |
| Disk | 5GB+ free space | For Docker images and test data |
| Network | Ports 8000 (lakeFS), 9000 (MinIO) | Docker Compose manages networking |
Dependencies
Container Images
- `treeverse/lakefs` (lakeFS server)
- `minio/minio:RELEASE.2023-11-20T22-40-07Z` (MinIO S3-compatible storage)
- `postgres:11` (metadata database)
Go Test Dependencies
- `github.com/minio/minio-go/v7` v7.0.63 (MinIO SDK)
- `github.com/aws/aws-sdk-go-v2` v1.39.2 (AWS SDK)
Build Tag
- `//go:build esti` (esti tests require this build tag)
Credentials
The following environment variables are required for the test runner:
- `ESTI_ENDPOINT_URL`: lakeFS server endpoint URL.
- `ESTI_STORAGE_NAMESPACE`: Storage namespace for test repositories.
- `ESTI_BLOCKSTORE_TYPE`: Storage backend type (`s3`, `local`, `gs`, `azure`).
- `AWS_ACCESS_KEY_ID`: AWS/MinIO access key.
- `AWS_SECRET_ACCESS_KEY`: AWS/MinIO secret key.
- `LAKEFS_BLOCKSTORE_S3_CREDENTIALS_ACCESS_KEY_ID`: lakeFS server S3 credentials.
- `LAKEFS_BLOCKSTORE_S3_CREDENTIALS_SECRET_ACCESS_KEY`: lakeFS server S3 secret.
Quick Install
# Start the test stack
docker compose -f deployments/compose/docker-compose.yml up -d
# Run esti tests
go test -tags esti -v ./esti/... -run TestS3
Code Evidence
MinIO client creation from `esti/s3_gateway_test.go:47-65`:
func newMinioClient(t *testing.T, credentials *model.CredentialsWithSecret) *minio.Client {
// Creates MinIO client pointing at lakeFS S3 gateway
}
func createS3Client(t *testing.T, credentials *model.CredentialsWithSecret) *s3.Client {
// Creates AWS SDK v2 S3 client pointing at lakeFS S3 gateway
}
Multipart upload constants from `esti/esti_utils.go:370-382`:
const (
// randomDataContentLength is the content length used for small
// objects. It is intentionally not a round number.
randomDataContentLength = 16
// minDataContentLengthForMultipart is the content length for all
// parts of a multipart upload except the last. Its value -- 5MiB
// -- is defined in the S3 protocol, and cannot be changed.
minDataContentLengthForMultipart = 5 << 20
)
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `blockstore type is not s3` (test skip) | Running S3-specific test against non-S3 backend | Set `ESTI_BLOCKSTORE_TYPE=s3` or accept test skip |
| MinIO connection refused | MinIO container not started | Run `docker compose up -d` first |
| `ESTI_STORAGE_NAMESPACE` not set | Missing test configuration | Export required ESTI_* environment variables |
Compatibility Notes
- S3 user metadata: Metadata ordering is not guaranteed through the S3 gateway (known issue referenced in `esti/s3_gateway_test.go:1037`).
- Local blockstore: Some S3 tests are automatically skipped when `ESTI_BLOCKSTORE_TYPE` is not `s3`.
- Presigned URLs: Only work with S3, GCS, and Azure backends; not supported for local blockstore.