Kubebuilder: Docs: Make the QuickStart a little more detailed with a Greeter example.

[erictune]

The Quickstart is kind of unsatisfactory because:

• it does not show the user that there are pre-generated API and Controller files. Conveying that KB does this for you is important to show the user why they want to use KB, and to give an initial taste of how Controllers and CRDs work together.
• it does not "do something", so the user does not get a sense of satisfaction at the end of the Quick Start.

Suggest the following changes to the Quickstart.

• The user will implement a very minimal one-spec-field, one-status-field API.
• It is modeled after the classic OO example of the Greeter class.
  The changes to the Quickstart Text are:
  
  
  
  • Rename "Guestbook" to "Greeter".
  
  
  • In Create an API replace the Optional bit with the following fairly steps:
  
  
  • Open api/v1/guestbook_types.go in your editor.
  
  
  • Find the line that says: type GuestbookSpec struct {
  
  
  • Insert this line below it: Who string `json:who.omitempty"`.
  
  
  • Find the line that says: type GuestbookStatus struct {
  
  
  • Insert this line below it: Greeting string `json:who.omitempty"`
  
  
  • Open controllers/guestbook_controller.go
  
  
  • Find the line that says: // your logic here.
  
  
  • Replace it with these lines:
  
  
  • var g webappv1.Guestbook
  
  
  • r.Get(context.Background(), req.NamespacedName, &g)
  
  
  • g.Status.Greeting = "Hello " + g.Spec.Who
  
  
  • r.Update(context.Background(), &g)
    
    
    
    
    
    • return ctrl.Result{}, nil
    
    
    
  
  
  • Run make
  
  
  • Open config/samples/webapp_v1_greeter.yaml (but give this a better name
  
  
  • Set who: to your name, such as who: Alice.
  
  
  • kubectl apply -f config/samples/webapp_v1_greeter.yaml
  
  
  • wait a second
  
  
  • view the status of the resource with kubectl get -f config/samples/webapp_v1_guestbook.yaml -o yaml
  
  
  • The controller offers you greetings.
  
  

[sb1975]

I agree, its a default assumption that everyone knows and then starts to work on kubebuilder but sufficient details are missing to get started..

[DirectXMan12]

Yeah, we probably need something between "remind you of the steps" and "here's a full real-world example". We had another comment to that effect recently, but I can't seem to find it now.

Your suggestion seems reasonable here, because it doesn't significantly interrupt the flow of the "here's the general steps".

[DirectXMan12]

/help

[k8s-ci-robot]

@DirectXMan12:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[DirectXMan12]

/kind documentation

[DirectXMan12]

alternatively, we could split out and have an middle "quick start"

cc https://github.com/kubernetes-sigs/kubebuilder/issues/984

[camilamacedo86]

/assign @camilamacedo86

[camilamacedo86]

Hi @DirectXMan12 and @erictune,

I think we can close it with the merge of PR: #1008. The quick was improved and may is not exactly as you suggested here but I think that it is covering now your main concerns raised here. WDYT? Can we close this one?

[erictune]

I don't feel like #1008 addresses either of the two points in the top post, namely:

• the quickstart does not show the user that there are pre-generated API and Controller files.
• the unmodified control loop does not "do something", so the user does not get a sense of satisfaction at the end of the Quick Start.

[camilamacedo86]

HI @erictune,

Sorry, I did not understand what you mean with the quickstart does not show the user that there are pre-generated API and Controller files.. could you please clarify and if possible provide a suggestion of what is missing?

Regards the unmodified control loop does not "do something", so the user does not get a sense of satisfaction at the end of the Quick Start. the goal of the Quick Start is not show how to getting started with a demo at the end in POV. Its only to give a macro idea over how to create, build and deploy a project. The demo project as the further explanations will be checked in the tutorial, because of this was added this info at the end of the doc. Is it make sense for you?

[camilamacedo86]

Hi @erictune,

I did a new PR to cover these points. Please, see #1076 and let me know if we can agree in close this one with or if it has anything else more that you would like to address.

[erictune]

Hi @camilamacedo86

I think we have differing ideas of how much a Quickstart should cover.
I will seek some advice from a Kubernetes Docs maintainer on this topic.
I'll also defer to the KubeBuilder maintainers on what they want.

[erictune]

@mistyhacks seeking your advice since you have worked on kubernetes/website docs. Low priority, but maybe you have a quick answer.

We have an existing "Quickstart" guide for KubeBuilder (here: https://book.kubebuilder.io/quick-start.html)

KubeBuilder is a tool that generates code scaffolding which the user then edits and adds their own code.
The question is whether it is suitable for such documentation to ask the user to edit a file to add a few lines of code, to illustrate the KubeBuilder workflow. Or is it better to stick to just illustrating the commands that KubeBuilder CLI provides.

[mdlinville]

A quickstart usually focuses on a very specific task. The document you linked above seems more like an end-to-end solution, where you start with nothing and you end up with a completely functional solution. It seems like here, there should be some kind of a flow such as Installation -> Basic setup -> Create a project -> Deploy the project. Maybe the last two could actually be separate, and it could be a staged tutorial.

This is just one perspective without much background. Others will have other info.

[camilamacedo86]

H @erictune,

Could you please let us know if after the above discussion and changes performed in the QuickStart if do you agree in close this one? If not, could you summarised and define what is missing here in POV to close this specific issue?

PS.: If I cannot help with, I will unassing and leave this one.

[erictune]

Mistyhack's comments made me question whether the change I suggested is useful. I will close.