From c03f75c895562393c6ad51cc7d3e9241e391fdb1 Mon Sep 17 00:00:00 2001 From: Swapnil Mhamane Date: Wed, 31 Jul 2019 23:03:29 +0530 Subject: [PATCH] Apply suggestions from code review Co-Authored-By: Shreyas Rao <42259948+shreyas-s-rao@users.noreply.github.com> --- .ci/integration_test | 4 ++-- README.md | 8 ++++---- doc/development/local_setup.md | 18 +++++++++--------- doc/development/testing_and_dependencies.md | 9 ++++----- doc/usage/getting_started.md | 11 ++++++----- 5 files changed, 25 insertions(+), 25 deletions(-) diff --git a/.ci/integration_test b/.ci/integration_test index f899a7747..d6b6dc0c7 100755 --- a/.ci/integration_test +++ b/.ci/integration_test @@ -27,7 +27,7 @@ VCS="github.com" ORGANIZATION="gardener" PROJECT="etcd-backup-restore" REPOSITORY=${VCS}/${ORGANIZATION}/${PROJECT} -VERSION_FILE="$(readlink -f "${SOURCE_PATH}/VERSION")" + VERSION_FILE="$(readlink -f "${SOURCE_PATH}/VERSION")" VERSION="$(cat "${VERSION_FILE}")" export GOBIN="${SOURCE_PATH}/bin" @@ -199,4 +199,4 @@ echo "Deleting test enviornment..." cleanup_test_environment echo "Successfully completed all tests." -exit $TEST_RESULT \ No newline at end of file +exit $TEST_RESULT diff --git a/README.md b/README.md index 8bc2ca93b..b7cf51f4d 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,13 @@ Etcd-backup-restore is collection of components to backup and restore the [etcd] ### Design and Proposals * [Core design](doc/proposals/design.md) -* [Etcd data Validation ](doc/proposals/validation.md) -* [High watch events ingress rate issue](doc.proposals/high_watch_event_ingress_rate.md) +* [Etcd data validation ](doc/proposals/validation.md) +* [High watch events ingress rate issue](doc/proposals/high_watch_event_ingress_rate.md) ### Development -* [Setting up a local development environment](doc.development/local_setup.md) -* [Testing and Dependency Management](doc.development/testing_and_dependencies.md) +* [Setting up a local development environment](doc/development/local_setup.md) +* [Testing and Dependency Management](doc/development/testing_and_dependencies.md) * [Adding support for a new cloud provider](doc/development/new_cp_support.md) diff --git a/doc/development/local_setup.md b/doc/development/local_setup.md index 8caa5cc54..6d139a58e 100644 --- a/doc/development/local_setup.md +++ b/doc/development/local_setup.md @@ -1,20 +1,20 @@ ## Prerequisites -Although the following installation instructions are for Mac OS X, similar alternate commands could be found for any Linux distribution +Although the following installation instructions are for Mac OS X, similar alternate commands can be found for any Linux distribution. ### Installing [Golang](https://golang.org/) environment -Install the latest version of Golang (at least `v1.12` is required). For Mac OS, you could use [Homebrew](https://brew.sh/): +Install the latest version of Golang (at least `v1.12` is required). For Mac OS, you may use [Homebrew](https://brew.sh/): ```sh brew install golang ``` -For other OS, please check [Go installation documentation](https://golang.org/doc/install). +For other OSes, please check [Go installation documentation](https://golang.org/doc/install). Make sure to set your `$GOPATH` environment variable properly (conventionally, it points to `$HOME/go`). -For your convenience, you can add the `bin` directory of the `$GOPATH` to your `$PATH`: `PATH=$PATH:$GOPATH/bin`, but it is not necessarily required. +For your convenience, you can add the `bin` directory of the `$GOPATH` to your `$PATH`: `PATH=$PATH:$GOPATH/bin`, but it is not mandatory. ### [Golint](https://github.com/golang/lint) @@ -45,12 +45,11 @@ brew install git ### Installing `gcloud` SDK (Optional) -In case you have to create a new release or a new hotfix, you have to push the resulting Docker image into a Docker registry. Currently, we are using the Google Container Registry (this could change in the future). Please follow the official [installation instructions from Google](https://cloud.google.com/sdk/downloads). - +In case you have to create a new release or a new hotfix, you have to push the resulting Docker image into a Docker registry. Currently, we use the Google Container Registry (this could change in the future). Please follow the official [installation instructions from Google](https://cloud.google.com/sdk/downloads). ## Build -Currently there are no binary build available, but it is pretty straight forward to build it by following the steps mentioned below. +Currently there are no binary builds available, but it is fairly simple to build it by following the steps mentioned below. * First, you need to create a target folder structure before cloning and building `etcdbrctl`. @@ -65,12 +64,13 @@ Currently there are no binary build available, but it is pretty straight forward make build-local ``` -* Next you can make it available to use as shell command by moving the executable to `/usr/local/bin`. +* Next you can make it available to use as shell command by moving the executable to `/usr/local/bin`, or by optionally including the `bin` directory in your `$PATH` environment variable. You can verify the installation by running following command: + ```console $ etcdbrctl -v INFO[0000] etcd-backup-restore Version: v0.7.0-dev INFO[0000] Git SHA: 38979f0 INFO[0000] Go Version: go1.12 INFO[0000] Go OS/Arch: darwin/amd64 - ``` \ No newline at end of file + ``` diff --git a/doc/development/testing_and_dependencies.md b/doc/development/testing_and_dependencies.md index aca981665..022fe6cad 100644 --- a/doc/development/testing_and_dependencies.md +++ b/doc/development/testing_and_dependencies.md @@ -1,12 +1,11 @@ # Dependency management -We use golang modules to manage golang dependencies. In order to add a new package dependency to the project, you can perform `go get @` or edit the `go.mod` file and append the package along with the version you want to use. +We use go-modules to manage golang dependencies. In order to add a new package dependency to the project, you can perform `go get @` or edit the `go.mod` file and append the package along with the version you want to use. ### Updating dependencies The `Makefile` contains a rule called `revendor` which performs `go mod vendor` and `go mod tidy`. -* `go mod vendor` resets the main module's vendor directory to include all packages needed to build and test all the main module's packages. It does not include test code for vendored packages. -It does not include test code for vendored packages. +* `go mod vendor` resets the main module's vendor directory to include all packages needed to build and test all the main module's packages. * `go mod tidy` makes sure go.mod matches the source code in the module. It adds any missing modules necessary to build the current module's packages and dependencies, and it removes unused modules that @@ -22,10 +21,10 @@ The dependencies are installed into the `vendor` folder which **should be added* # Testing -We have created `make` target `verify` which will internally run different rule like `fmt` for formatting, `lint` for linting check and most importantly `test` which will check the code against predefined unit tests. Although, currently there are not enough test cases written to cover entire code, hence one should check for failure cases manually before raising pull request. We will eventually add the test cases for complete code coverage. +We have created `make` target `verify` which will internally run different rules like `fmt` for formatting, `lint` for linting check and most importantly `test` which will check the code against predefined unit tests. As currently there aren't enough test cases written to cover the entire code, you must check for failure cases manually and include test cases before raising pull request. We will eventually add more test cases for complete code coverage. ```sh make verify ``` -By default, we try to run test in parallel without computing code coverage. To get the code coverage, you will have to set environment variable `COVER` to `true`. This will log the code coverage percentage at the end of test logs. Also, all cover profile files will accumulated under `test/output/coverprofile.out` directory. You can visualize exact code coverage using `make show-coverage`. +By default, we run tests without computing code coverage. To get the code coverage, you can set the environment variable `COVER` to `true`. This will log the code coverage percentage at the end of test logs. Also, all cover profile files will be accumulated under `test/output/coverprofile.out` directory. You can visualize the exact code coverage by running `make show-coverage` after running `make verify` with code coverage enabled. diff --git a/doc/usage/getting_started.md b/doc/usage/getting_started.md index cead71c71..94647572d 100644 --- a/doc/usage/getting_started.md +++ b/doc/usage/getting_started.md @@ -4,7 +4,7 @@ Currently we don't publish the binary build with the release, but it is pretty s ## Usage -You can follow the `help` flag on `etcdbrctl` command and its sub-commands to know the usage details. Some of the common use cases are mentioned below. Although examples below uses AWS S3 as storage provider, we have added support for AWS, GCS, Azure, Openstack swift and Alicloud OSS object store. It also supports local disk as storage provider. +You can follow the `help` flag on `etcdbrctl` command and its sub-commands to know the usage details. Some of the common use cases are mentioned below. Although examples below use AWS S3 as storage provider, etcd-backup-restore supports AWS, GCS, Azure, Openstack swift and Alicloud OSS object store. It also supports local disk as storage provider for development purposes, but it is not recommended to use this in a production environment. ### Cloud Provider Credentials @@ -22,13 +22,14 @@ The procedure to provide credentials to access the cloud provider object store v ### Taking scheduled snapshot -`etcd` should already be running. One can apply standard cron format scheduling for regular backup of etcd. The cron schedule is used to take full backups. The delta snapshots are taken at regular intervals in the period in between full snapshots as indicated by the `delta-snapshot-period-seconds` flag. The default for the same is 10 seconds. +Sub-command `snapshot` takes scheduled backups, or `snapshots` of a running `etcd` cluster, which are pushed to one of the storage providers specified above (please note that `etcd` should already be running). One can apply standard cron format scheduling for regular backup of etcd. The cron schedule is used to take full backups. The delta snapshots are taken at regular intervals in the period in between full snapshots as indicated by the `delta-snapshot-period-seconds` flag. The default for the same is 10 seconds. + +etcd-backup-restore has two garbage collection policies to clean up existing backups from the cloud bucket. The flag `garbage-collection-policy` is used to indicate the desired garbage collection policy. -etcd-backup-restore has two garbage collection policies to collect existing backups from the cloud bucket. The flag `garbage-collection-policy` is used to indicate the correct garbage collection policy. 1. `Exponential` 1. `LimitBased` -If using `LimitBased` policy, the `max-backups` flag should be provided to indicate the number of recent backups to persist at each garbage collection cycle. +If using `LimitBased` policy, the `max-backups` flag should be provided to indicate the number of recent-most backups to persist at each garbage collection cycle. ```console $ ./bin/etcdbrctl snapshot --storage-provider="S3" --etcd-endpoints http://localhost:2379 --schedule "*/1 * * * *" --store-container="etcd-backup" --delta-snapshot-period-seconds=10 --max-backups=10 --garbage-collection-policy='LimitBased' @@ -86,4 +87,4 @@ INFO[0000] Successfully restored the etcd data directory. ### Etcdbrctl server -With sub-command `server` you can start a http server which exposes an endpoint to initialize etcd over REST interface. The server also keeps on backup schedule thread running to have periodic backups. This is mainly made available to manage an etcd instance running in a Kubernetes cluster. You can deploy the example [helm chart](../../chart/etcd-backup-restore) on a Kubernetes cluster to have an fault resilient etcd instance. +With sub-command `server` you can start a http server which exposes an endpoint to initialize etcd over REST interface. The server also keeps the backup schedule thread running to keep taking periodic backups. This is mainly made available to manage an etcd instance running in a Kubernetes cluster. You can deploy the example [helm chart](../../chart/etcd-backup-restore) on a Kubernetes cluster to have a fault-resilient, self-healing etcd cluster.