Einheit 4.2: Object Storage Integration
Einführung
TaskBoard-Nutzer möchten Screenshots, Logs und Dokumente an Aufgaben anhängen. Die Weiterleitung dieser Daten über die API-Pods würde Arbeitsspeicher, Bandbreite und Anfragezeit kosten. Stattdessen lädt der Browser direkt in den Bucket aus Einheit 2.4 mit einer kurzlebigen presigned URL hoch, und die API speichert nur den Objekt-Schlüssel in PostgreSQL.
IONOS Cloud Object Storage spricht das S3-Protokoll, daher verwenden Sie standardmäßige S3 SDKs. Es handelt sich jedoch nicht um AWS: Sie setzen den Endpoint explizit, authentifizieren sich mit einem Access Key und Secret Key und prüfen, welche S3-Funktionen vorhanden sind, bevor Sie sie aufrufen. In dieser Einheit erstellen Sie den Anhang-Dienst mit boto3: Client-Einrichtung, presigned URLs, Multipart-Uploads, Streaming-Downloads und Lifecycle-Regeln. Das Code Lab führt den vollständigen Upload- und Download-Flow aus.
1. Der boto3-Client
import os
import boto3
from botocore.config import Config
s3 = boto3.client(
"s3",
endpoint_url="https://s3.eu-central-3.ionoscloud.com",
aws_access_key_id=os.environ["S3_ACCESS_KEY"], # terraform output uploads_access_key
aws_secret_access_key=os.environ["S3_SECRET_KEY"], # terraform output uploads_secret_key
region_name="eu-central-3",
config=Config(signature_version="s3v4"),
)
print([b["Name"] for b in s3.list_buckets()["Buckets"]])
Ohne endpoint_url kommuniziert boto3 mit AWS und Ihre Schlüssel schlagen fehl. Die Zugangsdaten bestehen aus einem Access Key- und Secret Key-Paar: Object Storage akzeptiert das Bearer Token der Cloud API nicht, und IAM-Rollen sowie der Security Token Service (STS) werden nicht unterstützt. Ihre Zugangsdaten sind nicht an eine bestimmte Region oder ein bestimmtes Bucket gebunden, sodass ein Schlüssel- und Geheimnis-Paar an jedem Endpunkt funktioniert.
1.1 Endpunkte pro Region
Der Endpunkt hängt vom Bucket-Typ und der Region ab. Die folgende Tabelle listet die Endpunkte für vertraglich verwaltete Buckets auf:
| Rechenzentrum | Region | Endpunkt | Endpunkt für statische Websites |
|---|---|---|---|
| Frankfurt, Deutschland | eu-central-4 |
s3.eu-central-4.ionoscloud.com |
s3-website.eu-central-4.ionoscloud.com |
| Berlin, Deutschland | eu-central-3 |
s3.eu-central-3.ionoscloud.com |
s3-website.eu-central-3.ionoscloud.com |
| Lenexa, USA | us-central-1 |
s3.us-central-1.ionoscloud.com |
s3-website.us-central-1.ionoscloud.com |
Von Benutzern verwaltete Buckets verwenden andere Regionen, beispielsweise s3.eu-central-2.ionoscloud.com für Berlin. Das Bucket von TaskBoard ist vertraglich verwaltet in eu-central-3. Die Endpunkte antworten über HTTP und HTTPS; verwenden Sie immer https://. Die Verschlüsselung während der Übertragung verwendet TLS 1.2 oder 1.3.
1.2 Die Checksummenänderung in boto3 1.36
Ab boto3 1.36.0 sendet PutObject neue Checksummen-Trailer, die Object Storage noch nicht unterstützt. Die Aufrufe schlagen dann mit InvalidTrailer fehl: "Invalid trailing header names in x-amz-trailer". Fixieren Sie entweder boto3<=1.35.99 oder setzen Sie diese Variablen für Ihren Prozess:
export AWS_REQUEST_CHECKSUM_CALCULATION=when_required
export AWS_RESPONSE_CHECKSUM_VALIDATION=when_required
Fügen Sie sie in die ConfigMap der API aus Einheit 3.2 ein, damit jeder Pod sie erhält.
2. Buckets, Zugriff und Presigned URLs
2.1 Bucket-Operationen
Terraform verwaltet den langlebigen Bucket von TaskBoard (Einheit 2.4). Tests und Werkzeuge können Buckets im Code weiterhin erstellen und auflisten:
from botocore.exceptions import ClientError
try:
s3.create_bucket(Bucket="taskboard-ci-4711",
CreateBucketConfiguration={"LocationConstraint": "eu-central-3"})
except ClientError as e:
if e.response["Error"]["Code"] != "BucketAlreadyOwnedByYou":
raise
print(s3.get_bucket_acl(Bucket="taskboard-ci-4711")["Grants"])
Objekte sind standardmäßig privat; nur der Bucket-Besitzer kann auf sie zugreifen. Bewahren Sie diese Einstellung bei. Für einen von einem Vertrag verwalteten Bucket teilt eine ACL den Zugriff nur mit Berechtigten aus anderen Verträgen; um Benutzern Ihres eigenen Vertrags Zugriff zu gewähren, verwenden Sie eine Bucket Policy. TaskBoard benötigt beides nicht, da presigned URLs zeitlich begrenzten Zugriff auf einzelne Objekte gewähren.
2.2 Presigned Upload URLs
import uuid
BUCKET = "taskboard-uploads-dev-7f3a"
def create_upload(task_id: int, filename: str, content_type: str) -> dict:
key = f"tasks/{task_id}/{uuid.uuid4()}/{filename}"
url = s3.generate_presigned_url(
"put_object",
Params={"Bucket": BUCKET, "Key": key, "ContentType": content_type},
ExpiresIn=900,
)
return {"key": key, "url": url, "headers": {"Content-Type": content_type}}
Presigned URLs werden lokal durch einen Signaturalgorithmus mit Ihren Zugangsdaten erstellt; es erfolgt kein API-Aufruf. Die Signaturtypen v2 und v4 werden unterstützt. Der Browser sendet anschließend die Datei selbst:
const { key, url, headers } = await (await fetch(`/api/tasks/${id}/attachments`, { method: "POST",
body: JSON.stringify({ filename: file.name, contentType: file.type }) })).json();
await fetch(url, { method: "PUT", headers, body: file });
await fetch(`/api/tasks/${id}/attachments/${encodeURIComponent(key)}/confirm`, { method: "POST" });
Da ContentType Teil der Signatur ist, muss der Browser genau diesen Header senden. Der Bestätigungsaufruf ermöglicht es der API, das Objekt mit head_object zu überprüfen, bevor der Schlüssel in PostgreSQL geschrieben wird.
Nur der Bucket-Besitzer kann eine gültige presigned URL generieren; für einen vom Vertrag verwalteten Bucket kann dies auch ein Administrator tun. Der zur Signierung verwendete Schlüssel muss zu einer dieser beiden Rollen gehören.
2.3 CORS für Browser-Uploads
Ein Browser auf https://taskboard.example.com darf nur PUT zum Bucket, wenn die CORS-Konfiguration des Buckets dies zulässt:
resource "ionoscloud_s3_bucket_cors_configuration" "uploads" {
bucket = ionoscloud_s3_bucket.uploads.name
cors_rule {
allowed_methods = ["PUT", "GET"]
allowed_origins = ["https://taskboard.example.com"]
allowed_headers = ["Content-Type"]
expose_headers = ["ETag"]
max_age_seconds = 3000
}
}
allowed_methods akzeptiert GET, PUT, HEAD, POST und DELETE.
3. Upload- und Download-Muster
3.1 Multipart-Upload für große Dateien
Eine einzelne Upload-Anfrage ist auf 5 GiB für contract-eigene Buckets und 4,65 GiB für benutzer-eigene Buckets begrenzt. Darüber hinaus wird der Multipart-Upload verwendet, bis zur maximalen Objektgröße von 5 TiB. Der verwaltete Transfer von boto3 unterteilt Dateien automatisch:
from boto3.s3.transfer import TransferConfig
cfg = TransferConfig(multipart_threshold=64 * 1024**2,
multipart_chunksize=64 * 1024**2,
max_concurrency=4)
s3.upload_file("export.tar.gz", BUCKET, "exports/2026-11/export.tar.gz",
ExtraArgs={"ContentType": "application/gzip"}, Config=cfg)
Serverseitige Jobs, wie die Exporte des Workers, verwenden dieses Muster. Für Browser-Uploads mit mehreren Gigabyte ruft die API create_multipart_upload auf, erstellt für jeden Teil eine presignierte upload_part-URL und schließt den Vorgang mit complete_multipart_upload unter Verwendung der zurückgegebenen ETags ab. Ein abgebrochener Multipart-Upload behält seine Teile bei, die die Lifecycle-Regel in Abschnitt 4 entfernt.
3.2 Streaming-Downloads
Bei Downloads gibt die API in der Regel eine Weiterleitung an eine presignierte GET zurück. Wenn sie die Datei selbst verarbeiten muss, sollte sie diese gestreamt werden, anstatt sie in den Arbeitsspeicher zu laden:
from fastapi.responses import StreamingResponse
def download(key: str):
obj = s3.get_object(Bucket=BUCKET, Key=key)
return StreamingResponse(obj["Body"].iter_chunks(chunk_size=1024 * 1024),
media_type=obj["ContentType"])
Der Inhaltstyp wird beim Hochladen gespeichert; get_object gibt ihn zurück. Benutzerspezifische Metadaten pro Objekt sind auf 2 kB begrenzt, und ein Objektname, einschließlich seines Ordnerpfads, kann bis zu 1024 Zeichen umfassen.
3.3 Ratenbeschränkungen für Auflisten und Löschen
Bei von Verträgen verwalteten Buckets führt der ressourcenintensive Einsatz von List Objects und Delete Objects zu Ratenbeschränkungen, die pro Vertrag durchgesetzt werden. Die Antwort ist 429 Too Many Requests mit einem Retry-After-Header:
import time
def list_all(prefix: str):
kwargs = {"Bucket": BUCKET, "Prefix": prefix}
while True:
try:
page = s3.list_objects_v2(**kwargs)
except ClientError as e:
if e.response["ResponseMetadata"]["HTTPStatusCode"] != 429:
raise
time.sleep(int(e.response["ResponseMetadata"]["HTTPHeaders"].get("retry-after", "1")))
continue
yield from page.get("Contents", [])
if not page.get("IsTruncated"):
return
kwargs["ContinuationToken"] = page["NextContinuationToken"]
Rufen Sie List Objects nicht nach einem festen Zeitplan ab; speichern Sie die Liste der Anhänge in PostgreSQL.
4. Lifecycle-Regeln über die API
Lifecycle-Regeln automatisieren die Löschung von Objekten und deren Versionen. Wenden Sie sie mit der S3 API an:
s3.put_bucket_lifecycle_configuration(
Bucket=BUCKET,
LifecycleConfiguration={"Rules": [
{"ID": "expire-tmp", "Status": "Enabled",
"Filter": {"Prefix": "tmp/"}, "Expiration": {"Days": 7}},
{"ID": "abort-multipart", "Status": "Enabled", "Filter": {},
"AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 5}},
]},
)
print(s3.get_bucket_lifecycle_configuration(Bucket=BUCKET)["Rules"])
Eine Regel unterstützt vier Aktionen: Ablauf der aktuellen Versionen, endgültige Löschung nicht aktueller Versionen, Löschung abgelaufener Objekt-Löschmarkierungen und Löschung unvollständiger Multipart-Uploads. Eine Konfiguration kann bis zu 1000 Regeln enthalten. Terraform verwaltet dieselbe Konfiguration mit ionoscloud_s3_bucket_lifecycle_configuration.
Übergangsregeln existieren hier nicht. Nur die STANDARD-Speicherklasse ist verfügbar, daher können Lifecycle-Regeln Objekte nicht in eine andere Speicherklasse verschieben. Kostenmanagement bei IONOS Cloud Object Storage bedeutet, das zu löschen, was man nicht mehr benötigt.
5. S3-Kompatibilitätsprüfungen
IONOS Cloud Object Storage unterstützt die meisten S3-APIs, aber nicht alle. Die folgende Tabelle zeigt die Unterstützung nach Funktion:
| Funktion | Unterstützt | Hinweise |
|---|---|---|
| Bucket CRUD | Ja | |
| Object CRUD | Ja | |
| Object Copy | Ja | Kopieren über Regionen hinweg wird nicht unterstützt |
| Multipart Uploads | Ja | |
| Pre-Signed URLs | Ja | Die Signaturentypen v2 und v4 werden unterstützt |
| Bucket ACLs | Ja | |
| Object ACLs | Ja | |
| Block Public Access | Ja | Nur über die API |
| Bucket Policies | Ja | |
| Object Policies | Ja | |
| CORS-Konfiguration | Ja | |
| Bucket Versioning | Ja | |
| Bucket Replication | Ja | Intraregionale und cross-regionale Replikation werden unterstützt |
| Bucket Tagging | Ja | Nur über die API |
| Object Tagging | Ja | Nur über die API |
| Bucket Lifecycle | Ja | |
| Bucket Access Logging | Ja | |
| Bucket Encryption Configuration | Ja | Serverseitige Verschlüsselung wird im Webinterface standardmäßig verwendet. Die Verschlüsselung mit kundenverwalteten Verschlüsselungsschlüsseln ist über die API verfügbar. |
| Object Encryption | Ja | Nur über die API |
| Bucket Websites | Ja | |
| Bucket Inventory | Ja | Nur über die API |
| Object Lock | Ja | |
| Legal Hold | Ja | |
| Identity and Access Management (IAM) | Nein | |
| Security Token Service (STS) | Nein | |
| Multi-factor Authentication | Nein | |
| Bucket Notifications | Nein | |
| Request Payment | Nein | |
| Bucket Metrics | Nein | |
| Bucket Analytics | Nein | |
| Bucket Accelerate | Nein | |
| S3 Select | Nein |
Wie die Tabelle zeigt, ist der Datenpfad weitgehend kompatibel, während AWS-Kontofunktionen fehlen. Zwei Konsequenzen für TaskBoard: Ohne Bucket Notifications ersetzt der Bestätigungsaufruf der API (Abschnitt 2.2) ein "object created"-Ereignis, und ohne STS erhält jeder Dienst sein eigenes langlebiges Schlüsselpaar. Auch die Bucket-Typen unterscheiden sich: Bucket Access Logging wird beispielsweise für vertragsgebundene Buckets nicht unterstützt. Prüfen Sie den Bucket-Typ, bevor Sie sich auf eine Funktion verlassen.
Schnellreferenz für die API
Wichtige S3-Operationen hinter dem Code dieser Einheit:
| Methode | Endpunkt | Beschreibung |
|---|---|---|
PUT |
/{Bucket}/{Key} |
Objekt hochladen (Ziel einer presignierten Upload-URL) |
GET |
/{Bucket}/{Key} |
Objekt herunterladen (Ziel einer presignierten Download-URL) |
GET |
/{Bucket}?list-type=2 |
Objekte auflisten (ListObjectsV2, drosselt bei vertraglich zugewiesenen Buckets) |
POST |
/{Bucket}/{Key}?uploads |
Multipart-Upload starten |
PUT |
/{Bucket}?lifecycle |
Lifecycle-Konfiguration festlegen |
Basis-URL: https://s3.eu-central-3.ionoscloud.com (ein Endpunkt pro Region)
Authentifizierung: AWS-Signatur (v4 oder v2) mit Access Key und Secret Key, nicht mit Bearer Token
Code Lab
Ziel: Hochladen und Abrufen von TaskBoard-Anhängen mit boto3: eine presignierte Upload-URL, ein Multipart-Upload und ein presignierter Download, alle authentifiziert mit einem Access Key und Secret Key.
Voraussetzungen:
- Der Bucket und der Access Key aus Einheit 2.4, angewendet, sowie das CORS-Resource aus Abschnitt 2.3
- Python 3.12 mit
boto3undrequests curlund eine 100 MB große Testdatei:head -c 100M /dev/urandom > big.bin
Schritt 1: Zugangsdaten konfigurieren
export S3_ACCESS_KEY=$(terraform output -raw uploads_access_key)
export S3_SECRET_KEY=$(terraform output -raw uploads_secret_key)
export AWS_REQUEST_CHECKSUM_CALCULATION=when_required
export AWS_RESPONSE_CHECKSUM_VALIDATION=when_required
python -c "import boto3; print(boto3.__version__)"
Erwartete Ausgabe:
1.x.y
Schritt 2: Das Authentifizierungsmodell nachweisen
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $IONOS_TOKEN" \
https://s3.eu-central-3.ionoscloud.com/taskboard-uploads-dev-7f3a
Erwartete Ausgabe:
4xx status code (not 200)
Das Cloud API-Token ist keine S3-Anmeldung, daher wird die Anfrage abgelehnt. Rufen Sie nun den Bucket mit dem Client aus Abschnitt 1 auf:
print(s3.list_objects_v2(Bucket=BUCKET).get("KeyCount"))
Erwartete Ausgabe:
0
Schritt 3: Eine presigned Upload-URL erstellen
up = create_upload(42, "screenshot.png", "image/png")
print(up["key"]); print(up["url"][:60], "...")
Erwartete Ausgabe:
tasks/42/<uuid>/screenshot.png
https://s3.eu-central-3.ionoscloud.com/taskboard-uploads-dev ...
Schritt 4: Hochladen wie der Browser
curl -s -o /dev/null -w "%{http_code}\n" -X PUT -H "Content-Type: image/png" \
--upload-file screenshot.png "<url from Step 3>"
Erwartete Ausgabe:
200
Schritt 5: Hochladen einer großen Datei in Teilen
s3.upload_file("big.bin", BUCKET, "tmp/big.bin", Config=cfg)
print(s3.head_object(Bucket=BUCKET, Key="tmp/big.bin")["ETag"])
Erwartete Ausgabe:
"<hash>-2"
Das Suffix -2 zeigt ein mehrteiliges Objekt mit zwei Teilen: 64 MB und die restlichen 36 MB.
Schritt 6: Download über eine vorab signierte URL
url = s3.generate_presigned_url("get_object", Params={"Bucket": BUCKET, "Key": up["key"]}, ExpiresIn=300)
import requests; r = requests.get(url); print(r.status_code, r.headers["Content-Type"])
Erwartete Ausgabe:
200 image/png
Schritt 7: Die Lebenszyklusregeln anwenden
Führen Sie den Code aus Abschnitt 4 aus. Erwartete Ausgabe:
[{'ID': 'expire-tmp', ...}, {'ID': 'abort-multipart', ...}]
Prüfliste:
- [ ] Das Bearer-Token wird abgelehnt, das Schlüsselpaar erhält Zugriff
- [ ] Die vorab signierten
PUTwerden ohne Anmeldeinformationen in der Anfrage hochgeladen - [ ] Der ETag des Multipart-Uploads endet mit einer Teileanzahl
- [ ] Der heruntergeladene Objekt hat den beim Hochladen festgelegten Inhaltstyp
Aufräumen:
for k in [up["key"], "tmp/big.bin"]:
s3.delete_object(Bucket=BUCKET, Key=k)
Häufige Fehlerquellen
Entwicklerfehler, die bei dem Thema dieser Einheit zu vermeiden sind:
-
InvalidTrailer bei jedem Upload
- Problem:
put_objectundupload_fileschlagen nach einem Abhängigkeitsupdate mit „Invalid trailing header names in x-amz-trailer" fehl. - Ursache: boto3 1.36.0 und spätere Versionen senden Prüfsummen-Trailer, die Object Storage noch nicht unterstützt.
- Lösung:
AWS_REQUEST_CHECKSUM_CALCULATION=when_requiredundAWS_RESPONSE_CHECKSUM_VALIDATION=when_requiredsetzen, oderboto3<=1.35.99auf eine bestimmte Version festlegen (Abschnitt 1.2).
- Problem:
-
SignatureDoesNotMatch bei presignierten Uploads
- Problem: Das
PUTdes Browsers liefert403mitSignatureDoesNotMatch. - Ursache: Der Browser sendet ein anderes
Content-Typeals das unterzeichnete, oder die URL wurde gegen einen anderen Endpunkt oder eine andere Region signiert. - Lösung: Die signierten Header zusammen mit der URL zurückgeben und unverändert senden; mit dem regionalen Endpunkt des Buckets signieren.
- Problem: Das
-
Warten auf eine AWS-Funktion, die nicht vorhanden ist
- Problem: Code, der
put_bucket_notification_configurationaufruft, oder eine Lifecycle-Regel mitTransitions, schlägt fehl. - Ursache: Bucket Notifications werden nicht unterstützt, und es existiert nur die
STANDARD-Speicherklasse. - Lösung: Zuerst die Kompatibilitätstabelle (Abschnitt 5) prüfen; einen expliziten Bestätigungsaufruf anstelle von Ereignissen und eine Ablaufzeit anstelle von Übergängen verwenden.
- Problem: Code, der
Zusammenfassung
Sie können IONOS Cloud Object Storage nun auf die S3-Art in TaskBoard integrieren, mit den Besonderheiten von IONOS CLOUD. Der boto3-Client erhält einen expliziten regionalen Endpunkt sowie einen Access Key und einen Secret Key. Browser laden über presigned URLs hoch und herunter, sodass die API die Bytes nie weiterleitet, und große Dateien verwenden den Multipart-Upload. Lifecycle-Regeln löschen temporäre Dateien und aufgegebenen Uploads, und Sie prüfen die Kompatibilitätstabelle, bevor Sie eine nur für AWS verfügbare Funktion verwenden.
Wichtige Punkte:
- Setzen Sie immer
endpoint_url; authentifizieren Sie sich mit einem Access Key und einem Secret Key, niemals mit einem Bearer Token - Setzen Sie die beiden Prüfsummenvariablen oder fixieren Sie boto3 auf eine Version unter 1.36.0
- Presigned URLs werden lokal signiert; der Signierungsschlüssel muss dem Bucket-Besitzer oder einem Administrator gehören
- Verwenden Sie den Multipart-Upload über dem Limit für einzelne Anfragen; fügen Sie eine Regel hinzu, die unvollständige Uploads abbricht
- Lifecycle-Regeln verfallen und löschen Objekte; es gibt keine Übergangsregeln
Wichtige Begriffe:
- Access Key und Secret Key: Das Zugangsdatenpaar, das jede S3-Anfrage signiert; nicht an eine Region oder ein Bucket gebunden
- Presigned URL: Eine URL, die eine zeitlich begrenzte Signatur für eine Operation an einem Objekt trägt
- Vertragszugehöriger Bucket: Ein Bucket, dem der Vertragsinhaber gehört, in
eu-central-3,eu-central-4oderus-central-1 - Multipart-Upload: Ein Upload, der in Teile aufgeteilt wird, die separat gesendet und dann zu einem Objekt zusammengeführt werden
- Lifecycle-Regel: Eine Bucket-Regel, die Objekte, nicht aktuelle Versionen oder unvollständige Uploads nach einer festgelegten Zeit verfallen lässt und löscht
Nächste Schritte
Weiter lernen: Einheit 4.3: Event Streaming Integration
Verwandte Themen: