mirrors/velero
1
0
Fork 0
mirror of https://github.com/vmware-tanzu/velero.git synced 2025-12-23 06:15:21 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Address code reviews

Browse Source 
Signed-off-by: Carlisia <carlisia@vmware.com>
This commit is contained in:
Carlisia
2020-03-11 08:31:11 -07:00
parent 2b614e7e3a
commit dafc1abd94
1 changed files with 57 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
design/cli-install-changes.md
View File

@@ -20,7 +20,7 @@ This proposal prioritizes discoverability and self-documentation over minimalizi
This document proposes users could benefit from a more intuitive and self-documenting CLI setup as compared to our existing CLI UX. Ultimately, it is proposed that a recipe-style CLI flow for installation, configuration and use would greatly contribute to this purpose.
Also, the `install` command currently can be reused to update Velero configurations, a behavior more appropriate for a command named `config`.
Also, the `install` command currently can be reused to update Velero configurations, a behavior more appropriate for a commands named something other than`install`.
## High-Level Design
@@ -34,72 +34,64 @@ The organization of the commands follows this format:
velero [resource] [operation] [flags]
```
To conform with Velero's current practice, these commands will also work by swapping the operation/resource.
To conform with Velero's current practice:
- commands will also work by swapping the operation/resource.
- the "object" of a command is an argument, and flags are strictly for modifiers (example: `backup get my-backup` and not `backup get --name my-backup`)
Below is the proposed set of new commands to setup and configure Velero.
1) `velero init`
1) `velero`
```
--server Configures up the namespace, RBAC, deployment, etc., but does not add any external plugins, BSL/VSL definitions. This would be the minimum set of commands to get the Velero server up and running and ready to accept other configurations.
--dry-run generate resources, but don't send them to the cluster. Use with -o. Optional.
--label-columns stringArray a comma-separated list of labels to be displayed as columns
-o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are 'table', 'json', and 'yaml'. 'table' is not valid for the install command.
--show-labels show labels in the last column
--image string image to use for the Velero and restic server pods. Optional. (default "velero/velero:latest")
--pod-annotations mapStringString annotations to add to the Velero and restic pods. Optional. Format is key1=value1,key2=value2
--restore-only run the server in restore-only mode. Optional.
--pod-cpu-limit string CPU limit for Velero pod. A value of "0" is treated as unbounded. Optional. (default "1000m")
--pod-cpu-request string CPU request for Velero pod. A value of "0" is treated as unbounded. Optional. (default "500m")
--pod-mem-limit string memory limit for Velero pod. A value of "0" is treated as unbounded. Optional. (default "256Mi")
--pod-mem-request string memory request for Velero pod. A value of "0" is treated as unbounded. Optional. (default "128Mi")
--client-burst int maximum number of requests by the server to the Kubernetes API in a short period of time (default 30)
--client-qps float32 maximum number of requests per second by the server to the Kubernetes API once the burst limit has been reached (default 20)
--default-backup-ttl duration how long to wait by default before backups can be garbage collected (default 720h0m0s)
--disable-controllers strings list of controllers to disable on startup. Valid values are backup,backup-sync,schedule,gc,backup-deletion,restore,download-request,restic-repo,server-status-request
-h, --help help for server
--log-format the format for log output. Valid values are text, json. (default text)
--log-level the level at which to log. Valid values are debug, info, warning, error, fatal, panic. (default info)
--metrics-address string the address to expose prometheus metrics (default ":8085")
--plugin-dir string directory containing Velero plugins (default "/plugins")
--profiler-address string the address to expose the pprof profiler (default "localhost:6060")
--restore-only run in a mode where only restores are allowed; backups, schedules, and garbage-collection are all disabled. DEPRECATED: this flag will be removed in v2.0. Use read-only backup storage locations instead.
--restore-resource-priorities strings desired order of resource restores; any resource not in the list will be restored alphabetically after the prioritized resources (default [namespaces,storageclasses,persistentvolumes,persistentvolumeclaims,secrets,configmaps,serviceaccounts,limitranges,pods,replicaset,customresourcedefinitions])
--terminating-resource-timeout duration how long to wait on persistent volumes and namespaces to terminate during a restore before timing out (default 10m0s)
init Configure up the namespace, RBAC, deployment, etc., but does not add any external plugins, BSL/VSL definitions. This would be the minimum set of commands to get the Velero server up and running and ready to accept other configurations.
--dry-run generate resources, but don't send them to the cluster. Use with -o. Optional.
--label-columns stringArray a comma-separated list of labels to be displayed as columns
--show-labels show labels in the last column
--image string image to use for the Velero and restic server pods. Optional. (default "velero/velero:latest")
--pod-annotations mapStringString annotations to add to the Velero and restic pods. Optional. Format is key1=value1,key2=value2
--restore-only run the server in restore-only mode. Optional.
--pod-cpu-limit string CPU limit for Velero pod. A value of "0" is treated as unbounded. Optional. (default "1000m")
--pod-cpu-request string CPU request for Velero pod. A value of "0" is treated as unbounded. Optional. (default "500m")
--pod-mem-limit string memory limit for Velero pod. A value of "0" is treated as unbounded. Optional. (default "256Mi")
--pod-mem-request string memory request for Velero pod. A value of "0" is treated as unbounded. Optional. (default "128Mi")
--client-burst int maximum number of requests by the server to the Kubernetes API in a short period of time (default 30)
--client-qps float32 maximum number of requests per second by the server to the Kubernetes API once the burst limit has been reached (default 20)
--default-backup-ttl duration how long to wait by default before backups can be garbage collected (default 720h0m0s)
--disable-controllers strings list of controllers to disable on startup. Valid values are backup,backup-sync,schedule,gc,backup-deletion,restore,download-request,restic-repo,server-status-request
--log-format the format for log output. Valid values are text, json. (default text)
--log-level the level at which to log. Valid values are debug, info, warning, error, fatal, panic. (default info)
--metrics-address string the address to expose prometheus metrics (default ":8085")
--plugin-dir string directory containing Velero plugins (default "/plugins")
--profiler-address string the address to expose the pprof profiler (default "localhost:6060")
--restore-only run in a mode where only restores are allowed; backups, schedules, and garbage-collection are all disabled. DEPRECATED: this flag will be removed in v2.0. Use read-only backup storage locations instead.
--restore-resource-priorities strings desired order of resource restores; any resource not in the list will be restored alphabetically after the prioritized resources (default [namespaces,storageclasses,persistentvolumes,persistentvolumeclaims,secrets,configmaps,serviceaccounts,limitranges,pods,replicaset,customresourcedefinitions])
--terminating-resource-timeout duration how long to wait on persistent volumes and namespaces to terminate during a restore before timing out (default 10m0s)
```
2) `velero backup-location`
Commands/flags for backup locations.
Commands/flags for backup locations.
```
set
--default string sets the default backup storage location (default "default") (NEW, -- was `server --default-backup-storage-location)
set
--default string sets the default backup storage location (default "default") (NEW, -- was `server --default-backup-storage-location; could be set as an annotation on the BSL)
create
create NAME [flags]
--dry-run generate resources, but don't send them to the cluster. Use with -o. Optional. (NEW)
--default Sets this new location to be the new default backup location. Default is false. (NEW)
--secret-file string file containing credentials for backup provider. If not specified, set --no-secret must be used for confirmation. Optional. (MOVED FROM install)
--no-secret flag indicating if a secret should be created. Must be used as confirmation if create --secret-file is not provided. Optional. (MOVED FROM install)
--access-mode access mode for the backup storage location. Valid values are ReadWrite,ReadOnly (default ReadWrite)
--backup-sync-period 0s how often to ensure all Velero backups in object storage exist as Backup API objects in the cluster. Optional. Set this to 0s to disable sync
--bucket string name of the object storage bucket where backups should be stored. Required.
--config mapStringString configuration to use for creating a backup storage location. Format is key1=value1,key2=value2 (was also in `velero install --backup-location-config`). Required for Azure.
--provider string provider name for backup storage. Required.
-h, --help help for create
--label-columns stringArray a comma-separated list of labels to be displayed as columns
--labels mapStringString labels to apply to the backup storage location
-o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are 'table', 'json', and 'yaml'. 'table' is not valid for the install command.
--prefix string prefix under which all Velero data should be stored within the bucket. Optional.
--provider string name of the backup storage provider (e.g. aws, azure, gcp)
--show-labels show labels in the last column
get Display backup storage locations
--default displays the current default backup storage location (NEW)
-h, --help help for get
--label-columns stringArray a comma-separated list of labels to be displayed as columns
-o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are 'table', 'json', and 'yaml'. 'table' is not valid for the install command. (default "table")
-l, --selector string only show items matching this label selector
--show-labels show labels in the last column
@@ -110,23 +102,18 @@ Commands/flags for snapshot locations.
```
set
--default mapStringString sets the list of unique volume providers and default volume snapshot location (provider1:location-01,provider2:location-02,...) (NEW, -- was `server --efault-volume-snapshot-locations)
--default mapStringString sets the list of unique volume providers and default volume snapshot location (provider1:location-01,provider2:location-02,...) (NEW, -- was `server --efault-volume-snapshot-locations; could be set as an annotation on the VSL)
create
create NAME [flags]
--dry-run generate resources, but don't send them to the cluster. Use with -o. Optional. (NEW)
--default Sets these new locations to be the new default snapshot locations. Default is false. (NEW)
--secret-file string file containing credentials for volume provider. If not specified, set --no-secret must be used for confirmation. Optional. (MOVED FROM install)
--no-secret flag indicating if a secret should be created. Must be used as confirmation if create --secret-file is not provided. Optional. (MOVED FROM install)
--config mapStringString configuration to use for creating a volume snapshot location. Format is key1=value1,key2=value2 (was also in `velero install --`snapshot-location-config`). Required.
--provider string provider name for volume storage. Required.
-h, --help help for create
--label-columns stringArray a comma-separated list of labels to be displayed as columns
--labels mapStringString labels to apply to the volume snapshot location
-o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are 'table', 'json', and 'yaml'. 'table' is not valid for the install command.
--provider string name of the volume snapshot provider (e.g. aws, azure, gcp)
--show-labels show labels in the last column
get Display snapshot locations
--default list of unique volume providers and default volume snapshot location (provider1:location-01,provider2:location-02,...) (NEW -- was `server --default-volume-snapshot-locations`))
```
@@ -135,15 +122,16 @@ Commands/flags for snapshot locations.
Configuration for plugins.
```
add
--images stringArray add plugin container images to install into the Velero Deployment
add stringArray IMAGES [flags] - add plugin container images to install into the Velero Deployment
get get information for all plugins on the velero server (was `get`)
-h, --help help for get
-o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are 'table', 'json', and 'yaml'. 'table' is not valid for the install command. (default "table")
--timeout duration maximum time to wait for plugin information to be reported (default 5s)
remove Remove a plugin [NAME | IMAGE]
set
--secret-file string file containing credentials for plugin provider. If not specified, set --no-secret must be used for confirmation. Optional (MOVED FROM install). [NOTE]: we currently only support a single secret per provider
--no-secret flag indicating if a secret should be created. Must be used as confirmation if create --secret-file is not provided. Optional. (MOVED FROM install)
--sa-annotations mapStringString annotations to add to the Velero ServiceAccount for GKE. Add iam.gke.io/gcp-service-account=[GSA_NAME]@[PROJECT_NAME].iam.gserviceaccount.com for workload identity. Optional. Format is key1=value1,key2=value2
```
@@ -158,9 +146,11 @@ Configuration for restic operations.
--pod-cpu-request string CPU request for restic pod. A value of "0" is treated as unbounded. Optional. (default "0")
--pod-mem-limit string memory limit for restic pod. A value of "0" is treated as unbounded. Optional. (default "0")
--pod-mem-request string memory request for restic pod. A value of "0" is treated as unbounded. Optional. (default "0")
--deployment create restic deployment. Defauylt is false. Optional. Other lags will only work if set to true. (NEW, was `velero install use-restic`)
--repo Work with restic repositories
--deployment create restic deployment. Default is false. Optional. Other flags will only work if set to true. (NEW, was `velero install use-restic`)
--timeout duration how long backups/restores of pod volumes should be allowed to run before timing out (default 1h0m0s)
repo
get Get restic repositories
```
#### Example
@@ -169,10 +159,11 @@ Considering this proposal, let's consider what a high-level documentation for ge
After installing the Velero CLI:
```
velero init --server... (required setup)
velero plugin add --images <NAME/CONTAINER>... (add/config provider plugins)
velero backup-location/snapshot-location create <NAME>... (run `velero plugin --get` to see what kind of plugins are available; create locations)
velero backup/restore/schedule create/get/delete <NAME>...
velero init [flags] (required)
velero plugin add IMAGES [flags] (add/config provider plugins)
velero backup-location/snapshot-location create NAME [flags] (run `velero plugin --get` to see what kind of plugins are available; create locations)
velero backup/restore/schedule create/get/delete NAME [flags]
velero restic
```
The above recipe-style documentation should highlight 1) the main components of Velero, and, 2) the relationship/dependency between the main components
@@ -193,7 +184,6 @@ Flags moved to `velero init`:
--dry-run generate resources, but don't send them to the cluster. Use with -o. Optional.
--image string image to use for the Velero and restic server pods. Optional. (default "velero/velero:latest")
--label-columns stringArray a comma-separated list of labels to be displayed as columns
-o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are 'table', 'json', and 'yaml'. 'table' is not valid for the install command.
--pod-annotations mapStringString annotations to add to the Velero and restic pods. Optional. Format is key1=value1,key2=value2
--restore-only run the server in restore-only mode. Optional.
--show-labels show labels in the last column
@@ -228,8 +218,6 @@ Flags moved to...
...both `backup-location create` and `snapshot-location create`
```
--provider string provider name for backup and volume storage
--no-secret flag indicating if a secret should be created. Must be used as confirmation if --secret-file is not provided. Optional.
--secret-file string file containing credentials for backup and volume provider. If not specified, --no-secret must be used for confirmation. Optional.
--dry-run generate resources, but don't send them to the cluster. Use with -o. Optional.
```
@@ -240,17 +228,18 @@ Flags moved to...
--restic-pod-cpu-request string CPU request for restic pod. A value of "0" is treated as unbounded. Optional. (default "0")
--restic-pod-mem-limit string memory limit for restic pod. A value of "0" is treated as unbounded. Optional. (default "0")
--restic-pod-mem-request string memory request for restic pod. A value of "0" is treated as unbounded. Optional. (default "0")
--use-restic create restic deployment. Optional.
```
...`plugin`
```
```
--plugins stringArray Plugin container images to install into the Velero Deployment
--sa-annotations mapStringString annotations to add to the Velero ServiceAccount. Add iam.gke.io/gcp-service-account=[GSA_NAME]@[PROJECT_NAME].iam.gserviceaccount.com for workload identity. Optional. Format is key1=value1,key2=value2
--no-secret flag indicating if a secret should be created. Must be used as confirmation if --secret-file is not provided. Optional.
--secret-file string file containing credentials for backup and volume provider. If not specified, --no-secret must be used for confirmation. Optional.
```
##### Velero Server
`velero server (DEPRECATED)`
`velero server (RENAMED init)`
`velero server --default-backup-storage-location (DEPRECATED)` moved to `velero backup-location set --default`
@@ -258,14 +247,16 @@ Flags moved to...
`velero server --default-restic-prune-frequency (DEPRECATED)` moved to `velero restic set --default-prune-frequency`
`velero server --restic-timeout DEPRECATED)` moved to `velero restic set timeout`
`velero server --restic-timeout (DEPRECATED)` moved to `velero restic set timeout`
`velero server --use-restic (DEPRECATED)` see `velero init restic`
All other `velero server` flags moved to under `velero init`.
## General CLI improvements
- Go over all flags and document what is optional, what is required, and default values.
These are improvements that are part of this proposal:
- Go over all flags and document what is optional, what is required, and default values.å
- Capitalize all help messages
## Detailed Design