Version: Weekly Build

Object Storage

Object Storage stellt eine S3-kompatible API für Dateien, Backups, Assets und andere unstrukturierte Daten bereit. Es ist für Workloads gedacht, die Bucket-basierten Objektspeicher anstelle eines Dateisystems oder einer relationalen Datenbank benötigen.

Eigenschaft	Wert	Hinweise
Provider-Name	`s3`	Wird in Landscape-Provider-Definitionen verwendet.
Version	`v1`	Aktuelle, vom Provider bereitgestellte Schema-Version.
Kategorie	`Storage`	Wird im Managed-Services-Katalog angezeigt.
Scope	`global`	Verfügbar auf Resource-Group-Ebene statt an eine einzelne Workspace-Runtime gebunden zu sein.
Resource-Group-Singleton	`false`	Resource Groups können mehrere Object-Storage-Serviceinstanzen erstellen.
Pause-Unterstützung	`false`	Dieser Provider unterstützt kein Pausieren.

Preview-Feature

Dieser Provider ist derzeit ein Preview-Feature. Er ist standardmäßig nicht aktiviert und muss vom Betreiber aktiviert werden. Als Preview entwickelt sich der Provider noch weiter – sein Schema, seine Pläne und sein Verhalten können sich in Zukunft ändern.

Fähigkeiten

Der Service ist hochverfügbar: Der zugrunde liegende Ceph-Storage ist redundant aufgebaut und auf Storage-Ebene repliziert.

Fähigkeit	Unterstützt	Hinweise
Backups	✅	Backups von Bucket-Daten werden für S3-kompatible Backup-Stores unterstützt.
Point-in-Time Recovery	❌	Nicht unterstützt. Ein bestimmtes Backup kann wiederhergestellt werden, jedoch nicht ein beliebiger Zeitpunkt.

Schema

Konfiguration

Feld	Typ	Bei Erstellung erforderlich	Hinweise
`accessKey`	`string`	Ja	Clusterweit eindeutiger Access Key. Muss genau 20 Großbuchstaben oder Ziffern enthalten. Kann im Erstellungsdialog generiert werden.
`userDisplayName`	`string`	Nein	Standard: `My S3 User`. Anzeigename für den generierten Benutzer.
`initialBucketName`	`string`	Ja	Clusterweit eindeutiger initialer Bucket-Name. Falls dieser bereits vergeben ist, wird der Bucket nicht erstellt.

Secrets

Feld	Typ	Bei Erstellung erforderlich	Hinweise
`secretKey`	`string`	Ja	Geheimer Zugriffsschlüssel. Muss genau 40 alphanumerische Zeichen enthalten.

Details / Ausgabe

Feld	Typ	Verfügbarkeit	Hinweise
`url`	`string`	Nach der Bereitstellung verfügbar	S3-kompatible Endpoint-URL. Bei von Codesphere verwaltetem S3 ist dies immer `http://rgw-load-balancer.rook-ceph.svc.cluster.local`.
`userId`	`string`	Nach der Bereitstellung verfügbar	Interne Kennung des generierten Object-Storage-Benutzers.

Plan

Der Provider stellt einen Plan bereit, Generic (id: 0), bei dem alle Quota-Parameter angepasst werden können. Beispielplan: Generic (id: 0).

Parameter	Typ	Standard	Minimum	Maximum	Statisch	Hinweise
`maxBuckets`	`integer`	`50`	`1`	`1000`	Nein	Maximale Anzahl an Buckets.
`maxObjects`	`integer`	`100000`	`1`	`10000000`	Nein	Maximale Anzahl an Objekten.
`maxSizeKb`	`integer`	`10000000`	`1`	`10000000000`	Nein	Gesamtgrößenlimit in KB.
`maxReadOpsPerS`	`integer`	`1000`	`1`	`10000`	Nein	Maximale Lesevorgänge pro Sekunde.
`maxWriteOpsPerS`	`integer`	`1000`	`1`	`10000`	Nein	Maximale Schreibvorgänge pro Sekunde.
`maxReadBytesPerS`	`integer`	`100000000`	`1`	`10000000000`	Nein	Maximaler Lesedurchsatz in Byte pro Sekunde.
`maxWriteBytesPerS`	`integer`	`100000000`	`1`	`10000000000`	Nein	Maximaler Schreibdurchsatz in Byte pro Sekunde.

Beispiel in einer Landscape

schemaVersion: v0.2

run:
  uploads:
    provider:
      name: s3
      version: v1
    plan:
      id: 0
      parameters:
        maxBuckets: 50
        maxObjects: 100000
        maxSizeKb: 10000000
        maxReadOpsPerS: 1000
        maxWriteOpsPerS: 1000
        maxReadBytesPerS: 100000000
        maxWriteBytesPerS: 100000000
    config:
      accessKey: "${{ workspace.env.S3_ACCESS_KEY }}"
      userDisplayName: "Landscape Upload User"
      initialBucketName: "${{ workspace.env.S3_BUCKET }}"
    secrets:
      secretKey: "${{ vault.s3SecretKey }}"

Konfiguriere innerhalb anderer Runtimes den S3-Client mit der zurückgegebenen url, dem konfigurierten accessKey und dem gespeicherten secretKey. Bei von Codesphere verwaltetem S3 ist der Endpoint immer http://rgw-load-balancer.rook-ceph.svc.cluster.local. Derselbe S3-kompatible Endpoint ist auch von anderen Codesphere-Runtimes aus verfügbar, einschließlich Reactives, Managed Containers und Workloads innerhalb eines Virtual Cluster.

Backups

Der Object-Storage-Provider unterstützt automatisierte Backups und Wiederherstellung auf einen anderen S3-kompatiblen Backup-Store. Die allgemeinen Konzepte sind in Managed Service Backups beschrieben.

Im Hintergrund synchronisiert ein Backup die Buckets mit einem versionierten Ziel-Bucket im Backup-Store, wobei S3-Objektversionierung genutzt wird, um historische Kopien jedes Objekts vorzuhalten. Bei einer Wiederherstellung werden die Objektversionen zum Zeitpunkt eines bestimmten Backups in den neuen Service kopiert.

Backups sind inkrementell: Nach dem ersten Backup werden nur Objekte synchronisiert, die seit dem vorherigen Backup hinzugefügt, geändert oder entfernt wurden. Dadurch bleiben regelmäßige Backups schnell und speichereffizient, unabhängig davon, wie viele Daten bereits in den Buckets vorhanden sind. Ein entferntes Objekt wird nicht aus dem Verlauf des Backup-Stores gelöscht; es wird im Ziel-Bucket mit einem Delete-Marker versehen, sodass frühere Versionen weiterhin verfügbar bleiben, während zukünftige Backups abbilden, dass es entfernt wurde. Da jedes Objekt unabhängig und nicht als einzelne atomare Operation synchronisiert wird, garantiert ein Backup keine objektübergreifende Konsistenz – werden Objekte geschrieben, während ein Backup läuft, kann es manche davon vor und andere nach der Änderung erfassen.

Backups aktivieren

Backups können entweder beim Erstellen eines neuen Object-Storage-Services oder durch Aktualisieren eines bestehenden Services aktiviert werden, sowohl über die UI als auch über die API. Das folgende Beispiel aktiviert Backups für einen bestehenden Service; derselbe backups-Block funktioniert auch beim Erstellen eines neuen Services mit POST /managed-services.

curl -X PATCH "https://api.codesphere.com/managed-services/YOUR_SERVICE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "backups": {
      "enabled": true,
      "intervalH": 12,
      "deleteRetentionDays": 30,
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "path": "my-codesphere-backups/",
        "accessKeyId": "YOUR_S3_ACCESS_KEY"
      },
      "secrets": {
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    }
  }'

Erforderliche S3-Berechtigungen

Die Zugangsdaten (Access Key und Secret Key), die für den Zugriff auf den S3-kompatiblen Backup-Store verwendet werden, müssen über ausreichende Berechtigungen verfügen, um den Ziel-Bucket zu erstellen, dessen Versionierung und Lifecycle-Konfiguration zu verwalten sowie Objekte darin zu lesen, zu schreiben und zu löschen. Bei AWS S3 bedeutet dies, dass der mit dem Access Key verknüpfte IAM-Benutzer oder die IAM-Rolle mindestens über die folgenden Berechtigungen verfügen muss.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BucketLevelOperations",
      "Effect": "Allow",
      "Action": [
        "s3:CreateBucket",
        "s3:ListBucket",
        "s3:GetBucketVersioning",
        "s3:PutBucketVersioning",
        "s3:GetLifecycleConfiguration",
        "s3:PutLifecycleConfiguration"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
    },
    {
      "Sid": "ObjectLevelOperations",
      "Effect": "Allow",
      "Action": [
        "s3:AbortMultipartUpload",
        "s3:DeleteObject",
        "s3:GetObject",
        "s3:ListMultipartUploadParts",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    }
  ]
}

Keine verifizierte Minimalrichtlinie

Diese Liste wurde aus den Operationen abgeleitet, die die Backup-Implementierung gegenüber dem Ziel-Bucket ausführt. Sie wurde jedoch nicht end-to-end als minimal funktionierende Richtlinie getestet – sie kann umfangreicher sein als unbedingt notwendig und ist nicht dieselbe Richtlinie wie die für PostgreSQL-Backups verwendete. Wenn eine kleinere, funktionierende Richtlinie gefunden wird, teile uns dies bitte mit, damit diese Liste verschärft werden kann.

Wiederherstellung aus einem Backup

Eine Wiederherstellung erstellt immer einen neuen Object-Storage-Service; der bestehende Service bleibt unverändert. Gib das wiederherzustellende Backup mit recoverFrom.id an:

curl -X POST "https://api.codesphere.com/managed-services" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceGroupId": 123,
    "name": "my-object-storage-recovered",
    "provider": {
      "name": "s3",
      "version": "v1"
    },
    "plan": {
      "id": 0
    },
    "config": {
      "accessKey": "YOUR_NEW_ACCESS_KEY",
      "initialBucketName": "my-bucket"
    },
    "secrets": {
      "secretKey": "YOUR_NEW_SECRET_KEY"
    },
    "recoverFrom": {
      "id": "BACKUP_UUID_HERE",
      "config": {
        "endpointUrl": "https://s3.eu-central-1.amazonaws.com",
        "path": "my-codesphere-backups/",
        "accessKeyId": "YOUR_S3_ACCESS_KEY"
      },
      "secrets": {
        "secretKey": "YOUR_S3_SECRET_KEY"
      }
    }
  }'

Haftungsausschlüsse und Einschränkungen zu Backups

Google Cloud Storage: Backups und Wiederherstellungen funktionieren mit einem Google Cloud Storage (GCS) Backup-Store, aber die automatische Aufbewahrung (deleteRetentionDays) wird gegenüber einem GCS-basierten Store noch nicht durchgesetzt, und das Löschen eines einzelnen Backups wird ebenfalls noch nicht unterstützt. Dies ist eine Einschränkung von GCS selbst und nicht eines bestimmten Endpoints: GCS stellt eine andere, nicht S3-kompatible Lifecycle-/Versionierungs-API bereit, sodass dies unabhängig davon gilt, auf welchen GCS-Endpoint die endpointUrl des Backup-Stores verweist.
Keine Kompression: Backup-Daten werden unverändert übertragen und gespeichert, ohne zusätzliche Kompression.

Verbindung zu einem Object Store herstellen

Voraussetzungen

Sobald der Object Store bereitgestellt ist, kann eine Verbindung von den Codesphere-Workspaces aus hergestellt werden. Jeder Service listet nicht sensible Verbindungsdetails auf der jeweiligen Einstellungsseite im Übersichtstab auf (bzw. in der details-Eigenschaft im Payload der öffentlichen API).

info

Stelle vor der Verbindung sicher, dass der Service synchronisiert ist.

Verbindung über die AWS CLI

Die AWS CLI funktioniert mit Object Storage, benötigt jedoch die Checksummeneinstellungen, die unter S3-Client-Checksummeneinstellungen beschrieben sind:

export AWS_ENDPOINT_URL="http://rgw-load-balancer.rook-ceph.svc.cluster.local"
export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_KEY"
export AWS_REQUEST_CHECKSUM_CALCULATION=when_required
export AWS_RESPONSE_CHECKSUM_VALIDATION=when_required

# Buckets auflisten
aws s3 ls

# Datei kopieren
aws s3 cp myfile.txt s3://my-bucket/

# Verzeichnis synchronisieren
aws s3 sync ./my-dir s3://my-bucket/my-dir

Anstatt die beiden Checksummen-Variablen in jeder Shell zu exportieren, können sie einmalig in ~/.aws/config gesetzt werden:

[default]
request_checksum_calculation = when_required
response_checksum_validation = when_required

Wenn Codesphere stattdessen in einem benannten Profil verwendet wird, platziere die beiden Schlüssel unter [profile <name>] und wähle das Profil mit --profile <name> oder AWS_PROFILE=<name> aus.

S3-Client-Checksummeneinstellungen

Seit botocore 1.36.0 — enthalten in AWS CLI v2.23 und später — sowie den entsprechenden Versionen der AWS SDKs berechnen AWS-Clients standardmäßig (when_supported) bei jedem Upload eine CRC32-Prüfsumme und validieren Antwort-Prüfsummen. Object Storage gibt die Prüfsummenmetadaten, die diese Clients dann erwarten, nicht zurück, sodass bei der Standardeinstellung Uploads mit Fehlern wie folgt fehlschlagen:

upload failed: ./myfile.txt to s3://my-bucket/myfile.txt
  argument of type 'NoneType' is not a container or iterable

Das Umstellen beider Einstellungen auf when_required stellt das frühere Opt-in-Verhalten wieder her und behebt dies. Prüfsummen werden weiterhin für Operationen gesendet, die tatsächlich eine benötigen, wie etwa DeleteObjects.

hinweis

Dies ist nicht spezifisch für Codesphere. Dieselbe Einstellung wird im Allgemeinen auch für nicht von AWS stammende, S3-kompatible Endpoints benötigt, und jedes AWS SDK stellt sie unter einem eigenen Namen bereit — zum Beispiel request_checksum_calculation in der gemeinsam genutzten AWS-Konfigurationsdatei, requestChecksumCalculation im JavaScript SDK und RequestChecksumCalculation im Go SDK.

Verbindung über das Terminal (`mc`)

Der MinIO Client (mc) ist ein robustes Tool für die Interaktion mit S3-kompatiblen APIs.

# mc installieren
nix-env -iA nixpkgs.minio-client

# Alias konfigurieren
mc alias set my-storage http://rgw-load-balancer.rook-ceph.svc.cluster.local "$ACCESS_KEY" "$SECRET_KEY"

# Buckets auflisten
mc ls my-storage

# Datei kopieren
mc cp myfile.txt my-storage/my-bucket/

Verbindung über Node.js

Verwendung des AWS SDK für JavaScript v3 (@aws-sdk/client-s3):

const { S3 } = require("@aws-sdk/client-s3");

const s3 = new S3({
    endpoint: "http://rgw-load-balancer.rook-ceph.svc.cluster.local",
    region: "us-east-1",
    credentials: {
        accessKeyId: "YOUR_ACCESS_KEY",
        secretAccessKey: "YOUR_SECRET_KEY"
    },
    forcePathStyle: true,
    tls: false,
    // Siehe „S3-Client-Checksummeneinstellungen" oben.
    requestChecksumCalculation: "WHEN_REQUIRED",
    responseChecksumValidation: "WHEN_REQUIRED"
});

const { Buckets } = await s3.listBuckets({});
console.log(Buckets);

Fähigkeiten​

Schema​

Konfiguration​

Secrets​

Details / Ausgabe​

Plan​

Beispiel in einer Landscape​

Backups​

Backups aktivieren​

Erforderliche S3-Berechtigungen​

Wiederherstellung aus einem Backup​

Haftungsausschlüsse und Einschränkungen zu Backups​

Verbindung zu einem Object Store herstellen​

Voraussetzungen​

Verbindung über die AWS CLI​

S3-Client-Checksummeneinstellungen​

Verbindung über das Terminal (mc)​

Verbindung über Node.js​