diff --git a/content/de/developer/integration/index.md b/content/de/developer/integration/index.md index e2b9514d..d363aff6 100644 --- a/content/de/developer/integration/index.md +++ b/content/de/developer/integration/index.md @@ -1,6 +1,6 @@ --- title: "Integration" -description: "Integrieren Sie RustFS mit Reverse Proxies, Backup-Tools, Datenanalyse-Systemen und Observability-Plattformen." +description: "Integrieren Sie RustFS mit Reverse Proxies, Backup-Tools, Datenanalyse-Systemen, Observability-Plattformen und Container-Registries." --- Use this section to connect **RustFS** to infrastructure and application platforms through its S3-compatible API. @@ -12,5 +12,7 @@ Use this section to connect **RustFS** to infrastructure and application platfor - [Datenanalyse](./big-data/index.md) covers Iceberg. - [Observability](./observability/index.md) covers OpenObserve. - [Others](./others/index.md) covers the community-driven capo SDK for Python. +- [Registry](./registry/index.md) covers Harbor. +- [Registry](./registry/index.md) covers Harbor. Each guide identifies the RustFS endpoint and addressing requirements to use when configuring the integrating system. \ No newline at end of file diff --git a/content/de/developer/integration/meta.json b/content/de/developer/integration/meta.json index e8db4e78..88d4e064 100644 --- a/content/de/developer/integration/meta.json +++ b/content/de/developer/integration/meta.json @@ -5,6 +5,7 @@ "backup", "big-data", "observability", - "others" + "others", + "registry" ] } diff --git a/content/de/developer/integration/registry/harbor.md b/content/de/developer/integration/registry/harbor.md new file mode 100644 index 00000000..b6b429dd --- /dev/null +++ b/content/de/developer/integration/registry/harbor.md @@ -0,0 +1,279 @@ +--- +title: "Harbor" +description: "Speichern Sie über Harbor gepushte Container-Images in RustFS-Objektspeicher über den S3-Storage-Treiber der Registry, bereitgestellt mit Docker Compose." +--- + +Diese Anleitung verbindet [Harbor](https://github.com/goharbor/harbor) — die CNCF-graduierte Cloud-native-Registry — mit **RustFS**. Harbor persistiert Image-Layer, Manifeste und andere OCI-Artefakte über seine eingebettete Registry-Komponente, die den S3-Storage-Treiber des [distribution](https://distribution.github.io/distribution/)-Projekts implementiert. Sie betreiben diese Registry-Komponente mit Docker Compose gegen RustFS, pushen ein Image, pullen es zurück und prüfen die Objekte in RustFS. Dasselbe Speicher-Setup gilt für eine vollständige Harbor-Bereitstellung. Der Ablauf wurde mit `goharbor/registry-photon:v2.12.2` und `rustfs/rustfs-x86-musl:v2.3.1` verifiziert. + +Sie benötigen Docker mit dem Compose-Plugin. Dieses Setup ist für lokale Integrationstests gedacht, nicht für den Produktivbetrieb. + +## Architektur + +```mermaid +flowchart LR + Client["Docker client"] -->|"push / pull"| Registry["Harbor registry component :5000"] + Registry -->|"S3 PUT / GET"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +Die Registry speichert alle Blobs, Manifeste und Repository-Links über den S3-Storage-Treiber unterhalb von `docker/registry/v2/` im Bucket. Die Treibereinstellungen `regionendpoint`, `secure: false` und `skipverify: true` richten den von der Registry verwendeten AWS-S3-Client auf den RustFS-Endpunkt mit Path-Style-Adressierung über Plain HTTP aus. + +## 1. Projektdateien anlegen + +Erstellen Sie ein Arbeitsverzeichnis: + +```bash +mkdir rustfs-harbor +cd rustfs-harbor +``` + +Erstellen Sie eine Umgebungsdatei und ersetzen Sie beide Platzhalter für die Anmeldeinformationen: + +```ini title=".env" +RUSTFS_ACCESS_KEY= +RUSTFS_SECRET_KEY= +``` + +Verwenden Sie dedizierte Anmeldeinformationen für den Bucket. Committen Sie `.env` nicht in die Versionsverwaltung. + +Erstellen Sie die Registry-Konfiguration, die Harbor für seine Registry-Komponente verwendet: + +```yaml title="config.yml" +version: 0.1 +log: + level: info +storage: + s3: + accesskey: + secretkey: + region: us-east-1 + regionendpoint: http://rustfs:9000 + bucket: my-bucket + secure: false + skipverify: true + delete: + enabled: true + redirect: + disable: true +http: + addr: 0.0.0.0:5000 +health: + storagedriver: + enabled: true + interval: 10s + threshold: 3 +``` + +`regionendpoint` leitet den Treiber zu RustFS statt zu AWS, `secure: false` wählt Plain HTTP innerhalb des Compose-Netzwerks, und `redirect.disable: true` lässt die Registry die Blobs selbst ausliefern — Harbor setzt dieselbe Option für Backends ohne Redirect-Unterstützung. + +Erstellen Sie die Compose-Datei: + +```yaml title="compose.yaml" +services: + rustfs: + image: rustfs/rustfs-x86-musl:v2.3.1 + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + RUSTFS_VOLUMES: /data + RUSTFS_ADDRESS: ":9000" + RUSTFS_CONSOLE_ADDRESS: ":9001" + RUSTFS_CONSOLE_ENABLE: "true" + volumes: + - rustfs-data:/data + ports: + - "9000:9000" + - "9001:9001" + healthcheck: + test: ["CMD", "curl", "-sf", "http://127.0.0.1:9000/health"] + interval: 10s + timeout: 5s + retries: 6 + start_period: 10s + networks: + - registry + + create-bucket: + image: rustfs/rc:latest + depends_on: + rustfs: + condition: service_healthy + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + entrypoint: + - /bin/sh + - -c + - | + until /usr/bin/rc alias set rustfs http://rustfs:9000 "$${RUSTFS_ACCESS_KEY}" "$${RUSTFS_SECRET_KEY}"; do + echo "Waiting for RustFS..." + sleep 2 + done + /usr/bin/rc ls rustfs/my-bucket >/dev/null 2>&1 || /usr/bin/rc mb rustfs/my-bucket + networks: + - registry + + registry: + image: goharbor/registry-photon:v2.12.2 + volumes: + - ./config.yml:/etc/registry/config.yml:ro + ports: + - "5000:5000" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - registry + +networks: + registry: + +volumes: + rustfs-data: +``` + +Das [`rc`-Image](https://github.com/rustfs/cli) stellt den offiziellen RustFS-Kommandozeilenclient bereit. Der Initialisierer prüft vor dem Anlegen, ob `my-bucket` bereits existiert, sodass wiederholte Starts keine bestehenden Artefakte löschen. + +## 2. Bereitstellung starten + +Prüfen Sie die Compose-Datei, bevor Sie Container starten: + +```bash +docker compose config +``` + +Starten Sie die Dienste und warten Sie, bis die Bucket-Initialisierung abgeschlossen ist: + +```bash +docker compose up -d +docker compose ps -a +``` + +Die Registry-API sollte mit einem leeren Katalog antworten: + +```bash +curl -s http://localhost:5000/v2/_catalog +``` + +```text +{"repositories":[]} +``` + +## 3. Ein Image pushen + +Pullen Sie ein kleines Image, taggen Sie es für die lokale Registry um und pushen Sie es: + +```bash +docker pull busybox:latest +docker tag busybox:latest localhost:5000/demo/app:v1 +docker push localhost:5000/demo/app:v1 +``` + +```text +v1: digest: sha256:1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8 size: 527 +``` + +## 4. Das Image zurückpullen + +Entfernen Sie die lokalen Tags und pullen Sie das Image aus der Registry — die Layer kommen jetzt aus RustFS: + +```bash +docker rmi localhost:5000/demo/app:v1 +docker pull localhost:5000/demo/app:v1 +``` + +```text +localhost:5000/demo/app:v1 +``` + +## 5. Objekte in RustFS prüfen + +Listen Sie das Repository-Präfix über das Bucket-Initialisierungs-Image auf: + +```bash +docker compose run --rm --entrypoint /bin/sh create-bucket -c \ + '/usr/bin/rc alias set rustfs http://rustfs:9000 "$RUSTFS_ACCESS_KEY" "$RUSTFS_SECRET_KEY" >/dev/null && /usr/bin/rc ls rustfs/my-bucket/docker/registry/v2/repositories/demo --recursive' +``` + +```text +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/b05093807bb0294152bb9cf86d64da722732dddaf7f8882fa1f120477dbc4db3/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/c6348fa86ba0fb2108c9334f5fe913ddc6d853313e655891f133a0127c30099f/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/revisions/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/current/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/index/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +``` + +Die Blob-Payloads selbst liegen unterhalb von `docker/registry/v2/blobs/`. Sie können das Präfix auch in der RustFS-Konsole unter `http://localhost:9001/rustfs/console/` anzeigen: + +![Die Repository-Metadaten des gepushten Images in der RustFS-Konsole](./images/rustfs-harbor-objects.png) + +## 6. RustFS in einer vollständigen Harbor-Bereitstellung verwenden + +Die oben verifizierte Registry-Komponente ist dieselbe, die eine vollständige Harbor-Bereitstellung ausführt — die Speichereinstellungen lassen sich daher direkt übernehmen. + +Setzen Sie im Helm-Chart die S3-Optionen unter `persistence.imageChartStorage`: + +```yaml title="values.yaml" +persistence: + imageChartStorage: + type: s3 + disableredirect: true + s3: + region: us-east-1 + bucket: my-bucket + accesskey: + secretkey: + regionendpoint: http://rustfs:9000 + secure: false + skipverify: true +``` + +Legen Sie beim Harbor-Installer mit einer `harbor.yml`-Datei dieselben Treiberschlüssel unter `storage_service.s3` ab. Beide Dateien akzeptieren die Storage-Treiber-Optionen, die im [distribution-Projekt](https://distribution.github.io/distribution/about/configuration/) dokumentiert sind — genau diese Konfigurationsoberfläche wurde in dieser Anleitung verifiziert. + +## 7. Stack stoppen oder zurücksetzen + +Stoppen Sie die Container und behalten Sie das RustFS-Datenvolumen: + +```bash +docker compose down +``` + +Um die gespeicherten Artefakte zu löschen und mit einem leeren RustFS-Volumen zu beginnen, fügen Sie ausdrücklich `--volumes` hinzu: + +```bash +docker compose down --volumes +``` + +## Fehlerbehebung + +### Die Registry startet nicht oder meldet einen Storage-Fehler + +Prüfen Sie die Registry-Logs auf Meldungen des S3-Treibers: + +```bash +docker compose logs registry +``` + +`regionendpoint` muss aus dem Registry-Container erreichbar sein. Verwenden Sie innerhalb des Compose-Netzwerks `http://rustfs:9000`; für einen Prozess auf dem Host `http://localhost:9000`. + +### TLS- oder Zertifikatsfehler mit einem Plain-HTTP-Endpunkt + +`secure: false` wählt Plain HTTP für den RustFS-Endpunkt. Ohne diese Einstellung versucht der Treiber HTTPS und schlägt mit einem Verbindungs- oder Zertifikatsfehler fehl. Bei einem TLS-Endpunkt mit selbstsigniertem Zertifikat belassen Sie `secure: true`, setzen `skipverify: true` und stellen das CA-Bundle über die `ca_bundle`-Option bereit, die Harbor in `harbor.yml` anbietet. + +### AccessDenied- oder 403-Antworten + +Stellen Sie sicher, dass die Anmeldeinformationen in `config.yml` mit den RustFS-Anmeldeinformationen übereinstimmen und dass der Dienst `create-bucket` erfolgreich abgeschlossen wurde: + +```bash +docker compose logs create-bucket +``` + +### Der Push ist erfolgreich, aber Objekte erscheinen nicht im erwarteten Präfix + +Der Treiber schreibt unterhalb von `docker/registry/v2/` im Bucket. Listen Sie den gesamten Bucket rekursiv auf, um den Repository-Baum zu finden, bevor Sie ein Konfigurationsproblem annehmen. + +## Nächste Schritte + +- Lesen Sie die [S3-Kompatibilitätshinweise](/administration/protocols/s3), bevor Sie weitere S3-Operationen verwenden. +- Erstellen Sie dedizierte Produktions-Anmeldeinformationen mit dem [Access Key Management](/security-compliance/iam/access-token). +- Folgen Sie der [Harbor-Dokumentation](https://goharbor.io/docs/), um eine vollständige Harbor-Bereitstellung mit Replikation, Vulnerability-Scanning und RBAC zu konfigurieren. diff --git a/content/de/developer/integration/registry/images/rustfs-harbor-objects.png b/content/de/developer/integration/registry/images/rustfs-harbor-objects.png new file mode 100644 index 00000000..3561eea8 Binary files /dev/null and b/content/de/developer/integration/registry/images/rustfs-harbor-objects.png differ diff --git a/content/de/developer/integration/registry/index.md b/content/de/developer/integration/registry/index.md new file mode 100644 index 00000000..23ec53e1 --- /dev/null +++ b/content/de/developer/integration/registry/index.md @@ -0,0 +1,12 @@ +--- +title: "Registry" +description: "Verbinden Sie Container-Registries über S3-kompatible Objektspeicher-Schnittstellen mit RustFS." +--- + +Nutzen Sie **RustFS** als Objektspeicher-Layer für Container-Registries mit einem S3-kompatiblen Storage-Treiber. + +## Registries + +- [Harbor](./harbor.md) + +Speichern Sie Image-Artefakte in einem dedizierten Bucket und beschränken Sie die Anmeldeinformationen auf die erforderlichen Bucket-Operationen. diff --git a/content/de/developer/integration/registry/meta.json b/content/de/developer/integration/registry/meta.json new file mode 100644 index 00000000..6c8b2280 --- /dev/null +++ b/content/de/developer/integration/registry/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Registry", + "pages": [ + "harbor" + ] +} diff --git a/content/en/developer/integration/index.md b/content/en/developer/integration/index.md index 1358c42f..d15bad08 100644 --- a/content/en/developer/integration/index.md +++ b/content/en/developer/integration/index.md @@ -1,6 +1,6 @@ --- title: "Integration" -description: "Integrate RustFS with reverse proxies, backup tools, data analytics systems, and observability platforms." +description: "Integrate RustFS with reverse proxies, backup tools, data analytics systems, observability platforms, and container registries." --- Use this section to connect **RustFS** to infrastructure and application platforms through its S3-compatible API. @@ -12,5 +12,7 @@ Use this section to connect **RustFS** to infrastructure and application platfor - [Data Analytics](./big-data/index.md) covers Iceberg. - [Observability](./observability/index.md) covers OpenObserve. - [Others](./others/index.md) covers the community-driven capo SDK for Python. +- [Registry](./registry/index.md) covers Harbor. +- [Registry](./registry/index.md) covers Harbor. Each guide identifies the RustFS endpoint and addressing requirements to use when configuring the integrating system. \ No newline at end of file diff --git a/content/en/developer/integration/meta.json b/content/en/developer/integration/meta.json index e8db4e78..88d4e064 100644 --- a/content/en/developer/integration/meta.json +++ b/content/en/developer/integration/meta.json @@ -5,6 +5,7 @@ "backup", "big-data", "observability", - "others" + "others", + "registry" ] } diff --git a/content/en/developer/integration/registry/harbor.md b/content/en/developer/integration/registry/harbor.md new file mode 100644 index 00000000..41f482ed --- /dev/null +++ b/content/en/developer/integration/registry/harbor.md @@ -0,0 +1,279 @@ +--- +title: "Harbor" +description: "Store container images pushed to Harbor in RustFS object storage through the registry S3 storage driver, deployed with Docker Compose." +--- + +This guide connects [Harbor](https://github.com/goharbor/harbor) — the CNCF graduated cloud native registry — to **RustFS**. Harbor persists image layers, manifests, and other OCI artifacts through its embedded registry component, which implements the S3 storage driver of the [distribution](https://distribution.github.io/distribution/) project. You will run that registry component against RustFS with Docker Compose, push an image, pull it back, and verify the objects in RustFS. The same storage settings apply to a full Harbor deployment. The workflow was verified with `goharbor/registry-photon:v2.12.2` and `rustfs/rustfs-x86-musl:v2.3.1`. + +You need Docker with the Compose plugin. This deployment is intended for local integration testing, not production. + +## Architecture + +```mermaid +flowchart LR + Client["Docker client"] -->|"push / pull"| Registry["Harbor registry component :5000"] + Registry -->|"S3 PUT / GET"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +The registry stores every blob, manifest, and repository link under `docker/registry/v2/` in the bucket through the S3 storage driver. The driver settings `regionendpoint`, `secure: false`, and `skipverify: true` point the AWS S3 client used by the driver at the RustFS endpoint with path-style addressing over plain HTTP. + +## 1. Create the project files + +Create a working directory: + +```bash +mkdir rustfs-harbor +cd rustfs-harbor +``` + +Create an environment file and replace both credential placeholders: + +```ini title=".env" +RUSTFS_ACCESS_KEY= +RUSTFS_SECRET_KEY= +``` + +Use dedicated credentials for the bucket. Do not commit `.env` to source control. + +Create the registry configuration that Harbor uses for its registry component: + +```yaml title="config.yml" +version: 0.1 +log: + level: info +storage: + s3: + accesskey: + secretkey: + region: us-east-1 + regionendpoint: http://rustfs:9000 + bucket: my-bucket + secure: false + skipverify: true + delete: + enabled: true + redirect: + disable: true +http: + addr: 0.0.0.0:5000 +health: + storagedriver: + enabled: true + interval: 10s + threshold: 3 +``` + +`regionendpoint` routes the driver to RustFS instead of AWS, `secure: false` selects plain HTTP inside the Compose network, and `redirect.disable: true` makes the registry serve blobs itself — Harbor sets the same option for backends without redirect support. + +Create the Compose file: + +```yaml title="compose.yaml" +services: + rustfs: + image: rustfs/rustfs-x86-musl:v2.3.1 + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + RUSTFS_VOLUMES: /data + RUSTFS_ADDRESS: ":9000" + RUSTFS_CONSOLE_ADDRESS: ":9001" + RUSTFS_CONSOLE_ENABLE: "true" + volumes: + - rustfs-data:/data + ports: + - "9000:9000" + - "9001:9001" + healthcheck: + test: ["CMD", "curl", "-sf", "http://127.0.0.1:9000/health"] + interval: 10s + timeout: 5s + retries: 6 + start_period: 10s + networks: + - registry + + create-bucket: + image: rustfs/rc:latest + depends_on: + rustfs: + condition: service_healthy + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + entrypoint: + - /bin/sh + - -c + - | + until /usr/bin/rc alias set rustfs http://rustfs:9000 "$${RUSTFS_ACCESS_KEY}" "$${RUSTFS_SECRET_KEY}"; do + echo "Waiting for RustFS..." + sleep 2 + done + /usr/bin/rc ls rustfs/my-bucket >/dev/null 2>&1 || /usr/bin/rc mb rustfs/my-bucket + networks: + - registry + + registry: + image: goharbor/registry-photon:v2.12.2 + volumes: + - ./config.yml:/etc/registry/config.yml:ro + ports: + - "5000:5000" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - registry + +networks: + registry: + +volumes: + rustfs-data: +``` + +The [`rc` image](https://github.com/rustfs/cli) provides the official RustFS command-line client. The initializer checks for `my-bucket` before creating it, so repeated starts do not delete existing artifacts. + +## 2. Start the deployment + +Resolve the Compose file before starting containers: + +```bash +docker compose config +``` + +Start the services and wait for the bucket initializer to finish: + +```bash +docker compose up -d +docker compose ps -a +``` + +The registry API should answer with an empty catalog: + +```bash +curl -s http://localhost:5000/v2/_catalog +``` + +```text +{"repositories":[]} +``` + +## 3. Push an image + +Pull a small image, retag it for the local registry, and push it: + +```bash +docker pull busybox:latest +docker tag busybox:latest localhost:5000/demo/app:v1 +docker push localhost:5000/demo/app:v1 +``` + +```text +v1: digest: sha256:1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8 size: 527 +``` + +## 4. Pull the image back + +Remove the local tags and pull the image from the registry — the layers now come from RustFS: + +```bash +docker rmi localhost:5000/demo/app:v1 +docker pull localhost:5000/demo/app:v1 +``` + +```text +localhost:5000/demo/app:v1 +``` + +## 5. Verify objects in RustFS + +List the repository prefix through the bucket-initializer image: + +```bash +docker compose run --rm --entrypoint /bin/sh create-bucket -c \ + '/usr/bin/rc alias set rustfs http://rustfs:9000 "$RUSTFS_ACCESS_KEY" "$RUSTFS_SECRET_KEY" >/dev/null && /usr/bin/rc ls rustfs/my-bucket/docker/registry/v2/repositories/demo --recursive' +``` + +```text +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/b05093807bb0294152bb9cf86d64da722732dddaf7f8882fa1f120477dbc4db3/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/c6348fa86ba0fb2108c9334f5fe913ddc6d853313e655891f133a0127c30099f/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/revisions/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/current/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/index/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +``` + +The blob payloads themselves live under `docker/registry/v2/blobs/`. You can also browse the prefix in the RustFS Console at `http://localhost:9001/rustfs/console/`: + +![The repository metadata of the pushed image in the RustFS Console](./images/rustfs-harbor-objects.png) + +## 6. Use RustFS in a full Harbor deployment + +The registry component verified above is the same component a full Harbor deployment runs, so the storage settings carry over directly. + +For the Helm chart, set the S3 options under `persistence.imageChartStorage`: + +```yaml title="values.yaml" +persistence: + imageChartStorage: + type: s3 + disableredirect: true + s3: + region: us-east-1 + bucket: my-bucket + accesskey: + secretkey: + regionendpoint: http://rustfs:9000 + secure: false + skipverify: true +``` + +For the Harbor installer behind a `harbor.yml` file, place the same driver keys under `storage_service.s3`. Both files accept the storage driver options documented by the [distribution project](https://distribution.github.io/distribution/about/configuration/), which is the configuration surface verified in this guide. + +## 7. Stop or reset the stack + +Stop the containers while keeping the RustFS data volume: + +```bash +docker compose down +``` + +To delete the stored artifacts and start from an empty RustFS volume, explicitly include `--volumes`: + +```bash +docker compose down --volumes +``` + +## Troubleshooting + +### The registry fails to start or reports a storage error + +Check the registry logs for the S3 driver message: + +```bash +docker compose logs registry +``` + +`regionendpoint` must be reachable from the registry container. Inside the Compose network use `http://rustfs:9000`; from a process on the host, use `http://localhost:9000`. + +### TLS or certificate errors with a plain-HTTP endpoint + +`secure: false` selects plain HTTP for the RustFS endpoint. Without it, the driver attempts HTTPS and fails with a connection or certificate error. For a TLS endpoint with a self-signed certificate, keep `secure: true`, set `skipverify: true`, and provide the CA bundle through the `ca_bundle` option that Harbor exposes in `harbor.yml`. + +### AccessDenied or 403 responses + +Confirm the credentials in `config.yml` match the RustFS credentials and that the `create-bucket` service completed successfully: + +```bash +docker compose logs create-bucket +``` + +### The push succeeds but objects do not appear in the expected prefix + +The driver writes below `docker/registry/v2/` inside the bucket. List the whole bucket recursively to locate the repository tree before assuming a configuration problem. + +## Next steps + +- Review [S3 compatibility notes](/administration/protocols/s3) before adopting additional S3 operations. +- Create dedicated production credentials with [Access Key Management](/security-compliance/iam/access-token). +- Follow the [Harbor documentation](https://goharbor.io/docs/) to configure a full Harbor deployment with replication, vulnerability scanning, and RBAC. diff --git a/content/en/developer/integration/registry/images/rustfs-harbor-objects.png b/content/en/developer/integration/registry/images/rustfs-harbor-objects.png new file mode 100644 index 00000000..3561eea8 Binary files /dev/null and b/content/en/developer/integration/registry/images/rustfs-harbor-objects.png differ diff --git a/content/en/developer/integration/registry/index.md b/content/en/developer/integration/registry/index.md new file mode 100644 index 00000000..626ab70f --- /dev/null +++ b/content/en/developer/integration/registry/index.md @@ -0,0 +1,12 @@ +--- +title: "Registry" +description: "Connect container registries to RustFS through S3-compatible object storage interfaces." +--- + +Use **RustFS** as the object storage layer for container registries that support an S3-compatible storage driver. + +## Registries + +- [Harbor](./harbor.md) + +Keep image artifacts in a dedicated bucket, and use credentials scoped to the required bucket operations. diff --git a/content/en/developer/integration/registry/meta.json b/content/en/developer/integration/registry/meta.json new file mode 100644 index 00000000..6c8b2280 --- /dev/null +++ b/content/en/developer/integration/registry/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Registry", + "pages": [ + "harbor" + ] +} diff --git a/content/fr/developer/integration/index.md b/content/fr/developer/integration/index.md index 819ba3ef..03cb4e9e 100644 --- a/content/fr/developer/integration/index.md +++ b/content/fr/developer/integration/index.md @@ -1,6 +1,6 @@ --- title: "Integration" -description: "Intégrez RustFS avec des reverse proxies, des outils de sauvegarde, des systèmes d'analyse de données et des plateformes d'observabilité." +description: "Intégrez RustFS avec des reverse proxies, des outils de sauvegarde, des systèmes d'analyse de données, des plateformes d'observabilité et des registries de conteneurs." --- Utilisez cette section pour connecter **RustFS** à des plateformes d'infrastructure et d'applications via son API compatible S3. @@ -12,5 +12,7 @@ Utilisez cette section pour connecter **RustFS** à des plateformes d'infrastruc - [Analyse de données](./big-data/index.md) couvre Iceberg. - [Observabilité](./observability/index.md) couvre OpenObserve. - [Autres](./others/index.md) couvre le SDK communautaire capo pour Python. +- [Registre](./registry/index.md) couvre Harbor. +- [Registre](./registry/index.md) couvre Harbor. Chaque guide indique le point de terminaison RustFS et les exigences d'adressage à utiliser lors de la configuration du système intégré. \ No newline at end of file diff --git a/content/fr/developer/integration/meta.json b/content/fr/developer/integration/meta.json index b901ffeb..88d4e064 100644 --- a/content/fr/developer/integration/meta.json +++ b/content/fr/developer/integration/meta.json @@ -1,10 +1,11 @@ { - "title": "Intégration", + "title": "Integration", "pages": [ "reverse-proxy", "backup", "big-data", "observability", - "others" + "others", + "registry" ] } diff --git a/content/fr/developer/integration/registry/harbor.md b/content/fr/developer/integration/registry/harbor.md new file mode 100644 index 00000000..fbcc6202 --- /dev/null +++ b/content/fr/developer/integration/registry/harbor.md @@ -0,0 +1,279 @@ +--- +title: "Harbor" +description: "Stockez les images de conteneurs poussées vers Harbor dans le stockage objet RustFS via le pilote de stockage S3 de la registry, déployés avec Docker Compose." +--- + +Ce guide connecte [Harbor](https://github.com/goharbor/harbor) — le registre cloud native gradué de la CNCF — à **RustFS**. Harbor persiste les couches d'images, les manifestes et les autres artefacts OCI via son composant de registry intégré, qui implémente le pilote de stockage S3 du projet [distribution](https://distribution.github.io/distribution/). Vous allez exécuter ce composant de registry contre RustFS avec Docker Compose, pousser une image, la retirer, puis vérifier les objets dans RustFS. Les mêmes réglages de stockage s'appliquent à un déploiement Harbor complet. Le flux a été validé avec `goharbor/registry-photon:v2.12.2` et `rustfs/rustfs-x86-musl:v2.3.1`. + +Vous avez besoin de Docker avec le plugin Compose. Ce déploiement est destiné aux tests d'intégration locaux, pas à la production. + +## Architecture + +```mermaid +flowchart LR + Client["Docker client"] -->|"push / pull"| Registry["Harbor registry component :5000"] + Registry -->|"S3 PUT / GET"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +La registry stocke chaque blob, manifeste et lien de dépôt sous `docker/registry/v2/` dans le bucket via le pilote de stockage S3. Les réglages `regionendpoint`, `secure: false` et `skipverify: true` orientent le client AWS S3 utilisé par le pilote vers le point de terminaison RustFS, avec un adressage path-style en HTTP simple. + +## 1. Créer les fichiers du projet + +Créez un répertoire de travail : + +```bash +mkdir rustfs-harbor +cd rustfs-harbor +``` + +Créez un fichier d'environnement et remplacez les deux espaces réservés d'identifiants : + +```ini title=".env" +RUSTFS_ACCESS_KEY= +RUSTFS_SECRET_KEY= +``` + +Utilisez des identifiants dédiés pour le bucket. Ne commettez pas `.env` dans le contrôle de version. + +Créez la configuration de registry qu'Harbor utilise pour son composant de registry : + +```yaml title="config.yml" +version: 0.1 +log: + level: info +storage: + s3: + accesskey: + secretkey: + region: us-east-1 + regionendpoint: http://rustfs:9000 + bucket: my-bucket + secure: false + skipverify: true + delete: + enabled: true + redirect: + disable: true +http: + addr: 0.0.0.0:5000 +health: + storagedriver: + enabled: true + interval: 10s + threshold: 3 +``` + +`regionendpoint` dirige le pilote vers RustFS plutôt que vers AWS, `secure: false` sélectionne HTTP simple à l'intérieur du réseau Compose, et `redirect.disable: true` fait servir les blobs par la registry elle-même — Harbor définit la même option pour les backends sans prise en charge de la redirection. + +Créez le fichier Compose : + +```yaml title="compose.yaml" +services: + rustfs: + image: rustfs/rustfs-x86-musl:v2.3.1 + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + RUSTFS_VOLUMES: /data + RUSTFS_ADDRESS: ":9000" + RUSTFS_CONSOLE_ADDRESS: ":9001" + RUSTFS_CONSOLE_ENABLE: "true" + volumes: + - rustfs-data:/data + ports: + - "9000:9000" + - "9001:9001" + healthcheck: + test: ["CMD", "curl", "-sf", "http://127.0.0.1:9000/health"] + interval: 10s + timeout: 5s + retries: 6 + start_period: 10s + networks: + - registry + + create-bucket: + image: rustfs/rc:latest + depends_on: + rustfs: + condition: service_healthy + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + entrypoint: + - /bin/sh + - -c + - | + until /usr/bin/rc alias set rustfs http://rustfs:9000 "$${RUSTFS_ACCESS_KEY}" "$${RUSTFS_SECRET_KEY}"; do + echo "Waiting for RustFS..." + sleep 2 + done + /usr/bin/rc ls rustfs/my-bucket >/dev/null 2>&1 || /usr/bin/rc mb rustfs/my-bucket + networks: + - registry + + registry: + image: goharbor/registry-photon:v2.12.2 + volumes: + - ./config.yml:/etc/registry/config.yml:ro + ports: + - "5000:5000" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - registry + +networks: + registry: + +volumes: + rustfs-data: +``` + +L'[image `rc`](https://github.com/rustfs/cli) fournit le client en ligne de commande officiel de RustFS. L'initialiseur vérifie l'existence de `my-bucket` avant de le créer, afin que des redémarrages répétés ne suppriment pas les artefacts existants. + +## 2. Démarrer le déploiement + +Vérifiez le fichier Compose avant de démarrer les conteneurs : + +```bash +docker compose config +``` + +Démarrez les services et attendez la fin de l'initialisation du bucket : + +```bash +docker compose up -d +docker compose ps -a +``` + +L'API de la registry doit répondre avec un catalogue vide : + +```bash +curl -s http://localhost:5000/v2/_catalog +``` + +```text +{"repositories":[]} +``` + +## 3. Pousser une image + +Retirez une petite image, retaguez-la pour la registry locale, puis poussez-la : + +```bash +docker pull busybox:latest +docker tag busybox:latest localhost:5000/demo/app:v1 +docker push localhost:5000/demo/app:v1 +``` + +```text +v1: digest: sha256:1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8 size: 527 +``` + +## 4. Retirer l'image + +Supprimez les tags locaux, puis retirez l'image depuis la registry — les couches proviennent désormais de RustFS : + +```bash +docker rmi localhost:5000/demo/app:v1 +docker pull localhost:5000/demo/app:v1 +``` + +```text +localhost:5000/demo/app:v1 +``` + +## 5. Vérifier les objets dans RustFS + +Listez le préfixe du dépôt via l'image d'initialisation du bucket : + +```bash +docker compose run --rm --entrypoint /bin/sh create-bucket -c \ + '/usr/bin/rc alias set rustfs http://rustfs:9000 "$RUSTFS_ACCESS_KEY" "$RUSTFS_SECRET_KEY" >/dev/null && /usr/bin/rc ls rustfs/my-bucket/docker/registry/v2/repositories/demo --recursive' +``` + +```text +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/b05093807bb0294152bb9cf86d64da722732dddaf7f8882fa1f120477dbc4db3/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/c6348fa86ba0fb2108c9334f5fe913ddc6d853313e655891f133a0127c30099f/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/revisions/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/current/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/index/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +``` + +Les blobs eux-mêmes se trouvent sous `docker/registry/v2/blobs/`. Vous pouvez également parcourir le préfixe dans la console RustFS à l'adresse `http://localhost:9001/rustfs/console/` : + +![Les métadonnées du dépôt de l'image poussée dans la console RustFS](./images/rustfs-harbor-objects.png) + +## 6. Utiliser RustFS dans un déploiement Harbor complet + +Le composant de registry validé ci-dessus est le même que celui qu'exécute un déploiement Harbor complet ; les réglages de stockage se reportent donc directement. + +Pour le chart Helm, définissez les options S3 sous `persistence.imageChartStorage` : + +```yaml title="values.yaml" +persistence: + imageChartStorage: + type: s3 + disableredirect: true + s3: + region: us-east-1 + bucket: my-bucket + accesskey: + secretkey: + regionendpoint: http://rustfs:9000 + secure: false + skipverify: true +``` + +Pour l'installateur Harbor piloté par un fichier `harbor.yml`, placez les mêmes clés du pilote sous `storage_service.s3`. Les deux fichiers acceptent les options du pilote de stockage documentées par le [projet distribution](https://distribution.github.io/distribution/about/configuration/) — c'est précisément la surface de configuration validée dans ce guide. + +## 7. Arrêter ou réinitialiser la pile + +Arrêtez les conteneurs en conservant le volume de données RustFS : + +```bash +docker compose down +``` + +Pour supprimer les artefacts stockés et repartir d'un volume RustFS vide, ajoutez explicitement `--volumes` : + +```bash +docker compose down --volumes +``` + +## Dépannage + +### La registry ne démarre pas ou signale une erreur de stockage + +Consultez les journaux de la registry pour les messages du pilote S3 : + +```bash +docker compose logs registry +``` + +`regionendpoint` doit être joignable depuis le conteneur de la registry. À l'intérieur du réseau Compose, utilisez `http://rustfs:9000` ; depuis un processus sur l'hôte, `http://localhost:9000`. + +### Erreurs TLS ou de certificat avec un point de terminaison HTTP simple + +`secure: false` sélectionne HTTP simple pour le point de terminaison RustFS. Sans cela, le pilote tente HTTPS et échoue avec une erreur de connexion ou de certificat. Pour un point de terminaison TLS avec un certificat auto-signé, conservez `secure: true`, définissez `skipverify: true` et fournissez le bundle CA via l'option `ca_bundle` qu'Harbor expose dans `harbor.yml`. + +### Réponses AccessDenied ou 403 + +Vérifiez que les identifiants de `config.yml` correspondent aux identifiants RustFS et que la tâche `create-bucket` s'est terminée avec succès : + +```bash +docker compose logs create-bucket +``` + +### Le push réussit mais les objets n'apparaissent pas dans le préfixe attendu + +Le pilote écrit sous `docker/registry/v2/` dans le bucket. Listez tout le bucket de manière récursive pour localiser l'arborescence du dépôt avant de supposer un problème de configuration. + +## Prochaines étapes + +- Consultez les [notes de compatibilité S3](/administration/protocols/s3) avant d'adopter d'autres opérations S3. +- Créez des identifiants de production dédiés avec la [gestion des clés d'accès](/security-compliance/iam/access-token). +- Suivez la [documentation Harbor](https://goharbor.io/docs/) pour configurer un déploiement Harbor complet avec réplication, scan de vulnérabilités et RBAC. diff --git a/content/fr/developer/integration/registry/images/rustfs-harbor-objects.png b/content/fr/developer/integration/registry/images/rustfs-harbor-objects.png new file mode 100644 index 00000000..3561eea8 Binary files /dev/null and b/content/fr/developer/integration/registry/images/rustfs-harbor-objects.png differ diff --git a/content/fr/developer/integration/registry/index.md b/content/fr/developer/integration/registry/index.md new file mode 100644 index 00000000..a9f49396 --- /dev/null +++ b/content/fr/developer/integration/registry/index.md @@ -0,0 +1,12 @@ +--- +title: "Registre" +description: "Connectez les registries de conteneurs à RustFS via des interfaces de stockage objet compatibles S3." +--- + +Utilisez **RustFS** comme couche de stockage objet pour les registries de conteneurs disposant d'un pilote de stockage compatible S3. + +## Registries + +- [Harbor](./harbor.md) + +Conservez les artefacts d'images dans un bucket dédié et limitez les identifiants aux opérations de bucket requises. diff --git a/content/fr/developer/integration/registry/meta.json b/content/fr/developer/integration/registry/meta.json new file mode 100644 index 00000000..9d00df2a --- /dev/null +++ b/content/fr/developer/integration/registry/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Registre", + "pages": [ + "harbor" + ] +} diff --git a/content/ja/developer/integration/index.md b/content/ja/developer/integration/index.md index b5df464a..7fc4bf29 100644 --- a/content/ja/developer/integration/index.md +++ b/content/ja/developer/integration/index.md @@ -1,6 +1,6 @@ --- title: "Integration" -description: "RustFS をリバースプロキシ、バックアップツール、データ分析システム、オブザーバビリティプラットフォームと連携させます。" +description: "RustFS をリバースプロキシ、バックアップツール、データ分析システム、オブザーバビリティプラットフォーム、コンテナレジストリと連携させます。" --- このセクションでは、**RustFS** を S3 互換 API 経由でインフラストラクチャとアプリケーションプラットフォームに接続します。 @@ -12,5 +12,7 @@ description: "RustFS をリバースプロキシ、バックアップツール - [データ分析](./big-data/index.md) は Iceberg を扱います。 - [オブザーバビリティ](./observability/index.md) は OpenObserve を扱います。 - [その他](./others/index.md) はコミュニティ主導の Python 用 capo SDK を扱います。 +- [コンテナレジストリ](./registry/index.md) は Harbor を扱います。 +- [コンテナレジストリ](./registry/index.md) は Harbor を扱います。 各ガイドでは、連携先システムを設定する際に使用する RustFS のエンドポイントとアドレス指定の要件を示します。 \ No newline at end of file diff --git a/content/ja/developer/integration/meta.json b/content/ja/developer/integration/meta.json index 4ab3de80..88d4e064 100644 --- a/content/ja/developer/integration/meta.json +++ b/content/ja/developer/integration/meta.json @@ -1,10 +1,11 @@ { - "title": "連携", + "title": "Integration", "pages": [ "reverse-proxy", "backup", "big-data", "observability", - "others" + "others", + "registry" ] } diff --git a/content/ja/developer/integration/registry/harbor.md b/content/ja/developer/integration/registry/harbor.md new file mode 100644 index 00000000..2f501ea2 --- /dev/null +++ b/content/ja/developer/integration/registry/harbor.md @@ -0,0 +1,279 @@ +--- +title: "Harbor" +description: "Harbor への push でコンテナイメージを registry の S3 ストレージドライバー経由で RustFS オブジェクトストレージに保存します。Docker Compose でデプロイします。" +--- + +このガイドでは、CNCF を卒業したクラウドネイティブレジストリである [Harbor](https://github.com/goharbor/harbor) を **RustFS** に接続します。Harbor は、[distribution](https://distribution.github.io/distribution/) プロジェクトの S3 ストレージドライバーを実装する組み込み registry コンポーネントを通じて、イメージレイヤー・マニフェスト・その他の OCI アーティファクトを永続化します。Docker Compose でその registry コンポーネントを RustFS に対して実行し、イメージを push して pull で戻し、RustFS 内のオブジェクトを確認します。同じストレージ設定は完全な Harbor デプロイにも適用できます。この流れは `goharbor/registry-photon:v2.12.2` と `rustfs/rustfs-x86-musl:v2.3.1` で検証済みです。 + +Docker と Compose プラグインが必要です。このデプロイはローカルでの統合テストを目的としており、本番環境向けではありません。 + +## アーキテクチャ + +```mermaid +flowchart LR + Client["Docker client"] -->|"push / pull"| Registry["Harbor registry component :5000"] + Registry -->|"S3 PUT / GET"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +registry は、S3 ストレージドライバーを通じて、すべての blob・マニフェスト・リポジトリリンクをバケット内の `docker/registry/v2/` の下に保存します。ドライバー設定の `regionendpoint`、`secure: false`、`skipverify: true` により、ドライバーが使用する AWS S3 クライアントが、平文 HTTP 上のパススタイルアドレス指定で RustFS エンドポイントに向くようになります。 + +## 1. プロジェクトファイルを作成する + +作業ディレクトリを作成します。 + +```bash +mkdir rustfs-harbor +cd rustfs-harbor +``` + +環境変数ファイルを作成し、2 つの認証情報プレースホルダーを置き換えます。 + +```ini title=".env" +RUSTFS_ACCESS_KEY= +RUSTFS_SECRET_KEY= +``` + +バケットには専用の認証情報を使用してください。`.env` をバージョン管理にコミットしないでください。 + +Harbor が registry コンポーネントに使う registry 設定を作成します。 + +```yaml title="config.yml" +version: 0.1 +log: + level: info +storage: + s3: + accesskey: + secretkey: + region: us-east-1 + regionendpoint: http://rustfs:9000 + bucket: my-bucket + secure: false + skipverify: true + delete: + enabled: true + redirect: + disable: true +http: + addr: 0.0.0.0:5000 +health: + storagedriver: + enabled: true + interval: 10s + threshold: 3 +``` + +`regionendpoint` はドライバーを AWS ではなく RustFS へ向けます。`secure: false` は Compose ネットワーク内での平文 HTTP を選択し、`redirect.disable: true` は registry 自身が blob を提供するようにします。Harbor はリダイレクト非対応のバックエンドに対して同じオプションを設定します。 + +Compose ファイルを作成します。 + +```yaml title="compose.yaml" +services: + rustfs: + image: rustfs/rustfs-x86-musl:v2.3.1 + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + RUSTFS_VOLUMES: /data + RUSTFS_ADDRESS: ":9000" + RUSTFS_CONSOLE_ADDRESS: ":9001" + RUSTFS_CONSOLE_ENABLE: "true" + volumes: + - rustfs-data:/data + ports: + - "9000:9000" + - "9001:9001" + healthcheck: + test: ["CMD", "curl", "-sf", "http://127.0.0.1:9000/health"] + interval: 10s + timeout: 5s + retries: 6 + start_period: 10s + networks: + - registry + + create-bucket: + image: rustfs/rc:latest + depends_on: + rustfs: + condition: service_healthy + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + entrypoint: + - /bin/sh + - -c + - | + until /usr/bin/rc alias set rustfs http://rustfs:9000 "$${RUSTFS_ACCESS_KEY}" "$${RUSTFS_SECRET_KEY}"; do + echo "Waiting for RustFS..." + sleep 2 + done + /usr/bin/rc ls rustfs/my-bucket >/dev/null 2>&1 || /usr/bin/rc mb rustfs/my-bucket + networks: + - registry + + registry: + image: goharbor/registry-photon:v2.12.2 + volumes: + - ./config.yml:/etc/registry/config.yml:ro + ports: + - "5000:5000" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - registry + +networks: + registry: + +volumes: + rustfs-data: +``` + +[`rc` イメージ](https://github.com/rustfs/cli)は RustFS の公式コマンドラインクライアントを提供します。初期化ジョブは作成前に `my-bucket` の存在を確認するため、繰り返し起動しても既存のアーティファクトは削除されません。 + +## 2. デプロイを起動する + +コンテナを起動する前に Compose ファイルを検証します。 + +```bash +docker compose config +``` + +サービスを起動し、バケット初期化の完了を待ちます。 + +```bash +docker compose up -d +docker compose ps -a +``` + +registry API は空のカタログで応答するはずです。 + +```bash +curl -s http://localhost:5000/v2/_catalog +``` + +```text +{"repositories":[]} +``` + +## 3. イメージを push する + +小さなイメージを pull し、ローカルのレジストリ向けにタグを付け直して push します。 + +```bash +docker pull busybox:latest +docker tag busybox:latest localhost:5000/demo/app:v1 +docker push localhost:5000/demo/app:v1 +``` + +```text +v1: digest: sha256:1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8 size: 527 +``` + +## 4. イメージを pull で戻す + +ローカルのタグを削除してから、registry からイメージを pull します。レイヤーは今や RustFS から提供されます。 + +```bash +docker rmi localhost:5000/demo/app:v1 +docker pull localhost:5000/demo/app:v1 +``` + +```text +localhost:5000/demo/app:v1 +``` + +## 5. RustFS 内のオブジェクトを確認する + +バケット初期化イメージを使ってリポジトリのプレフィックスを一覧表示します。 + +```bash +docker compose run --rm --entrypoint /bin/sh create-bucket -c \ + '/usr/bin/rc alias set rustfs http://rustfs:9000 "$RUSTFS_ACCESS_KEY" "$RUSTFS_SECRET_KEY" >/dev/null && /usr/bin/rc ls rustfs/my-bucket/docker/registry/v2/repositories/demo --recursive' +``` + +```text +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/b05093807bb0294152bb9cf86d64da722732dddaf7f8882fa1f120477dbc4db3/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/c6348fa86ba0fb2108c9334f5fe913ddc6d853313e655891f133a0127c30099f/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/revisions/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/current/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/index/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +``` + +blob の実体は `docker/registry/v2/blobs/` の下に保存されます。RustFS コンソール (`http://localhost:9001/rustfs/console/`) でこのプレフィックスを参照することもできます。 + +![RustFS コンソールに表示された push したイメージのリポジトリメタデータ](./images/rustfs-harbor-objects.png) + +## 6. 完全な Harbor デプロイで RustFS を使用する + +上で検証した registry コンポーネントは、完全な Harbor デプロイが実行するものと同じコンポーネントです。そのためストレージ設定はそのまま引き継げます。 + +Helm チャートでは `persistence.imageChartStorage` の下に S3 オプションを設定します。 + +```yaml title="values.yaml" +persistence: + imageChartStorage: + type: s3 + disableredirect: true + s3: + region: us-east-1 + bucket: my-bucket + accesskey: + secretkey: + regionendpoint: http://rustfs:9000 + secure: false + skipverify: true +``` + +`harbor.yml` ファイルを使う Harbor インストーラーでは、同じドライバーキーを `storage_service.s3` の下に置きます。どちらのファイルも、[distribution プロジェクト](https://distribution.github.io/distribution/about/configuration/)でドキュメント化されているストレージドライバーのオプションを受け付けます。このガイドで検証したのはまさにその設定面です。 + +## 7. スタックを停止・リセットする + +RustFS データボリュームを保持したままコンテナを停止します。 + +```bash +docker compose down +``` + +保存したアーティファクトを削除して空の RustFS ボリュームからやり直す場合は、明示的に `--volumes` を付けます。 + +```bash +docker compose down --volumes +``` + +## トラブルシューティング + +### registry が起動しない、またはストレージエラーが出る + +S3 ドライバーのメッセージを確認するために registry のログを確認します。 + +```bash +docker compose logs registry +``` + +`regionendpoint` は registry コンテナから到達可能である必要があります。Compose ネットワーク内では `http://rustfs:9000` を、ホスト上のプロセスからは `http://localhost:9000` を使用してください。 + +### 平文 HTTP エンドポイントでの SSL エラーや証明書エラー + +`secure: false` は RustFS エンドポイントで平文 HTTP を選択します。設定しないとドライバーは HTTPS を試みて接続エラーや証明書エラーになります。自己署名証明書の TLS エンドポイントでは、`secure: true` を維持し、`skipverify: true` を設定した上で、Harbor が `harbor.yml` で公開している `ca_bundle` オプションで CA バンドルを提供してください。 + +### AccessDenied や 403 レスポンス + +`config.yml` の認証情報が RustFS の認証情報と一致しているか、`create-bucket` ジョブが正常に完了しているかを確認してください。 + +```bash +docker compose logs create-bucket +``` + +### push は成功するがオブジェクトが期待のプレフィックスに現れない + +ドライバーはバケット内の `docker/registry/v2/` の下に書き込みます。設定問題と判断する前に、バケット全体を再帰的に一覧表示してリポジトリツリーの場所を確認してください。 + +## 次のステップ + +- 追加の S3 オペレーションを採用する前に、[S3 互換性ノート](/administration/protocols/s3)を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token)で本番用の専用認証情報を作成してください。 +- [Harbor ドキュメント](https://goharbor.io/docs/)に従って、レプリケーション・脆弱性スキャン・RBAC を備えた完全な Harbor デプロイを構成してください。 diff --git a/content/ja/developer/integration/registry/images/rustfs-harbor-objects.png b/content/ja/developer/integration/registry/images/rustfs-harbor-objects.png new file mode 100644 index 00000000..3561eea8 Binary files /dev/null and b/content/ja/developer/integration/registry/images/rustfs-harbor-objects.png differ diff --git a/content/ja/developer/integration/registry/index.md b/content/ja/developer/integration/registry/index.md new file mode 100644 index 00000000..7fb0bc9b --- /dev/null +++ b/content/ja/developer/integration/registry/index.md @@ -0,0 +1,12 @@ +--- +title: "コンテナレジストリ" +description: "S3 互換オブジェクトストレージインターフェースを経由して、コンテナレジストリを RustFS に接続します。" +--- + +S3 互換ストレージドライバーをサポートするコンテナレジストリのオブジェクトストレージ層として **RustFS** を使用します。 + +## レジストリ + +- [Harbor](./harbor.md) + +イメージアーティファクトは専用バケットに保存し、必要なバケット操作のみに権限が絞られた認証情報を使用してください。 diff --git a/content/ja/developer/integration/registry/meta.json b/content/ja/developer/integration/registry/meta.json new file mode 100644 index 00000000..a90c29a3 --- /dev/null +++ b/content/ja/developer/integration/registry/meta.json @@ -0,0 +1,6 @@ +{ + "title": "コンテナレジストリ", + "pages": [ + "harbor" + ] +} diff --git a/content/zh/developer/integration/index.md b/content/zh/developer/integration/index.md index 498367b3..1bfbf253 100644 --- a/content/zh/developer/integration/index.md +++ b/content/zh/developer/integration/index.md @@ -1,6 +1,6 @@ --- title: "集成" -description: "将 RustFS 与反向代理、备份工具、数据分析系统和可观测性平台集成。" +description: "将 RustFS 与反向代理、备份工具、数据分析系统、可观测性平台和容器镜像仓库集成。" --- 通过 S3 兼容 API 将 **RustFS** 连接到基础设施和应用平台。 @@ -12,5 +12,7 @@ description: "将 RustFS 与反向代理、备份工具、数据分析系统和 - [数据分析](./big-data/index.md)涵盖 Iceberg。 - [可观测性](./observability/index.md)涵盖 OpenObserve。 - [其他](./others/index.md)涵盖社区驱动的 Python capo SDK。 +- [镜像仓库](./registry/index.md)涵盖 Harbor。 +- [镜像仓库](./registry/index.md)涵盖 Harbor。 每篇指南都会说明配置集成系统时需要使用的 RustFS 端点和寻址要求。 \ No newline at end of file diff --git a/content/zh/developer/integration/meta.json b/content/zh/developer/integration/meta.json index f5512f36..88d4e064 100644 --- a/content/zh/developer/integration/meta.json +++ b/content/zh/developer/integration/meta.json @@ -1,10 +1,11 @@ { - "title": "集成", + "title": "Integration", "pages": [ "reverse-proxy", "backup", "big-data", "observability", - "others" + "others", + "registry" ] } diff --git a/content/zh/developer/integration/registry/harbor.md b/content/zh/developer/integration/registry/harbor.md new file mode 100644 index 00000000..9d30b150 --- /dev/null +++ b/content/zh/developer/integration/registry/harbor.md @@ -0,0 +1,279 @@ +--- +title: "Harbor" +description: "通过 registry 的 S3 存储驱动,将推送到 Harbor 的容器镜像存储在 RustFS 对象存储中,使用 Docker Compose 部署。" +--- + +本指南将 [Harbor](https://github.com/goharbor/harbor)——CNCF 毕业的云原生镜像仓库——连接到 **RustFS**。Harbor 通过内嵌的 registry 组件持久化镜像层、清单和其他 OCI 制品,该组件实现了 [distribution](https://distribution.github.io/distribution/) 项目的 S3 存储驱动。你将使用 Docker Compose 让该 registry 组件对接 RustFS,推送一个镜像、拉回它,并在 RustFS 中验证这些对象。相同的存储设置同样适用于完整的 Harbor 部署。整个流程使用 `goharbor/registry-photon:v2.12.2` 和 `rustfs/rustfs-x86-musl:v2.3.1` 验证通过。 + +你需要安装带有 Compose 插件的 Docker。本部署用于本地集成测试,不适用于生产环境。 + +## 架构 + +```mermaid +flowchart LR + Client["Docker client"] -->|"push / pull"| Registry["Harbor registry component :5000"] + Registry -->|"S3 PUT / GET"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +registry 通过 S3 存储驱动,将所有 blob、清单和仓库链接存储在桶内 `docker/registry/v2/` 前缀之下。驱动设置 `regionendpoint`、`secure: false` 和 `skipverify: true` 将驱动使用的 AWS S3 客户端指向 RustFS 端点,采用纯 HTTP 上的 path-style 寻址。 + +## 1. 创建项目文件 + +创建工作目录: + +```bash +mkdir rustfs-harbor +cd rustfs-harbor +``` + +创建环境变量文件,并替换两个凭证占位符: + +```ini title=".env" +RUSTFS_ACCESS_KEY= +RUSTFS_SECRET_KEY= +``` + +请为桶使用专用的凭证,不要将 `.env` 提交到版本控制。 + +创建 Harbor registry 组件所使用的 registry 配置: + +```yaml title="config.yml" +version: 0.1 +log: + level: info +storage: + s3: + accesskey: + secretkey: + region: us-east-1 + regionendpoint: http://rustfs:9000 + bucket: my-bucket + secure: false + skipverify: true + delete: + enabled: true + redirect: + disable: true +http: + addr: 0.0.0.0:5000 +health: + storagedriver: + enabled: true + interval: 10s + threshold: 3 +``` + +`regionendpoint` 将驱动路由到 RustFS 而不是 AWS;`secure: false` 表示在 Compose 网络内使用纯 HTTP;`redirect.disable: true` 让 registry 自行提供 blob 数据——Harbor 对不支持重定向的后端也会设置同样的选项。 + +创建 Compose 文件: + +```yaml title="compose.yaml" +services: + rustfs: + image: rustfs/rustfs-x86-musl:v2.3.1 + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + RUSTFS_VOLUMES: /data + RUSTFS_ADDRESS: ":9000" + RUSTFS_CONSOLE_ADDRESS: ":9001" + RUSTFS_CONSOLE_ENABLE: "true" + volumes: + - rustfs-data:/data + ports: + - "9000:9000" + - "9001:9001" + healthcheck: + test: ["CMD", "curl", "-sf", "http://127.0.0.1:9000/health"] + interval: 10s + timeout: 5s + retries: 6 + start_period: 10s + networks: + - registry + + create-bucket: + image: rustfs/rc:latest + depends_on: + rustfs: + condition: service_healthy + environment: + RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY} + RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY} + entrypoint: + - /bin/sh + - -c + - | + until /usr/bin/rc alias set rustfs http://rustfs:9000 "$${RUSTFS_ACCESS_KEY}" "$${RUSTFS_SECRET_KEY}"; do + echo "Waiting for RustFS..." + sleep 2 + done + /usr/bin/rc ls rustfs/my-bucket >/dev/null 2>&1 || /usr/bin/rc mb rustfs/my-bucket + networks: + - registry + + registry: + image: goharbor/registry-photon:v2.12.2 + volumes: + - ./config.yml:/etc/registry/config.yml:ro + ports: + - "5000:5000" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - registry + +networks: + registry: + +volumes: + rustfs-data: +``` + +[`rc` 镜像](https://github.com/rustfs/cli)提供 RustFS 官方命令行客户端。初始化任务在创建前会先检查 `my-bucket` 是否存在,因此重复启动不会删除已有制品。 + +## 2. 启动部署 + +启动容器前先解析 Compose 文件: + +```bash +docker compose config +``` + +启动服务并等待桶初始化任务完成: + +```bash +docker compose up -d +docker compose ps -a +``` + +registry API 应返回空目录: + +```bash +curl -s http://localhost:5000/v2/_catalog +``` + +```text +{"repositories":[]} +``` + +## 3. 推送镜像 + +拉取一个小镜像,为本地仓库重新打标签,然后推送: + +```bash +docker pull busybox:latest +docker tag busybox:latest localhost:5000/demo/app:v1 +docker push localhost:5000/demo/app:v1 +``` + +```text +v1: digest: sha256:1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8 size: 527 +``` + +## 4. 拉回镜像 + +删除本地标签,再从仓库拉取镜像——层数据现在来自 RustFS: + +```bash +docker rmi localhost:5000/demo/app:v1 +docker pull localhost:5000/demo/app:v1 +``` + +```text +localhost:5000/demo/app:v1 +``` + +## 5. 在 RustFS 中验证对象 + +通过桶初始化镜像列出仓库前缀: + +```bash +docker compose run --rm --entrypoint /bin/sh create-bucket -c \ + '/usr/bin/rc alias set rustfs http://rustfs:9000 "$RUSTFS_ACCESS_KEY" "$RUSTFS_SECRET_KEY" >/dev/null && /usr/bin/rc ls rustfs/my-bucket/docker/registry/v2/repositories/demo --recursive' +``` + +```text +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/b05093807bb0294152bb9cf86d64da722732dddaf7f8882fa1f120477dbc4db3/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_layers/sha256/c6348fa86ba0fb2108c9334f5fe913ddc6d853313e655891f133a0127c30099f/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/revisions/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/current/link +[2026-09-20 12:11:25] 71 B docker/registry/v2/repositories/demo/app/_manifests/tags/v1/index/sha256/1cfa4e2b09e127b9c4ed43578d3f3c18e7d44ea47b9ea98475c0cbe9086525f8/link +``` + +blob 数据本身存储在 `docker/registry/v2/blobs/` 之下。你也可以在 RustFS 控制台中浏览该前缀 (`http://localhost:9001/rustfs/console/`): + +![RustFS 控制台中推送镜像的仓库元数据](./images/rustfs-harbor-objects.png) + +## 6. 在完整 Harbor 部署中使用 RustFS + +上面验证的 registry 组件就是完整 Harbor 部署所运行的同一组件,因此存储设置可以直接沿用。 + +对于 Helm Chart,在 `persistence.imageChartStorage` 下设置 S3 选项: + +```yaml title="values.yaml" +persistence: + imageChartStorage: + type: s3 + disableredirect: true + s3: + region: us-east-1 + bucket: my-bucket + accesskey: + secretkey: + regionendpoint: http://rustfs:9000 + secure: false + skipverify: true +``` + +对于基于 `harbor.yml` 的安装器,将相同的驱动键放到 `storage_service.s3` 之下。两个文件都接受 [distribution 项目](https://distribution.github.io/distribution/about/configuration/)文档中描述的存储驱动选项,这也是本指南验证的配置面。 + +## 7. 停止或重置环境 + +停止容器并保留 RustFS 数据卷: + +```bash +docker compose down +``` + +如需删除已存储的制品并从空的 RustFS 数据卷开始,请显式加上 `--volumes`: + +```bash +docker compose down --volumes +``` + +## 故障排除 + +### registry 启动失败或报存储错误 + +查看 registry 日志中的 S3 驱动信息: + +```bash +docker compose logs registry +``` + +`regionendpoint` 必须能被 registry 容器访问。Compose 网络内使用 `http://rustfs:9000`; 宿主机上的进程使用 `http://localhost:9000`. + +### 纯 HTTP 端点出现 TLS 或证书错误 + +`secure: false` 表示 RustFS 端点使用纯 HTTP。不设置时驱动会尝试 HTTPS 并报连接或证书错误。对于自签名证书的 TLS 端点,保持 `secure: true`、设置 `skipverify: true`,并通过 Harbor 在 `harbor.yml` 中暴露的 `ca_bundle` 选项提供 CA 证书。 + +### 返回 AccessDenied 或 403 响应 + +确认 `config.yml` 中的凭证与 RustFS 凭证一致,并确认 `create-bucket` 任务已成功完成: + +```bash +docker compose logs create-bucket +``` + +### 推送成功但对象没有出现在预期前缀 + +驱动会将数据写入桶内 `docker/registry/v2/` 之下。请先递归列出整个桶定位仓库目录树,再判断是否存在配置问题。 + +## 后续步骤 + +- 在采用其他 S3 操作前,请查看 [S3 兼容性说明](/administration/protocols/s3)。 +- 通过[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。 +- 按照 [Harbor 文档](https://goharbor.io/docs/)配置带副本同步、漏洞扫描和 RBAC 的完整 Harbor 部署。 diff --git a/content/zh/developer/integration/registry/images/rustfs-harbor-objects.png b/content/zh/developer/integration/registry/images/rustfs-harbor-objects.png new file mode 100644 index 00000000..f5cceabc Binary files /dev/null and b/content/zh/developer/integration/registry/images/rustfs-harbor-objects.png differ diff --git a/content/zh/developer/integration/registry/index.md b/content/zh/developer/integration/registry/index.md new file mode 100644 index 00000000..bd2bc5ac --- /dev/null +++ b/content/zh/developer/integration/registry/index.md @@ -0,0 +1,12 @@ +--- +title: "镜像仓库" +description: "通过 S3 兼容的对象存储接口将容器镜像仓库连接到 RustFS。" +--- + +将 **RustFS** 用作支持 S3 兼容存储驱动的容器镜像仓库的对象存储层。 + +## 镜像仓库 + +- [Harbor](./harbor.md) + +请将镜像制品保存在专用存储桶中,并为凭证仅授予所需桶操作的权限。 diff --git a/content/zh/developer/integration/registry/meta.json b/content/zh/developer/integration/registry/meta.json new file mode 100644 index 00000000..fe1633a4 --- /dev/null +++ b/content/zh/developer/integration/registry/meta.json @@ -0,0 +1,6 @@ +{ + "title": "镜像仓库", + "pages": [ + "harbor" + ] +}