From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id D866D1FF16F for ; Tue, 22 Jul 2025 14:48:18 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 6A1EF97C7; Tue, 22 Jul 2025 14:49:33 +0200 (CEST) From: Christian Ebner To: pbs-devel@lists.proxmox.com Date: Tue, 22 Jul 2025 14:48:35 +0200 Message-ID: <20250722124837.864242-5-c.ebner@proxmox.com> X-Mailer: git-send-email 2.47.2 In-Reply-To: <20250722124837.864242-1-c.ebner@proxmox.com> References: <20250722124837.864242-1-c.ebner@proxmox.com> MIME-Version: 1.0 X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1753188528519 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.045 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pbs-devel] [PATCH proxmox-backup 4/6] docs: use `endpoint` over `client` for the s3 endpoint configuration X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox Backup Server development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pbs-devel-bounces@lists.proxmox.com Sender: "pbs-devel" The WebUI and CLI have been adapted to use s3 endpoint rather than S3 client, so update the documentation to be consistent. Signed-off-by: Christian Ebner --- docs/storage.rst | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/storage.rst b/docs/storage.rst index b1f1a5732..eae72a487 100644 --- a/docs/storage.rst +++ b/docs/storage.rst @@ -237,17 +237,18 @@ Datastores with S3 Backend (experimental) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Proxmox Backup Server supports S3 compatible object stores as storage backend for datastores. For -this, an S3 client needs to be set-up under "Configuration" > "S3 Clients". +this, an S3 endpoint needs to be set-up under "Configuration" > "Remotes" > "S3 Endpoints". -In the client configuration, provide the REST API endpoint for the object store. The endpoint +In the endpoint configuration, provide the REST API endpoint for the object store. The endpoint is provider dependent and allows for the bucket and region templating. For example, configuring the endpoint as e.g. ``{{bucket}}.s3.{{region}}.amazonaws.com`` will be expanded to ``my-pbs-bucket.s3.eu-central-1.amazonaws.com`` with a configured bucket of name ``my-pbs-bucket`` located in region ``eu-central-1``. -The bucket name is part of the datastore backend configuration rather than the client configuration, -as the same client might be reused for multiple bucket. Objects placed in the bucket are prefixed by -the datastore name, therefore it is possible to create multiple datastores using the same bucket. +The bucket name is part of the datastore backend configuration rather than the endpoint +configuration, as the same endpoint might be reused for multiple bucket. Objects placed in the +bucket are prefixed by the datastore name, therefore it is possible to create multiple datastores +using the same bucket. .. note:: Proxmox Backup Server does not handle bucket creation and access control. The bucket used to store the datastore's objects as well as the access key have to be setup beforehand in your S3 @@ -262,22 +263,22 @@ flag. Proxmox Backup Server does not support plain text communication with the S3 API, all communication is encrypted using HTTPS in transit. Therefore, for self-hosted S3 object stores using a self-signed -certificate, the matching fingerprint has to be provided to the client configuration. Otherwise the -client refuses connections to the S3 object store. +certificate, the matching fingerprint has to be provided to the endpoint configuration. Otherwise +the client refuses connections to the S3 object store. -The following example shows the setup of a new s3 client configuration: +The following example shows the setup of a new s3 endpoint configuration: .. code-block:: console - # proxmox-backup-manager s3 client create my-s3-client --access-key 'my-access-key' --secret-key 'my-secret-key' --endpoint '{{bucket}}.s3.{{region}}.amazonaws.com' --region eu-central-1 + # proxmox-backup-manager s3 endpoint create my-s3-ep --access-key 'my-access-key' --secret-key 'my-secret-key' --endpoint '{{bucket}}.s3.{{region}}.amazonaws.com' --region eu-central-1 -To list your s3 client configuration, run: +To list your s3 endpoint configuration, run: .. code-block:: console - # proxmox-backup-manager s3 client list + # proxmox-backup-manager s3 endpoint list -A new datastore with S3 backend can be created using one of the configures S3 clients. Although +A new datastore with S3 backend can be created using one of the configured S3 endpoints. Although storing all contents on the S3 object store, the datastore requires nevertheless a local cache store, used to increase performance and reduce the number of requests to the backend. For this, a local filesystem path has to be provided during datastore creation, just like for regular datastore setup. @@ -288,7 +289,7 @@ To setup a new datastore called ``my-s3-store`` placed in a bucket called ``pbs- .. code-block:: console - # proxmox-backup-manager datastore create my-s3-store /mnt/datastore/my-s3-store-cache --backend type=s3,client=my-s3-client,bucket=pbs-s3-bucket + # proxmox-backup-manager datastore create my-s3-store /mnt/datastore/my-s3-store-cache --backend type=s3,client=my-s3-ep,bucket=pbs-s3-bucket A datastore cannot be shared between multiple Proxmox Backup Server instances, only one instance can operate on the datastore at a time. However, datastore contents used on an instance which is no @@ -298,7 +299,7 @@ same datastore name must be used. .. code-block:: console - # proxmox-backup-manager datastore create my-s3-store /mnt/datastore/my-new-s3-store-cache --backend type=s3,client=my-s3-client,bucket=pbs-s3-bucket --reuse-datastore true --overwrite-in-use true + # proxmox-backup-manager datastore create my-s3-store /mnt/datastore/my-new-s3-store-cache --backend type=s3,client=my-s3-ep,bucket=pbs-s3-bucket --reuse-datastore true --overwrite-in-use true .. note:: If your S3 object store runs out of space while performing write operation to it, most likely cleanup operations such as cleaning up of contents within a snapshot directory will fail -- 2.47.2 _______________________________________________ pbs-devel mailing list pbs-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel