TCE Guided UI Experience

[miclettej]

Abstract

We believe one of the largest areas of friction for TCE end users is successfully creating clusters. This process includes:

1. Determine which cluster deployment model is most appropriate
   a. ie: unmanaged vs managed
2. Deploy a cluster
3. Delete a cluster

Along with introducing a new UI, this proposal focuses on an initial use case where a user can accomplish the above with a simplified user experience by leveraging sensible defaults. This increases the likelihood of success for users with limited expertise in Kubernetes and cloud-providers.

Proposal

To achieve the above, we will:

Offer a web-based UI that provides guided and simplified user experiences for underlying CLI functionality. The initial focus will be to provide simplified paths for cluster creation. Including:

• Unmanaged-cluster running locally
• Management and workload clusters running on AWS
• Management and workload clusters running on vSphere
• Management and workload clusters running on Azure
• Management and workload clusters running locally via Cluster API Docker (CAPD)

Users should be able to achieve each of the above without subject matter expertise in Kubernetes or the underlying infrastructure provider. As this new UI model is proved out, we’ll expand into other areas the community sees as viable. These could include things like:

• Advanced cluster configurations
• Cluster upgrades (via Tanzu Kubernetes Releases TKrs)
• Troubleshooting

The above list can also be considered our non-goals for this initial effort.
The remainder of this proposal describes how we are going to achieve the above.

Create new UI Tanzu CLI plugin

A new CLI plugin, named ui, will be introduced to TCE. This plugin will live in the TCE repository as we incubate the project. Based on usage and adoption, we’ll reconsider this home over time. This plugin will be used to launch the web-based UI along and for interacting with other CLI plugins, based on user input. A high-level diagram of this relationship is:

The ui plugin is intended to serve as a UI platform for surfacing selected underlying Tanzu CLI functionality in the form of a GUI. The UI is to be built on web technologies and embedded in a new Tanzu CLI plugin which will be entirely dedicated to running the UI and communicating with other Tanzu CLI plugins.

The current Kickstart UI is embedded in the Tanzu CLI management cluster plugin and is therefore limited to management cluster creation capabilities. The result of moving UI to a dedicated plugin should include greater flexibility in terms of the breadth of underlying CLI functionality that may be exposed in a GUI. Included will be the ability to run the UI “headless” on a remote machine while using a local web browser to offer flexibility for a breadth of users and lab environments.

Introduce sensible defaults

The primary initial use case is to do simplified cluster creations where known-good defaults are chosen and the user needs to provide minimal input. We believe this reduction in choices will increase the likelihood humans are able to stand-up their first clusters. For each provider, the user will only need to input the following:

Unmanaged Cluster

• Cluster name

Docker Provider (Managed)

• Cluster name

AWS Provider (Managed)

• Region
• Instance size profile
  • Compute optimized, Memory Optimized, etc
• Availability Zone
• SSH Key
  • List will be available based on region selected
• Cluster name

vSphere Provider (Managed)

• Datacenter
• Instance size profile
• Existing T-Shirt sizes
• SSH Key
• Control Plane Endpoint IP
• Select discovered vSphere resources
• Select the network (portgroup) that the management nodes will attach to for their networking (VM network)
• Datastore
• Resource Pool

Azure Provider (Managed)

• Region
• Public Cloud
• Instance size profile
• Compute optimized, Memory Optimized, etc
• SSH Key

Every setting that is missing from the above list, for example Cluster Service CIDR and Cluster Pod CIDR, are intentionally removed and set to known-good default where possible. These settings will remain configurable by the user in optional Advanced Settings areas of each provider workflow.

Advanced Settings Common to All Providers (Proposed):

• Cluster Metadata including location, description and labels
• Identity Provider Configuration (if decided to include in this UI)
• Cluster Service CIDR and Cluster Pod CIDR (Kubernetes Network Settings)
• Machine health checks and audit logging
• Activate and Configure a proxy

AWS-specific Advanced Settings:

• Select an existing VPC
• Automate creation of CloudFormation stack
• Activate Bastion host
• Node instance types complete list (IE all compatible instance types)

vSphere-specific Advanced Settings:

• NSX Advanced Load Balancer configuration

Azure-specific Advanced Settings:

• Gov cloud option
• Select an existing Resource Group
• Select an existing VNET
• Private Azure cluster toggle and IP address
• Node instance types complete list (IE all compatible instance types)

Example of "Advanced settings" toggle enabled is shown later in this proposal.

Welcome screen invites user to learn more by linking to learning programs, in-app documentation content and/or external documentation. Left hand navigation panel is collapsible and allows returning users to easily navigate into a familiar area of the UI.

