UX: package command feedback

stmcginnis commented 3 years ago

Using this to capture my feedback as a new person trying to use the package commands.

Goal was to get a new package installed just to verify functionality. Referenced some docs being added to the TCE repo to support this, but tried to follow a typical user route of ignoring docs as much as possible.

Add new repo

To start I wanted to add the TCE repo to work with those packages. This one I had to look at the docs to figure out:

tanzu package repository add tce-main --namespace default --url projects.registry.vmware.com/tce/main:latest

OK, a little lengthy, but seems reasonable, especially for a command that likely won't be run too often.

List packages

Now that I have the repo added, need to see what packages are available to me.

tanzu package list
Error: unknown command "list" for "package"

Oops, not that. Take a look at the package help. OK, package available. As opposed to unavailable packages I suppose?

tanzu package available list
...

Wow, that's a lot more packages than I expected from TCE. Right, products being built on top of tanzu-framework got added into the framework instead of the product: https://github.com/vmware-tanzu/tanzu-framework/issues/327

Harbor installation

Let's pick harbor to install.

tanzu package install harbor.community.tanzu.vmware.com

Failed. Help output scrolled off the top of my terminal, let's see if it had something useful before all the help output.

Error: accepts 1 arg(s), received 2
Usage:
  tanzu package install INSTALLED_PACKAGE_NAME [flags]

Hmm, I have it a package name, and the rest are flags, so what did I miss.

Read farther and see some of the "Examples" output. OK, even though I need to tell it what package I want to install, that's actually a named argument. Seems a little odd, since I would think that name of the package I want to install would be pretty important to a package install command. I'll try again.

tanzu package install harbor --package-name harbor.community.tanzu.vmware.com

Nope, help output again. I must have missed something. Scroll back up...

Error: required flag(s) "version" not set

I don't care about the version, I just want to install whatever package is available for harbor. I also have no idea what versions are available. Let's see, how do I do that. I didn't see any version information in tanzu package available list, so where can I find that out? Ah, there's a get command for tanzu package. I want information about a specific package, so that must be it.

tanzu package available get harbor.community.tanzu.vmware.com

Well, that's a lot of details about the package, but I still don't see anything about versions I can choose from.

Finally consult someone that knows. I run list to get details of a specific package. Well that seems really odd, but OK.

tanzu package available list harbor.community.tanzu.vmware.com
- Retrieving package versions for harbor.community.tanzu.vmware.com... 
  NAME                               VERSION  RELEASED-AT           
  harbor.community.tanzu.vmware.com  2.2.3    2021-07-07T18:00:00Z

What?! I had to go through all of that and there's only one version anyway? Why bother asking me. That was a waste of my valuable end user time. :)

Whew, finally I have everything I need to install...

$ tanzu package install --package-name harbor.community.tanzu.vmware.com harbor-install --version 2.2.3
/ Installing package 'harbor.community.tanzu.vmware.com' 
- Getting package metadata for harbor.community.tanzu.vmware.com 

| Creating package resource 
- Package install status: Reconciling 

Please consider using 'tanzu package installed update' to update the installed package with correct settings: package reconciliation failed: ytt: Error: Evaluating starlark template: 
- assert.fail: fail: Harbor admin password should be provided
    in validate_harbor_admain_password
      26 |   values.harborAdminPassword or assert.fail("Harbor admin password should be provided")
    in validate_harbor
      101 |      validate_func()
    in <toplevel>
      109 | validate_harbor()

Error: 
Please consider using 'tanzu package installed update' to update the installed package with correct settings: package reconciliation failed: ytt: Error: Evaluating starlark template: 
- assert.fail: fail: Harbor admin password should be provided
    in validate_harbor_admain_password
      26 |   values.harborAdminPassword or assert.fail("Harbor admin password should be provided")
    in validate_harbor
      101 |      validate_func()
    in <toplevel>
      109 | validate_harbor()

Help output, scroll back up to see what the error was. Well, that doesn't look good. How do I provide an admin password?

Let's look at that help output again. OK, there's -f, --values-file string. So I must need to put that password in a values file and pass it in to the command. What's the format of that file? How do I get an example? What is the value supposed to be named for the admin password?

Can't find anything, let's just create a file and try again.

