Merge pull request #1038 from Bradamant3/issue-819

add draft content for docs issue 819

Author: skriss

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 `<SCHEDULE NAME>` in the command as desired):
+
+    ```
+    ark schedule create <SCHEDULE NAME> --schedule "0 7 * * *"
+    ```
+    This creates a Backup object with the name `<SCHEDULE NAME>-<TIMESTAMP>`.
+
+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 <SCHEDULE NAME>-<TIMESTAMP>
+    ```
+
+
+

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 `<BACKUP-NAME>` as desired):
+
+    ```
+    ark backup create <BACKUP-NAME>
+    ```
+    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 <BACKUP-NAME>
+    ```
+
+    **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 (`<BACKUP-NAME>`) is now present, you can restore everything with:
+
+    ```
+    ark restore create --from-backup <BACKUP-NAME>
+    ```
+
+## 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 <RESTORE-NAME-FROM-GET-COMMAND>
+    ```
+
+If you encounter issues, make sure that Ark is running in the same namespace in both clusters.

docs/output-file-format.md

@@ -15,7 +15,7 @@ rootBucket/
 
 ## Example backup JSON file
 
-```
+```json
 {
   "kind": "Backup",
   "apiVersion": "ark.heptio.com/v1",

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 <restoreName>` - 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.