Skip to content

Commit 2782a48

Browse files
nastena1606nastena1606
authored
PBM-1631 Documented the minio storage type (#308)
PBM-1631 Documented the minio storage type new file: docs/details/endpoint-map.md new file: docs/details/minio.md modified: docs/details/s3-storage.md modified: docs/details/storage-configuration.md modified: docs/features/split-merge-backup.md modified: docs/install/backup-storage.md modified: docs/reference/configuration-options.md modified: docs/reference/glossary.md modified: docs/troubleshoot/index.md modified: mkdocs-base.yml
1 parent 4da2516 commit 2782a48

File tree

12 files changed

+447
-170
lines changed

12 files changed

+447
-170
lines changed

‎.github/styles/config/vocabularies/Percona/accept.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,8 @@ MinIO
2323
[Rr]esync
2424
(?i)HMAC
2525
retryer
26+
MinIO
27+
S3-compatible
28+
uncomment
29+
CAs
30+
Ceph

‎.vale.ini‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
StylesPath = .github/styles
22

3-
MinAlertLevel = suggestion
3+
MinAlertLevel = warning
44

55
Packages = Google
66

@@ -10,4 +10,6 @@ Vocab = Percona
1010
[*]
1111
BasedOnStyles = Vale, Google
1212

13+
Vale.Spelling = warning
14+
1315
Vale.Terms = NO

‎docs/details/endpoint-map.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Multiple endpoints to the same storage
2+
3+
!!! admonition "Version added: [2.8.0](../release-notes/2.8.0.md)"
4+
5+
In environments where `pbm-agents` run on servers that are distributed across several data centers, accessing the same remote backup storage can become challenging. This can be due to complex network configurations or strict policies that prevent direct connections to the outside world. As a result, `pbm-agents` can't use the same URL to reach the storage, which is necessary for Percona Backup for MongoDB to work properly.
6+
7+
To address these challenges, you can configure custom endpoint URLs for specific nodes in the PBM configuration. This allows all `pbm-agents` to access the same storage while respecting the network settings of their data centers.
8+
9+
The supported storage types are:
10+
11+
* AWS S3
12+
* MinIO and S3-compatible storage services
13+
* Microsoft Azure Blob storage
14+
15+
Here's the example of the configuration file with the endpoint map:
16+
17+
=== ":fontawesome-brands-amazon: AWS S3"
18+
19+
```yaml
20+
storage:
21+
type: s3
22+
s3:
23+
endpointUrl: http://S3:9000
24+
endpointUrlMap:
25+
"node01:27017": "did.socf.s3.com"
26+
"node03:27017": "https://example.aws.s3.com"
27+
...
28+
```
29+
30+
=== ":simple-minio: MinIO and S3-compatible storage"
31+
32+
```yaml
33+
storage:
34+
type: minio
35+
minio:
36+
endpoint: localhost:9100
37+
endpointMap:
38+
"node01:27017": "did.socf.s3.com"
39+
"node03:27017": "example.min.io"
40+
...
41+
```
42+
43+
=== ":material-microsoft-azure: Microsoft Azure Blob storage"
44+
45+
```yaml
46+
storage:
47+
type: azure
48+
azure:
49+
endpointUrl: https://myaccount.blob.core.windows.net
50+
endpointUrlMap:
51+
"node01:27017": "did.socf.blob.core.windows.net"
52+
"node03:27017": "example.azure.blob.core.windows.net"
53+
...
54+
```
55+
56+
57+
You can define specific nodes using the `endpointUrlMap` (for AWS S3 and Azure) or `endpointMap` (for MinIO and S3-compatible storage) parameters. Both parameters are maps of `'host:port'` to endpoint URL, as shown in the earlier examples. Nodes not listed in the map use the endpoint defined by the `endpointUrl` or `endpoint` parameter, respectively.
58+
59+
For the solution to work, you should also have the mapping mechanism in place. This mechanism should be able to map the custom endpoints to the main endpoint URL of the storage, routing the requests from `pbm-agents` to the storage and back seamlessly.
60+
61+
With this ability to control the endpoints for `pbm-agents` to reach the same storage, you reduce the administrative overhead on PBM configuration and ensure its proper functioning.

‎docs/details/minio.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# MinIO and S3-compatible storage
2+
3+
Percona Backup for MongoDB (PBM) works with both AWS S3 and other S3-compatible storage services. We test S3-compatible storage services with PBM using [MinIO :octicons-link-external-16:](https://min.io/)
4+
5+
This document provides an overview of MinIO as the closest S3-compatible storage. To use the native AWS S3 service, see [AWS S3 storage](s3-storage.md).
6+
7+
[Configuration example :material-arrow-down:](#configuration-example){.md-button}
8+
9+
## Bucket creation
10+
11+
1. Install a [MinIO client :octicons-link-external-16:](https://min.io/docs/minio/linux/reference/minio-mc.html#install-mc). After the installation, the `mc` is available for you.
12+
13+
2. Configure the `mc` command line tool with a MinIO Server
14+
15+
```{.bash data-prompt="$"}
16+
$ mc alias set myminio http://127.0.0.1:9000 MINIO_ACCESS_KEY MINIO_SECRET_KEY
17+
```
18+
19+
3. Create a bucket
20+
21+
```{.bash data-prompt="$"}
22+
$ mc mb myminio/my-minio-bucket
23+
```
24+
25+
4. Verify the bucket creation
26+
27+
```{.bash data-prompt="$"}
28+
$ mc ls myminio
29+
```
30+
31+
After the bucket is created, apply the proper [permissions for PBM to use the bucket](storage-configuration.md#permissions-setup).
32+
33+
## Configuration example
34+
35+
!!! important
36+
37+
Percona Backup for MongoDB (PBM) needs its own dedicated S3 bucket exclusively for backup-related files. Ensure that this [bucket is created](#bucket-creation) and managed solely by PBM.
38+
39+
This is the example for the basic configuration of MinIO and other S3-compatible storage services in Percona Backup for MongoDB. You can find [the configuration file template :octicons-link-external-16:](https://github.com/percona/percona-backup-mongodb/blob/v{{release}}/packaging/conf/pbm-conf-reference.yml) and uncomment the required fields.
40+
41+
```yaml
42+
storage:
43+
type: minio
44+
minio:
45+
endpoint: localhost:9100
46+
bucket: pbm-example
47+
prefix: data/pbm/test
48+
credentials:
49+
access-key-id: <your-access-key-id-here>
50+
secret-access-key: <your-secret-key-here>
51+
```
52+
53+
For the description of configuration options, see [Configuration file options](../reference/configuration-options.md).
54+
55+
## Fine-tune storage configuration
56+
57+
The following sections describe how you can fine-tune your storage configuration:
58+
59+
* [debug logging](#debug-logging)
60+
* [upload retries](#upload-retries)
61+
* [data upload to storage with self-signed TLS certificates](#data-upload-to-storage-with-self-signed-tls-certificates)
62+
* [multiple endpoints to the same S3 storage](endpoint-map.md)
63+
64+
### Debug logging
65+
66+
You can enable debug logging for different types of storage requests in Percona Backup for MongoDB. Percona Backup for MongoDB prints log messages in the `pbm logs` output so that you can debug and diagnose storage request issues or failures.
67+
68+
To enable debug logging, set the `storage.minio.debugTrace` option in Percona Backup for MongoDB configuration. This instructs PBM to also print HTTP trace from the MinIO storage in the logs.
69+
70+
## Upload retries
71+
72+
You can set up the number of attempts for Percona Backup for MongoDB to upload data to S3 storage. Set the `storage.minio.retryer.numMaxRetries` option in Percona Backup for MongoDB configuration.
73+
74+
```yaml
75+
retryer:
76+
numMaxRetries: 3
77+
```
78+
79+
This upload retry increases the chances of data upload completion in cases of unstable connection.
80+
81+
## Data upload to storage with self-signed TLS certificates
82+
83+
Percona Backup for MongoDB supports data upload to S3-compatible storage service over HTTPS with a self-signed or a private CA certificate. This feature is especially important when you use services like MinIO, Ceph, or internal S3 gateways that don't use certificates signed by public Certificate Authorities (CAs).
84+
85+
Providing a whole chain of certificates is recommended to ensure the connection is legit. The `SSL_CERT_FILE` environment variable specifies the path to a custom certificate chain file in PEM-format that PBM uses to validate TLS/SSL connection.
86+
87+
### Usage example
88+
89+
Let's assume that your custom CA certificate is at `/etc/ssl/minio-ca.crt` path and your S3 endpoint is `https://minio.internal.local:9000`. To use self-issued TLS certificates, do the following:
90+
91+
1. Ensure the cert file is in PEM format. Use the following command to check it:
92+
93+
```bash
94+
cat /etc/ssl/minio-ca.crt
95+
```
96+
97+
??? example "Sample output"
98+
99+
100+
```{text .no-copy}
101+
-----BEGIN CERTIFICATE-----
102+
MIIC+TCCAeGgAwIBAgIJANH3WljB...
103+
-----END CERTIFICATE-----
104+
```
105+
106+
2. Set the `SSL_CERT_FILE` environment variable to that file's path on each host where `pbm-agent` and PBM CLI are running:
107+
108+
```{.bash data-prompt="$"}
109+
$ export SSL_CERT_FILE=/etc/ssl/minio-ca.crt
110+
```
111+
112+
If this variable isn't set, PBM uses the system root certificates.
113+
114+
3. Restart `pbm-agent`:
115+
116+
```{.bash data-prompt="$"}
117+
$ sudo systemctl start pbm-agent
118+
```
119+
120+
4. Verify that your custom certificate is recognized. Check PBM logs for successful storage access.
121+
122+
123+
Alternatively, you can turn off the TLS verification of the S3 storage in Percona Backup for MongoDB configuration:
124+
125+
```{.bash data-prompt="$"}
126+
$ pbm config --set storage.minio.insecureSkipTLSVerify=True
127+
```
128+
129+
!!! warning
130+
131+
Use this option with caution as it might leave a hole for man-in-the-middle attacks.
132+

0 commit comments

Comments
 (0)