mirrors/velero
1
0
Fork 0
mirror of https://github.com/vmware-tanzu/velero.git synced 2026-07-29 19:42:45 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve contributing docs (#1852)

Browse Source 
Signed-off-by: Carlisia <carlisia@vmware.com>
This commit is contained in:
KubeKween
2019-09-16 12:18:38 -06:00
committed by Steve Kriss
parent c55845f168
commit 6ef67fe0e7
19 changed files with 311 additions and 456 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1 -21
View File
@@ -36,19 +36,7 @@ If you encounter issues, review the [troubleshooting docs][30], [file an issue][
## Contributing
Thanks for taking the time to join our community and start contributing!
Feedback and discussion are available on [the mailing list][24].
### Before you start
* Please familiarize yourself with the [Code of Conduct][8] before contributing.
* See [CONTRIBUTING.md][5] for instructions on the developer certificate of origin that we require.
* Read how [we're using ZenHub][26] for project and roadmap planning
### Pull requests
* We welcome pull requests. Feel free to dig through the [issues][4] and jump in.
If you are ready to jump in and test, add code, or help with documentation, follow the instructions on our [Start contributing](https://velero.io/docs/master/start-contributing/) documentation for guidance on how to setup Velero for development.
## Changelog
@@ -56,25 +44,17 @@ See [the list of releases][6] to find out about feature changes.
[1]: https://travis-ci.org/heptio/velero.svg?branch=master
[2]: https://travis-ci.org/heptio/velero
[4]: https://github.com/heptio/velero/issues
[5]: https://github.com/heptio/velero/blob/master/CONTRIBUTING.md
[6]: https://github.com/heptio/velero/releases
[8]: https://github.com/heptio/velero/blob/master/CODE_OF_CONDUCT.md
[9]: https://kubernetes.io/docs/setup/
[10]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos
[11]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1
[12]: https://github.com/kubernetes/kubernetes/blob/master/cluster/addons/dns/README.md
[14]: https://github.com/kubernetes/kubernetes
[24]: https://groups.google.com/forum/#!forum/projectvelero
[25]: https://kubernetes.slack.com/messages/velero
[26]: https://velero.io/docs/zenhub
[28]: https://velero.io/docs/install-overview
[29]: https://velero.io/docs/
[30]: https://velero.io/docs/troubleshooting
[99]: https://velero.io/docs/support-matrix
[100]: /site/docs/master/img/velero.png
site/_data/master-toc.yml
+13 -9
View File
@@ -35,6 +35,12 @@ toc:
url: /backup-reference
- page: Restore reference
url: /restore-reference
- page: Run in any namespace
url: /namespace
- page: Extend with plugins
url: /plugins
- page: Extend with hooks
url: /hooks
- title: Troubleshoot
subfolderitems:
- page: Troubleshooting
@@ -45,18 +51,16 @@ toc:
url: /debugging-restores
- page: Troubleshoot Restic
url: /restic#troubleshooting
- title: Customize
- title: Contribute
subfolderitems:
- page: Start Contributing
url: /start-contributing
- page: Development
url: /development
- page: Build from source
url: /build-from-source
- page: Run in any namespace
url: /namespace
- page: Extend
url: /extend
- page: Extend with plugins
url: /plugins
- page: Extend with hooks
url: /hooks
- page: Run locally
url: /run-locally
- title: More information
subfolderitems:
- page: Backup file format
site/_data/v1-0-0-toc.yml
+1 -1
View File
@@ -60,4 +60,4 @@ toc:
- page: API types
url: /api-types
- page: FAQ
url: /faq
url: /faq
site/_data/v1-1-0-toc.yml
+13 -9
View File
@@ -35,6 +35,12 @@ toc:
url: /backup-reference
- page: Restore reference
url: /restore-reference
- page: Run in any namespace
url: /namespace
- page: Extend with plugins
url: /plugins
- page: Extend with hooks
url: /hooks
- title: Troubleshoot
subfolderitems:
- page: Troubleshooting
@@ -45,18 +51,16 @@ toc:
url: /debugging-restores
- page: Troubleshoot Restic
url: /restic#troubleshooting
- title: Customize
- title: Contribute
subfolderitems:
- page: Start Contributing
url: /start-contributing
- page: Development
url: /development
- page: Build from source
url: /build-from-source
- page: Run in any namespace
url: /namespace
- page: Extend
url: /extend
- page: Extend with plugins
url: /plugins
- page: Extend with hooks
url: /hooks
- page: Run locally
url: /run-locally
- title: More information
subfolderitems:
- page: Backup file format
site/community.md
+5
View File
@@ -8,6 +8,11 @@ id: community
If you’re a newcomer, check out the “[Good first issue](https://github.com/heptio/velero/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+first+issue%22)” and “[Help wanted](https://github.com/heptio/velero/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22Help+wanted%22+)” labels in the Velero repository.
Read how [we're using ZenHub](https://velero.io/docs/master/zenhub) for project and roadmap planning.
If you are ready to jump in and test, add code, or help with documentation, follow the instructions on our [Start contributing](https://velero.io/docs/master/start-contributing/) documentation for guidance on how to setup Velero for development.
You can follow the work we do, see our milestones, and our backlog on our [ZenHub board](https://app.zenhub.com/workspace/o/heptio/velero/boards?filterLogic=all&repos=99143276).
* Follow us on Twitter at [@projectvelero](https://twitter.com/projectvelero)
site/docs/master/README.md
+2 -18
View File
@@ -36,19 +36,7 @@ If you encounter issues, review the [troubleshooting docs][30], [file an issue][
## Contributing
Thanks for taking the time to join our community and start contributing!
Feedback and discussion are available on [the mailing list][24].
### Before you start
* Please familiarize yourself with the [Code of Conduct][8] before contributing.
* See [CONTRIBUTING.md][5] for instructions on the developer certificate of origin that we require.
* Read how [we're using ZenHub][26] for project and roadmap planning
### Pull requests
* We welcome pull requests. Feel free to dig through the [issues][4] and jump in.
If you are ready to jump in and test, add code, or help with documentation, follow the instructions on our [Start contributing](https://velero.io/docs/master/start-contributing/) documentation for guidance on how to setup Velero for development.
## Changelog
@@ -58,10 +46,8 @@ See [the list of releases][6] to find out about feature changes.
[2]: https://travis-ci.org/heptio/velero
[4]: https://github.com/heptio/velero/issues
[5]: https://github.com/heptio/velero/blob/master/CONTRIBUTING.md
[6]: https://github.com/heptio/velero/releases
[8]: https://github.com/heptio/velero/blob/master/CODE_OF_CONDUCT.md
[9]: https://kubernetes.io/docs/setup/
[10]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos
[11]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1
@@ -70,12 +56,10 @@ See [the list of releases][6] to find out about feature changes.
[24]: https://groups.google.com/forum/#!forum/projectvelero
[25]: https://kubernetes.slack.com/messages/velero
[26]: /zenhub.md
[28]: install-overview.md
[29]: https://velero.io/docs/master/
[30]: troubleshooting.md
[99]: support-matrix.md
[100]: img/velero.png
[100]: img/velero.png
site/docs/master/build-from-source.md
+30 -180
View File
@@ -1,12 +1,5 @@
# Build from source
* [Prerequisites][1]
* [Getting the source][2]
* [Build][3]
* [Test][12]
* [Run][7]
* [Vendoring dependencies][10]
## Prerequisites
* Access to a Kubernetes cluster, version 1.7 or later.
@@ -14,7 +7,7 @@
* `kubectl` installed
* [Go][5] installed (minimum version 1.8)
## Getting the source
## Get the source
### Option 1) Get latest (recommended)
@@ -29,73 +22,42 @@ Where `go` is your [import path][4] for Go.
For Go development, it is recommended to add the Go import path (`$HOME/go` in this example) to your path.
### Option 2) Release archive
Download the archive named `Source code` from the [release page][22] and extract it in your Go import path as `src/github.com/heptio/velero`.
Note that the Makefile targets assume building from a git repository. When building from an archive, you will be limited to the `go build` commands described below.
## Build
There are a number of different ways to build `velero` depending on your needs. This section outlines the main possibilities.
To build the `velero` binary on your local machine, compiled for your OS and architecture, run:
When building by using `make`, it will place the binaries under `_output/bin/$GOOS/$GOARCH`. For example, you will find the binary for darwin here: `_output/bin/darwin/amd64/velero`, and the binary for linux here: `_output/bin/linux/amd64/velero`. `make` will also splice version and git commit information in so that `velero version` displays proper output.
Note: `velero install` will also use the version information to determine which tagged image to deploy. If you would like to overwrite what image gets deployed, use the `image` flag (see below for instructions on how to build images).
### Build the binary
To build the `velero` binary on your local machine, compiled for your OS and architecture, run one of these two commands:
```bash
go build ./cmd/velero
```
or:
```bash
make local
```
The latter will place the compiled binary under `$PWD/_output/bin/$GOOS/$GOARCH`, and will splice version and git commit information in so that `velero version` displays proper output. `velero install` will also use the version information to determine which tagged image to deploy.
### Cross compiling
To build the `velero` binary targeting `linux/amd64` within a build container on your local machine, run:
To build the velero binary targeting linux/amd64 within a build container on your local machine, run:
```bash
make build
```
See the **Cross compiling** section below for details on building for alternate OS/architecture combinations.
For any specific platform, run `make build-<GOOS>-<GOARCH>`.
To build a Velero container image, first set the `$REGISTRY` environment variable. For example, if you want to build the `gcr.io/my-registry/velero:master` image, set `$REGISTRY` to `gcr.io/my-registry`. Optionally, set the `$VERSION` environment variable to change the image tag. Then, run:
```bash
make container
```
To push your image to a registry, run:
```bash
make push
```
### Update generated files
The following files are automatically generated from the source code:
* The clientset
* Listers
* Shared informers
* Documentation
* Protobuf/gRPC types
Run `make update` to regenerate files if you make the following changes:
* Add/edit/remove command line flags and/or their help text
* Add/edit/remove commands or subcommands
* Add new API types
Run [generate-proto.sh][13] to regenerate files if you make the following changes:
* Add/edit/remove protobuf message or service definitions. These changes require the [proto compiler][14] and compiler plugin `protoc-gen-go` version v1.0.0.
### Cross compiling
By default, `make build` builds an `velero` binary for `linux-amd64`.
To build for another platform, run `make build-<GOOS>-<GOARCH>`.
For example, to build for the Mac, run `make build-darwin-amd64`.
All binaries are placed in `_output/bin/<GOOS>/<GOARCH>`-- for example, `_output/bin/darwin/amd64/velero`.
Velero's `Makefile` has a convenience target, `all-build`, that builds the following platforms:
@@ -105,146 +67,34 @@ Velero's `Makefile` has a convenience target, `all-build`, that builds the follo
* darwin-amd64
* windows-amd64
## 3. Test
## Making images and updating Velero
To run unit tests, use `make test`. You can also run `make verify` to ensure that all generated
files (clientset, listers, shared informers, docs) are up to date.
## 4. Run
### Prerequisites
When running Velero, you will need to ensure that you set up all of the following:
* Appropriate RBAC permissions in the cluster
* Read access for all data from the source cluster and namespaces
* Write access to the target cluster and namespaces
* Cloud provider credentials
* Read/write access to volumes
* Read/write access to object storage for backup data
* A [BackupStorageLocation][20] object definition for the Velero server
* (Optional) A [VolumeSnapshotLocation][21] object definition for the Velero server, to take PV snapshots
### Create a cluster
To provision a cluster on AWS using Amazon’s official CloudFormation templates, here are two options:
* EC2 [Quick Start for Kubernetes][17]
* eksctl - [a CLI for Amazon EKS][18]
### Option 1: Run your Velero server locally
Running the Velero server locally can speed up iterative development. This eliminates the need to rebuild the Velero server
image and redeploy it to the cluster with each change.
#### 1. Set enviroment variables
Set the appropriate environment variable for your cloud provider:
AWS: [AWS_SHARED_CREDENTIALS_FILE][15]
GCP: [GOOGLE_APPLICATION_CREDENTIALS][16]
Azure:
1. AZURE_CLIENT_ID
2. AZURE_CLIENT_SECRET
3. AZURE_SUBSCRIPTION_ID
4. AZURE_TENANT_ID
5. AZURE_STORAGE_ACCOUNT_ID
6. AZURE_STORAGE_KEY
7. AZURE_RESOURCE_GROUP
#### 2. Create required Velero resources in the cluster
You can use the `velero install` command to install velero into your cluster, then remove the deployment from the cluster, leaving you
with all of the required in-cluster resources.
##### Example
This examples assumes you are using an existing cluster in AWS.
Using the `velero` binary that you've built, run `velero install`:
If after installing Velero you would like to change the image used by its deployment to one that contains your code changes, you may do so by updating the image:
```bash
# velero install requires a credentials file to exist, but we will
# not be using it since we're running the server locally, so just
# create an empty file to pass to the install command.
touch fake-credentials-file
velero install \
--provider aws \
--bucket $BUCKET \
--backup-location-config region=$REGION \
--snapshot-location-config region=$REGION \
--secret-file ./fake-credentials-file
# 'velero install' creates an in-cluster deployment of the
# velero server using an official velero image, but we want
# to run the velero server on our local machine using the
# binary we built, so delete the in-cluster deployment.
kubectl --namespace velero delete deployment velero
rm fake-credentials-file
kubectl -n velero set image deploy/velero velero=myimagerepo/velero:$VERSION
```
#### 3. Start the Velero server locally
To build a Velero container image, first set the `$REGISTRY` environment variable. For example, if you want to build the `gcr.io/my-registry/velero:master` image, set `$REGISTRY` to `gcr.io/my-registry`. If this variable is not set, the default is `gcr.io/heptio-images`.
* Make sure the `velero` binary you build is in your `PATH`, or specify the full path.
Optionally, set the `$VERSION` environment variable to change the image tag. Then, run:
* Start the server: `velero server [CLI flags]`. The following CLI flags may be useful to customize, but see `velero server --help` for full details:
* `--kubeconfig`: set the path to the kubeconfig file the Velero server uses to talk to the Kubernetes apiserver (default `$KUBECONFIG`)
* `--namespace`: the set namespace where the Velero server should look for backups, schedules, restores (default `velero`)
* `--log-level`: set the Velero server's log level (default `info`)
* `--plugin-dir`: set the directory where the Velero server looks for plugins (default `/plugins`)
* `--metrics-address`: set the bind address and port where Prometheus metrics are exposed (default `:8085`)
```bash
make container
```
### Option 2: Run your Velero server in a deployment
To push your image to the registry, run:
1. Ensure you've built a `velero` container image and either loaded it onto your cluster's nodes, or pushed it to a registry (see [build][3]).
```bash
make push
```
1. Install Velero into the cluster (the example below assumes you're using AWS):
Note: if you want to update the image but not change its name, you will have to trigger Kubernetes to pick up the new image. One way of doing so is by deleting the Velero deployment pod:
```bash
velero install \
--provider aws \
--image $YOUR_CONTAINER_IMAGE \
--bucket $BUCKET \
--backup-location-config region=$REGION \
--snapshot-location-config region=$REGION \
--secret-file $YOUR_AWS_CREDENTIALS_FILE
```
```bash
kubectl -n velero delete pods -l deploy=velero
```
## 5. Vendoring dependencies
If you need to add or update the vendored dependencies, see [Vendoring dependencies][11].
[0]: ../README.md
[1]: #prerequisites
[2]: #getting-the-source
[3]: #build
[4]: https://blog.golang.org/organizing-go-code
[5]: https://golang.org/doc/install
[6]: https://github.com/heptio/velero/tree/master/examples
[7]: #run
[8]: config-definition.md
[10]: #vendoring-dependencies
[11]: vendoring-dependencies.md
[12]: #test
[13]: https://github.com/heptio/velero/blob/master/hack/generate-proto.sh
[14]: https://grpc.io/docs/quickstart/go.html#install-protocol-buffers-v3
[15]: https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#the-shared-credentials-file
[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
[20]: api-types/backupstoragelocation.md
[21]: api-types/volumesnapshotlocation.md
[22]: https://github.com/heptio/velero/releases
[22]: https://github.com/heptio/velero/releases
site/docs/master/development.md
+35
View File
@@ -0,0 +1,35 @@
# Development
## Update generated files
Run `make update` to regenerate files if you make the following changes:
* Add/edit/remove command line flags and/or their help text
* Add/edit/remove commands or subcommands
* Add new API types
Run [generate-proto.sh][13] to regenerate files if you make the following changes:
* Add/edit/remove protobuf message or service definitions. These changes require the [proto compiler][14] and compiler plugin `protoc-gen-go` version v1.0.0.
The following files are automatically generated from the source code:
* The clientset
* Listers
* Shared informers
* Documentation
* Protobuf/gRPC types
You can run `make verify` to ensure that all generated files (clientset, listers, shared informers, docs) are up to date.
## Test
To run unit tests, use `make test`.
## Vendor dependencies
If you need to add or update the vendored dependencies, see [Vendoring dependencies][11].
[11]: vendoring-dependencies.md
[13]: https://github.com/heptio/velero/blob/master/hack/generate-proto.sh
[14]: https://grpc.io/docs/quickstart/go.html#install-protocol-buffers-v3
site/docs/master/extend.md
-9
View File
@@ -1,9 +0,0 @@
# Extend Velero
Velero includes mechanisms for extending the core functionality to meet your individual backup/restore needs:
* [Hooks][27] allow you to specify commands to be executed within running pods during a backup. This is useful if you need to run a workload-specific command prior to taking a backup (for example, to flush disk buffers or to freeze a database).
* [Plugins][28] allow you to develop custom object/block storage back-ends or per-item backup/restore actions that can execute arbitrary logic, including modifying the items being backed up/restored. Plugins can be used by Velero without needing to be compiled into the core Velero binary.
[27]: hooks.md
[28]: plugins.md
site/docs/master/run-locally.md
+50
View File
@@ -0,0 +1,50 @@
# Run Velero locally in development
Running the Velero server locally can speed up iterative development. This eliminates the need to rebuild the Velero server
image and redeploy it to the cluster with each change.
## Run Velero locally with a remote cluster
Velero runs against the Kubernetes API server as the endpoint (as per the `kubeconfig` configuration), so both the Velero server and client use the same `client-go` to communicate with Kubernetes. This means the Velero server can be run locally just as functionally as if it was running in the remote cluster.
### Prerequisites
When running Velero, you will need to ensure that you set up all of the following:
* Appropriate RBAC permissions in the cluster
* Read access for all data from the source cluster and namespaces
* Write access to the target cluster and namespaces
* Cloud provider credentials
* Read/write access to volumes
* Read/write access to object storage for backup data
* A [BackupStorageLocation][20] object definition for the Velero server
* (Optional) A [VolumeSnapshotLocation][21] object definition for the Velero server, to take PV snapshots
### 1. Install Velero
See documentation on how to install Velero in some specific providers: [Install overview][22]
### 2. Scale deployment down to zero
After you use the `velero install` command to install Velero into your cluster, you scale the Velero deployment down to 0 so it is not simultaneously being run on the remote cluster and potentially causing things to get out of sync:
`kubectl scale --replicas=0 deployment velero -n velero`
#### 3. Start the Velero server locally
* To run the server locally, use the full path according to the binary you need. Example, if you are on a Mac, and using `AWS` as a provider, this is how to run the binary you built from source using the full path: `AWS_SHARED_CREDENTIALS_FILE=<path-to-credentials-file> ./_output/bin/darwin/amd64/velero`. Alternatively, you may add the `velero` binary to your `PATH`.
* Start the server: `velero server [CLI flags]`. The following CLI flags may be useful to customize, but see `velero server --help` for full details:
* `--log-level`: set the Velero server's log level (default `info`, use `debug` for the most logging)
* `--kubeconfig`: set the path to the kubeconfig file the Velero server uses to talk to the Kubernetes apiserver (default `$KUBECONFIG`)
* `--namespace`: the set namespace where the Velero server should look for backups, schedules, restores (default `velero`)
* `--plugin-dir`: set the directory where the Velero server looks for plugins (default `/plugins`)
* `--metrics-address`: set the bind address and port where Prometheus metrics are exposed (default `:8085`)
[15]: https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#the-shared-credentials-file
[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/
[20]: api-types/backupstoragelocation.md
[21]: api-types/volumesnapshotlocation.md
[22]: install-overview/
site/docs/master/start-contributing.md
+21
View File
@@ -0,0 +1,21 @@
## Start contributing
### Before you start
* Please familiarize yourself with the [Code of Conduct][1] before contributing.
* Also, see [CONTRIBUTING.md][2] for instructions on the developer certificate of origin that we require.
### Finding your way around
You may join the Velero community and contribute in many different ways, including helping us design or test new features. For any significant feature we consider adding, we start with a design document. You may find a list of currently in progress new designs here: https://github.com/heptio/velero/pulls?q=is%3Aopen+is%3Apr+label%3ADesign. Feel free to review and help us with your input.
For information on how to connect with our maintainers and community, join our online meetings, or find good first issues, start on our [Velero community](https://velero.io/community/) page.
Please browse our list of resources, including a playlist of past online community meetings, blog posts, and other resources to help you get familiar with our project: [Velero resources](https://velero.io/resources/).
### Contributing
If you are ready to jump in and test, add code, or help with documentation, please use the navigation on the left under `Contribute`.
[1]: https://github.com/heptio/velero/blob/master/CODE_OF_CONDUCT.md
[2]: https://github.com/heptio/velero/blob/master/CONTRIBUTING.md
site/docs/v1.0.0/build-from-source.md
+1 -1
View File
@@ -247,4 +247,4 @@ If you need to add or update the vendored dependencies, see [Vendoring dependenc
[19]: ../examples/README.md
[20]: api-types/backupstoragelocation.md
[21]: api-types/volumesnapshotlocation.md
[22]: https://github.com/heptio/velero/releases
[22]: https://github.com/heptio/velero/releases
site/docs/v1.1.0/README.md
+3 -19
View File
@@ -36,19 +36,7 @@ If you encounter issues, review the [troubleshooting docs][30], [file an issue][
## Contributing
Thanks for taking the time to join our community and start contributing!
Feedback and discussion are available on [the mailing list][24].
### Before you start
* Please familiarize yourself with the [Code of Conduct][8] before contributing.
* See [CONTRIBUTING.md][5] for instructions on the developer certificate of origin that we require.
* Read how [we're using ZenHub][26] for project and roadmap planning
### Pull requests
* We welcome pull requests. Feel free to dig through the [issues][4] and jump in.
If you are ready to jump in and test, add code, or help with documentation, follow the instructions on our [Start contributing](https://velero.io/docs/master/start-contributing/) documentation for guidance on how to setup Velero for development.
## Changelog
@@ -58,10 +46,8 @@ See [the list of releases][6] to find out about feature changes.
[2]: https://travis-ci.org/heptio/velero
[4]: https://github.com/heptio/velero/issues
[5]: https://github.com/heptio/velero/blob/v1.1.0/CONTRIBUTING.md
[6]: https://github.com/heptio/velero/releases
[8]: https://github.com/heptio/velero/blob/v1.1.0/CODE_OF_CONDUCT.md
[9]: https://kubernetes.io/docs/setup/
[10]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos
[11]: https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1
@@ -70,12 +56,10 @@ See [the list of releases][6] to find out about feature changes.
[24]: https://groups.google.com/forum/#!forum/projectvelero
[25]: https://kubernetes.slack.com/messages/velero
[26]: /zenhub.md
[28]: install-overview.md
[29]: https://velero.io/docs/v1.1.0/
[29]: https://velero.io/docs/master/
[30]: troubleshooting.md
[99]: support-matrix.md
[100]: img/velero.png
[100]: img/velero.png
site/docs/v1.1.0/build-from-source.md
+30 -180
View File
@@ -1,12 +1,5 @@
# Build from source
* [Prerequisites][1]
* [Getting the source][2]
* [Build][3]
* [Test][12]
* [Run][7]
* [Vendoring dependencies][10]
## Prerequisites
* Access to a Kubernetes cluster, version 1.7 or later.
@@ -14,7 +7,7 @@
* `kubectl` installed
* [Go][5] installed (minimum version 1.8)
## Getting the source
## Get the source
### Option 1) Get latest (recommended)
@@ -29,73 +22,42 @@ Where `go` is your [import path][4] for Go.
For Go development, it is recommended to add the Go import path (`$HOME/go` in this example) to your path.
### Option 2) Release archive
Download the archive named `Source code` from the [release page][22] and extract it in your Go import path as `src/github.com/heptio/velero`.
Note that the Makefile targets assume building from a git repository. When building from an archive, you will be limited to the `go build` commands described below.
## Build
There are a number of different ways to build `velero` depending on your needs. This section outlines the main possibilities.
To build the `velero` binary on your local machine, compiled for your OS and architecture, run:
When building by using `make`, it will place the binaries under `_output/bin/$GOOS/$GOARCH`. For example, you will find the binary for darwin here: `_output/bin/darwin/amd64/velero`, and the binary for linux here: `_output/bin/linux/amd64/velero`. `make` will also splice version and git commit information in so that `velero version` displays proper output.
Note: `velero install` will also use the version information to determine which tagged image to deploy. If you would like to overwrite what image gets deployed, use the `image` flag (see below for instructions on how to build images).
### Build the binary
To build the `velero` binary on your local machine, compiled for your OS and architecture, run one of these two commands:
```bash
go build ./cmd/velero
```
or:
```bash
make local
```
The latter will place the compiled binary under `$PWD/_output/bin/$GOOS/$GOARCH`, and will splice version and git commit information in so that `velero version` displays proper output. `velero install` will also use the version information to determine which tagged image to deploy.
### Cross compiling
To build the `velero` binary targeting `linux/amd64` within a build container on your local machine, run:
To build the velero binary targeting linux/amd64 within a build container on your local machine, run:
```bash
make build
```
See the **Cross compiling** section below for details on building for alternate OS/architecture combinations.
For any specific platform, run `make build-<GOOS>-<GOARCH>`.
To build a Velero container image, first set the `$REGISTRY` environment variable. For example, if you want to build the `gcr.io/my-registry/velero:master` image, set `$REGISTRY` to `gcr.io/my-registry`. Optionally, set the `$VERSION` environment variable to change the image tag. Then, run:
```bash
make container
```
To push your image to a registry, run:
```bash
make push
```
### Update generated files
The following files are automatically generated from the source code:
* The clientset
* Listers
* Shared informers
* Documentation
* Protobuf/gRPC types
Run `make update` to regenerate files if you make the following changes:
* Add/edit/remove command line flags and/or their help text
* Add/edit/remove commands or subcommands
* Add new API types
Run [generate-proto.sh][13] to regenerate files if you make the following changes:
* Add/edit/remove protobuf message or service definitions. These changes require the [proto compiler][14] and compiler plugin `protoc-gen-go` version v1.0.0.
### Cross compiling
By default, `make build` builds an `velero` binary for `linux-amd64`.
To build for another platform, run `make build-<GOOS>-<GOARCH>`.
For example, to build for the Mac, run `make build-darwin-amd64`.
All binaries are placed in `_output/bin/<GOOS>/<GOARCH>`-- for example, `_output/bin/darwin/amd64/velero`.
Velero's `Makefile` has a convenience target, `all-build`, that builds the following platforms:
@@ -105,146 +67,34 @@ Velero's `Makefile` has a convenience target, `all-build`, that builds the follo
* darwin-amd64
* windows-amd64
## 3. Test
## Making images and updating Velero
To run unit tests, use `make test`. You can also run `make verify` to ensure that all generated
files (clientset, listers, shared informers, docs) are up to date.
## 4. Run
### Prerequisites
When running Velero, you will need to ensure that you set up all of the following:
* Appropriate RBAC permissions in the cluster
* Read access for all data from the source cluster and namespaces
* Write access to the target cluster and namespaces
* Cloud provider credentials
* Read/write access to volumes
* Read/write access to object storage for backup data
* A [BackupStorageLocation][20] object definition for the Velero server
* (Optional) A [VolumeSnapshotLocation][21] object definition for the Velero server, to take PV snapshots
### Create a cluster
To provision a cluster on AWS using Amazon’s official CloudFormation templates, here are two options:
* EC2 [Quick Start for Kubernetes][17]
* eksctl - [a CLI for Amazon EKS][18]
### Option 1: Run your Velero server locally
Running the Velero server locally can speed up iterative development. This eliminates the need to rebuild the Velero server
image and redeploy it to the cluster with each change.
#### 1. Set enviroment variables
Set the appropriate environment variable for your cloud provider:
AWS: [AWS_SHARED_CREDENTIALS_FILE][15]
GCP: [GOOGLE_APPLICATION_CREDENTIALS][16]
Azure:
1. AZURE_CLIENT_ID
2. AZURE_CLIENT_SECRET
3. AZURE_SUBSCRIPTION_ID
4. AZURE_TENANT_ID
5. AZURE_STORAGE_ACCOUNT_ID
6. AZURE_STORAGE_KEY
7. AZURE_RESOURCE_GROUP
#### 2. Create required Velero resources in the cluster
You can use the `velero install` command to install velero into your cluster, then remove the deployment from the cluster, leaving you
with all of the required in-cluster resources.
##### Example
This examples assumes you are using an existing cluster in AWS.
Using the `velero` binary that you've built, run `velero install`:
If after installing Velero you would like to change the image used by its deployment to one that contains your code changes, you may do so by updating the image:
```bash
# velero install requires a credentials file to exist, but we will
# not be using it since we're running the server locally, so just
# create an empty file to pass to the install command.
touch fake-credentials-file
velero install \
--provider aws \
--bucket $BUCKET \
--backup-location-config region=$REGION \
--snapshot-location-config region=$REGION \
--secret-file ./fake-credentials-file
# 'velero install' creates an in-cluster deployment of the
# velero server using an official velero image, but we want
# to run the velero server on our local machine using the
# binary we built, so delete the in-cluster deployment.
kubectl --namespace velero delete deployment velero
rm fake-credentials-file
kubectl -n velero set image deploy/velero velero=myimagerepo/velero:$VERSION
```
#### 3. Start the Velero server locally
To build a Velero container image, first set the `$REGISTRY` environment variable. For example, if you want to build the `gcr.io/my-registry/velero:master` image, set `$REGISTRY` to `gcr.io/my-registry`. If this variable is not set, the default is `gcr.io/heptio-images`.
* Make sure the `velero` binary you build is in your `PATH`, or specify the full path.
Optionally, set the `$VERSION` environment variable to change the image tag. Then, run:
* Start the server: `velero server [CLI flags]`. The following CLI flags may be useful to customize, but see `velero server --help` for full details:
* `--kubeconfig`: set the path to the kubeconfig file the Velero server uses to talk to the Kubernetes apiserver (default `$KUBECONFIG`)
* `--namespace`: the set namespace where the Velero server should look for backups, schedules, restores (default `velero`)
* `--log-level`: set the Velero server's log level (default `info`)
* `--plugin-dir`: set the directory where the Velero server looks for plugins (default `/plugins`)
* `--metrics-address`: set the bind address and port where Prometheus metrics are exposed (default `:8085`)
```bash
make container
```
### Option 2: Run your Velero server in a deployment
To push your image to the registry, run:
1. Ensure you've built a `velero` container image and either loaded it onto your cluster's nodes, or pushed it to a registry (see [build][3]).
```bash
make push
```
1. Install Velero into the cluster (the example below assumes you're using AWS):
Note: if you want to update the image but not change its name, you will have to trigger Kubernetes to pick up the new image. One way of doing so is by deleting the Velero deployment pod:
```bash
velero install \
--provider aws \
--image $YOUR_CONTAINER_IMAGE \
--bucket $BUCKET \
--backup-location-config region=$REGION \
--snapshot-location-config region=$REGION \
--secret-file $YOUR_AWS_CREDENTIALS_FILE
```
```bash
kubectl -n velero delete pods -l deploy=velero
```
## 5. Vendoring dependencies
If you need to add or update the vendored dependencies, see [Vendoring dependencies][11].
[0]: ../README.md
[1]: #prerequisites
[2]: #getting-the-source
[3]: #build
[4]: https://blog.golang.org/organizing-go-code
[5]: https://golang.org/doc/install
[6]: https://github.com/heptio/velero/tree/master/examples
[7]: #run
[8]: config-definition.md
[10]: #vendoring-dependencies
[11]: vendoring-dependencies.md
[12]: #test
[13]: https://github.com/heptio/velero/blob/v1.1.0/hack/generate-proto.sh
[14]: https://grpc.io/docs/quickstart/go.html#install-protocol-buffers-v3
[15]: https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#the-shared-credentials-file
[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
[20]: api-types/backupstoragelocation.md
[21]: api-types/volumesnapshotlocation.md
[22]: https://github.com/heptio/velero/releases
[22]: https://github.com/heptio/velero/releases
site/docs/v1.1.0/development.md
+35
View File
@@ -0,0 +1,35 @@
# Development
## Update generated files
Run `make update` to regenerate files if you make the following changes:
* Add/edit/remove command line flags and/or their help text
* Add/edit/remove commands or subcommands
* Add new API types
Run [generate-proto.sh][13] to regenerate files if you make the following changes:
* Add/edit/remove protobuf message or service definitions. These changes require the [proto compiler][14] and compiler plugin `protoc-gen-go` version v1.0.0.
The following files are automatically generated from the source code:
* The clientset
* Listers
* Shared informers
* Documentation
* Protobuf/gRPC types
You can run `make verify` to ensure that all generated files (clientset, listers, shared informers, docs) are up to date.
## Test
To run unit tests, use `make test`.
## Vendor dependencies
If you need to add or update the vendored dependencies, see [Vendoring dependencies][11].
[11]: vendoring-dependencies.md
[13]: https://github.com/heptio/velero/blob/master/hack/generate-proto.sh
[14]: https://grpc.io/docs/quickstart/go.html#install-protocol-buffers-v3
site/docs/v1.1.0/extend.md
-9
View File
@@ -1,9 +0,0 @@
# Extend Velero
Velero includes mechanisms for extending the core functionality to meet your individual backup/restore needs:
* [Hooks][27] allow you to specify commands to be executed within running pods during a backup. This is useful if you need to run a workload-specific command prior to taking a backup (for example, to flush disk buffers or to freeze a database).
* [Plugins][28] allow you to develop custom object/block storage back-ends or per-item backup/restore actions that can execute arbitrary logic, including modifying the items being backed up/restored. Plugins can be used by Velero without needing to be compiled into the core Velero binary.
[27]: hooks.md
[28]: plugins.md
site/docs/v1.1.0/run-locally.md
+50
View File
@@ -0,0 +1,50 @@
# Run Velero locally in development
Running the Velero server locally can speed up iterative development. This eliminates the need to rebuild the Velero server
image and redeploy it to the cluster with each change.
## Run Velero locally with a remote cluster
Velero runs against the Kubernetes API server as the endpoint (as per the `kubeconfig` configuration), so both the Velero server and client use the same `client-go` to communicate with Kubernetes. This means the Velero server can be run locally just as functionally as if it was running in the remote cluster.
### Prerequisites
When running Velero, you will need to ensure that you set up all of the following:
* Appropriate RBAC permissions in the cluster
* Read access for all data from the source cluster and namespaces
* Write access to the target cluster and namespaces
* Cloud provider credentials
* Read/write access to volumes
* Read/write access to object storage for backup data
* A [BackupStorageLocation][20] object definition for the Velero server
* (Optional) A [VolumeSnapshotLocation][21] object definition for the Velero server, to take PV snapshots
### 1. Install Velero
See documentation on how to install Velero in some specific providers: [Install overview][22]
### 2. Scale deployment down to zero
After you use the `velero install` command to install Velero into your cluster, you scale the Velero deployment down to 0 so it is not simultaneously being run on the remote cluster and potentially causing things to get out of sync:
`kubectl scale --replicas=0 deployment velero -n velero`
#### 3. Start the Velero server locally
* To run the server locally, use the full path according to the binary you need. Example, if you are on a Mac, and using `AWS` as a provider, this is how to run the binary you built from source using the full path: `AWS_SHARED_CREDENTIALS_FILE=<path-to-credentials-file> ./_output/bin/darwin/amd64/velero`. Alternatively, you may add the `velero` binary to your `PATH`.
* Start the server: `velero server [CLI flags]`. The following CLI flags may be useful to customize, but see `velero server --help` for full details:
* `--log-level`: set the Velero server's log level (default `info`, use `debug` for the most logging)
* `--kubeconfig`: set the path to the kubeconfig file the Velero server uses to talk to the Kubernetes apiserver (default `$KUBECONFIG`)
* `--namespace`: the set namespace where the Velero server should look for backups, schedules, restores (default `velero`)
* `--plugin-dir`: set the directory where the Velero server looks for plugins (default `/plugins`)
* `--metrics-address`: set the bind address and port where Prometheus metrics are exposed (default `:8085`)
[15]: https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#the-shared-credentials-file
[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/
[20]: api-types/backupstoragelocation.md
[21]: api-types/volumesnapshotlocation.md
[22]: install-overview/
site/docs/v1.1.0/start-contributing.md
+21
View File
@@ -0,0 +1,21 @@
## Start contributing
### Before you start
* Please familiarize yourself with the [Code of Conduct][1] before contributing.
* Also, see [CONTRIBUTING.md][2] for instructions on the developer certificate of origin that we require.
### Finding your way around
You may join the Velero community and contribute in many different ways, including helping us design or test new features. For any significant feature we consider adding, we start with a design document. You may find a list of currently in progress new designs here: https://github.com/heptio/velero/pulls?q=is%3Aopen+is%3Apr+label%3ADesign. Feel free to review and help us with your input.
For information on how to connect with our maintainers and community, join our online meetings, or find good first issues, start on our [Velero community](https://velero.io/community/) page.
Please browse our list of resources, including a playlist of past online community meetings, blog posts, and other resources to help you get familiar with our project: [Velero resources](https://velero.io/resources/).
### Contributing
If you are ready to jump in and test, add code, or help with documentation, please use the navigation on the left under `Contribute`.
[1]: https://github.com/heptio/velero/blob/master/CODE_OF_CONDUCT.md
[2]: https://github.com/heptio/velero/blob/master/CONTRIBUTING.md
site/img/contributors/carlisia-campos.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 380 KiB

After

Width:  |  Height:  |  Size: 607 KiB