mirrors/velero
1
0
Fork 0
mirror of https://github.com/vmware-tanzu/velero.git synced 2026-05-01 12:55:46 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

remove all references to Config from docs/examples

Browse Source 
Signed-off-by: Steve Kriss <steve@heptio.com>
This commit is contained in:
Steve Kriss
2018-10-15 09:47:14 -06:00
parent c36131a024
commit ec124673fa
17 changed files with 44 additions and 308 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/about.md
View File

@@ -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

14
docs/aws-config.md
View File

@@ -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 `<YOUR_REGION>`. See the [Config definition][6] for details.
* In `examples/aws/05-ark-backupstoragelocation.yaml`:
* Replace `<YOUR_BUCKET>` and `<YOUR_REGION>` (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 `<YOUR_REGION>`. See the [VolumeSnapshotLocation definition][6] for details.
* (Optional) If you run the nginx example, in file `examples/nginx-app/with-pv.yaml`:
* Replace `<YOUR_STORAGE_CLASS_NAME>` 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

25
docs/azure-config.md
View File

@@ -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 `<YOUR_TIMEOUT>`. See the [Config definition][8] for details.
* In file `examples/azure/05-ark-backupstoragelocation.yaml`:
* Replace `<YOUR_BLOB_CONTAINER>`, `<YOUR_STORAGE_RESOURCE_GROUP>`, and `<YOUR_STORAGE_ACCOUNT>`. See the [BackupStorageLocation definition][21] for details.
Here is an example of a completed config file.
* In file `examples/azure/06-ark-volumesnapshotlocation.yaml`:
* Replace `<YOUR_TIMEOUT>`. See the [VolumeSnapshotLocation definition][8] for details.
```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
```
## 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

146
docs/config-definition.md
View File

@@ -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.<br><br>If not specified, Backups and Restores requesting PV snapshots & restores, respectively, are considered invalid. <br><br> *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<br><br>(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<br><br>(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"<br><br>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

8
docs/faq.md
View File

@@ -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

3
docs/gcp-config.md
View File

@@ -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
```

2
docs/ibm-config.md
View File

@@ -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
```

32
docs/namespace.md
View File

@@ -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,16 +29,9 @@ 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
For GCP, 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`
### Azure
@@ -46,14 +39,25 @@ For GCP, edit:
For Azure, edit:
* `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`
* `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
For GCP, 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`
### 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

2
docs/quickstart.md
View File

@@ -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

6
docs/use-cases.md
View File

@@ -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 `<BACKUP-NAME>` 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 <BACKUP-NAME>
```
[0]: #disaster-recovery
[1]: #cluster-migration
[1]: #cluster-migration

24
examples/aws/00-ark-config.yaml
View File

@@ -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: <YOUR_REGION>

2
examples/azure/06-ark-volumesnapshotlocation.yaml
View File

@@ -21,4 +21,4 @@ metadata:
spec:
provider: azure
config:
apiTimeout: 2m0s
apiTimeout: <YOUR_TIMEOUT>

24
examples/azure/10-ark-config.yaml
View File

@@ -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: <YOUR_TIMEOUT>

15
examples/common/00-prereqs.yaml
View File

@@ -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

2
examples/common/README.md
View File

@@ -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.)

22
examples/gcp/00-ark-config.yaml
View File

@@ -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

20
examples/minio/10-ark-config.yaml
View File

@@ -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