Skip to content

CLOUD-776 Documented Backup and Restore CRs #241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

CLOUD-776 Documented Backup and Restore CRs #241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions docs/backup-resource-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Backup Resource options

A Backup resource is a Kubernetes object that tells the Operator how to create and manage your database backups. The `deploy/backup/backup.yaml` file is a template for creating backup resources when you make an on-demand backup. It defines the `PerconaServerMongoDBBackup` resource.

This document describes all available options that you can use to customize your backups.

## `apiVersion`

Specifies the API version of the Custom Resource.
`psmdb.percona.com` indicates the group, and `v1` is the version of the API.

## `kind`

Defines the type of resource being created: `PerconaServerMongoDBBackup`.

## `metadata`

The metadata part of the `deploy/backup/backup.yaml` contains metadata about the resource, such as its name and other attributes. It includes the following keys:

* `finalizers` ensure safe deletion of resources in Kubernetes under certain conditions. This subsection includes the following finalizers:

* `percona.com/delete-backup` - deletes the backup resource after the backup data is deleted from storage. Note that it is ignored for incremental backups.

* `name` - The name of the backup resource used to identify it in your deployment. You also use the backup name for the restore operation.

## `spec`

This subsection includes the configuration of a backup resource.

### `clusterName`

Specifies the name of the MongoDB cluster to back up.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `my-cluster-name` |

### `storageName`

Specifies the name of the storage where to save a backup. It must match the name you specified in the `spec.backup.storages` subsection of the `deploy/cr.yaml` file.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `s3-us-west` |

### `type`

Specifies the backup type. Supported types are: `logical`, `physical`, `incremental-base`, `incremental`.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `physical` |

### `compressionType`

