From fa14255e531ad4dec6ac1c3cc76cecdbe5d40a2b Mon Sep 17 00:00:00 2001 From: JENNIFER RONDEAU Date: Wed, 7 Nov 2018 10:43:31 -0500 Subject: [PATCH] add content for docs issue 819 Signed-off-by: JENNIFER RONDEAU --- docs/disaster-case.md | 24 ++++++++++++++++++ docs/migration-case.md | 48 +++++++++++++++++++++++++++++++++++ docs/output-file-format.md | 2 +- docs/troubleshooting.md | 11 ++++---- docs/use-cases.md | 52 -------------------------------------- 5 files changed, 79 insertions(+), 58 deletions(-) create mode 100644 docs/disaster-case.md create mode 100644 docs/migration-case.md delete mode 100644 docs/use-cases.md diff --git a/docs/disaster-case.md b/docs/disaster-case.md new file mode 100644 index 0000000000..73d569fba5 --- /dev/null +++ b/docs/disaster-case.md @@ -0,0 +1,24 @@ +# Disaster recovery + +*Using Schedules and Restore-Only Mode* + +If you periodically back up your cluster's resources, you are able to return to a previous state in case of some unexpected mishap, such as a service outage. Doing so with Heptio Ark looks like the following: + +1. After you first run the Ark server on your cluster, set up a daily backup (replacing `` in the command as desired): + + ``` + ark schedule create --schedule "0 7 * * *" + ``` + This creates a Backup object with the name `-`. + +1. A disaster happens and you need to recreate your resources. + +1. Update the Ark server deployment, adding the argument for the `server` command flag `restore-only` set to `true`. This prevents Backup objects from being created or deleted during your Restore process. + +1. Create a restore with your most recent Ark Backup: + ``` + ark restore create --from-backup - + ``` + + + diff --git a/docs/migration-case.md b/docs/migration-case.md new file mode 100644 index 0000000000..f3c6a4f077 --- /dev/null +++ b/docs/migration-case.md @@ -0,0 +1,48 @@ +# Cluster migration + +*Using Backups and Restores* + +Heptio Ark can help you port your resources from one cluster to another, as long as you point each Ark instance to the same cloud object storage location. In this scenario, we are also assuming that your clusters are hosted by the same cloud provider. **Note that Heptio Ark does not support the migration of persistent volumes across cloud providers.** + +1. *(Cluster 1)* Assuming you haven't already been checkpointing your data with the Ark `schedule` operation, you need to first back up your entire cluster (replacing `` as desired): + + ``` + ark backup create + ``` + The default TTL is 30 days (720 hours); you can use the `--ttl` flag to change this as necessary. + +1. *(Cluster 2)* Add the `--restore-only` flag to the server spec in the Ark deployment YAML. + +1. *(Cluster 2)* Make sure that the `BackupStorageLocation` and `VolumeSnapshotLocation` CRDs match the ones from *Cluster 1*, so that your new Ark server instance points to the same bucket. + +1. *(Cluster 2)* Make sure that the Ark Backup object is created. Ark resources are synchronized with the backup files in cloud storage. + + ``` + ark backup describe + ``` + + **Note:** As of version 0.10, the default sync interval is 1 minute, so make sure to wait before checking. You can configure this interval with the `--backup-sync-period` flag to the Ark server. + +1. *(Cluster 2)* Once you have confirmed that the right Backup (``) is now present, you can restore everything with: + + ``` + ark restore create --from-backup + ``` + +## Verify both clusters + +Check that the second cluster is behaving as expected: + +1. *(Cluster 2)* Run: + + ``` + ark restore get + ``` + +1. Then run: + + ``` + ark restore describe + ``` + +If you encounter issues, make sure that Ark is running in the same namespace in both clusters. \ No newline at end of file diff --git a/docs/output-file-format.md b/docs/output-file-format.md index 8541e3a827..abdc0166b4 100644 --- a/docs/output-file-format.md +++ b/docs/output-file-format.md @@ -15,7 +15,7 @@ rootBucket/ ## Example backup JSON file -``` +```json { "kind": "Backup", "apiVersion": "ark.heptio.com/v1", diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 7c43a13ce6..40dc9854d4 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2,6 +2,11 @@ These tips can help you troubleshoot known issues. If they don't help, you can [file an issue][4], or talk to us on the [#ark-dr channel][25] on the Kubernetes Slack server. +See also: + +- [Debug installation/setup issues][2] +- [Debug restores][1] + ## General troubleshooting information In `ark` version >= `0.1.0`, you can use the `ark bug` command to open a [Github issue][4] by launching a browser window with some prepopulated values. Values included are OS, CPU architecture, `kubectl` client and server versions (if available) and the `ark` client version. This information isn't submitted to Github until you click the `Submit new issue` button in the Github UI, so feel free to add, remove or update whatever information you like. @@ -14,7 +19,7 @@ Some general commands for troubleshooting that may be helpful: * `ark restore logs ` - fetch the logs for this specific restore. Useful for viewing failures and warnings, including resources that could not be restored. * `kubectl logs deployment/ark -n heptio-ark` - fetch the logs of the Ark server pod. This provides the output of the Ark server processes. -## Getting ark debug logs +### Getting ark debug logs You can increase the verbosity of the Ark server by editing your Ark deployment to look like this: @@ -40,10 +45,6 @@ Because of how Kubernetes handles Service objects of `type=LoadBalancer`, when y Alternatively, you might be able to use the Service's `spec.loadBalancerIP` field to keep connections valid, if your cloud provider supports this value. See [the Kubernetes documentation about Services of Type LoadBalancer](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). -## [Debug installation/setup issues][2] - -## [Debug restores][1] - ## Miscellaneous issues ### Ark reports `custom resource not found` errors when starting up. diff --git a/docs/use-cases.md b/docs/use-cases.md deleted file mode 100644 index 428a83c134..0000000000 --- a/docs/use-cases.md +++ /dev/null @@ -1,52 +0,0 @@ -# Use Cases - -This doc provides sample Ark commands for the following common scenarios: -* [Disaster recovery][0] -* [Cluster migration][1] - -## Disaster recovery - -*Using Schedules and Restore-Only Mode* - -If you periodically back up your cluster's resources, you are able to return to a previous state in case of some unexpected mishap, such as a service outage. Doing so with Heptio Ark looks like the following: - -1. After you first run the Ark server on your cluster, set up a daily backup (replacing `` in the command as desired): - - ``` - ark schedule create --schedule "0 7 * * *" - ``` - This creates a Backup object with the name `-`. - -2. A disaster happens and you need to recreate your resources. - -3. Update the Ark server deployment, adding the argument for the `server` command flag `restore-only` set to `true`. This prevents Backup objects from being created or deleted during your Restore process. - -4. Create a restore with your most recent Ark Backup: - ``` - ark restore create --from-backup - - ``` - -## Cluster migration - -*Using Backups and Restores* - -Heptio Ark can help you port your resources from one cluster to another, as long as you point each Ark instance to the same cloud object storage location. In this scenario, we are also assuming that your clusters are hosted by the same cloud provider. **Note that Heptio Ark does not support the migration of persistent volumes across cloud providers.** - -1. *(Cluster 1)* Assuming you haven't already been checkpointing your data with the Ark `schedule` operation, you need to first back up your entire cluster (replacing `` as desired): - - ``` - ark backup create - ``` - The default TTL is 30 days (720 hours); you can use the `--ttl` flag to change this as necessary. - -2. *(Cluster 2)* Make sure that the `BackupStorageLocation` and `VolumeSnapshotLocation` CRDs match the ones from *Cluster 1*, so that your new Ark server instance is pointing to the same bucket. - -3. *(Cluster 2)* Make sure that the Ark Backup object has been created. Ark resources are synced with the backup files available in cloud storage. - -4. *(Cluster 2)* Once you have confirmed that the right Backup (``) is now present, you can restore everything with: -``` -ark restore create --from-backup -``` - -[0]: #disaster-recovery -[1]: #cluster-migration