diff --git a/README.md b/README.md index 713cd7b04e..f8bf5a9058 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ 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: @@ -17,6 +17,8 @@ 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 diff --git a/docs/build-from-scratch.md b/docs/build-from-scratch.md index 17e9337a1c..42ebf73522 100644 --- a/docs/build-from-scratch.md +++ b/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 \ No newline at end of file +[19]: ../examples/README.md diff --git a/docs/cloud-common.md b/docs/cloud-common.md deleted file mode 100644 index 2715366dbf..0000000000 --- a/docs/cloud-common.md +++ /dev/null @@ -1,82 +0,0 @@ -# Set up Ark with your cloud provider - -To run Ark with your cloud provider, you specify provider-specific settings for the Ark server. In version 0.7.0 and later, you can run Ark in any namespace, which requires additional customization. See [Run in custom namespace][3]. - -The Ark repository includes a set of example YAML files that specify the settings for each 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] - -In version 0.9.0 and later, you can use Ark's integration with restic, which requires additional setup. See [Restic instructions][20]. - -## 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, your Kubernetes cluster needs to be version 1.7.2+ to support PV snapshotting of its 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 backing the PV. The deletion process 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]: https://github.com/heptio/ark/blob/master/docs/restic.md diff --git a/docs/install-overview.md b/docs/install-overview.md new file mode 100644 index 0000000000..1cdd5a7fcb --- /dev/null +++ b/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 diff --git a/docs/quickstart.md b/docs/quickstart.md index 62ab4e86c5..31b337a6b3 100644 --- a/docs/quickstart.md +++ b/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 diff --git a/docs/restic.md b/docs/restic.md index d631dcb053..53afb65404 100644 --- a/docs/restic.md +++ b/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 \ No newline at end of file +[5]: http://restic.readthedocs.io/en/latest/100_references.html#terminology