S3 Tables

RustFS S3 Tables verwaltet Apache Iceberg-Tabellen über einen integrierten REST-Katalog. Tabellendaten, Manifeste und Iceberg-Metadaten bleiben als S3-Objekte in RustFS gespeichert. Diese Anleitung zeigt, wie Sie einen eigenen Tabellen-Bucket aktivieren, Clients verbinden und Berechtigungen sowie Wartungsgrenzen berücksichtigen.

Funktionsweise

Ein Iceberg-Client nutzt den REST-Katalog, um Tabellen zu finden und Metadatenänderungen festzuschreiben. Tabellendateien liest und schreibt er über die S3-API. RustFS stellt beide Schnittstellen am S3-API-Port bereit.

Das Aktivieren eines Tabellen-Buckets registriert vorhandene Parquet-Dateien nicht automatisch als Iceberg-Tabellen. Erstellen oder registrieren Sie Tabellen über einen Iceberg-Client. Ohne Angabe von location weist RustFS einen Speicherort zu; ein benutzerdefinierter Speicherort muss im selben Bucket liegen. Clients sollten den zurückgegebenen Speicherort verwenden.

Das standardmäßige Katalog-Backend object speichert den Katalogzustand dauerhaft im RustFS-Objektspeicher. Ein Tabellen-Commit prüft seine Ausgangsmetadaten und referenzierten Objekte, bevor der Zeiger auf die aktuellen Metadaten bedingt aktualisiert wird. Bei einem Schreibkonflikt muss der Client die Tabelle neu laden und den Konflikt auflösen. Eine Transaktion umfasst genau eine Tabelle.

Voraussetzungen

• Starten Sie eine RustFS-Bereitstellung mit den oben beschriebenen S3-Tables-Endpunkten. Siehe Installation.
• Installieren Sie die AWS CLI und curl ab Version 7.76 mit Unterstützung für --aws-sigv4 und --fail-with-body.
• Erstellen Sie für diese Anleitung einen eigenen neuen Bucket. Das Beispiel verwendet my-bucket.
• Verwenden Sie ein vorhandenes Administratorkonto mit Zugriff auf Katalogoperationen und S3-Objekte. Die integrierte Richtlinie consoleAdmin deckt diese Anleitung ab; konfigurieren Sie enger begrenzte Richtlinien für Anwendungen.

Die Beispiele verwenden http://localhost:9000. Ersetzen Sie dies durch Ihren Server-Endpunkt und verwenden Sie außerhalb lokaler Tests TLS mit aktivierter Zertifikatsprüfung.

export RUSTFS_ENDPOINT="http://localhost:9000"
export AWS_ACCESS_KEY_ID="<your-access-key>"
export AWS_SECRET_ACCESS_KEY="<your-secret-key>"
export AWS_DEFAULT_REGION="us-east-1"

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api create-bucket --bucket my-bucket

curl --fail-with-body --silent --show-error \
	--aws-sigv4 "aws:amz:us-east-1:s3" \
	--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
	--header "x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
	--request PUT "$RUSTFS_ENDPOINT/iceberg/v1/buckets/my-bucket"

curl --fail-with-body --silent --show-error \
	--aws-sigv4 "aws:amz:us-east-1:s3" \
	--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
	--header "x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
	"$RUSTFS_ENDPOINT/iceberg/v1/buckets/my-bucket"

{
	"table-bucket": "my-bucket",
	"enabled": true,
	"catalog-type": "iceberg-rest",
	"warehouse": "my-bucket",
	"catalog-entry-present": true
}

Berechtigungen und Zugangsdaten

Zum Aktivieren eines Tabellen-Buckets ist admin:SetTableBucket erforderlich, zum Prüfen des Zustands admin:GetTableBucket. Die Katalogerkennung verwendet admin:GetTableCatalog. Namespace- und Tabellenoperationen besitzen eigene RustFS-Admin-Aktionen, darunter admin:SetTableNamespace, admin:CreateTable, admin:GetTableMetadata und admin:CommitTable.

Für das Lesen und Schreiben von Tabellendateien sind zusätzlich normale S3-Berechtigungen erforderlich. RustFS prüft Tabellenberechtigungen für Objektpfade im Warehouse: Lesen erfordert die entsprechende Autorisierung für admin:GetTableMetadata, Schreiben für admin:SetTableMetadata. Eine Berechtigung für Katalog-Commits allein erlaubt nicht die vorausgehenden S3-Dateischreibvorgänge. Konfigurieren Sie IAM-Richtlinien für beide Schnittstellen.

Die Ausgabe von Zugangsdaten durch den Katalog ist standardmäßig deaktiviert. Bei aktivierter Funktion muss ein kompatibler Client X-Iceberg-Access-Delegation: vended-credentials aushandeln, und der Aufrufer benötigt die Berechtigung, Tabellenzugangsdaten anzufordern. Der erste Katalogzugriff erfordert weiterhin eine autorisierte Identität. Die verlinkte PyIceberg-Anleitung verwendet ausdrücklich konfigurierte Zugangsdaten.

Wartung und Schutz vor Datenverlust

Das Löschen von Metadaten und die Hintergrundwartung sind standardmäßig deaktiviert. RustFS stellt explizite Operationen für Planung, Scheduler-Läufe und Worker-Läufe bereit; ein integrierter periodischer Wartungs-Scheduler wird nicht ausgeführt. Prüfen Sie einen Wartungsplan und die darin beibehaltenen Referenzen, bevor Sie Löschvorgänge aktivieren.

Beim Löschen einer Tabelle wird ihr Katalogeintrag entfernt, während die zugrunde liegenden Objekte erhalten bleiben. Führen Sie erforderliche Tabellenwartungen vor dem Entfernen aus dem Katalog durch; danach können Wartungsoperationen die Tabelle nicht mehr finden. Die Bereinigung verbliebener Objekte erfordert einen separaten Plan, der alle verbleibenden Referenzen berücksichtigt. Löschen Sie keine S3-Pfade rekursiv, auf die Snapshots oder andere Metadaten noch verweisen könnten.

Behalten Sie für diese Anleitung das Standard-Katalog-Backend bei. Der Wechsel einer vorhandenen Bereitstellung zu durable-strong erfordert das Verfahren zur Katalogumstellung, einschließlich Migrationsvorprüfung und koordinierter Sperrung der schreibenden Clients.

Client-Kompatibilität und Grenzen

Das Quellcode-Repository pflegt folgenden Validierungsumfang:

Die Iceberg-Formate v1 und v2 werden unterstützt; v2 ist der Standard. Gestuftes Erstellen von Tabellen, Datenbereinigung beim Löschen und Iceberg-Format v3 werden nicht unterstützt.

RustFS S3 Tables bietet weder eine SQL-Ausführungsengine noch atomare Transaktionen über mehrere Tabellen oder unabhängige regionsübergreifende Active-Active-Schreibzugriffe. Eine vollständige Kompatibilität mit der AWS-S3-Tables-Steuerungsebene wird nicht zugesichert. Prüfen Sie die Supportmatrix, bevor Sie eine andere Engine oder ein anbieterspezifisches Profil verwenden.

Nächste Schritte

• Führen Sie die PyIceberg-Anleitung aus.
• Prüfen Sie die IAM-Richtlinien, bevor Sie Anwendungen Zugriff gewähren.
• Validieren Sie weitere Client-Versionen mit den Client-Konformitätsprüfungen des Repositorys.