Specifies the compression algorithm for backups. Supported values are: `gzip`, `pgzip`, `zstd`, `snappy`. Read more about compression types in the [Configure backup compression :octicons-link-external-16:](https://docs.percona.com/percona-backup-mongodb/usage/compression.html#configure-backup-compression) section of PBM documentation.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `gzip` |

### `compressionLevel`

Specifies the compression level. Note that the higher value you specify, the more time and computing resources it will take to compress the data. The default value depends on the compression method used. Read more about compression levels in the [Configure backup compression :octicons-link-external-16:](https://docs.percona.com/percona-backup-mongodb/usage/compression.html#configure-backup-compression) section of PBM documentation.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `6` |
33 changes: 27 additions & 6 deletions docs/operator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,36 @@
# Custom Resource options

The operator is configured via the spec section of the
[deploy/cr.yaml :octicons-link-external-16:](https://github.com/percona/percona-server-mongodb-operator/blob/main/deploy/cr.yaml) file.
A Custom Resource (CR) is how you configure the Operator to manage Percona Server for MongoDB. It defines a custom resource of type `PerconaServerMongoDB`.

To customize it, edit the `spec` section in the [deploy/cr.yaml :octicons-link-external-16:](https://github.com/percona/percona-server-mongodb-operator/blob/main/deploy/cr.yaml).

This document explains every section of the `deploy/cr.yaml` Custom Resource manifest and describes available options.

## `apiVersion`

Specifies the API version of the Custom Resource.
`psmdb.percona.com` indicates the group, and `v1` is the version of the API.

This tells Kubernetes which version of the custom resource definition (CRD) to use.

## `kind`

Defines the type of resource being created.

## `metadata`

The metadata part of this file contains the following keys:
The metadata part of the `deploy/cr.yaml` contains metadata about the resource, such as its name and other attributes. It includes the following keys:

* `name` sets the name of your Percona Server for MongoDB Cluster. The name must follow these rules:

* include only [URL-compatible characters :octicons-link-external-16:](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3),
* not exceed 22 characters,
* start and end with an alphanumeric character

The default name is `my-cluster-name`.

* `finalizers` ensure safe deletion of resources in Kubernetes under certain conditions. This subsection includes the following finalizers:

* `name` (`my-cluster-name` by default) sets the name of your Percona Server
for MongoDB Cluster; it should include only [URL-compatible characters :octicons-link-external-16:](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3), not exceed 22 characters, start with an alphabetic character, and end with an alphanumeric character
* `finalizers` subsection:
* `percona.com/delete-psmdb-pods-in-order` if present, activates the [Finalizer :octicons-link-external-16:](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#finalizers) which controls the proper Pods deletion order in case of the cluster deletion event (on by default)
* `percona.com/delete-psmdb-pvc` if present, activates the [Finalizer :octicons-link-external-16:](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#finalizers) which deletes appropriate [Persistent Volume Claims :octicons-link-external-16:](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) after the cluster deletion event (off by default)
* `percona.com/delete-pitr-chunks` if present, activates the [Finalizer :octicons-link-external-16:](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#finalizers) which deletes all [point-in-time recovery chunks from the cloud storage](backups-pitr.md) on cluster deletion (off by default)
Expand Down
201 changes: 201 additions & 0 deletions docs/restore-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,201 @@
# Restore Resource options

A Restore resource is a Kubernetes object that tells the Operator how to restore your database from a specific backup. The `deploy/backup/restore.yaml` file is a template for creating restore resources. It defines the `PerconaServerMongoDBRestore` resource.

This document describes all available options that you can use to customize a restore.

## `apiVersion`

Specifies the API version of the Custom Resource.
`psmdb.percona.com` indicates the group, and `v1` is the version of the API.

## `kind`

Defines the type of resource being created: `PerconaServerMongoDBRestore`.

## `metadata`

The metadata part of the `deploy/backup/restore.yaml` contains metadata about the resource, such as its name and other attributes. It includes the following keys:

* `name` - The name of the restore object used to identify it in your deployment. You use this name to track the restore operation status and view information about it.

## `spec`

This section includes the configuration of a restore resource.

### `clusterName`

Specifies the name of the MongoDB cluster to restore.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `my-cluster-name` |

### `backupName`

Specifies the name of a backup to be used for a restore. This backup should be from the same cluster.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `backup1` |

## The `selective` subsection

Controls the selective restore, which enables you to restore a specific subset of namespaces - databases and collections.

### `selective.withUsersAndRoles`

Allows restoring specified custom databases with users and roles that were created against them. Read more about [Selective restore with users and roles :octicons-link-external-16:](https://docs.percona.com/percona-backup-mongodb/features/selective-backup.html#restore-a-database-with-users-and-roles) in PBM documentation.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: boolean | `true` |

### `selective.namespaces`

Specifies the list of namespaces to restore. The namespace has the format `<db.collection>`

| Value type | Example |
| ----------- | ---------- |
| :material-text-long: array | `["db1.collection1", "db2.collection2"]` |

## The `pitr` subsection

Controls how to make a point-in-time restore

### `pitr.type`

Specifies the type of a point-in-time restore. Available options:

* `date` - restore to a specific date.
* `latest` - recover to the latest possible transaction

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `date` |

### `pitr.date`

Specifies the timestamp for the restore in the datetime format `YYYY-MM-DD hh:mm:ss`.

Use it together with the `type=date` option.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `YYYY-MM-DD hh:mm:ss` |

## The `backupSource` subsection

Contains the configuration options to restore from a backup made in a different cluster, namespace, or Kubernetes environment.

### `backupSource.type`

Specifies the backup type. Available options: physical, logical, incremental

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `physical` |

### `backupSource.destination`

Specifies the path to the backup on the storage

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `s3://bucket-name/backup-destination/` |

### `backupSource.s3.credentialsSecret`

Specifies the Secrets object name with the credentials to access the storage with a backup.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `my-cluster-name-backup-s3` |

### `backupSource.s3.serverSideEncryption.kmsKeyID`

Specifies your customer-managed key stored in the AWS Key Management Service (AWS KMS). This key is used to encrypt backup data uploaded to S3 buckets if you don't wish to use the default server-side encryption with Amazon S3 managed keys (SSE-S3)

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `1234abcd-12ab-34cd-56ef-1234567890ab` |

### `backupSource.s3.serverSideEncryption.sseAlgorithm`

The encryption algorithm used to encrypt data

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `AES256` |

### `backupSource.s3.serverSideEncryption.sseCustomerAlgorithm`

The encryption algorithm used for server-side encryption with customer-provided keys (SSE-C).

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `AES256` |

### `backupSource.s3.serverSideEncryption.sseCustomerKey`

The customer-provided encryption key.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `Y3VzdG9tZXIta2V5` |

### `backupSource.s3.region`

The [AWS region :octicons-link-external-16:](https://docs.aws.amazon.com/general/latest/gr/rande.html) to use. Please note **this option is mandatory** for Amazon and all S3-compatible storages.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `us-west-2`|

### `backupSource.s3.bucket`

The [Amazon S3 bucket :octicons-link-external-16:](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html) name for backups.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | |

### `backupSource.s3.endpointUrl`

The URL of the S3-compatible storage to be used (not needed for the original Amazon S3 cloud).

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | `https://s3.us-west-2.amazonaws.com/` |

### `backupSource.s3.prefix`

The path to the data directory in the bucket. If undefined, backups are stored in the bucket’s root directory.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | |

### `backupSource.azure.credentialsSecret`

Specifies the Secrets object name with the credentials to access the Azure Blob storage with a backup.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | |

### `backupSource.azure.prefix`

The path to the data directory in the bucket. If undefined, backups are stored in the bucket’s root directory.

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | |

### `backupSource.s3.container`

The name of the storage container. See the [naming conventions :octicons-link-external-16:](https://docs.microsoft.com/en-us/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata#container-names)

| Value type | Example |
| ----------- | ---------- |
| :material-code-string: string | |
2 changes: 2 additions & 0 deletions mkdocs-base.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,8 @@ nav:

- Reference:
- "Custom Resource options": operator.md
- backup-resource-options.md
- restore-options.md
- "Percona certified images": images.md
- "Versions compatibility": versions.md
- "Operator API": api.md
Expand Down