Proxmox-Port/proxmox-backup
1
0
Fork 0
forked from proxmox-mirrors/proxmox-backup
Code Pull Requests Activity

docs: use endpoint over client for the s3 endpoint configuration

Browse Source 
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 <c.ebner@proxmox.com>
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
This commit is contained in:
Christian Ebner 2025-07-22 14:11:24 +02:00 committed by Thomas Lamprecht
parent cfc93ebd03
commit f7eb5fc86d
1 changed files with 15 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/storage.rst
View File

@ -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