# Proposal for a more intuitive CLI to install and configure Velero
Currently, the Velero CLI tool has a `install` command that configures numerous major and minor aspects of Velero. As a result, the combined set of flags for this `install` command makes it hard to intuit and reason about the different Velero components. This document proposes changes to improve the UX for installation and configuration in a way that would make it easier for the user to discover what needs to be configured by looking at what is available in the CLI rather then having to rely heavily on our documentation for the usage. At the same time, it is expected that the documentation update to reflect these changes will also make the documentation flow easier to follow.
- 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)
- Propose changes to the CLI that go beyond the functionality of install and configure
- Optimize for shorter length or number of commands/flags
## Background
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 deployment configurations. For server and restic related install and configurations, settings will be moved to under `velero config`.
The naming and organization of the proposed new CLI commands below have been inspired on the `kubectl` commands, particularly `kubectl set` and `kubectl config`.
- 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`)
All commands will include the `--dry-run` flag, which can be used to output yaml files containing the commands' configuration for resource creation or patching.
`--dry-run generate resources, but don't send them to the cluster. Use with -o. Optional.`
The `--help` and `--output` flags will also be included for all commands, omitted below for brevity.
server 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.
--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")
--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)
--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)
--default Sets this new location to be the new default backup location. Default is false. (NEW)
--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.
--label-columns stringArray a comma-separated list of labels to be displayed as columns
--labels mapStringString labels to apply to the backup storage location
--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)
--label-columns stringArray a comma-separated list of labels to be displayed as columns
-l, --selector string only show items matching this label selector
--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)
--default Sets these new locations to be the new default snapshot locations. Default is false. (NEW)
--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.
--label-columns stringArray a comma-separated list of labels to be displayed as columns
--labels mapStringString labels to apply to the volume snapshot location
--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`))
--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
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.
--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.
--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.
A detailed design describing how the changes to the product should be made.
The names of types, fields, interfaces, and methods should be agreed on here, not debated in code review.
The same applies to changes in CRDs, YAML examples, and so on.
Ideally the changes should be made in sequence so that the work required to implement this design can be done incrementally, possibly in parallel.
## Alternatives Considered
If there are alternative high level or detailed designs that were not pursued they should be called out here with a brief explanation of why they were not pursued.
## Security Considerations
If this proposal has an impact to the security of the product, its users, or data stored or transmitted via the product, they must be addressed here.