Discovery of existing management clusters is performed on application load. If one or more existing management clusters is detected, then an emphasis is placed on creating workload clusters. Otherwise, user will be invited to create a management cluster.

A list of existing management clusters (inventory) is displayed with the available actions for setting context and deletion. The user must set the context of a management cluster for retrieval of workload cluster inventory and to enable delete option.

Cluster creation flow

Management Cluster Creation
Users may create a management cluster by first selecting their preferred provider.

In the example below, a user has selected AWS as their provider. They will be presented with a simplified cluster creation UI that requires as few steps and inputs as necessary to get their cluster up and running. Advanced options may be optionally exposed for the user if they choose to toggle them on (see advanced settings toggle top-right of wizard). A clear indication of progress and organization can be seen as Steps 1-4 atop the wizard.

Minimal inputs required for authenticating with an AWS account using either a profile or temporary credentials.

Cluster settings include providing a name for the management cluster and a pointed set of instance size profiles to select from.

Regions and resources section includes required fields for region and availability zone selection, AMI ID and EC2 key pair. EC2 key pair is now intended to be displayed as a list of keys that are discovered on the AWS account and region.

The concept of Development and Production control planes is no longer used. Instead, a single node control plane is the default option and selecting the toggle for “Increase availability zones” will deploy three nodes and ask the user to select additional availability zones.

The example below represents how additional inputs will be shown if the user chooses to toggle "Advanced settings" on.

Once all fields have been completed, the user may continue to Go! A summary of simplified cluster settings are displayed along with a tab to expose advanced settings that the customer may have used, giving them a more complete view of their cluster configuration. Below the summary is a CLI command equivalent if they choose to exit the UI before beginning cluster creation in favor of the CLI.

Once a user clicks Create Management Cluster they will be directed to the final screen which displays an abbreviated but inclusive set of steps for cluster creation. Cluster creation logs are displayed in real-time while next steps are suggested in an area below the logs.

Workload Cluster Creation
Workload cluster creation will leverage Cluster Class constructs that are to be installed by default on a management cluster. Cluster Class templates should require minimum user input for creation of workload clusters. Mockups TBD.

Cluster deletion flow

Users will have the option to delete management clusters and workload clusters in the UI. Management cluster delete operations may only be performed once they are confirmed to have zero associated workload clusters. Users will be presented with a confirmation dialog before cluster deletion is performed.

[thefluffysysop]

As mentioned here: https://kubernetes.slack.com/archives/C02GY94A8KT/p1646566051368379
I think its important to remember who the target audience is. In the case of deploying on vSphere, it might be a 'VIAdmin' where this is their first ever experience of installing Kubernetes.

In the thread referenced above, I mention the example of the section called 'Kubernetes service network.'. While this section contains the definition for the SERVICE_CIDR and CLUSTER_CIDR values, it also contains the portgroup selection that sets where the k8s (management) nodes will actually attach to (VSPHERE_NETWORK: ); which is something that many folks are far more familiar with, conceptually and would consider more important. But the way it is worded is misleading and confusing.

select a vSphere network to use as the Kubernetes service network.

No, its actually "Select the network (portgroup) that the management nodes (VMs) will attach to for their networking"

In fact, if we are talking about streamlining, the values for the SERVICE_CIDR and CLUSTER_CIDR would be no1 on my list of unnecessary defaults to drop from the installer UI.. or at least to hide behind some 'advanced' section.

[joshrosso]

In fact, if we are talking about streamlining, the values for the SERVICE_CIDR and CLUSTER_CIDR would be no1 on my list of unnecessary defaults to drop from the installer UI.. or at least to hide behind some 'advanced' section.

Fully agree with this sentiment @thefluffysysop. We'll be dropping a large update to this proposal, where we talk about what will qualify as "defaulted" vs "user selectable", for each provider. We will ping you here to take a look at that when we have it.

@miclettej FYI on the section we've been drafting titled ### Introduce sensible defaults.

Thanks!

[joshrosso]

We are officially RFC'ing this proposal through March.

Mailing list notification: https://groups.google.com/g/tanzu-community-edition/c/6zZwbVv86-I

[thesteve0]

What kind of feedback are you looking for on this? If it is "Is this a good idea" or "I support this" and then we will get into the details later then this seems fine.
If you want detailed feedback then is there a place this proposal is stored where it would be easier to give detailed feedback. For example it is hard to put comments right next to the line where the question arises or to put specific comments on images.

FYI I am really excited for this!

[joshrosso]

