13 Min. Lesezeit

Lernziele

Am Ende dieses Moduls werden Sie in der Lage sein:

  • boto3 mit einem regionalen IONOS Cloud Object Storage-Endpunkt, einem Access Key und einem Secret Key konfigurieren
  • Presigned Upload- und Download-URLs implementieren, damit Browser TaskBoard-Anhänge direkt übertragen
  • Große Dateien mit Multipart Upload hochladen und Downloads mit den richtigen Content-Typen streamen
  • Lifecycle-Regeln über die S3 API automatisieren, um temporäre Objekte und abgebrochene Uploads zu verfallen lassen
  • Die S3-Funktionsunterstützung prüfen, bevor Sie eine AWS-spezifische API in Ihrem Code verwenden

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 boto3 und requests
  • curl und 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 PUT werden 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:

  1. InvalidTrailer bei jedem Upload

    • Problem: put_object und upload_file schlagen 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_required und AWS_RESPONSE_CHECKSUM_VALIDATION=when_required setzen, oder boto3<=1.35.99 auf eine bestimmte Version festlegen (Abschnitt 1.2).
  2. SignatureDoesNotMatch bei presignierten Uploads

    • Problem: Das PUT des Browsers liefert 403 mit SignatureDoesNotMatch.
    • Ursache: Der Browser sendet ein anderes Content-Type als 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.
  3. Warten auf eine AWS-Funktion, die nicht vorhanden ist

    • Problem: Code, der put_bucket_notification_configuration aufruft, oder eine Lifecycle-Regel mit Transitions, 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.

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-4 oder us-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: