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

Cleanup of CLI commands and flags

Browse Source 
Signed-off-by: Carlisia <carlisia@vmware.com>
This commit is contained in:
Carlisia
2020-02-04 12:20:10 -08:00
parent b2bdb562d2
commit 418f831d18
1 changed files with 194 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -6,13 +6,13 @@ This proposal prioritizes discoverability and self-documentation over minimalizi
## Goals
- Split flags currently under the `velero install` command into multiple commands
- Groups flags under commands in a way that allows a good level of discovery and self-documentation
- Rename commands and flags as needed
- Split flags currently under the `velero install` command into multiple commands, and group flags under commands in a way that allows a good level of discovery and self-documentation
- Maintain compatibility with gitops practices (i.e. ability to generate a full set of yaml for install that can be stored in source control)
- Have a clear path for deprecating commands
## Non Goals
- Introduce new CLI features (new commands for existing functionality ok)
- Introduce new CLI features
- Propose changes to the CLI that go beyond the functionality of install and configure
- Optimize for shorter length or number of commands/flags
@@ -24,120 +24,248 @@ Also, the `install` command currently can be reused to update Velero configurati
## High-Level Design
<!-- One to two paragraphs that describe the high level changes that will be made to implement this proposal. -->
The naming and organization of the proposed new CLI commands below have been inspired on the `kubectl` commands, particularly `kubectl set` and `kubectl config`.
#### Grouping commands
#### Commands
Below is the proposed set of new commands to install and configure Velero.
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.
Below is the proposed set of new commands to setup and configure Velero.
1) `velero init`
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. Mostly things to be run once at setup time. Could be named something else, like `install`.
These ones might make sense to include under all the other commands
```
--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.
-h, --help help for install
--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.
--wait wait for Velero deployment to be ready. Optional.
--show-labels show labels in the last column
```
Minimum set for initialization
```
--image string image to use for the Velero and restic server pods. Optional. (default "velero/velero:latest")
--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
```
2) `velero set`
All the other configuration that is not component specific nor necessary for initialization. Mostly things to be updated. Might be grouped under `init`.
```
--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")
```
3) `velero config`
Component specific configuration for both backup and snapshot locations.
Much like `kubectl config` is about clusters and context, so does this `velero config` should be only about the backup/snapshot locations.
--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)
```
--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.
--backup-location mapStringString configuration to use for creating a backup storage location. Format is key1=value1,key2=value2 (was `backup-location-config`)
--get-backup-locations Display backup storage locations
--current-backup-location displays the current default backup storage location (NEW)
--use-backup-location string sets the default backup storage location (default "default") (was `default-backup-storage-location`)
2) `velero backup-location`
Commands/flags for backup locations.
--snapshot-location mapStringString configuration to use for creating a volume snapshot location. Format is key1=value1,key2=value2 (was `snapshot-location-config`)
--get-snapshot-locations Display snapshot locations
--current-snapshot-locations displays the current default volume snapshot locations (NEW)
--use-snapshot-locations mapStringString sets the list of unique volume providers and default volume snapshot location (provider1:location-01,provider2:location-02,...) (was `default-volume-snapshot-locations`)
```
set
--default string sets the default backup storage location (default "default") (NEW, -- was `server --default-backup-storage-location)
--set-default-location configuration to create a default locations. Format is bucket=value,prefix=value,plugin-name=value,snapshot-location=true/false. Optional.
create
--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
--provider string provider name for backup and volume storage - (DEPRECATED)
--no-default-backup-location flag indicating if a default backup location should be created. Must be used as confirmation if --bucket or --provider are not provided. Optional. (DEPRECATED)
--use-volume-snapshots whether or not to create snapshot location automatically. Set to false if you do not plan to create volume snapshots via a storage provider. (default true) (DEPRECATED)
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
```
3) `velero snapshot-location`
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)
create
--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`))
```
4) `velero plugin`
Component specific configuration for plugins.
Configuration for plugins.
```
--add stringArray Add plugin container images to install into the Velero Deployment
--list Get information for all plugins on the velero server (was `get`)
--remove Remove a plugin
--plugin-dir string directory containing Velero plugins (default "/plugins")
add
--images stringArray 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
--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
```
5) `velero restic`
Component specific configuration for restic operations.
Configuration for restic operations.
```
set
--default-prune-frequency duration how often 'restic prune' is run for restic repositories by default. Optional.
--pod-annotations mapStringString annotations to add to the Velero and restic pods. Optional. Format is key1=value1,key2=value2
--pod-cpu-limit string CPU limit for restic pod. A value of "0" is treated as unbounded. Optional. (default "0")
--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")
--create create restic deployment. Optional. (was `use-restic`)
--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
--restic-timeout duration how long backups/restores of pod volumes should be allowed to run before timing out (default 1h0m0s)
--timeout duration how long backups/restores of pod volumes should be allowed to run before timing out (default 1h0m0s)
```
#### Example
Considering this proposal, let's exemplify what a high-level documentation for getting Velero ready to do backups could look like for two types of Velero users, in a very recipe-like manner:
##### Administrator
Considering this proposal, let's consider what a high-level documentation for getting Velero ready to do backups could look like for Velero users:
After installing the Velero CLI:
```
velero init ... (required setup)
velero set ... (optional setup)
velero plugin ... (add/manage provider connectors)
velero config ... (run `velero plugin --list` to see what you can use to configure locations; configure locations)
```
##### Operator
```
velero plugin ... Optional. (manage list of provider connectors as needed)
velero config ... Optional. (run `velero config --get-backup-locations` to see available backup locations or `velero config --current-backup-location`; then run `velero plugin --list` to see what providers you can use if you need to configure new locations; configure locations)
velero backup/restore/schedule create/get/delete <NAME> ...
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>...
```
The above recipe-style documentation should highlight 1) the main components of Velero, and, 2) the relationship/dependency between the main components
### Deprecation
#### Timeline
In order to maintain compatibility with the current Velero version for a sufficient amount of time, and give users a chance to upgrade any install scripts they might have, we will keep the current `velero install` command in parallel with the new commands until the next major Velero version, which will be Velero 2.0. In the mean time, ia deprecation warning will be added to the `velero install` command.
#### Commands/flags deprecated or moved
##### Velero Install
`velero install (DEPRECATED)`
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
--velero-pod-cpu-limit string CPU limit for Velero pod. A value of "0" is treated as unbounded. Optional. (default "1000m")
--velero-pod-cpu-request string CPU request for Velero pod. A value of "0" is treated as unbounded. Optional. (default "500m")
--velero-pod-mem-limit string memory limit for Velero pod. A value of "0" is treated as unbounded. Optional. (default "256Mi")
--velero-pod-mem-request string memory request for Velero pod. A value of "0" is treated as unbounded. Optional. (default "128Mi")
```
Flags to delete:
```
--no-default-backup-location flag indicating if a default backup location should be created. Must be used as confirmation if --bucket or --provider are not provided. Optional.
--use-volume-snapshots whether or not to create snapshot location automatically. Set to false if you do not plan to create volume snapshots via a storage provider. (default true)
--wait wait for Velero deployment to be ready. Optional.
```
Flags moved to...
...`backup-location create`
```
--backup-location-config mapStringString configuration to use for the backup storage location. Format is key1=value1,key2=value2
--bucket string name of the object storage bucket where backups should be stored
--prefix string prefix under which all Velero data should be stored within the bucket. Optional.
```
...`snapshot-location create`
```
--snapshot-location-config mapStringString configuration to use for the volume snapshot location. Format is key1=value1,key2=value2
```
...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.
```
...`restic`
```
--default-restic-prune-frequency duration how often 'restic prune' is run for restic repositories by default. Optional.
--restic-pod-cpu-limit string CPU limit for restic pod. A value of "0" is treated as unbounded. Optional. (default "0")
--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
```
##### Velero Server
`velero server (DEPRECATED)`
`velero server --default-backup-storage-location (DEPRECATED)` moved to `velero backup-location set --default`
`velero server --default-volume-snapshot-locations (DEPRECATED)` moved to `velero snapshot-location set --default`
`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`
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.
- Capitalize all help messages
## Detailed Design
A detailed design describing how the changes to the product should be made.