Merge pull request #948 from heptio/snapshot-locations

Add VolumeSnapshotLocations support

docs/api-types/README.md

@@ -2,6 +2,9 @@
 
 ## API types
 
+Here we list the API types that have some functionality that you can only configure via json/yaml vs the `ark` cli
+(hooks)
+
 * [Backup][1]
 
 [1]: backup.md

docs/api-types/backup.md

@@ -60,6 +60,12 @@ spec:
   # AWS. Valid values are true, false, and null/unset. If unset, Ark performs snapshots as long as
   # a persistent volume provider is configured for Ark.
   snapshotVolumes: null
+  # Where to store the tarball and logs.
+  storageLocation: aws-primary
+  # The list of locations in which to store volume snapshots created for this backup.
+  volumeSnapshotLocations:
+    - aws-primary
+    - gcp-primary
   # The amount of time before this backup is eligible for garbage collection.
   ttl: 24h0m0s
   # Actions to perform at different times during a backup. The only hook currently supported is

docs/api-types/volumesnapshotlocation.md

@@ -0,0 +1,60 @@
+# Ark Volume Snapshot Location
+
+## Volume Snapshot Location
+
+A volume snapshot location is the location in which to store the volume snapshots created for a backup.
+
+Ark can be configured to take snapshots of volumes from multiple providers. Ark also allows you to configure multiple possible `VolumeSnapshotLocation` per provider, although you can only select one location per provider at backup time.
+
+Each VolumeSnapshotLocation describes a provider + location. These are represented in the cluster via the `VolumeSnapshotLocation` CRD. Ark must have at least one `VolumeSnapshotLocation` per cloud provider.
+
+A sample YAML `VolumeSnapshotLocation` looks like the following:
+
+```yaml
+apiVersion: ark.heptio.com/v1
+kind: VolumeSnapshotLocation
+metadata:
+  name: aws-default
+  namespace: heptio-ark
+spec:
+  provider: aws
+  config:
+    region: us-west-2
+```
+
+### Parameter Reference
+
+The configurable parameters are as follows:
+
+#### Main config parameters
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `provider` | String (Ark natively supports `aws`, `gcp`, and `azure`. Other providers may be available via external plugins.)| Required Field | The name for whichever cloud provider will be used to actually store the volume. |
+| `config` | See the corresponding [AWS][0], [GCP][1], and [Azure][2]-specific configs or your provider's documentation.
+
+#### AWS
+
+##### config
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `region` | string | Empty | *Example*: "us-east-1"<br><br>See [AWS documentation][3] for the full list.<br><br>Queried from the AWS S3 API if not provided. |
+
+#### Azure
+
+##### config
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `apiTimeout` | metav1.Duration | 2m0s | How long to wait for an Azure API request to complete before timeout. |
+| `resourceGroup` | string | Optional | The name of the resource group where volume snapshots should be stored, if different from the cluster's resource group. |
+
+#### GCP
+
+No parameters required.
+
+[0]: #aws
+[1]: #gcp
+[2]: #azure
+[3]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions

docs/aws-config.md

@@ -303,4 +303,4 @@ It can be set up for Ark by creating a role that will have required permissions,
 [6]: config-definition.md#aws
 [14]: http://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html
 [20]: faq.md
-[21]: backupstoragelocation-definition.md#aws
+[21]: api-types/backupstoragelocation.md#aws

docs/azure-config.md

@@ -165,5 +165,5 @@ In the root of your Ark directory, run:
 [18]: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli
 [19]: https://docs.microsoft.com/en-us/azure/architecture/best-practices/naming-conventions#storage
 [20]: faq.md
-[21]: backupstoragelocation-definition.md#azure
+[21]: api-types/backupstoragelocation.md#azure
 [22]: https://azure.microsoft.com/en-us/services/kubernetes-service/

docs/gcp-config.md

@@ -129,7 +129,7 @@ In the root of your Ark directory, run:
   ```
 
   [0]: namespace.md
-  [7]: backupstoragelocation-definition.md#gcp
+  [7]: api-types/backupstoragelocation.md#gcp
   [15]: https://cloud.google.com/compute/docs/access/service-accounts
   [16]: https://cloud.google.com/sdk/docs/
   [20]: faq.md

docs/ibm-config.md

@@ -78,5 +78,5 @@ In the root of your Ark directory, run:
   [3]: https://console.bluemix.net/docs/services/cloud-object-storage/iam/service-credentials.html#service-credentials
   [4]: https://www.ibm.com/support/knowledgecenter/SSBS6K_2.1.0/kc_welcome_containers.html
   [5]: https://console.bluemix.net/docs/containers/container_index.html#container_index
-  [6]: backupstoragelocation-definition.md#aws
+  [6]: api-types/backupstoragelocation.md#aws
   [14]: http://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html

examples/aws/06-ark-volumesnapshotlocation.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 the Heptio Ark contributors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+---
+apiVersion: ark.heptio.com/v1
+kind: VolumeSnapshotLocation
+metadata:
+  name: aws-default
+  namespace: heptio-ark
+spec:
+  provider: aws
+  config:
+    region: <YOUR_REGION>

examples/azure/06-ark-volumesnapshotlocation.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 the Heptio Ark contributors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+---
+apiVersion: ark.heptio.com/v1
+kind: VolumeSnapshotLocation
+metadata:
+  name: azure-default
+  namespace: heptio-ark
+spec:
+  provider: azure
+  config:
+    apiTimeout: 2m0s

examples/common/00-prereqs.yaml

@@ -162,6 +162,21 @@ spec:
     plural: backupstoragelocations
     kind: BackupStorageLocation
 
+---
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  name: volumesnapshotlocations.ark.heptio.com
+  labels:
+    component: ark
+spec:
+  group: ark.heptio.com
+  version: v1
+  scope: Namespaced
+  names:
+    plural: volumesnapshotlocations
+    kind: VolumeSnapshotLocation
+
 ---
 apiVersion: v1
 kind: Namespace

examples/gcp/06-ark-volumesnapshotlocation.yaml

@@ -0,0 +1,22 @@
+# Copyright 2018 the Heptio Ark contributors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+---
+apiVersion: ark.heptio.com/v1
+kind: VolumeSnapshotLocation
+metadata:
+  name: gcp-default
+  namespace: heptio-ark
+spec:
+  provider: gcp

pkg/apis/ark/v1/backup.go

@@ -61,6 +61,9 @@ type BackupSpec struct {
 
 	// StorageLocation is a string containing the name of a BackupStorageLocation where the backup should be stored.
 	StorageLocation string `json:"storageLocation"`
+
+	// VolumeSnapshotLocations is a list containing names of VolumeSnapshotLocations associated with this backup.
+	VolumeSnapshotLocations []string `json:"volumeSnapshotLocations"`
 }
 
 // BackupHooks contains custom behaviors that should be executed at different phases of the backup.

pkg/apis/ark/v1/register.go

@@ -59,16 +59,17 @@ func newTypeInfo(pluralName string, itemType, itemListType runtime.Object) typeI
 // API group, keyed on Kind.
 func CustomResources() map[string]typeInfo {
 	return map[string]typeInfo{
-		"Backup":                newTypeInfo("backups", &Backup{}, &BackupList{}),
-		"Restore":               newTypeInfo("restores", &Restore{}, &RestoreList{}),
-		"Schedule":              newTypeInfo("schedules", &Schedule{}, &ScheduleList{}),
-		"Config":                newTypeInfo("configs", &Config{}, &ConfigList{}),
-		"DownloadRequest":       newTypeInfo("downloadrequests", &DownloadRequest{}, &DownloadRequestList{}),
-		"DeleteBackupRequest":   newTypeInfo("deletebackuprequests", &DeleteBackupRequest{}, &DeleteBackupRequestList{}),
-		"PodVolumeBackup":       newTypeInfo("podvolumebackups", &PodVolumeBackup{}, &PodVolumeBackupList{}),
-		"PodVolumeRestore":      newTypeInfo("podvolumerestores", &PodVolumeRestore{}, &PodVolumeRestoreList{}),
-		"ResticRepository":      newTypeInfo("resticrepositories", &ResticRepository{}, &ResticRepositoryList{}),
-		"BackupStorageLocation": newTypeInfo("backupstoragelocations", &BackupStorageLocation{}, &BackupStorageLocationList{}),
+		"Backup":                 newTypeInfo("backups", &Backup{}, &BackupList{}),
+		"Restore":                newTypeInfo("restores", &Restore{}, &RestoreList{}),
+		"Schedule":               newTypeInfo("schedules", &Schedule{}, &ScheduleList{}),
+		"Config":                 newTypeInfo("configs", &Config{}, &ConfigList{}),
+		"DownloadRequest":        newTypeInfo("downloadrequests", &DownloadRequest{}, &DownloadRequestList{}),
+		"DeleteBackupRequest":    newTypeInfo("deletebackuprequests", &DeleteBackupRequest{}, &DeleteBackupRequestList{}),
+		"PodVolumeBackup":        newTypeInfo("podvolumebackups", &PodVolumeBackup{}, &PodVolumeBackupList{}),
+		"PodVolumeRestore":       newTypeInfo("podvolumerestores", &PodVolumeRestore{}, &PodVolumeRestoreList{}),
+		"ResticRepository":       newTypeInfo("resticrepositories", &ResticRepository{}, &ResticRepositoryList{}),
+		"BackupStorageLocation":  newTypeInfo("backupstoragelocations", &BackupStorageLocation{}, &BackupStorageLocationList{}),
+		"VolumeSnapshotLocation": newTypeInfo("volumesnapshotlocations", &VolumeSnapshotLocation{}, &VolumeSnapshotLocationList{}),
 	}
 }
 

pkg/apis/ark/v1/volume_snapshot_location.go

@@ -0,0 +1,65 @@
+/*
+Copyright 2018 the Heptio Ark contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1
+
+import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+// +genclient
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// VolumeSnapshotLocation is a location where Ark stores volume snapshots.
+type VolumeSnapshotLocation struct {
+	metav1.TypeMeta   `json:",inline"`
+	metav1.ObjectMeta `json:"metadata"`
+
+	Spec   VolumeSnapshotLocationSpec   `json:"spec"`
+	Status VolumeSnapshotLocationStatus `json:"status"`
+}
+
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// VolumeSnapshotLocationList is a list of VolumeSnapshotLocations.
+type VolumeSnapshotLocationList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata"`
+	Items           []VolumeSnapshotLocation `json:"items"`
+}
+
+// VolumeSnapshotLocationSpec defines the specification for an Ark VolumeSnapshotLocation.
+type VolumeSnapshotLocationSpec struct {
+	// Provider is the provider of the volume storage.
+	Provider string `json:"provider"`
+
+	// Config is for provider-specific configuration fields.
+	Config map[string]string `json:"config"`
+}
+
+// VolumeSnapshotLocationPhase is the lifecyle phase of an Ark VolumeSnapshotLocation.
+type VolumeSnapshotLocationPhase string
+
+const (
+	// VolumeSnapshotLocationPhaseAvailable means the location is available to read and write from.
+	VolumeSnapshotLocationPhaseAvailable VolumeSnapshotLocationPhase = "Available"
+
+	// VolumeSnapshotLocationPhaseUnavailable means the location is unavailable to read and write from.
+	VolumeSnapshotLocationPhaseUnavailable VolumeSnapshotLocationPhase = "Unavailable"
+)
+
+// VolumeSnapshotLocationStatus describes the current status of an Ark VolumeSnapshotLocation.
+type VolumeSnapshotLocationStatus struct {
+	Phase VolumeSnapshotLocationPhase `json:"phase,omitempty"`
+}