Heptio Ark

Getting started

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. For additional functionality with this setup, see the docs on how to expose Minio outside your cluster.

NOTE The example lets you explore basic Ark functionality. Configuring Minio for production is out of scope.

See Set up Ark on your platform for how to configure Ark for a production environment.

If you encounter issues with installing or configuring, see Debugging Installation Issues.

Prerequisites

• Access to a Kubernetes cluster, version 1.7 or later. Version 1.7.5 or later is required to run ark backup delete.
• A DNS server on the cluster
• kubectl installed

Download

1. Download the latest release’s tarball for your platform.

2. Extract the tarball:

    tar -xzf <RELEASE-TARBALL-NAME>.tar.gz -C /dir/to/extract/to 
   

   We’ll refer to the directory you extracted to as the “Ark directory” in subsequent steps.

3. Move the ark binary from the Ark directory to somewhere in your PATH.

MacOS Installation

On Mac, you can use HomeBrew to install the ark client:

brew install ark

Set up server

These instructions start the Ark server and a Minio instance that is accessible from within the cluster only. See Expose Minio outside your cluster for information about configuring your cluster for outside access to Minio. Outside access is required to access logs and run ark describe commands.

1. Start the server and the local storage service. In the Ark directory, run:

   kubectl apply -f config/common/00-prereqs.yaml
   kubectl apply -f config/minio/
   

2. Deploy the example nginx application:

    kubectl apply -f config/nginx-app/base.yaml
   

3. Check to see that both the Ark and nginx deployments are successfully created:

    kubectl get deployments -l component=ark --namespace=heptio-ark
    kubectl get deployments --namespace=nginx-example
   

Back up

1. Create a backup for any object that matches the app=nginx label selector:

    ark backup create nginx-backup --selector app=nginx
   

   Alternatively if you want to backup all objects except those matching the label backup=ignore:

   ark backup create nginx-backup --selector 'backup notin (ignore)'
   

2. (Optional) Create regularly scheduled backups based on a cron expression using the app=nginx label selector:

    ark schedule create nginx-daily --schedule="0 1 * * *" --selector app=nginx
   

   Alternatively, you can use some non-standard shorthand cron expressions:

    ark schedule create nginx-daily --schedule="@daily" --selector app=nginx
   

   See the cron package’s documentation for more usage examples.

3. Simulate a disaster:

    kubectl delete namespace nginx-example
   

4. To check that the nginx deployment and service are gone, run:

    kubectl get deployments --namespace=nginx-example
    kubectl get services --namespace=nginx-example
    kubectl get namespace/nginx-example
   

   You should get no results.

   NOTE: You might need to wait for a few minutes for the namespace to be fully cleaned up.

Restore

1. Run:

    ark restore create --from-backup nginx-backup
   

2. Run:

    ark restore get
   

   After the restore finishes, the output looks like the following:

    NAME                          BACKUP         STATUS      WARNINGS   ERRORS    CREATED                         SELECTOR
    nginx-backup-20170727200524   nginx-backup   Completed   0          0         2017-07-27 20:05:24 +0000 UTC   <none>
   

NOTE: The restore can take a few moments to finish. During this time, the STATUS column reads InProgress.

After a successful restore, the STATUS column is Completed, and WARNINGS and ERRORS are 0. All objects in the nginx-example namespace should be just as they were before you deleted them.

If there are errors or warnings, you can look at them in detail:

ark restore describe <RESTORE_NAME>

For more information, see the debugging information.

Clean up

If you want to delete any backups you created, including data in object storage and persistent volume snapshots, you can run:

ark backup delete BACKUP_NAME

This asks the Ark server to delete all backup data associated with BACKUP_NAME. You need to do this for each backup you want to permanently delete. A future version of Ark will allow you to delete multiple backups by name or label selector.

Once fully removed, the backup is no longer visible when you run:

ark backup get BACKUP_NAME

If you want to uninstall Ark but preserve the backup data in object storage and persistent volume snapshots, it is safe to remove the heptio-ark namespace and everything else created for this example:

kubectl delete -f config/common/
kubectl delete -f config/minio/
kubectl delete -f config/nginx-app/base.yaml