From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 4D3BD1FF17A for ; Fri, 18 Jul 2025 16:02:07 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 0AC3230140; Fri, 18 Jul 2025 16:03:15 +0200 (CEST) References: <20250715125332.954494-1-c.ebner@proxmox.com> <20250715125332.954494-55-c.ebner@proxmox.com> User-agent: mu4e 1.10.8; emacs 30.1 From: Maximiliano Sandoval To: Proxmox Backup Server development discussion Date: Fri, 18 Jul 2025 15:14:03 +0200 In-reply-to: <20250715125332.954494-55-c.ebner@proxmox.com> Message-ID: MIME-Version: 1.0 X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1752847357356 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.096 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 RCVD_IN_VALIDITY_CERTIFIED_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_RPBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. RCVD_IN_VALIDITY_SAFE_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to Validity was blocked. See https://knowledge.validity.com/hc/en-us/articles/20961730681243 for more information. SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: Re: [pbs-devel] [PATCH proxmox-backup v8 45/45] docs: Add section describing how to setup s3 backed datastore 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" Documentation looks good to me. Some small comments bellow. Christian Ebner writes: > Describe required basic S3 client setup and possible configuration > options as well as the actual setup of a datastore using the client and > a bucket as backend. > > Signed-off-by: Christian Ebner > --- > changes since version 7: > - new in this version > > docs/storage.rst | 68 ++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 68 insertions(+) > > diff --git a/docs/storage.rst b/docs/storage.rst > index 4a8d8255e..0bac85fc3 100644 > --- a/docs/storage.rst > +++ b/docs/storage.rst > @@ -233,6 +233,74 @@ datastore is not mounted when they are scheduled. Sync jobs start, but fail > with an error saying the datastore was not mounted. The reason is that syncs > not happening as scheduled should at least be noticeable. > > +Datastores with S3 Backend (experimental) I think we generally use the term "technology preview" in these cases. > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > + > +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". > + > +In the client 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. > + > +.. 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 > + provider interface. The Proxmox Backup Server acts as client and requires permissions to get, put > + list and delete objects in the bucket. > + > +Most providers allow to access buckets either using a vhost style addressing, the bucket name being > +part of the endpoint address, or via path style addressing, the bucket name being the prefix to > +the path components of requests. Proxmox Backup Server supports both styles, favoring the vhost > +style urls over the path style. To use path style addresses, set the corresponding configuration > +flag. > + > +Proxmox Backup Server does not support plain text communication with the S3 API, all communication > +is excrypted using HTTPS in transit. Therefore, for self-hostsd S3 object stores using a self-signed s/excrypted/encrypted and s/hostsd/hosted. > +certificate, the matching fingerprint has to be provided to the client configuration. Otherwise the > +client refuses connections to the S3 object store. > + > +The following example shows the setup of a new s3 client configuration: > + > +.. code-block:: console > + > + # proxmox-backup-manager s3 client create my-s3-client --secrets-id my-s3-client --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: > + > +.. code-block:: console > + > + # proxmox-backup-manager s3 client list > + > +A new datastore with S3 backend can be created using one of the configures S3 clients. 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. > +A minimum size of a few GiB of storage is recommended, given that cache datastore contents include > +also data chunks. > + > +To setup a new datastore called ``my-s3-store`` placed in a bucket called ``pbs-s3-bucket``, run: > + > +.. 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 > + > +A datastore cannot be shared between multiple instances, only one instance can operate on the A Backup Server instance? I would personally specify this here instead of in the next line. > +datastore at a time. However, datastore contents used on a Proxmox Backup Server instance which is > +no longer available can be reused on a fresh installation. To recreate the datastore, you must pass > +the ``reuse-datastore`` and ``overwrite-in-use`` flags. Since the datastore name is used as prefix, > +the 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 > + > + > Managing Datastores > ^^^^^^^^^^^^^^^^^^^ Reviewed-by: Maximiliano Sandoval _______________________________________________ pbs-devel mailing list pbs-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel