add documentation on running Ark on-premises

Signed-off-by: JENNIFER RONDEAU <[email protected]>
Signed-off-by: Steve Kriss <[email protected]>

README.md

@@ -9,14 +9,16 @@
 Ark gives you tools to back up and restore your Kubernetes cluster resources and persistent volumes. Ark lets you:
 
 * Take backups of your cluster and restore in case of loss.
-* Copy cluster resources across cloud providers. NOTE: Cloud volume migrations are not yet supported.
+* Copy cluster resources to other clusters.
 * Replicate your production environment for development and testing environments.
 
 Ark consists of:
 
 * A server that runs on your cluster
 * A command-line client that runs locally
 
+You can run Ark in clusters on a cloud provider or on-premises. For detailed information, see [Compatible Storage Providers][99].
+
 ## More information
 
 [The documentation][29] provides a getting started guide, plus information about building from source, architecture, extending Ark, and more.
@@ -68,3 +70,5 @@ See [the list of releases][6] to find out about feature changes.
 
 [29]: https://heptio.github.io/ark/
 [30]: /docs/troubleshooting.md
+
+[99]: support-matrix.md

docs/build-from-scratch.md

@@ -103,8 +103,6 @@ To provision a cluster on `aws` using Amazon’s official CloudFormation templat
 
 * eksctl - [a CLI for Amazon EKS][18]
 
-To provision production grade clusters, see [Cloud Provider Specifics][9] instructions.
-
 ### Option 1: Run your Ark server locally
 
 Running the Ark server locally can speed up iterative development. This eliminates the need to rebuild the Ark server
@@ -197,7 +195,6 @@ If you need to add or update the vendored dependencies, see [Vendoring dependenc
 [6]: https://github.com/heptio/ark/tree/master/examples
 [7]: #run
 [8]: config-definition.md
-[9]: cloud-common.md
 [10]: #vendoring-dependencies
 [11]: vendoring-dependencies.md
 [12]: #test
@@ -207,4 +204,4 @@ If you need to add or update the vendored dependencies, see [Vendoring dependenc
 [16]: https://cloud.google.com/docs/authentication/getting-started#setting_the_environment_variable
 [17]: https://aws.amazon.com/quickstart/architecture/heptio-kubernetes/
 [18]: https://eksctl.io/
-[19]: ../examples/README.md
+[19]: ../examples/README.md

docs/install-overview.md

@@ -0,0 +1,103 @@
+# Set up Ark on your platform
+
+You can run Ark with a cloud provider or on-premises. For detailed information about the platforms that Ark supports, see [Compatible Storage Providers][99].
+
+In version 0.7.0 and later, you can run Ark in any namespace, which requires additional customization. See [Run in custom namespace][3].
+
+In version 0.9.0 and later, you can use Ark's integration with restic, which requires additional setup. See [restic instructions][20].
+
+## Cloud provider
+
+The Ark repository includes a set of example YAML files that specify the settings for each supported cloud provider. For provider-specific instructions, see:
+
+* [Run Ark on AWS][0]
+* [Run Ark on GCP][1]
+* [Run Ark on Azure][2]
+* [Use IBM Cloud Object Store as Ark's storage destination][4]
+
+## On-premises
+
+You can run Ark in an on-premises cluster in different ways depending on your requirements. 
+
+First, you must select an object storage backend that Ark can use to store backup data. [Compatible Storage Providers][99] contains information on various
+options that are supported or have been reported to work by users. [Minio][101] is an option if you want to keep your backup data on-premises and you are 
+not using another storage platform that offers an S3-compatible object storage API.
+
+Second, if you need to back up persistent volume data, you must select a volume backup solution. [Volume Snapshot Providers][100] contains information on
+the supported options. For example, if you use [Portworx][102] for persistent storage, you can install their Ark plugin to get native Portworx snapshots as part
+of your Ark backups. If there is no native snapshot plugin available for your storage platform, you can use Ark's [restic integration][20], which provides a
+platform-agnostic backup solution for volume data.
+
+## Examples
+
+After you set up the Ark server, try these examples:
+
+### Basic example (without PersistentVolumes)
+
+1. Start the sample nginx app:
+
+    ```bash
+    kubectl apply -f examples/nginx-app/base.yaml
+    ```
+
+1. Create a backup:
+
+    ```bash
+    ark backup create nginx-backup --include-namespaces nginx-example
+    ```
+
+1. Simulate a disaster:
+
+    ```bash
+    kubectl delete namespaces nginx-example
+    ```
+
+    Wait for the namespace to be deleted.
+
+1. Restore your lost resources:
+
+    ```bash
+    ark restore create --from-backup nginx-backup
+    ```
+
+### Snapshot example (with PersistentVolumes)
+
+> NOTE: For Azure, you must run Kubernetes version 1.7.2 or later to support PV snapshotting of managed disks.
+
+1. Start the sample nginx app:
+
+    ```bash
+    kubectl apply -f examples/nginx-app/with-pv.yaml
+    ```
+
+1. Create a backup with PV snapshotting:
+
+    ```bash
+    ark backup create nginx-backup --include-namespaces nginx-example
+    ```
+
+1. Simulate a disaster:
+
+    ```bash
+    kubectl delete namespaces nginx-example
+    ```
+
+    Because the default [reclaim policy][19] for dynamically-provisioned PVs is "Delete", these commands should trigger your cloud provider to delete the disk that backs the PV. Deletion is asynchronous, so this may take some time. **Before continuing to the next step, check your cloud provider to confirm that the disk no longer exists.**
+
+1. Restore your lost resources:
+
+    ```bash
+    ark restore create --from-backup nginx-backup
+    ```
+
+[0]: aws-config.md
+[1]: gcp-config.md
+[2]: azure-config.md
+[3]: namespace.md
+[4]: ibm-config.md
+[19]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#reclaiming
+[20]: restic.md
+[99]: support-matrix.md
+[100]: support-matrix.md#volume-snapshot-providers
+[101]: https://www.minio.io
+[102]: https://portworx.com

docs/quickstart.md

@@ -2,7 +2,11 @@
 
 The following example sets up the Ark server and client, then backs up and restores a sample application.
 
-For simplicity, the example uses Minio, an S3-compatible storage service that runs locally on your cluster. See [Set up Ark with your cloud provider][3] for how to run on a cloud provider. 
+For simplicity, the example uses Minio, an S3-compatible storage service that runs locally on your cluster.
+
+**NOTE** The example lets you explore basic Ark functionality. In the real world, however, you would back your cluster up to external storage.
+
+See [Set up Ark on your platform][3] for how to configure Ark for a production environment. 
 
 ### Prerequisites
 
@@ -158,7 +162,7 @@ kubectl delete -f examples/minio/
 kubectl delete -f examples/nginx-app/base.yaml
 ```
 
-[3]: cloud-common.md
+[3]: install-overview.md
 [18]: debugging-restores.md
 [26]: https://github.com/heptio/ark/releases
 [30]: https://godoc.org/github.com/robfig/cron

docs/restic.md

@@ -261,7 +261,7 @@ on to running other init containers/the main containers.
 
 
 [1]: https://github.com/restic/restic
-[2]: cloud-common.md
+[2]: install-overview.md
 [3]: https://github.com/heptio/ark/releases/
 [4]: https://kubernetes.io/docs/concepts/storage/volumes/#local
-[5]: http://restic.readthedocs.io/en/latest/100_references.html#terminology
+[5]: http://restic.readthedocs.io/en/latest/100_references.html#terminology