diff --git a/content/de/developer/integration/observability/images/rustfs-influxdb-objects.png b/content/de/developer/integration/observability/images/rustfs-influxdb-objects.png new file mode 100644 index 00000000..d5adc886 Binary files /dev/null and b/content/de/developer/integration/observability/images/rustfs-influxdb-objects.png differ diff --git a/content/de/developer/integration/observability/index.md b/content/de/developer/integration/observability/index.md index 2290000a..af194d42 100644 --- a/content/de/developer/integration/observability/index.md +++ b/content/de/developer/integration/observability/index.md @@ -10,5 +10,6 @@ Nutzen Sie **RustFS** als Objektspeicher-Layer für Observability-Plattformen, d - [OpenObserve](./openobserve.md) - [Loki](./loki.md) - [Tempo](./tempo.md) +- [InfluxDB](./influxdb.md) Speichern Sie Telemetriedaten in einem dedizierten Bucket und beschränken Sie die Anmeldeinformationen auf die erforderlichen Bucket-Operationen. diff --git a/content/de/developer/integration/observability/influxdb.md b/content/de/developer/integration/observability/influxdb.md new file mode 100644 index 00000000..9e6b2c6b --- /dev/null +++ b/content/de/developer/integration/observability/influxdb.md @@ -0,0 +1,279 @@ +--- +title: "InfluxDB" +description: "Betreiben Sie InfluxDB 3 Core mit RustFS als S3-Objektspeicher, bereitgestellt mit Docker Compose." +--- + +Diese Anleitung betreibt [InfluxDB](https://github.com/influxdata/influxdb) — konkret **InfluxDB 3 Core**, die Rust-basierte Zeitreihendatenbank mit einer Parquet-Speicher-Engine — mit **RustFS** als Objektspeicher. Sie starten InfluxDB mit Docker Compose, schreiben Line Protocol über die HTTP-API, fragen es per SQL zurück, prüfen die persistierten Objekte in RustFS und bestätigen, dass die Daten einen Neustart von InfluxDB überstehen. Der Ablauf wurde mit `influxdb:3-core` (v3.11.5) 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["Instrumented app"] -->|"line protocol"| InfluxDB["InfluxDB 3 Core :8181"] + InfluxDB -->|"catalog, WAL, Parquet"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +InfluxDB 3 Core hält Katalog, Write-Ahead-Log und Parquet-Datendateien im konfigurierten Objektspeicher. Schreibvorgänge landen zuerst im WAL und werden nach RustFS persistiert, sodass jeder Schreibvorgang einen Neustart übersteht, noch bevor die Kompaktierung Parquet-Dateien erzeugt. Der Server verwendet standardmäßig Path-Style-Adressierung gegenüber dem konfigurierten Endpunkt. + +## 1. Projektdateien anlegen + +Erstellen Sie ein Arbeitsverzeichnis: + +```bash +mkdir rustfs-influxdb +cd rustfs-influxdb +``` + +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 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: + - influxdb + + 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: + - influxdb + + influxdb: + image: influxdb:3-core + command: + - serve + - --node-id + - influxdb-demo + - --object-store + - s3 + - --bucket + - my-bucket + - --aws-endpoint + - http://rustfs:9000 + - --aws-access-key-id + - ${RUSTFS_ACCESS_KEY} + - --aws-secret-access-key + - ${RUSTFS_SECRET_KEY} + - --aws-allow-http + ports: + - "8181:8181" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - influxdb + +networks: + influxdb: + +volumes: + rustfs-data: +``` + +`--object-store s3` mit `--aws-endpoint` leitet alle Katalog-, WAL- und Parquet-Schreibvorgänge an RustFS. InfluxDB verwendet standardmäßig Path-Style-Adressierung gegenüber dem Endpunkt, und `--aws-allow-http` erlaubt Plain HTTP innerhalb des Compose-Netzwerks. + +## 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 +``` + +## 3. Den Admin-Token erstellen + +InfluxDB 3 Core schützt jede API-Anfrage mit einem Bearer-Token. Erstellen Sie den Admin-Token einmal nach dem ersten Start und bewahren Sie den ausgegebenen Wert auf: + +```bash +docker compose exec influxdb3 influxdb3 create token --admin +``` + +```text +Token: +``` + +:::note[Token-Erstellung] + +Der Token-Wert wird nur einmal ausgegeben und kann später nicht wiederhergestellt werden. Existiert der Token-Name bereits (HTTP 409), hat der Knoten Metadaten — beginnen Sie mit einem frischen Bucket-Präfix oder löschen Sie das Knoten-Präfix im Bucket, bevor Sie es erneut versuchen. + +::: + +## 4. Line Protocol schreiben + +Senden Sie einen Batch von CPU-Messungen im Line Protocol an die Datenbank `rustfs_demo`: + +```bash +python3 - <<'PY' +import time, urllib.request + +token = "" +now_ns = int(time.time() * 1e9) +lines = [] +for i in range(30): + ts = now_ns - i * 1_000_000_000 + lines.append(f"cpu_usage,host=az-server,region=us-east-1 usage={60 + i % 30}.{i % 10} {ts}") + +req = urllib.request.Request( + "http://localhost:8181/api/v3/write_lp?db=rustfs_demo", + data="\n".join(lines).encode(), + headers={"Content-Type": "text/plain", "Authorization": f"Bearer {token}"}, + method="POST", +) +with urllib.request.urlopen(req, timeout=30) as r: + print("write:", r.status) +PY +``` + +```text +write: 204 +``` + +## 5. Mit SQL abfragen + +Fragen Sie die Messung über die SQL-API zurück: + +```bash +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +## 6. Objekte in RustFS prüfen + +Listen Sie das Knoten-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/influxdb-demo --recursive' +``` + +Katalog, Write-Ahead-Log und später die Parquet-Datendateien liegen unter dem Knoten-Präfix: + +```text +[2026-09-20 23:18:28] 105 B influxdb-demo/catalog/v3/snapshot +[2026-09-20 23:20:54] 1.45 KiB influxdb-demo/wal/00000000001.wal +[2026-09-20 23:20:19] 31 B influxdb-demo/table-index-conversion-completed +``` + +Sie können das Präfix auch in der RustFS-Konsole anzeigen: + +![Das InfluxDB-Knoten-Präfix in der RustFS-Konsole](./images/rustfs-influxdb-objects.png) + +## 7. Persistenz über einen Neustart bestätigen + +Starten Sie InfluxDB neu und wiederholen Sie die SQL-Abfrage: + +```bash +docker compose restart influxdb +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +Die Zählung bleibt unverändert, weil Katalog und WAL aus RustFS wiedereingespielt wurden — der Objektspeicher ist die persistente Schicht, genau wie in Produktionstopologien. + +## 8. Stack stoppen oder zurücksetzen + +Stoppen Sie die Container und behalten Sie das RustFS-Datenvolumen: + +```bash +docker compose down +``` + +Um die gespeicherten Daten zu löschen und mit einem leeren RustFS-Volumen zu beginnen, fügen Sie ausdrücklich `--volumes` hinzu: + +```bash +docker compose down --volumes +``` + +## Fehlerbehebung + +### "the request was not authenticated" bei jeder Anfrage + +InfluxDB 3 Core verlangt den Admin-Bearer-Token für API-Anfragen. Erstellen Sie ihn einmal mit `influxdb3 create token --admin` und senden Sie ihn als `Authorization: Bearer `. + +### "token name already exists" beim Erstellen des Admin-Tokens + +Der Knoten hat bereits einen Admin-Token, und der Wert kann nicht wiederhergestellt werden. Löschen Sie das Knoten-Präfix im Bucket (zum Beispiel `influxdb-demo/`), während der Container gestoppt ist, starten Sie ihn erneut und erstellen Sie den Token neu. + +### AccessDenied- oder 403-Antworten + +Stellen Sie sicher, dass die Anmeldeinformationen in der Compose-Datei mit den RustFS-Anmeldeinformationen übereinstimmen und dass der Dienst `create-bucket` erfolgreich abgeschlossen wurde: + +```bash +docker compose logs create-bucket +``` + +### Verbindungs- oder Zertifikatsfehler + +`--aws-endpoint` nimmt eine vollständige URL; `--aws-allow-http` erlaubt Plain HTTP für den Container-Netzwerk-Endpunkt. Verwenden Sie innerhalb des Compose-Netzwerks `http://rustfs:9000` und auf dem Host `http://localhost:9000`. + +## 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 [InfluxDB-3-Core-Dokumentation](https://docs.influxdata.com/influxdb3/core/), um Telegraf oder die Write-APIs als Datenproduzenten anzubinden. diff --git a/content/de/developer/integration/observability/meta.json b/content/de/developer/integration/observability/meta.json index 7bbbe719..9625ee07 100644 --- a/content/de/developer/integration/observability/meta.json +++ b/content/de/developer/integration/observability/meta.json @@ -3,6 +3,7 @@ "pages": [ "openobserve", "loki", - "tempo" + "tempo", + "influxdb" ] } diff --git a/content/en/developer/integration/observability/images/rustfs-influxdb-objects.png b/content/en/developer/integration/observability/images/rustfs-influxdb-objects.png new file mode 100644 index 00000000..d5adc886 Binary files /dev/null and b/content/en/developer/integration/observability/images/rustfs-influxdb-objects.png differ diff --git a/content/en/developer/integration/observability/index.md b/content/en/developer/integration/observability/index.md index c91dc8b9..bea29344 100644 --- a/content/en/developer/integration/observability/index.md +++ b/content/en/developer/integration/observability/index.md @@ -10,5 +10,6 @@ Use **RustFS** as the object storage layer for observability platforms that supp - [OpenObserve](./openobserve.md) - [Loki](./loki.md) - [Tempo](./tempo.md) +- [InfluxDB](./influxdb.md) Keep telemetry data in a dedicated bucket, and use credentials scoped to the required bucket operations. diff --git a/content/en/developer/integration/observability/influxdb.md b/content/en/developer/integration/observability/influxdb.md new file mode 100644 index 00000000..d6db8679 --- /dev/null +++ b/content/en/developer/integration/observability/influxdb.md @@ -0,0 +1,279 @@ +--- +title: "InfluxDB" +description: "Run InfluxDB 3 Core with RustFS as its S3 object store, deployed with Docker Compose." +--- + +This guide runs [InfluxDB](https://github.com/influxdata/influxdb) — specifically **InfluxDB 3 Core**, the Rust-based time-series database with a Parquet storage engine — with **RustFS** as its object store. You will start InfluxDB with Docker Compose, write line protocol through the HTTP API, query it back with SQL, verify the persisted objects in RustFS, and confirm the data survives an InfluxDB restart. The workflow was verified with `influxdb:3-core` (v3.11.5) 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["Instrumented app"] -->|"line protocol"| InfluxDB["InfluxDB 3 Core :8181"] + InfluxDB -->|"catalog, WAL, Parquet"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +InfluxDB 3 Core keeps its catalog, write-ahead log, and Parquet data files in the configured object store. Writes land in the WAL first and are persisted to RustFS, so every write survives a restart even before compaction produces Parquet files. The server uses path-style addressing against the configured endpoint by default. + +## 1. Create the project files + +Create a working directory: + +```bash +mkdir rustfs-influxdb +cd rustfs-influxdb +``` + +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 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: + - influxdb + + 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: + - influxdb + + influxdb: + image: influxdb:3-core + command: + - serve + - --node-id + - influxdb-demo + - --object-store + - s3 + - --bucket + - my-bucket + - --aws-endpoint + - http://rustfs:9000 + - --aws-access-key-id + - ${RUSTFS_ACCESS_KEY} + - --aws-secret-access-key + - ${RUSTFS_SECRET_KEY} + - --aws-allow-http + ports: + - "8181:8181" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - influxdb + +networks: + influxdb: + +volumes: + rustfs-data: +``` + +`--object-store s3` with `--aws-endpoint` routes all catalog, WAL, and Parquet writes to RustFS. InfluxDB uses path-style addressing against the endpoint by default, and `--aws-allow-http` permits plain HTTP inside the Compose network. + +## 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 +``` + +## 3. Create the admin token + +InfluxDB 3 Core protects every API request with a bearer token. Create the admin token once after the first start and keep the printed value: + +```bash +docker compose exec influxdb3 influxdb3 create token --admin +``` + +```text +Token: +``` + +:::note[Token creation] + +The token value is printed only once and cannot be recovered later. If the token name is already taken (HTTP 409), the node has existing metadata — start from a fresh bucket prefix or delete the node prefix in the bucket before retrying. + +::: + +## 4. Write line protocol + +Send a batch of CPU measurements in line protocol to the `rustfs_demo` database: + +```bash +python3 - <<'PY' +import time, urllib.request + +token = "" +now_ns = int(time.time() * 1e9) +lines = [] +for i in range(30): + ts = now_ns - i * 1_000_000_000 + lines.append(f"cpu_usage,host=az-server,region=us-east-1 usage={60 + i % 30}.{i % 10} {ts}") + +req = urllib.request.Request( + "http://localhost:8181/api/v3/write_lp?db=rustfs_demo", + data="\n".join(lines).encode(), + headers={"Content-Type": "text/plain", "Authorization": f"Bearer {token}"}, + method="POST", +) +with urllib.request.urlopen(req, timeout=30) as r: + print("write:", r.status) +PY +``` + +```text +write: 204 +``` + +## 5. Query with SQL + +Query the measurement back through the SQL API: + +```bash +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +## 6. Verify objects in RustFS + +List the node 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/influxdb-demo --recursive' +``` + +The catalog, the write-ahead log, and later the Parquet data files live under the node identifier prefix: + +```text +[2026-09-20 23:18:28] 105 B influxdb-demo/catalog/v3/snapshot +[2026-09-20 23:20:54] 1.45 KiB influxdb-demo/wal/00000000001.wal +[2026-09-20 23:20:19] 31 B influxdb-demo/table-index-conversion-completed +``` + +You can also browse the prefix in the RustFS Console: + +![The InfluxDB node prefix stored in the RustFS Console](./images/rustfs-influxdb-objects.png) + +## 7. Confirm persistence across a restart + +Restart InfluxDB and repeat the SQL query: + +```bash +docker compose restart influxdb +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +The count is unchanged because the catalog and WAL were replayed from RustFS — the object store is the persistence layer, exactly as in production topologies. + +## 8. Stop or reset the stack + +Stop the containers while keeping the RustFS data volume: + +```bash +docker compose down +``` + +To delete the stored data and start from an empty RustFS volume, explicitly include `--volumes`: + +```bash +docker compose down --volumes +``` + +## Troubleshooting + +### "the request was not authenticated" on every request + +InfluxDB 3 Core requires the admin bearer token on API requests. Create it once with `influxdb3 create token --admin` and send it as `Authorization: Bearer `. + +### "token name already exists" when creating the admin token + +The node already has an admin token, and the value cannot be recovered. Delete the node prefix in the bucket (for example `influxdb-demo/`) while the container is stopped, start it again, and create the token fresh. + +### AccessDenied or 403 responses + +Confirm the credentials in the Compose file match the RustFS credentials and that the `create-bucket` service completed successfully: + +```bash +docker compose logs create-bucket +``` + +### Connection or certificate errors + +`--aws-endpoint` takes a full URL; `--aws-allow-http` permits plain HTTP for the container-network endpoint. Inside the Compose network use `http://rustfs:9000`; from the host use `http://localhost:9000`. + +## 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 [InfluxDB 3 Core documentation](https://docs.influxdata.com/influxdb3/core/) to connect telegraf or the write APIs as data producers. diff --git a/content/en/developer/integration/observability/meta.json b/content/en/developer/integration/observability/meta.json index 7bbbe719..9625ee07 100644 --- a/content/en/developer/integration/observability/meta.json +++ b/content/en/developer/integration/observability/meta.json @@ -3,6 +3,7 @@ "pages": [ "openobserve", "loki", - "tempo" + "tempo", + "influxdb" ] } diff --git a/content/fr/developer/integration/observability/images/rustfs-influxdb-objects.png b/content/fr/developer/integration/observability/images/rustfs-influxdb-objects.png new file mode 100644 index 00000000..d5adc886 Binary files /dev/null and b/content/fr/developer/integration/observability/images/rustfs-influxdb-objects.png differ diff --git a/content/fr/developer/integration/observability/index.md b/content/fr/developer/integration/observability/index.md index cd3d854e..ae80427f 100644 --- a/content/fr/developer/integration/observability/index.md +++ b/content/fr/developer/integration/observability/index.md @@ -10,5 +10,6 @@ Utilisez **RustFS** comme couche de stockage objet pour les plateformes d'observ - [OpenObserve](./openobserve.md) - [Loki](./loki.md) - [Tempo](./tempo.md) +- [InfluxDB](./influxdb.md) Conservez les données de télémétrie dans un bucket dédié et limitez les identifiants aux opérations de bucket requises. diff --git a/content/fr/developer/integration/observability/influxdb.md b/content/fr/developer/integration/observability/influxdb.md new file mode 100644 index 00000000..48a8f686 --- /dev/null +++ b/content/fr/developer/integration/observability/influxdb.md @@ -0,0 +1,279 @@ +--- +title: "InfluxDB" +description: "Exécutez InfluxDB 3 Core avec RustFS comme magasin d'objets S3, déployé avec Docker Compose." +--- + +Ce guide exécute [InfluxDB](https://github.com/influxdata/influxdb) — plus précisément **InfluxDB 3 Core**, la base de données temporelle écrite en Rust avec un moteur de stockage Parquet — avec **RustFS** comme magasin d'objets. Vous allez démarrer InfluxDB avec Docker Compose, écrire du line protocol via l'API HTTP, l'interroger en SQL, vérifier les objets persistés dans RustFS et confirmer que les données survivent à un redémarrage d'InfluxDB. Le flux a été validé avec `influxdb:3-core` (v3.11.5) 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["Instrumented app"] -->|"line protocol"| InfluxDB["InfluxDB 3 Core :8181"] + InfluxDB -->|"catalog, WAL, Parquet"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +InfluxDB 3 Core conserve son catalogue, son journal d'écriture anticipée (WAL) et ses fichiers de données Parquet dans le magasin d'objets configuré. Les écritures arrivent d'abord dans le WAL et sont persistées vers RustFS, de sorte que chaque écriture survit à un redémarrage avant même que la compaction ne produise des fichiers Parquet. Le serveur utilise par défaut un adressage path-style vers le point de terminaison configuré. + +## 1. Créer les fichiers du projet + +Créez un répertoire de travail : + +```bash +mkdir rustfs-influxdb +cd rustfs-influxdb +``` + +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 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: + - influxdb + + 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: + - influxdb + + influxdb: + image: influxdb:3-core + command: + - serve + - --node-id + - influxdb-demo + - --object-store + - s3 + - --bucket + - my-bucket + - --aws-endpoint + - http://rustfs:9000 + - --aws-access-key-id + - ${RUSTFS_ACCESS_KEY} + - --aws-secret-access-key + - ${RUSTFS_SECRET_KEY} + - --aws-allow-http + ports: + - "8181:8181" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - influxdb + +networks: + influxdb: + +volumes: + rustfs-data: +``` + +`--object-store s3` avec `--aws-endpoint` route toutes les écritures de catalogue, de WAL et de Parquet vers RustFS. InfluxDB utilise par défaut un adressage path-style vers le point de terminaison, et `--aws-allow-http` autorise HTTP simple à l'intérieur du réseau Compose. + +## 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 +``` + +## 3. Créer le token d'administration + +InfluxDB 3 Core protège chaque requête API avec un token porteur. Créez le token d'administration une fois après le premier démarrage et conservez la valeur affichée : + +```bash +docker compose exec influxdb3 influxdb3 create token --admin +``` + +```text +Token: +``` + +:::note[Création du token] + +La valeur du token n'est affichée qu'une seule fois et ne peut pas être récupérée ultérieurement. Si le nom du token existe déjà (HTTP 409), le nœud possède des métadonnées — repartez d'un préfixe de bucket neuf ou supprimez le préfixe du nœud dans le bucket avant de réessayer. + +::: + +## 4. Écrire du line protocol + +Envoyez un lot de mesures CPU en line protocol vers la base `rustfs_demo` : + +```bash +python3 - <<'PY' +import time, urllib.request + +token = "" +now_ns = int(time.time() * 1e9) +lines = [] +for i in range(30): + ts = now_ns - i * 1_000_000_000 + lines.append(f"cpu_usage,host=az-server,region=us-east-1 usage={60 + i % 30}.{i % 10} {ts}") + +req = urllib.request.Request( + "http://localhost:8181/api/v3/write_lp?db=rustfs_demo", + data="\n".join(lines).encode(), + headers={"Content-Type": "text/plain", "Authorization": f"Bearer {token}"}, + method="POST", +) +with urllib.request.urlopen(req, timeout=30) as r: + print("write:", r.status) +PY +``` + +```text +write: 204 +``` + +## 5. Interroger en SQL + +Interrogez la mesure via l'API SQL : + +```bash +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +## 6. Vérifier les objets dans RustFS + +Listez le préfixe du nœud 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/influxdb-demo --recursive' +``` + +Le catalogue, le WAL et ensuite les fichiers de données Parquet résident sous le préfixe identifiant le nœud : + +```text +[2026-09-20 23:18:28] 105 B influxdb-demo/catalog/v3/snapshot +[2026-09-20 23:20:54] 1.45 KiB influxdb-demo/wal/00000000001.wal +[2026-09-20 23:20:19] 31 B influxdb-demo/table-index-conversion-completed +``` + +Vous pouvez également parcourir le préfixe dans la console RustFS : + +![Le préfixe du nœud InfluxDB stocké dans la console RustFS](./images/rustfs-influxdb-objects.png) + +## 7. Confirmer la persistance après un redémarrage + +Redémarrez InfluxDB et répétez la requête SQL : + +```bash +docker compose restart influxdb +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +Le compteur est inchangé car le catalogue et le WAL ont été rejoués depuis RustFS — le magasin d'objets est la couche de persistance, exactement comme dans les topologies de production. + +## 8. 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 données stockées et repartir d'un volume RustFS vide, ajoutez explicitement `--volumes` : + +```bash +docker compose down --volumes +``` + +## Dépannage + +### "the request was not authenticated" sur chaque requête + +InfluxDB 3 Core exige le token porteur d'administration sur les requêtes API. Créez-le une fois avec `influxdb3 create token --admin` et envoyez-le sous la forme `Authorization: Bearer `. + +### "token name already exists" lors de la création du token d'administration + +Le nœud possède déjà un token d'administration, et la valeur ne peut pas être récupérée. Supprimez le préfixe du nœud dans le bucket (par exemple `influxdb-demo/`) pendant que le conteneur est arrêté, redémarrez-le, puis créez un nouveau token. + +### Réponses AccessDenied ou 403 + +Vérifiez que les identifiants du fichier Compose correspondent aux identifiants RustFS et que la tâche `create-bucket` s'est terminée avec succès : + +```bash +docker compose logs create-bucket +``` + +### Erreurs de connexion ou de certificat + +`--aws-endpoint` prend une URL complète ; `--aws-allow-http` autorise HTTP simple pour le point de terminaison du réseau de conteneurs. À l'intérieur du réseau Compose, utilisez `http://rustfs:9000` ; depuis l'hôte, `http://localhost:9000`. + +## 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 InfluxDB 3 Core](https://docs.influxdata.com/influxdb3/core/) pour connecter telegraf ou les API d'écriture comme producteurs de données. diff --git a/content/fr/developer/integration/observability/meta.json b/content/fr/developer/integration/observability/meta.json index c9fe1865..abbab2fa 100644 --- a/content/fr/developer/integration/observability/meta.json +++ b/content/fr/developer/integration/observability/meta.json @@ -3,6 +3,7 @@ "pages": [ "openobserve", "loki", - "tempo" + "tempo", + "influxdb" ] } diff --git a/content/ja/developer/integration/observability/images/rustfs-influxdb-objects.png b/content/ja/developer/integration/observability/images/rustfs-influxdb-objects.png new file mode 100644 index 00000000..d5adc886 Binary files /dev/null and b/content/ja/developer/integration/observability/images/rustfs-influxdb-objects.png differ diff --git a/content/ja/developer/integration/observability/index.md b/content/ja/developer/integration/observability/index.md index 896cf131..3da1e3bc 100644 --- a/content/ja/developer/integration/observability/index.md +++ b/content/ja/developer/integration/observability/index.md @@ -10,5 +10,6 @@ S3 互換エンドポイントをサポートするオブザーバビリティ - [OpenObserve](./openobserve.md) - [Loki](./loki.md) - [Tempo](./tempo.md) +- [InfluxDB](./influxdb.md) テレメトリデータは専用バケットに保存し、必要なバケット操作のみに権限が絞られた認証情報を使用してください。 diff --git a/content/ja/developer/integration/observability/influxdb.md b/content/ja/developer/integration/observability/influxdb.md new file mode 100644 index 00000000..88c25fef --- /dev/null +++ b/content/ja/developer/integration/observability/influxdb.md @@ -0,0 +1,279 @@ +--- +title: "InfluxDB" +description: "S3 オブジェクトストアとして RustFS を使って InfluxDB 3 Core を実行します。Docker Compose でデプロイします。" +--- + +このガイドでは、[InfluxDB](https://github.com/influxdata/influxdb) — 具体的には Rust 製で Parquet ストレージエンジンを採用する時系列データベース **InfluxDB 3 Core** — を、**RustFS** をオブジェクトストアとして実行します。Docker Compose で InfluxDB を起動し、HTTP API 経由でラインプロトコルを書き込み、SQL で読み戻し、RustFS 内の永続化オブジェクトを確認して、データが InfluxDB の再起動後も保持されることを確認します。この流れは `influxdb:3-core`(v3.11.5)と `rustfs/rustfs-x86-musl:v2.3.1` で検証済みです。 + +Docker と Compose プラグインが必要です。このデプロイはローカルでの統合テストを目的としており、本番環境向けではありません。 + +## アーキテクチャ + +```mermaid +flowchart LR + Client["Instrumented app"] -->|"line protocol"| InfluxDB["InfluxDB 3 Core :8181"] + InfluxDB -->|"catalog, WAL, Parquet"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +InfluxDB 3 Core は、カタログ・先行書き込みログ(WAL)・Parquet データファイルを設定されたオブジェクトストアに保持します。書き込みはまず WAL に記録されて RustFS へ永続化されるため、コンパクションが Parquet ファイルを生成する前でも、すべての書き込みが再起動後も保持されます。サーバーは設定されたエンドポイントに対してデフォルトでパススタイルのアドレス指定を使用します。 + +## 1. プロジェクトファイルを作成する + +作業ディレクトリを作成します。 + +```bash +mkdir rustfs-influxdb +cd rustfs-influxdb +``` + +環境変数ファイルを作成し、2 つの認証情報プレースホルダーを置き換えます。 + +```ini title=".env" +RUSTFS_ACCESS_KEY= +RUSTFS_SECRET_KEY= +``` + +バケットには専用の認証情報を使用してください。`.env` をバージョン管理にコミットしないでください。 + +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: + - influxdb + + 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: + - influxdb + + influxdb: + image: influxdb:3-core + command: + - serve + - --node-id + - influxdb-demo + - --object-store + - s3 + - --bucket + - my-bucket + - --aws-endpoint + - http://rustfs:9000 + - --aws-access-key-id + - ${RUSTFS_ACCESS_KEY} + - --aws-secret-access-key + - ${RUSTFS_SECRET_KEY} + - --aws-allow-http + ports: + - "8181:8181" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - influxdb + +networks: + influxdb: + +volumes: + rustfs-data: +``` + +`--object-store s3` と `--aws-endpoint` により、カタログ・WAL・Parquet のすべての書き込みが RustFS にルーティングされます。InfluxDB はエンドポイントに対してデフォルトでパススタイルのアドレス指定を使用し、`--aws-allow-http` は Compose ネットワーク内での平文 HTTP を許可します。 + +## 2. デプロイを起動する + +コンテナを起動する前に Compose ファイルを検証します。 + +```bash +docker compose config +``` + +サービスを起動し、バケット初期化の完了を待ちます。 + +```bash +docker compose up -d +docker compose ps -a +``` + +## 3. 管理者トークンを作成する + +InfluxDB 3 Core はすべての API リクエストにベアラートークンを要求します。初回起動後に管理者トークンを一度作成し、表示された値を保存してください。 + +```bash +docker compose exec influxdb3 influxdb3 create token --admin +``` + +```text +Token: +``` + +:::note[トークンの作成] + +トークンの値は一度しか表示されず、後から復元できません。トークン名が既に存在する場合(HTTP 409)は、ノードにメタデータが残っています。新しいバケットプレフィックスでやり直すか、再試行前にバケット内のノードプレフィックスを削除してください。 + +::: + +## 4. ラインプロトコルを書き込む + +`rustfs_demo` データベースへ、ラインプロトコル形式の CPU 測定値のバッチを送信します。 + +```bash +python3 - <<'PY' +import time, urllib.request + +token = "" +now_ns = int(time.time() * 1e9) +lines = [] +for i in range(30): + ts = now_ns - i * 1_000_000_000 + lines.append(f"cpu_usage,host=az-server,region=us-east-1 usage={60 + i % 30}.{i % 10} {ts}") + +req = urllib.request.Request( + "http://localhost:8181/api/v3/write_lp?db=rustfs_demo", + data="\n".join(lines).encode(), + headers={"Content-Type": "text/plain", "Authorization": f"Bearer {token}"}, + method="POST", +) +with urllib.request.urlopen(req, timeout=30) as r: + print("write:", r.status) +PY +``` + +```text +write: 204 +``` + +## 5. SQL で照会する + +SQL API で計測データを読み戻します。 + +```bash +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +## 6. 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/influxdb-demo --recursive' +``` + +カタログ・WAL・後から生成される Parquet データファイルは、ノード識別子のプレフィックスの下に保存されます。 + +```text +[2026-09-20 23:18:28] 105 B influxdb-demo/catalog/v3/snapshot +[2026-09-20 23:20:54] 1.45 KiB influxdb-demo/wal/00000000001.wal +[2026-09-20 23:20:19] 31 B influxdb-demo/table-index-conversion-completed +``` + +RustFS コンソールでこのプレフィックスを参照することもできます。 + +![RustFS コンソールに保存された InfluxDB のノードプレフィックス](./images/rustfs-influxdb-objects.png) + +## 7. 再起動後の永続性を確認する + +InfluxDB を再起動して、SQL クエリを繰り返します。 + +```bash +docker compose restart influxdb +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +カタログと WAL が RustFS からリプレイされるため、カウントは変わりません。オブジェクトストアがまさに永続層であり、本番トポロジと同じ仕組みです。 + +## 8. スタックを停止・リセットする + +RustFS データボリュームを保持したままコンテナを停止します。 + +```bash +docker compose down +``` + +保存したデータを削除して空の RustFS ボリュームからやり直す場合は、明示的に `--volumes` を付けます。 + +```bash +docker compose down --volumes +``` + +## トラブルシューティング + +### すべてのリクエストで "the request was not authenticated" が出る + +InfluxDB 3 Core は API リクエストに管理者ベアラートークンを要求します。`influxdb3 create token --admin` で一度作成し、`Authorization: Bearer ` として送信してください。 + +### 管理者トークンの作成で "token name already exists" が出る + +ノードには既に管理者トークンがあり、値は復元できません。コンテナを停止した状態でバケット内のノードプレフィックス(例 `influxdb-demo/`)を削除し、再起動後に新しいトークンを作成してください。 + +### AccessDenied や 403 レスポンス + +Compose ファイルの認証情報が RustFS の認証情報と一致しているか、`create-bucket` ジョブが正常に完了しているかを確認してください。 + +```bash +docker compose logs create-bucket +``` + +### 接続エラーや証明書エラー + +`--aws-endpoint` には完全な URL を指定します。`--aws-allow-http` はコンテナネットワークエンドポイントでの平文 HTTP を許可します。Compose ネットワーク内では `http://rustfs:9000` を、ホストからは `http://localhost:9000` を使用してください。 + +## 次のステップ + +- 追加の S3 オペレーションを採用する前に、[S3 互換性ノート](/administration/protocols/s3)を確認してください。 +- [アクセスキー管理](/security-compliance/iam/access-token)で本番用の専用認証情報を作成してください。 +- [InfluxDB 3 Core ドキュメント](https://docs.influxdata.com/influxdb3/core/)に従って、telegraf や書き込み API をデータプロデューサーとして接続してください。 diff --git a/content/ja/developer/integration/observability/meta.json b/content/ja/developer/integration/observability/meta.json index f6d8d61c..4a13f8c7 100644 --- a/content/ja/developer/integration/observability/meta.json +++ b/content/ja/developer/integration/observability/meta.json @@ -3,6 +3,7 @@ "pages": [ "openobserve", "loki", - "tempo" + "tempo", + "influxdb" ] } diff --git a/content/zh/developer/integration/observability/images/rustfs-influxdb-objects.png b/content/zh/developer/integration/observability/images/rustfs-influxdb-objects.png new file mode 100644 index 00000000..e9658c20 Binary files /dev/null and b/content/zh/developer/integration/observability/images/rustfs-influxdb-objects.png differ diff --git a/content/zh/developer/integration/observability/index.md b/content/zh/developer/integration/observability/index.md index 9234d46d..ff2ff20f 100644 --- a/content/zh/developer/integration/observability/index.md +++ b/content/zh/developer/integration/observability/index.md @@ -10,5 +10,6 @@ description: "通过 S3 兼容对象存储接口,将可观测性平台连接 - [OpenObserve](./openobserve.md) - [Loki](./loki.md) - [Tempo](./tempo.md) +- [InfluxDB](./influxdb.md) 请使用专用的存储桶保存遥测数据,并为凭证仅授予所需桶操作的权限。 diff --git a/content/zh/developer/integration/observability/influxdb.md b/content/zh/developer/integration/observability/influxdb.md new file mode 100644 index 00000000..35bb168f --- /dev/null +++ b/content/zh/developer/integration/observability/influxdb.md @@ -0,0 +1,279 @@ +--- +title: "InfluxDB" +description: "使用 Docker Compose 运行 InfluxDB 3 Core,以 RustFS 作为其 S3 对象存储。" +--- + +本指南运行 [InfluxDB](https://github.com/influxdata/influxdb)——具体是 **InfluxDB 3 Core**,基于 Rust、采用 Parquet 存储引擎的时序数据库——并以 **RustFS** 作为其对象存储。你将使用 Docker Compose 启动 InfluxDB,通过 HTTP API 写入 line protocol,用 SQL 查询回来,在 RustFS 中验证持久化的对象,并确认数据能在 InfluxDB 重启后保留。整个流程使用 `influxdb:3-core`(v3.11.5)和 `rustfs/rustfs-x86-musl:v2.3.1` 验证通过。 + +你需要安装带有 Compose 插件的 Docker。本部署用于本地集成测试,不适用于生产环境。 + +## 架构 + +```mermaid +flowchart LR + Client["Instrumented app"] -->|"line protocol"| InfluxDB["InfluxDB 3 Core :8181"] + InfluxDB -->|"catalog, WAL, Parquet"| RustFS["RustFS :9000"] + Init["init-bucket job"] -->|"create my-bucket"| RustFS +``` + +InfluxDB 3 Core 将目录(catalog)、预写日志(WAL)和 Parquet 数据文件保存在配置的对象存储中。写入先落入 WAL 并持久化到 RustFS,因此在压缩生成 Parquet 文件之前,每次写入也能在重启后保留。服务端默认对所配置的端点使用 path-style 寻址。 + +## 1. 创建项目文件 + +创建工作目录: + +```bash +mkdir rustfs-influxdb +cd rustfs-influxdb +``` + +创建环境变量文件,并替换两个凭证占位符: + +```ini title=".env" +RUSTFS_ACCESS_KEY= +RUSTFS_SECRET_KEY= +``` + +请为桶使用专用的凭证,不要将 `.env` 提交到版本控制。 + +创建 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: + - influxdb + + 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: + - influxdb + + influxdb: + image: influxdb:3-core + command: + - serve + - --node-id + - influxdb-demo + - --object-store + - s3 + - --bucket + - my-bucket + - --aws-endpoint + - http://rustfs:9000 + - --aws-access-key-id + - ${RUSTFS_ACCESS_KEY} + - --aws-secret-access-key + - ${RUSTFS_SECRET_KEY} + - --aws-allow-http + ports: + - "8181:8181" + depends_on: + create-bucket: + condition: service_completed_successfully + networks: + - influxdb + +networks: + influxdb: + +volumes: + rustfs-data: +``` + +`--object-store s3` 加上 `--aws-endpoint` 会把所有 catalog、WAL 和 Parquet 写入路由到 RustFS。InfluxDB 默认对该端点使用 path-style 寻址,`--aws-allow-http` 允许在 Compose 网络内使用纯 HTTP。 + +## 2. 启动部署 + +启动容器前先解析 Compose 文件: + +```bash +docker compose config +``` + +启动服务并等待桶初始化任务完成: + +```bash +docker compose up -d +docker compose ps -a +``` + +## 3. 创建管理员令牌 + +InfluxDB 3 Core 的每个 API 请求都需要持有者令牌(bearer token)。首次启动后创建一次管理员令牌,并保存打印出的值: + +```bash +docker compose exec influxdb3 influxdb3 create token --admin +``` + +```text +Token: +``` + +:::note[令牌创建] + +令牌值只会打印一次,之后无法找回。如果提示令牌名已存在(HTTP 409),说明该节点已有元数据——请换一个全新的桶前缀,或删除桶中的节点前缀后重试。 + +::: + +## 4. 写入 line protocol + +向 `rustfs_demo` 数据库发送一批 CPU 指标的 line protocol: + +```bash +python3 - <<'PY' +import time, urllib.request + +token = "" +now_ns = int(time.time() * 1e9) +lines = [] +for i in range(30): + ts = now_ns - i * 1_000_000_000 + lines.append(f"cpu_usage,host=az-server,region=us-east-1 usage={60 + i % 30}.{i % 10} {ts}") + +req = urllib.request.Request( + "http://localhost:8181/api/v3/write_lp?db=rustfs_demo", + data="\n".join(lines).encode(), + headers={"Content-Type": "text/plain", "Authorization": f"Bearer {token}"}, + method="POST", +) +with urllib.request.urlopen(req, timeout=30) as r: + print("write:", r.status) +PY +``` + +```text +write: 204 +``` + +## 5. 使用 SQL 查询 + +通过 SQL API 把刚才的测量数据查询回来: + +```bash +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +## 6. 在 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/influxdb-demo --recursive' +``` + +catalog、预写日志以及后续生成的 Parquet 数据文件都位于节点标识前缀之下: + +```text +[2026-09-20 23:18:28] 105 B influxdb-demo/catalog/v3/snapshot +[2026-09-20 23:20:54] 1.45 KiB influxdb-demo/wal/00000000001.wal +[2026-09-20 23:20:19] 31 B influxdb-demo/table-index-conversion-completed +``` + +你也可以在 RustFS 控制台中浏览该前缀: + +![RustFS 控制台中存储的 InfluxDB 节点前缀](./images/rustfs-influxdb-objects.png) + +## 7. 确认重启后数据仍在 + +重启 InfluxDB 并重复 SQL 查询: + +```bash +docker compose restart influxdb +curl -sG "http://localhost:8181/api/v3/query_sql" \ + --data-urlencode "db=rustfs_demo" \ + --data-urlencode "format=json" \ + --data-urlencode "q=SELECT count(*) AS cnt FROM cpu_usage" \ + -H "Authorization: Bearer " +``` + +```text +[{"cnt":30}] +``` + +计数保持不变,因为 catalog 和 WAL 是从 RustFS 重放的——对象存储就是持久层,与生产拓扑完全一致。 + +## 8. 停止或重置环境 + +停止容器并保留 RustFS 数据卷: + +```bash +docker compose down +``` + +如需删除已存储的数据并从空的 RustFS 数据卷开始,请显式加上 `--volumes`: + +```bash +docker compose down --volumes +``` + +## 故障排除 + +### 所有请求都提示 "the request was not authenticated" + +InfluxDB 3 Core 的 API 请求需要管理员持有者令牌。先用 `influxdb3 create token --admin` 创建一次,并以 `Authorization: Bearer ` 的形式发送。 + +### 创建管理员令牌时提示 "token name already exists" + +节点已有管理员令牌,且令牌值无法找回。在容器停止的情况下删除桶中的节点前缀(例如 `influxdb-demo/`),重新启动后再创建新令牌。 + +### 返回 AccessDenied 或 403 响应 + +确认 Compose 文件中的凭证与 RustFS 凭证一致,并确认 `create-bucket` 任务已成功完成: + +```bash +docker compose logs create-bucket +``` + +### 连接或证书错误 + +`--aws-endpoint` 接收完整 URL;`--aws-allow-http` 允许容器网络端点使用纯 HTTP。Compose 网络内使用 `http://rustfs:9000` (宿主机上使用 `http://localhost:9000`)。 + +## 后续步骤 + +- 在采用其他 S3 操作前,请查看 [S3 兼容性说明](/administration/protocols/s3)。 +- 通过[访问密钥管理](/security-compliance/iam/access-token)创建专用的生产凭证。 +- 按照 [InfluxDB 3 Core 文档](https://docs.influxdata.com/influxdb3/core/)接入 telegraf 或通过写入 API 作为数据生产者。 diff --git a/content/zh/developer/integration/observability/meta.json b/content/zh/developer/integration/observability/meta.json index 7efedc39..05fb2e87 100644 --- a/content/zh/developer/integration/observability/meta.json +++ b/content/zh/developer/integration/observability/meta.json @@ -3,6 +3,7 @@ "pages": [ "openobserve", "loki", - "tempo" + "tempo", + "influxdb" ] }