What kind of feedback are you looking for on this? If it is "Is this a good idea" or "I support this" and then we will get into the details later then this seems fine. If you want detailed feedback then is there a place this proposal is stored where it would be easier to give detailed feedback. For example it is hard to put comments right next to the line where the question arises or to put specific comments on images.

FYI I am really excited for this!

Please give feedback as comment(s) in this issue.

If you want detailed feedback then is there a place this proposal is stored where it would be easier to give detailed feedback.

This does not exist.

[joshrosso]

Capturing some feedback from @jorgemoralespou in the community meeting that I think is sound on the instance types:

These instance type options are good for workload clusters. But don't make as much sense for management clusters. For management cluster creation, we should move to a few options that represent:

• non-ha minimal node sizing; single node cp
• ha minimal node sizing; multi-node cp
• prod ha recommended node sizing for prod cases; multi-node cp

Naming need to be better, but the above captures the sentiment.

[davidvonthenen]

Minor comment... for the AWS install, do we need to expose the user to the AMI option? maybe just an advanced option and by default select a preferred one

[jpmcb]

Proposal review:

TLDR action items:

• Would love to see documentation integration called out. Deep integration would be an amazing UX.
• I'd like to also see more details on integration with unmanaged cluster (creating, listing, deleting)

---

As this new UI model is proved out, we’ll expand into other areas the community sees as viable. These could include things like

Would also like to see documentation pop-ups (some kind of tool-tip? Implementation to be determined) the can help guide the advanced user through more advanced configurations as the UI plugin grows and expands to capture more and more use cases

---

I'm very curious what the Unmanaged Cluster creation workflow would look like. If all that would need to be provided is a name, it could be a fairly easy one click install.

But as we continue to expand the unmanaged-cluster model (like adding more configuration options, different providers besides kind), I hope the UI would also capture that.

---

Getting a list of unmanaged clusters and their provider is also possible today. I could see this being useful for users wanting to see what's on their system and also delete those clusters.

For example, running

$ tanzu unmanaged-cluster ls -o yaml

returns a yaml chunk like:

- name: test
  provider: kind
- name: test-custom-config
  provider: kind

[seemiller]

For the Azure flow, is there any way to include accepting the base image license into this UI? New versions of the TCE that change the Kubernetes version will require this, and it is not an obvious step to have to remember having to redo.

[jorgemoralespou]

I see some of the comments are pivoting this "new experience/plugin" into something more like a "local cluster manager interface". While I think this might be super interesting and definitely would win my heart, don't think than a tanzu plugin would be the model I would prefer, but rather a desktop application. :-D (Just my 2 cents on that one).

Some additional feedback, but definitely easier to give on Figmas:

• As a user, I would not want to always land in Welcome, but probably only first time, and then go to the last used screen (managed, unmanaged, ...) or at least to the "Getting started". Is there settings that can be saved locally on the user's browser for this?
• I would always have Docker provider last, as it should be the less relevant / less used infrastructure provider.
• In the create workflow, I would not have an global "advanced settings" toggle, but rather only on those pages where there will be advanced settings only.
• Have slide-in on the right contextual help (as it was planned/demoed some time ago on previous iterations of kickstart ui)
• Cluster name is something that I would most likely would always want to know, so would take that out of the wizard into the top level "global" section.
• When selecting an instance type, I would show in a side panel what that means (so what machine types that has resolved to) so that people is right away educated. Or at least, have a tooltip, so they can easily look until they are familiar to what this means. Also, are same instance types always available in every region? In my experience, instances might be dependant on regions, but my experience is very limited.
• Are the instance type selection for "worker" or for "control-plane" for both, does it something smart to size a cluster for the given use case? And as I said before, probably management cluster and workload clusters need different "types"
• For the cluster settings (instance types), seeing the recording, what I would expect to have always visible is only shown when advanced is selected. I would not have an advanced setting here, but have that dropdown always visible. The complexity wouldn't grow but it's more explicit and educational for the user.
• Regions (availability zones) is really complicated. How do I select the number of workers and control-plane nodes? It seems that availability zones control the number of control-plane nodes. Do we support 3 control plane nodes on one availability zone? Do we support 5 control plane nodes? Where do the workloads land? In this screen also, there's a drop-down for the instance type, but one might have forgotten what the name in the dropdown maps to. Also, why, if I already selected in the previous screen?
• Is there advanced settings for "Regions and Zones"? If not, then another point to not having the "advanced settings" as a global toggle
• For "Configuration", I would also have a sub tabbed view, instead than a scrolling pane. This makes easier to identify the section you might want to tweak, and not have to scroll the whole page. The more settings that will be here, the more difficult will be to locate one specific.
• Is there an advanced view for "Configuration"?
• The "Go" page shows a summary that is not a real summary as it looks more as full configuration.
• The "Go" page should have the create button on top, or even have that button available on the header and have it activated once the required configuration is provided, even if the user has not gone through the complete stepper, for fast cluster deployments.
• The "Go" page should probably provide an option to "Download" the config file. Even if this file is stored in the user's filesystem, it will simplify the user the "get a configuration to share" so they can save it wherever they decide, and not have to go find the clusterconfigs folder and copy the file from there. Sorry!!! just noticed the "Export configuration button" that probably does this :-D
• Last page seems awesome, although I would have buttons at the top, as those will be common actions, to prevent scrolling. I hate scrolling :-D
• Now that I see the view clusters, maybe that's an alternative view to the "Getting started" pinned main screen that I detailed above :-D

