Skip to content

Commit

Permalink
[DOC] Edit backuprestore content initial (#21)
Browse files Browse the repository at this point in the history 
Co-authored-by: Thomas Polkowski <[email protected]>
Co-authored-by: sakshisharma84 <[email protected]>
Co-authored-by: Noah Merlis-Stephens <[email protected]>
Co-authored-by: Magdalena Dziadosz <[email protected]>
  • Loading branch information
@KoryKessel-Mirantis @tppolkow
@sakshisharma84 @nsteph @MagdaDziadosz
5 people authored Jun 7, 2024
1 parent 5c3c598 commit be88301
Show file tree
Hide file tree
Showing 4 changed files with 146 additions and 79 deletions.
45 changes: 0 additions & 45 deletions content/docs/reference/backuprestore/README.md
View file

This file was deleted.

64 changes: 64 additions & 0 deletions content/docs/reference/backuprestore/backup-restore.md
View file
Original file line number Diff line number Diff line change
@@ -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.
67 changes: 42 additions & 25 deletions content/docs/reference/backuprestore/external.md
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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.
Expand All @@ -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 <none>
```

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
Expand All @@ -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 <none>
```

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)
49 changes: 40 additions & 9 deletions content/docs/reference/backuprestore/in_cluster.md
View file
Original file line number Diff line number Diff line change
@@ -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 <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 <name>
```

Example output:

```shell
mkectl backup create --name test
Expand All @@ -17,17 +29,29 @@ 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
NAME STATUS ERRORS WARNINGS CREATED EXPIRES STORAGE LOCATION SELECTOR
test Completed 0 0 2024-05-07 17:29:18 -0400 EDT 29d default <none>
```

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
Expand All @@ -45,14 +69,21 @@ 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
NAME BACKUP STATUS STARTED COMPLETED ERRORS WARNINGS CREATED SELECTOR
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 <none>
```

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.


0 comments on commit be88301

Please sign in to comment.