Version: Weekly Build

Object Storage

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

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.
Geltungsbereich	`global`	Auf Team-Ebene verfügbar, statt an eine einzelne Workspace-Runtime gebunden zu sein.
Team-Singleton	`false`	Teams können mehrere Object-Storage-Serviceinstanzen erstellen.
Pause-Unterstützung	`false`	Dieser Provider unterstützt kein Pausieren.

Preview-Funktion

Dieser Provider ist derzeit eine Preview-Funktion. Er ist standardmäßig nicht aktiviert und muss vom Operator aktiviert werden. Als Preview entwickelt sich der Provider noch weiter; sein Schema, seine Pläne und sein Verhalten können sich zukünftig ändern.

Funktionen

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

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

Schema

Config

Feld	Typ	Erforderlich bei Erstellung	Hinweise
`accessKey`	`string`	Ja	Clusterweit eindeutiger Access-Key. Muss exakt aus 20 Großbuchstaben oder Ziffern bestehen.
`userDisplayName`	`string`	Nein	Standard: `My S3 User`. Anzeigename des erzeugten Nutzers.
`initialBucketName`	`string`	Ja	Clusterweit eindeutiger Name des initialen Buckets. Ist er bereits vergeben, wird der Bucket nicht erstellt.

Secrets

Feld	Typ	Erforderlich bei Erstellung	Hinweise
`secretKey`	`string`	Ja	Geheimer Access-Key. Muss exakt aus 40 alphanumerischen Zeichen bestehen.

Details / Ausgabe

Feld	Typ	Verfügbarkeit	Hinweise
`url`	`string`	Nach Provisionierung 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 Provisionierung verfügbar	Interner Bezeichner des erzeugten Object-Storage-Nutzers.

Plan

Der Provider stellt einen Plan bereit, Generic (id: 0), bei dem alle Quotenparameter 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 Leseoperationen pro Sekunde.
`maxWriteOpsPerS`	`integer`	`1000`	`1`	`10000`	Nein	Maximale Schreiboperationen 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 }}"

In anderen Runtimes konfiguriert man 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 in einen anderen S3-kompatiblen Backup-Speicher. Die allgemeinen Konzepte werden unter Managed Service Backups beschrieben.

Im Hintergrund synchronisiert ein Backup die Buckets mit einem versionierten Ziel-Bucket im Backup-Speicher, wobei S3-Objektversionierung genutzt wird, um historische Kopien jedes Objekts vorzuhalten. Bei der 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. So bleiben regelmäßige Backups schnell und speichereffizient, unabhängig davon, wie viele Daten sich bereits in den Buckets befinden. Ein entferntes Objekt wird nicht aus dem Verlauf des Backup-Speichers 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 widerspiegeln, dass es entfernt wurde. Da jedes Objekt unabhängig synchronisiert wird und nicht als eine einzige atomare Operation, garantiert ein Backup keine objektübergreifende Konsistenz — werden Objekte während eines laufenden Backups geschrieben, kann es sein, dass manche vor und andere nach der Änderung erfasst werden.

Backups aktivieren

Backups können bei der Erstellung eines neuen Object-Storage-Service oder durch Aktualisieren eines bestehenden Service aktiviert werden, entweder über die Benutzeroberfläche oder über die API. Das folgende Beispiel aktiviert Backups für einen bestehenden Service; derselbe backups-Block funktioniert auch beim Erstellen eines neuen Service 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-Speicher verwendet werden, müssen ausreichende Berechtigungen besitzen, um den Ziel-Bucket zu erstellen, dessen Versionierung und Lifecycle-Konfiguration zu verwalten sowie Objekte darin zu lesen, zu schreiben und zu löschen. Für AWS S3 bedeutet das, dass der IAM-Benutzer oder die IAM-Rolle, die mit dem Access-Key verknüpft ist, mindestens die folgenden Berechtigungen benötigt.

{
  "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 durchführt. Sie wurde jedoch nicht end-to-end als minimal funktionierende Richtlinie getestet — sie könnte umfangreicher sein als unbedingt notwendig, und sie ist nicht identisch mit der Richtlinie, die für PostgreSQL-Backups verwendet wird. Wenn eine kleinere, funktionierende Richtlinie gefunden wird, gerne mitteilen, damit diese Liste eingeschränkt werden kann.

Wiederherstellung aus einem Backup

Eine Wiederherstellung erzeugt immer einen neuen Object-Storage-Service; der bestehende Service bleibt unverändert. Das Backup, aus dem wiederhergestellt werden soll, wird mit recoverFrom.id angegeben:

curl -X POST "https://api.codesphere.com/managed-services" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 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 bei Backups

Google Cloud Storage: Backups und Wiederherstellungen funktionieren mit einem Google Cloud Storage (GCS)-Backup-Speicher, jedoch wird automatische Aufbewahrung (deleteRetentionDays) für einen GCS-basierten Speicher 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-Speichers verweist.
Keine Kompression: Backup-Daten werden unverändert übertragen und gespeichert, ohne zusätzliche Komprimierung.

Verbindung zu einem Object Store herstellen

Voraussetzungen

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

info

Vor dem Verbinden sicherstellen, dass der Service synchronisiert ist.

Verbindung über die AWS CLI

Die AWS CLI funktioniert mit Object Storage, benötigt jedoch die in S3-Client-Checksummeneinstellungen beschriebenen Checksummeneinstellungen:

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

Wird Codesphere stattdessen in einem benannten Profil verwendet, sind die beiden Schlüssel unter [profile <name>] einzutragen und mit --profile <name> oder AWS_PROFILE=<name> auszuwählen.

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 eine CRC32-Prüfsumme bei jedem Upload und validieren Antwort-Prüfsummen (when_supported). Object Storage liefert die Prüfsummen-Metadaten, die diese Clients dann erwarten, nicht zurück, sodass Uploads bei der Standardeinstellung 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

Werden beide Einstellungen auf when_required umgestellt, wird das frühere Opt-in-Verhalten wiederhergestellt und das Problem behoben. Prüfsummen werden weiterhin für die Operationen gesendet, die tatsächlich eine benötigen, wie z. B. 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 gemeinsamen AWS-Konfigurationsdatei, requestChecksumCalculation im JavaScript-SDK und RequestChecksumCalculation im Go-SDK.

Verbindung über das Terminal (`mc`)

Der MinIO Client (mc) ist ein robustes Werkzeug 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);

Preview-Funktion

Funktionen​

Schema​

Config​

Secrets​

Details / Ausgabe​

Plan​

Beispiel in einer Landscape​

Backups​

Backups aktivieren​

Erforderliche S3-Berechtigungen​