From ec124673fa9ae2950ec9806c053be8f3d39a87ad Mon Sep 17 00:00:00 2001 From: Steve Kriss Date: Mon, 15 Oct 2018 09:47:14 -0600 Subject: [PATCH] remove all references to Config from docs/examples Signed-off-by: Steve Kriss --- docs/about.md | 5 +- docs/aws-config.md | 14 +- docs/azure-config.md | 27 +--- docs/config-definition.md | 146 ------------------ docs/faq.md | 8 +- docs/gcp-config.md | 3 +- docs/ibm-config.md | 2 +- docs/namespace.md | 30 ++-- docs/quickstart.md | 2 - docs/use-cases.md | 6 +- examples/aws/00-ark-config.yaml | 24 --- .../azure/06-ark-volumesnapshotlocation.yaml | 2 +- examples/azure/10-ark-config.yaml | 24 --- examples/common/00-prereqs.yaml | 15 -- examples/common/README.md | 2 +- examples/gcp/00-ark-config.yaml | 22 --- examples/minio/10-ark-config.yaml | 20 --- 17 files changed, 44 insertions(+), 308 deletions(-) delete mode 100644 docs/config-definition.md delete mode 100644 examples/aws/00-ark-config.yaml delete mode 100644 examples/azure/10-ark-config.yaml delete mode 100644 examples/gcp/00-ark-config.yaml delete mode 100644 examples/minio/10-ark-config.yaml diff --git a/docs/about.md b/docs/about.md index 3d0dd8fecf..6f6c045bbc 100644 --- a/docs/about.md +++ b/docs/about.md @@ -1,6 +1,6 @@ # How Ark Works -Each Ark operation -- on-demand backup, scheduled backup, restore -- is a custom resource, defined with a Kubernetes [Custom Resource Definition (CRD)][20] and stored in [etcd][22]. The config custom resource specifies core information and options such as cloud provider settings. Ark also includes controllers that process the custom resources to perform backups, restores, and all related operations. +Each Ark operation -- on-demand backup, scheduled backup, restore -- is a custom resource, defined with a Kubernetes [Custom Resource Definition (CRD)][20] and stored in [etcd][22]. Ark also includes controllers that process the custom resources to perform backups, restores, and all related operations. You can back up or restore all objects in your cluster, or you can filter objects by type, namespace, and/or label. @@ -66,8 +66,9 @@ This allows restore functionality to work in a cluster migration scenario, where Likewise, if a backup object exists in Kubernetes but not in object storage, it will be deleted from Kubernetes since the backup tarball no longer exists. +[10]: hooks.md [19]: /docs/img/backup-process.png [20]: https://kubernetes.io/docs/concepts/api-extension/custom-resources/#customresourcedefinitions [21]: https://kubernetes.io/docs/concepts/api-extension/custom-resources/#custom-controllers [22]: https://github.com/coreos/etcd -[10]: hooks.md \ No newline at end of file + diff --git a/docs/aws-config.md b/docs/aws-config.md index 5cc8c40f3d..b4b98a438d 100644 --- a/docs/aws-config.md +++ b/docs/aws-config.md @@ -139,14 +139,15 @@ kubectl create secret generic cloud-credentials \ Specify the following values in the example files: -* In `examples/aws/00-ark-config.yaml`: - - * Replace ``. See the [Config definition][6] for details. - * In `examples/aws/05-ark-backupstoragelocation.yaml`: * Replace `` and `` (for S3 backup storage, region is optional and will be queried from the AWS S3 API if not provided). See the [BackupStorageLocation definition][21] for details. +* In `examples/aws/06-ark-volumesnapshotlocation.yaml`: + + * Replace ``. See the [VolumeSnapshotLocation definition][6] for details. + + * (Optional) If you run the nginx example, in file `examples/nginx-app/with-pv.yaml`: * Replace `` with `gp2`. This is AWS's default `StorageClass` name. @@ -181,7 +182,8 @@ Specify the following values in the example files: In the root of your Ark directory, run: ```bash - kubectl apply -f examples/aws/00-ark-config.yaml + kubectl apply -f examples/aws/05-ark-backupstoragelocation.yaml + kubectl apply -f examples/aws/06-ark-volumesnapshotlocation.yaml kubectl apply -f examples/aws/10-deployment.yaml ``` @@ -300,7 +302,7 @@ It can be set up for Ark by creating a role that will have required permissions, [0]: namespace.md [5]: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html -[6]: config-definition.md#aws +[6]: api-types/volumesnapshotlocation.md#aws [14]: http://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html [20]: faq.md [21]: api-types/backupstoragelocation.md#aws diff --git a/docs/azure-config.md b/docs/azure-config.md index e0eb503962..b1793832cf 100644 --- a/docs/azure-config.md +++ b/docs/azure-config.md @@ -125,31 +125,14 @@ kubectl create secret generic cloud-credentials \ Now that you have your Azure credentials stored in a Secret, you need to replace some placeholder values in the template files. Specifically, you need to change the following: -* In file `examples/azure/10-ark-config.yaml`: - - * Replace ``. See the [Config definition][8] for details. - * In file `examples/azure/05-ark-backupstoragelocation.yaml`: * Replace ``, ``, and ``. See the [BackupStorageLocation definition][21] for details. -Here is an example of a completed config file. - -```yaml -apiVersion: ark.heptio.com/v1 -kind: Config -metadata: - namespace: heptio-ark - name: default -persistentVolumeProvider: - name: azure - config: - apiTimeout: 15m -backupSyncPeriod: 30m -gcSyncPeriod: 30m -scheduleSyncPeriod: 1m -restoreOnlyMode: false -``` +* In file `examples/azure/06-ark-volumesnapshotlocation.yaml`: + + * Replace ``. See the [VolumeSnapshotLocation definition][8] for details. + ## Start the server @@ -160,7 +143,7 @@ In the root of your Ark directory, run: ``` [0]: namespace.md -[8]: config-definition.md#azure +[8]: docs/api-types/volumesnapshotlocation.md#azure [17]: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-application-objects [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 diff --git a/docs/config-definition.md b/docs/config-definition.md deleted file mode 100644 index 0b124ea7b8..0000000000 --- a/docs/config-definition.md +++ /dev/null @@ -1,146 +0,0 @@ -# Ark Config definition and Ark server deployment - -* [Config][8] - * [Example][9] - * [Parameter Reference][6] - * [Main config][7] - * [AWS][0] - * [GCP][1] - * [Azure][2] -* [Deployment][11] - * [Sample Deployment][13] - * [Parameter Options][14] - -## Config - -Heptio Ark defines its own Config object (a custom resource) for specifying Ark backup and cloud provider settings. When the Ark server is first deployed, it waits until you create a Config --specifically one named `default`-- in the `heptio-ark` namespace. - -> *NOTE*: There is an underlying assumption that you're running the Ark server as a Kubernetes deployment. If the `default` Config is modified, the server shuts down gracefully. Once the kubelet restarts the Ark server pod, the server then uses the updated Config values. - -### Example - -A sample YAML `Config` looks like the following: - -```yaml -apiVersion: ark.heptio.com/v1 -kind: Config -metadata: - namespace: heptio-ark - name: default -persistentVolumeProvider: - name: aws - config: - region: us-west-2 -``` - -### Parameter Reference - -The configurable parameters are as follows: - -#### Main config parameters - -| Key | Type | Default | Meaning | -| --- | --- | --- | --- | -| `persistentVolumeProvider` | CloudProviderConfig | None (Optional) | The specification for whichever cloud provider the cluster is using for persistent volumes (to be snapshotted), if any.

