5.5 KiB

Raw Blame History

Periodically tell user about minikube features/tips and tricks

First proposed: 2021-06-18
Authors: Peixuan Ding (@dinever)

Reviewer Priorities

Please review this proposal with the following priorities:

Does this fit with minikube's principles?
Are there other approaches to consider?
Could the implementation be made simpler?
Are there usability, reliability, or technical debt concerns?

Please leave the above text in your proposal as instructions to the reader.

Summary

minikube has lots of great features. We want to proactively remind users that those features are available.

To achieve this, we can have a tips feature that randomly shows a tip from a curated list whenever the user starts a new minikube profile.

For example:

Goals

Store a list of tips in a static file
Show a random minikube usage tip each time a user starts a minikube profile
Have the tips synced to the Hugo docs website to make those available through docs
Allow user to disable the Tips feature with minikube config

Non-Goals

Modify any existing functionalities or docs

Design Details

First, we need a static file to store all the tips, we can have a YAML file at pkg/generate/tips/tips.yaml:

tips:
  - |
    You can specify any Kubernetes version you want. For example:

    ```
    minikube start --kubernetes-version=v1.19.0
    ```    
  - |
    You can use minikube's built-in kubectl. For example:

    ```
    minikube kubectl -- get pods
    ```    
  - |
    minikube has the built-in Kubernetes Dashboard UI. To access it:

    ```
    minikube dashboard
    ```

Use goembed to embed this file into the minikube binary.

The current out.Boxed has a hard-coded style (red). I propose to add another out.BoxedWithConfig method to allow output with customized style:

// BoxedWithConfig writes a templated message in a box with customized style config to stdout
func BoxedWithConfig(cfg box.Config, st style.Enum, title string, format string, a ...V) {
}

Whenever minikube successfully starts, we randomly choose a tip.

Before printing it out, we need to do some regex replacement to strip the markdown syntax for better view experience in Terminal:

From this:

You can specify any Kubernetes version you want. For example:

```
minikube start --kubernetes-version=v1.19.0
```

To this:

You can specify any Kubernetes version you want. For example:

minikube start --kubernetes-version=v1.19.0

Then we can print out the tip:

boxCfg := out.BoxConfig{
	Config: box.Config{
		Py: 1,
		Px: 5,
		TitlePos: "Top",
		Type: "Round",
		Color: tipBoxColor,
	},
	Title: tipTitle,
	Icon: style.Tip,
}

out.BoxedWithConfig(boxCfg, tips.Tips[chosen] + "\n\n" + tipSuffix)

User can choose to disable this through minikube config set disable-tips true

We will have make generate-docs generating the docs site based on this YAML file as well.

We can have a Nice to know sub-page under FAQ?

About the tip collection

I plan to start with the command lines and cover almost all CLI usages of minikube.

That includes but not limited to:

addons
cached images
command line completion
config
file copy
dashboard
delete minikube cluster
configure minikube's docker/podman env
image build / load / ls / rm
ip
logging
kubectl
mount file directory
multi-node
pause/unpause to save resource
multi-profile
surface URL to a k8s service
ssh into minikube
status
tunnel to connect to LB
update-check to check versions
update-context

Implementation

I plan to open at least 4 PRs:

out.Boxed with custom style
random tips display with ability to disable through config, with an initial set of about 10 tips
make generate-docs to sync tips to docs
Add more tips

Alternatives Considered

Is there a more preferred file format to YAML?
Maybe we just want to sync the tips to the FAQ page list instead of creating a new page?

Instead of the file format I proposed, maybe add a question field?

tips:
  - question: How to specify a different Kubernetes version?
    answer: |
      You can specify any Kubernetes version you want. For example:

      ```
      minikube start --kubernetes-version=v1.19.0
      ```      
  - question: Do I have to install `kubectl` myself?
    answer: |
      You can use minikube's built-in kubectl. For example:

      ```
      minikube kubectl -- get pods
      ```      
  - question: How do I access the Kubernetes Dashboard UI?
    answer: |   
      minikube has the built-in Kubernetes Dashboard UI. To access it:

      ```
      minikube dashboard
      ```

On the docs side we can show both questions and answers. On the CLI side we can either show both questions and answers, or just show the answers to make it more compact.

5.5 KiB Raw Blame History