$ tanzu package install --package-name harbor.community.tanzu.vmware.com harbor-install --version 2.2.3 
/ Installing package 'harbor.community.tanzu.vmware.com' 
Package install 'harbor-install' already exists in namespace 'default'

It already exists? But I tried to install it and it failed. OK, if I look all the way back, the original error output mentioned tanzu package installed update (twice) so I guess I just have to update the failed installation.

Package removal

But I still don't really know what the format of that values file should be, so maybe I should just remove this failed install so I can figure that out and start from scratch.

Looks like from the help output that there is a remove command. Oh good, it has an example, so I can list installed and use that to remove.

$ tanzu package installed delete harbor-install
| Uninstalling package 'harbor-install' from namespace 'default' 
| Getting package install for 'harbor-install' 
\ Deleting package install 'harbor-install' from namespace 'default' 
| Deleting role binding 'harbor-install-default-cluster-rolebinding' 

 Uninstalled package 'harbor-install' from namespace 'default'

Whew, that worked.

vijaykatam commented 3 years ago

List packages - available was chosen to explicitly differentiate between installed list and the ones available from repositories. cc @cppforlife
Install - We'll fix help text for sample usage to include required flags
Install improvements that I think of to make install experience better a. Generate an installation name if not provided b. Use the highest version of an available package if version is not specified
Values file improvements in the queue a. We did add --values-schema for package get(https://github.com/vmware-tanzu/tanzu-framework/blob/main/cmd/cli/plugin/package/package_available_get.go#L31) that got merged post RC.1, it outputs a table of properties, default, type and description. b. Another enhancement that is in backlog is to generate a template values-file from the schema.

mcwumbly commented 3 years ago

I also have no idea what versions are available. Let's see, how do I do that. I didn't see any version information in tanzu package available list, so where can I find that out? Ah, there's a get command for tanzu package. I want information about a specific package, so that must be it.
tanzu package available get harbor.community.tanzu.vmware.com
Well, that's a lot of details about the package, but I still don't see anything about versions I can choose from.

Finally consult someone that knows. I run list to get details of a specific package. Well that seems really odd, but OK.
tanzu package available list harbor.community.tanzu.vmware.com
- Retrieving package versions for harbor.community.tanzu.vmware.com... 
  NAME                               VERSION  RELEASED-AT           
  harbor.community.tanzu.vmware.com  2.2.3    2021-07-07T18:00:00Z 

related: we added a TanzuPackageAvailableVersion test helper function in our e2e tests for the external dns package to work around this UX issue: https://github.com/vmware-tanzu/tce/pull/1227/files#diff-1d73b9c000e3f42ddd254f760b259e57737677aab891410eee3768468487633f

We also initially thought that get would return that info and were surprised when it did not. Maybe it should?

Use the highest version of an available package if version is not specified

That, or include a --latest flag or something if we want to make this explicit.

thesteve0 commented 3 years ago

I had some of the similar issues in my limited usage of tanzu package. Since tanzu package is a package management system, I would have really loved if the cli had, where possible, followed the command pattern of either yum/dnf or apt. This way I could leverage my existing knowledge to get comfortable in the basics of tanzu package. I know there will have to be deviations because we are packaging for a different type of platform, but where possible, this would have made me feel really good as a user.

tschwaller commented 3 years ago

If you look at the output of the following command

$ tanzu package available list
- Retrieving available packages...
  NAME                           DISPLAY-NAME  SHORT-DESCRIPTION
  cert-manager.tanzu.vmware.com  cert-manager  Certificate management
  contour.tanzu.vmware.com       Contour       An ingress controller
  external-dns.tanzu.vmware.com  external-dns  This package provides DNS synchronization functionality.
  fluent-bit.tanzu.vmware.com    fluent-bit    Fluent Bit is a fast Log Processor and Forwarder
  grafana.tanzu.vmware.com       grafana       Visualization and analytics software
  harbor.tanzu.vmware.com        Harbor        OCI Registry
  multus-cni.tanzu.vmware.com    multus-cni    This package provides the ability for enabling attaching multiple network interfaces to pods in Kubernetes
  prometheus.tanzu.vmware.com    prometheus    A time series database for your metrics

each package is described very differently. Some standardization of the descriptions and their text length would be highly welcome.

vmware-tanzu / tanzu-framework