If not specified, Backups and Restores requesting PV snapshots & restores, respectively, are considered invalid.

*NOTE*: For Azure, your Kubernetes cluster needs to be version 1.7.2+ in order to support PV snapshotting of its managed disks. | -| `persistentVolumeProvider/name` | String

(Ark natively supports `aws`, `gcp`, and `azure`. Other providers may be available via external plugins.) | None (Optional) | The name of the cloud provider the cluster is using for persistent volumes, if any. | -| `persistentVolumeProvider/config` | map[string]string

(See the corresponding [AWS][0], [GCP][1], and [Azure][2]-specific configs or your provider's documentation.) | None (Optional) | Configuration keys/values to be passed to the cloud provider for persistent volumes. | - -#### AWS - -##### persistentVolumeProvider/config (AWS Only) - -| Key | Type | Default | Meaning | -| --- | --- | --- | --- | -| `region` | string | Required Field | *Example*: "us-east-1"

See [AWS documentation][3] for the full list. | - -#### Azure - -##### persistentVolumeProvider/config - -| Key | Type | Default | Meaning | -| --- | --- | --- | --- | -| `apiTimeout` | metav1.Duration | 2m0s | How long to wait for an Azure API request to complete before timeout. | - -#### GCP - -##### persistentVolumeProvider/config - -No parameters required. - - -## Deployment - -Heptio Ark also defines its own Deployment object for starting the Ark server on Kubernetes. When the Ark server is deployed, there are specific configurations that might be changed. - -### Sample Deployment - -A sample YAML `Deployment` looks like the following: - -```yaml -apiVersion: apps/v1beta1 -kind: Deployment -metadata: - namespace: heptio-ark - name: ark -spec: - replicas: 1 - template: - metadata: - labels: - component: ark - annotations: - prometheus.io/scrape: "true" - prometheus.io/port: "8085" - prometheus.io/path: "/metrics" - spec: - restartPolicy: Always - serviceAccountName: ark - containers: - - name: ark - image: gcr.io/heptio-images/ark:latest - command: - - /ark - args: - - server - - --backup-sync-period - - 30m - volumeMounts: - - name: cloud-credentials - mountPath: /credentials - - name: plugins - mountPath: /plugins - - name: scratch - mountPath: /scratch - env: - - name: AWS_SHARED_CREDENTIALS_FILE - value: /credentials/cloud - - name: ARK_SCRATCH_DIR - value: /scratch - volumes: - - name: cloud-credentials - secret: - secretName: cloud-credentials - - name: plugins - emptyDir: {} - - name: scratch - emptyDir: {} -``` - -### Parameter Options - -The list of configurable options for the `ark server` deployment can be found by running `ark server --help`. - - - -[0]: #aws -[1]: #gcp -[2]: #azure -[3]: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions -[6]: #parameter-reference -[7]: #main-config-parameters -[8]: #config -[9]: #example -[10]: http://docs.aws.amazon.com/kms/latest/developerguide/overview.html -[11]: #deployment -[13]: #sample-deployment -[14]: #parameter-options diff --git a/docs/faq.md b/docs/faq.md index f3da086cf8..b25b4f4399 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -31,9 +31,7 @@ across multiple Ark instances can lead to numerous problems - failed backups, ov inadvertently deleted backups, etc., all of which can be avoided by using a separate bucket per Ark instance. -Related to this, if you need to restore a backup from cluster A into cluster B, please use [restore-only][1] -mode in cluster B's Ark instance while it's configured to use cluster A's bucket. This will ensure no +Related to this, if you need to restore a backup from cluster A into cluster B, please use restore-only +mode in cluster B's Ark instance (via the `--restore-only` flag on the `ark server` command specified +in your Ark deployment) while it's configured to use cluster A's bucket. This will ensure no new backups are created, and no existing backups are deleted or overwritten. - - -[1]: config-definition.md#main-config-parameters \ No newline at end of file diff --git a/docs/gcp-config.md b/docs/gcp-config.md index dc4466cbe9..4b07954644 100644 --- a/docs/gcp-config.md +++ b/docs/gcp-config.md @@ -124,7 +124,8 @@ Specify the following values in the example files: In the root of your Ark directory, run: ```bash - kubectl apply -f examples/gcp/00-ark-config.yaml + kubectl apply -f examples/gcp/05-ark-backupstoragelocation.yaml + kubectl apply -f examples/gcp/06-ark-volumesnapshotlocation.yaml kubectl apply -f examples/gcp/10-deployment.yaml ``` diff --git a/docs/ibm-config.md b/docs/ibm-config.md index 64b4b700b5..7b9fa8823c 100644 --- a/docs/ibm-config.md +++ b/docs/ibm-config.md @@ -68,7 +68,7 @@ Specify the following values in the example files: In the root of your Ark directory, run: ```bash - kubectl apply -f examples/ibm/00-ark-config.yaml + kubectl apply -f examples/ibm/05-ark-backupstoragelocation.yaml kubectl apply -f examples/ibm/10-deployment.yaml ``` diff --git a/docs/namespace.md b/docs/namespace.md index 004771634e..61d8b1cb7b 100644 --- a/docs/namespace.md +++ b/docs/namespace.md @@ -7,7 +7,7 @@ you run Ark client commands. ## Edit the example files The Ark repository includes [a set of examples][0] that you can use to set up your Ark server. The -examples place the server and backup/schedule/restore/config data in the `heptio-ark` namespace. +examples place the server and backup/schedule/restore/etc. data in the `heptio-ark` namespace. To run the server in another namespace, you edit the relevant files, changing `heptio-ark` to your desired namespace. @@ -18,9 +18,9 @@ files, changing `heptio-ark` to your desired namespace. You also need to create For all cloud providers, edit `https://github.com/heptio/ark/blob/master/examples/common/00-prereqs.yaml`. This file defines: -* CustomResourceDefinitions for the Ark objects (backups, schedules, restores, configs, downloadrequests) +* CustomResourceDefinitions for the Ark objects (backups, schedules, restores, downloadrequests, etc.) * The namespace where the Ark server runs -* The namespace where backups, schedules, restores, and the config are stored +* The namespace where backups, schedules, restores, etc. are stored * The Ark service account * The RBAC rules to grant permissions to the Ark service account @@ -29,31 +29,35 @@ For all cloud providers, edit `https://github.com/heptio/ark/blob/master/example For AWS, edit: +* `https://github.com/heptio/ark/blob/master/examples/aws/05-ark-backupstoragelocation.yaml` +* `https://github.com/heptio/ark/blob/master/examples/aws/06-ark-volumesnapshotlocation.yaml` * `https://github.com/heptio/ark/blob/master/examples/aws/10-deployment.yaml` -* `https://github.com/heptio/ark/blob/master/examples/aws/00-ark-config.yaml` -### GCP +### Azure -For GCP, edit: +For Azure, edit: -* `https://github.com/heptio/ark/blob/master/examples/gcp/10-deployment.yaml` -* `https://github.com/heptio/ark/blob/master/examples/gcp/00-ark-config.yaml` +* `https://github.com/heptio/ark/blob/master/examples/azure/00-ark-deployment.yaml` +* `https://github.com/heptio/ark/blob/master/examples/azure/05-ark-backupstoragelocation.yaml` +* `https://github.com/heptio/ark/blob/master/examples/azure/06-ark-volumesnapshotlocation.yaml` +### GCP -### Azure +For GCP, edit: -For Azure, edit: +* `https://github.com/heptio/ark/blob/master/examples/gcp/05-ark-backupstoragelocation.yaml` +* `https://github.com/heptio/ark/blob/master/examples/gcp/06-ark-volumesnapshotlocation.yaml` +* `https://github.com/heptio/ark/blob/master/examples/gcp/10-deployment.yaml` -* `https://github.com/heptio/ark/blob/master/examples/azure/00-ark-deployment.yaml` -* `https://github.com/heptio/ark/blob/master/examples/azure/10-ark-config.yaml` ### IBM For IBM, edit: +* `https://github.com/heptio/ark/blob/master/examples/ibm/05-ark-backupstoragelocation.yaml` * `https://github.com/heptio/ark/blob/master/examples/ibm/10-deployment.yaml` -* `https://github.com/heptio/ark/blob/master/examples/ibm/00-ark-config.yaml` + ## Specify the namespace in client commands diff --git a/docs/quickstart.md b/docs/quickstart.md index 31b337a6b3..4ed5111e40 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -33,8 +33,6 @@ NOTE: Make sure to check out the appropriate version. We recommend that you chec kubectl apply -f examples/minio/ ``` - NOTE: If you get an error about Config creation, wait for a minute, then run the commands again. - 1. Deploy the example nginx application: ```bash diff --git a/docs/use-cases.md b/docs/use-cases.md index ffb4317ba7..428a83c134 100644 --- a/docs/use-cases.md +++ b/docs/use-cases.md @@ -30,7 +30,7 @@ If you periodically back up your cluster's resources, you are able to return to *Using Backups and Restores* -Heptio Ark can help you port your resources from one cluster to another, as long as you point each Ark Config to the same cloud object storage. 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.** +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 `` as desired): @@ -39,7 +39,7 @@ Heptio Ark can help you port your resources from one cluster to another, as long ``` The default TTL is 30 days (720 hours); you can use the `--ttl` flag to change this as necessary. -2. *(Cluster 2)* Make sure that the `persistentVolumeProvider` and `backupStorageProvider` fields in the Ark Config match the ones from *Cluster 1*, so that your new Ark server instance is pointing to the same bucket. +2. *(Cluster 2)* Make sure that the `BackupStorageLocation` and `VolumeSnapshotLocation` CRDs match the ones from *Cluster 1*, so that your new Ark server instance is pointing to the same bucket. 3. *(Cluster 2)* Make sure that the Ark Backup object has been created. Ark resources are synced with the backup files available in cloud storage. @@ -49,4 +49,4 @@ ark restore create --from-backup ``` [0]: #disaster-recovery -[1]: #cluster-migration \ No newline at end of file +[1]: #cluster-migration diff --git a/examples/aws/00-ark-config.yaml b/examples/aws/00-ark-config.yaml deleted file mode 100644 index 2068deec22..0000000000 --- a/examples/aws/00-ark-config.yaml +++ /dev/null @@ -1,24 +0,0 @@ -# Copyright 2017 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: Config -metadata: - namespace: heptio-ark - name: default -persistentVolumeProvider: - name: aws - config: - region: \ No newline at end of file diff --git a/examples/azure/06-ark-volumesnapshotlocation.yaml b/examples/azure/06-ark-volumesnapshotlocation.yaml index 14fdd76a60..7c73cd2482 100644 --- a/examples/azure/06-ark-volumesnapshotlocation.yaml +++ b/examples/azure/06-ark-volumesnapshotlocation.yaml @@ -21,4 +21,4 @@ metadata: spec: provider: azure config: - apiTimeout: 2m0s + apiTimeout: diff --git a/examples/azure/10-ark-config.yaml b/examples/azure/10-ark-config.yaml deleted file mode 100644 index 9acb3d1c3b..0000000000 --- a/examples/azure/10-ark-config.yaml +++ /dev/null @@ -1,24 +0,0 @@ -# Copyright 2017 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: Config -metadata: - namespace: heptio-ark - name: default -persistentVolumeProvider: - name: azure - config: - apiTimeout: \ No newline at end of file diff --git a/examples/common/00-prereqs.yaml b/examples/common/00-prereqs.yaml index 4ffb20b9b6..fa9de43feb 100644 --- a/examples/common/00-prereqs.yaml +++ b/examples/common/00-prereqs.yaml @@ -57,21 +57,6 @@ spec: plural: restores kind: Restore ---- -apiVersion: apiextensions.k8s.io/v1beta1 -kind: CustomResourceDefinition -metadata: - name: configs.ark.heptio.com - labels: - component: ark -spec: - group: ark.heptio.com - version: v1 - scope: Namespaced - names: - plural: configs - kind: Config - --- apiVersion: apiextensions.k8s.io/v1beta1 kind: CustomResourceDefinition diff --git a/examples/common/README.md b/examples/common/README.md index e662173b21..ea56ea63eb 100644 --- a/examples/common/README.md +++ b/examples/common/README.md @@ -7,4 +7,4 @@ This file contains the prerequisites necessary to run the Ark server: - `heptio-ark` namespace - `ark` service account - RBAC rules to grant permissions to the `ark` service account -- CRDs for the Ark-specific resources (Backup, Schedule, Restore, Config) +- CRDs for the Ark-specific resources (Backup, Schedule, Restore, etc.) diff --git a/examples/gcp/00-ark-config.yaml b/examples/gcp/00-ark-config.yaml deleted file mode 100644 index 9ebc5622da..0000000000 --- a/examples/gcp/00-ark-config.yaml +++ /dev/null @@ -1,22 +0,0 @@ -# Copyright 2017 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: Config -metadata: - namespace: heptio-ark - name: default -persistentVolumeProvider: - name: gcp \ No newline at end of file diff --git a/examples/minio/10-ark-config.yaml b/examples/minio/10-ark-config.yaml deleted file mode 100644 index 947c0adff8..0000000000 --- a/examples/minio/10-ark-config.yaml +++ /dev/null @@ -1,20 +0,0 @@ -# Copyright 2017 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: Config -metadata: - namespace: heptio-ark - name: default