Really good stuff. But I retain my comment that this might make more sense as a Desktop application, rather than a tanzu plugin :-D

[miclettej]

Minor comment... for the AWS install, do we need to expose the user to the AMI option? maybe just an advanced option and by default select a preferred one

@dvonthenen this came up in our feedback session that continued after TCE office hours. Short answer is no I don't think we need to expose the AMI option for the simplified workflows, and will tweak the mockups accordingly. CC: @garrying

[miclettej]

Capturing some feedback from @jorgemoralespou in the community meeting that I think is sound on the instance types:

These instance type options are good for workload clusters. But don't make as much sense for management clusters. For management cluster creation, we should move to a few options that represent:

• non-ha minimal node sizing; single node cp
• ha minimal node sizing; multi-node cp
• prod ha recommended node sizing for prod cases; multi-node cp

Naming need to be better, but the above captures the sentiment.

Agreed, we should work the revised set that you suggested into the clickable mockups

[miclettej]

Proposal review:

TLDR action items:

• Would love to see documentation integration called out. Deep integration would be an amazing UX.
• I'd like to also see more details on integration with unmanaged cluster (creating, listing, deleting)

As this new UI model is proved out, we’ll expand into other areas the community sees as viable. These could include things like

Would also like to see documentation pop-ups (some kind of tool-tip? Implementation to be determined) the can help guide the advanced user through more advanced configurations as the UI plugin grows and expands to capture more and more use cases

I'm very curious what the Unmanaged Cluster creation workflow would look like. If all that would need to be provided is a name, it could be a fairly easy one click install.

But as we continue to expand the unmanaged-cluster model (like adding more configuration options, different providers besides kind), I hope the UI would also capture that.

Getting a list of unmanaged clusters and their provider is also possible today. I could see this being useful for users wanting to see what's on their system and also delete those clusters.

For example, running

$ tanzu unmanaged-cluster ls -o yaml

returns a yaml chunk like:

- name: test
  provider: kind
- name: test-custom-config
  provider: kind

Agreed, at the least we should be offering contextual help that exposes a panel containing some level of integrated docs. An icon or text link next to a UI element should open the contextual help panel with content specific to that UI element. We have created something like this for the kickstart UI that I imagine us bringing over to this TCE UI. We can start working that into the mockups to provide some visibility on what that solution would look like.

To your second point, we'll hopefully start on mockups for unmanaged cluster UI soon.

[miclettej]

For the Azure flow, is there any way to include accepting the base image license into this UI? New versions of the TCE that change the Kubernetes version will require this, and it is not an obvious step to have to remember having to redo.

Thanks for calling that out. I'll make a note to see how we can go about exposing this in the UI.

[jpmcb]

To your second point, we'll hopefully start on mockups for unmanaged cluster UI soon.

Awesome!! 👏🏼

[joshrosso]

Capturing some feedback from @jorgemoralespou in the community meeting that I think is sound on the instance types:

These instance type options are good for workload clusters. But don't make as much sense for management clusters. For management cluster creation, we should move to a few options that represent:

• non-ha minimal node sizing; single node cp
• ha minimal node sizing; multi-node cp
• prod ha recommended node sizing for prod cases; multi-node cp

Naming need to be better, but the above captures the sentiment.

Agreed, we should work the revised set that you suggested into the clickable mockups

@garrying on this one, were there updated mockups we could update the proposal with?

[garrying]

@joshrosso This is the updated direction we're moving in:

(@miclettej could you move this this up into the proposal?)

[joshrosso]

@joshrosso This is the updated direction we're moving in: (@miclettej could you move this this up into the proposal?)

lgtm. I updated the screenshot in the original proposal 👍 .

[joshrosso]

We've officially accepted this proposal and work is (has been) in flight to satisfy this proposal.