diff --git a/content/docs/reference/backuprestore/README.md b/content/docs/reference/backuprestore/README.md deleted file mode 100644 index 3f198fc8..00000000 --- a/content/docs/reference/backuprestore/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Backup & Restore - -MKE4 supports backup and restoring of the cluster data using the [Velero](https://velero.io/) addon. Backup is enabled by default. - -## Configuration - -The default `backup` section of the MKE4 config is as follows: - -```yaml -backup: - enabled: true - storage_provider: - type: InCluster - in_cluster_options: - exposed: true - distributed: false - -``` - -With the default setup, MKE is set up to support backups using the in-cluster storage provider. This is implemented via the MinIO addon that supports in-cluster object storage. -The `exposed` option is set to `true` which means that the MinIO service is exposed via NodePort. This is needed for all Velero operations to work correctly (i.e logs, describing backups). However the core backup functionality should work even if the service is not exposed. -The `distributed` option configures whether to run the MinIO storage in distributed mode. - -See [in_cluster.md](./in_cluster.md) for instructions on how to create backups and restores using the in-cluster storage provider. -See [external.md](./external.md) for instructions on how to create backups and restores using an external storage provider. (currently just AWS) - -## Existing Limitations - -Scheduled backups are a feature in MKE3 that is planned to be supported before MKE4 GA but not yet implemented. -Additionally, restoring a backup to a new set of nodes is not yet supported for in cluster storage provider. The backup must currently be restored in the same cluster it was taken in. - -## All fields - - -| Field | Description | Default | -|------------------------------------------------------------|-------------------------------------------------------------------------------------------------|---------------| -| enabled | Enables backup/restore functionality.
Valid values: true, false. | true | -| storage_provider.type | What Storage Provider Type to use.
Valid values: 'InCluster', 'External'. | InCluster | -| storage_provider.in_cluster_options.exposed | Whether to expose InCluster (MinIO) storage via NodePort.
Valid values: true, false. | true | -| storage_provider.in_cluster_options.distributed | Whether to run MinIO in distributed mode.
Valid values: true, false. | false | -| storage_provider.external_options.provider | What External Provider to use.
Valid values: Currently just 'aws'. | "" | -| storage_provider.external_options.bucket | Name of the pre-created bucket to use for backup storage. | "" | -| storage_provider.external_options.region | Region where the bucket exists. | "" | -| storage_provider.external_options.credentials_file_path | Path to Credentials File. | "" | -| storage_provider.external_options.credentials_file_profile | Profile in the Credentials file to use. | "" | \ No newline at end of file diff --git a/content/docs/reference/backuprestore/backup-restore.md b/content/docs/reference/backuprestore/backup-restore.md new file mode 100644 index 00000000..f7878d9e --- /dev/null +++ b/content/docs/reference/backuprestore/backup-restore.md @@ -0,0 +1,64 @@ +# Backup and Restore + +>MKE 4 backup is enabled by default. + +MKE 4 supports backup and restore of cluster data through the use of the +[Velero](https://velero.io/) addon. + +## Configuration + +The `backup` section of the MKE4 configuration file renders as follows: + +```yaml +backup: + enabled: true + storage_provider: + type: InCluster + in_cluster_options: + exposed: true + distributed: false +``` + +By default, MKE 4 supports backups that use the in-cluster storage +provider, as indicated in the `type` option setting of `InCluster`. MKE 4 +in-cluster backups are implemented using the [MinIO +addon](https://microk8s.io/docs/addon-minio). + +The `exposed` option setting of `true` indicates that the MinIO service is +exposed through `NodePort`, which Velero requires to function correctly. Core +backup functionality should work, however, even if +the service is not exposed. + +The `distributed` option configures MinIO storage to run in distributed mode. + +Refer to the following table for detail on all of the conifguration file +`backup` fields: + +| Field | Description | Valid values | Default | +|------------------------------------------------------------|------------------------------------------------------------------------------------|---------------------|:---------:| +| enabled | Indicates whether backup/restore functionality is enabled. | true, false | true | +| storage_provider.type | Indicates whether the storage type in use is in-cluster or external. | InCluster, External | InCluster | +| storage_provider.in_cluster_options.exposed | Indicates whether to expose InCluster (MinIO) storage through NodePort. | true, false | true | +| storage_provider.in_cluster_options.distributed | Indicates whether to run MinIO in distributed mode. | true, false | false | +| storage_provider.external_options.provider | Name of the external storage provider. AWS is currently the only available option. | aws | aws | +| storage_provider.external_options.bucket | Name of the pre-created bucket to use for backup storage. | "" | "" | +| storage_provider.external_options.region | Region in which the bucket exists. | "" | "" | +| storage_provider.external_options.credentials_file_path | Path to the credentials file. | "" | "" | +| storage_provider.external_options.credentials_file_profile | Profile in the Credentials file to use. | "" | "" | + +## Create backups and perform restores + +For information on how to create backups and perform restores for both storage +provider types, refer to: + +- In-cluster storage provider: [in_cluster.md](./in_cluster.md) +- External storage provider: [external.md](./external.md) + +## Existing Limitations + +- Scheduled backups, an MKE 3 feature that is planned for integration to MKE 4, + have not yet been implemented. + +- Backups must currently be restored in the same cluster in which the backup + was taken, and thus restoring a backup to a new set of nodes is not yet + supported for the in-cluster storage provider. \ No newline at end of file diff --git a/content/docs/reference/backuprestore/external.md b/content/docs/reference/backuprestore/external.md index 0859587c..ad5abe25 100644 --- a/content/docs/reference/backuprestore/external.md +++ b/content/docs/reference/backuprestore/external.md @@ -1,22 +1,24 @@ -# Backup and Restore Using External Storage Providers +# Backup and restore using external storage providers -It is possible to configure MKE to store backups and restores externally, for example in object storage provided by a public cloud provider. Currently only AWS S3 is supported as an external backup store. +You can configure MKE 4 to store backups and restores externally, for example +in object storage provided by a public cloud provider. + +>AWS S3 is currently the only supported external backup store +>that MKE 4 supports. ## Configuration -Prior to modifying the MKE configuration file, create an IAM credentials file. This file should look like below -``` -[386383511305_docker-testing] -aws_access_key_id=key -aws_secret_access_key=secret -aws_session_token=token -``` +1. Copy the credentials information from the AWS console to create an IAM +credentials file. + + ![img.png](img.png) -This can be easily copied from AWS console below: +2. Edit the `storage_provider` section of the MKE configuration file to point +to the file, including the profile name. -![img.png](img.png) +3. Create an S3 bucket and point the configuration to the bucket and region. -Once the Credentials file is created, update the `storage_provider` section of the mke config file to point to the created creds file including the profile name. Additionally, you need to create an S3 bucket and point the configuration to the correct bucket and region. +Example configuration: ```yaml storage_provider: @@ -29,27 +31,35 @@ Once the Credentials file is created, update the `storage_provider` section of t credentials_file_profile: "386383511305_docker-testing" ``` -## Usage - -Once AWS backup storage has been configured and the mke config file applied, check that the `BackupStorageLocation` CR exists and is ready. This may take a few minutes after `mkectl apply` is run. +Once you have configured the AWS backup storage and the MKE configuration file +has been applied, verify the existence of the `BackupStorageLocation` custom resource. ```shell kubectl get backupstoragelocation -n mke ``` -Output: +> After you run `mkectl apply` the output may require a few minutes to display. + +Example output: + ```shell NAME PHASE LAST VALIDATED AGE DEFAULT default Available 20s 32s true ``` -We can now create backups as usual and restore them. After creating a restore, the Kubernetes cluster state should resemble what it was when the backup was taken. +## Create backups and perform restores + +With configuration complete, you can now create backups and perform restores +from those backups. After you have run a restore operation from a backup, the +Kubernetes cluster state should resemble what it was at the time you created +that backup. ```shell mkectl backup create --name aws-backup ``` -Output: +Example output: + ```shell INFO[0000] Creating backup aws-backup... Backup request "aws-backup" submitted successfully. @@ -63,23 +73,27 @@ INFO[0015] Waiting for backup to complete. Current phase: Completed INFO[0015] Backup aws-backup completed successfully ``` -List the backups: +To list the backups, run the `mkectl backup list` command: + ```shell mkectl backup list ``` -Output: +Example output: + ```shell NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR aws-backup Completed 0 0 2024-05-08 16:17:18 -0400 EDT 29d default ``` -Create the restore: +To perform a restore using an external backup, run: + ```shell mkectl restore create --name aws-backup ``` -Output: +Example output: + ```shell INFO[0000] Waiting for restore aws-backup-20240508161811 to complete... INFO[0000] Waiting for restore to complete. Current phase: InProgress @@ -94,17 +108,20 @@ INFO[0024] Waiting for restore to complete. Current phase: Completed INFO[0024] Restore aws-backup-20240508161811 completed successfully ``` -List the restores: +To list the restores, run: + ```shell mkectl restore list ``` -Output: +Example output: + ```shell NAME BACKUP STATUS STARTED COMPLETED ERRORS WARNINGS CREATED SELECTOR aws-backup-20240508161811 aws-backup Completed 2024-05-08 16:18:11 -0400 EDT 2024-05-08 16:18:34 -0400 EDT 0 108 2024-05-08 16:18:11 -0400 EDT ``` -We can also see that both the backup and restore are created in our S3 bucket: +From your AWS console, you can see that both the backup and restore are created +in the S3 bucket: ![img_1.png](img_1.png) diff --git a/content/docs/reference/backuprestore/in_cluster.md b/content/docs/reference/backuprestore/in_cluster.md index 23a623fa..fadb74fd 100644 --- a/content/docs/reference/backuprestore/in_cluster.md +++ b/content/docs/reference/backuprestore/in_cluster.md @@ -1,8 +1,20 @@ -# Backup and Restore Using In Cluster Storage Provider -By default, MKE will store backups and restores using the in cluster storage provider (MinIO). The below instructions assume you have created a cluster and applied a blueprint with the default MKE backup configuration. +# Backup and restore using the in-cluster storage provider -## Usage -Backups can be created using `mkectl backup create --name `. +By default, MKE 4 stores backups and restores using the in-cluster storage +provider, the [MinIO addon](https://microk8s.io/docs/addon-minio). + +>The offered instructions assume that you have created a cluster and +applied a blueprint with the default MKE backup configuration. + +## Create an in-cluster backup + +To create an in-cluster backup, run: + +```shell +mkectl backup create --name +``` + +Example output: ```shell mkectl backup create --name test @@ -17,7 +29,10 @@ INFO[0012] Waiting for backup to complete. Current phase: InProgress INFO[0015] Waiting for backup to complete. Current phase: Completed ``` -The backup should now be present in the MinIO bucket. You can list the backups using `mkectl backup list`. +The backup should be present in the MinIO bucket. To list the backups, run +the `mkectl backup list` command: + +Example output: ```shell mkectl backup list @@ -25,9 +40,18 @@ NAME STATUS ERRORS WARNINGS CREATED EXPIRES test Completed 0 0 2024-05-07 17:29:18 -0400 EDT 29d default ``` -Optionally, detailed logs of a backup can be viewed via `mkectl backup logs --name test` +Optionally, you can view detailed logs of a backup by running the `mkectl +backup logs --name test` command. + +## Restore from an in-cluster backup -To create a restore off the backup we created we can run `mkectl restore create --name test` +To perform a restore using an in-cluster backup, run: + +```shell +mkectl restore create --name test +``` + +Example output: ```shell mkectl restore create --name test @@ -45,7 +69,13 @@ INFO[0027] Waiting for restore to complete. Current phase: Completed INFO[0027] Restore test-20240507173309 completed successfully ``` -We can list the restores using `mkectl restore list` +To list the restores, run: + +```shell + mkectl restore list + ``` + +Example output: ```shell mkectl restore list @@ -53,6 +83,7 @@ NAME BACKUP STATUS STARTED COMPL test-20240507173309 test Completed 2024-05-07 17:33:09 -0400 EDT 2024-05-07 17:33:34 -0400 EDT 0 121 2024-05-07 17:33:09 -0400 EDT ``` -We can optionally view detailed logs similar to the backup logs using `mkectl restore logs --name test-20240507173309`. +Optionally, you can view detailed logs by running the +`mkectl restore logs --name test-20240507173309` command.