-
Notifications
You must be signed in to change notification settings - Fork 14.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document the unpublished APIs #23889
Comments
xref: #23885, #23837, #21109, #21558, kubernetes/kubernetes#84081 |
/triage accepted |
For this umbrella issue, I would include the gRPC socket that serves the Pod Resources API / also see kubernetes/kubernetes#92165 What do you think @tengqm ? Is this the right home for tracking that? |
@sftim I'm don't have a strong opinion on where the API docs are served. Maybe just some simple markdown tables (or HTML tables) capturing the comments in the source code would be a good starting point. |
Hi @tengqm . I need to read through the changes. Can you elaborate on this comment:
How does an administrator use the content (component flags, client code)? |
@kbhawkey See this section: https://kubernetes.io/docs/tasks/administer-cluster/kubelet-config-file/#create-the-config-file When we are trying to tell admins how to create/customize kubelet config file, we are forcing them to read Go code. The configuration file is nothing more than a JSON data. See the need for this kind of reference? |
This still feels like a really useful improvement. |
Hi, @alculquicondor Are these issues related: |
Hi @tengqm . I think this information is useful ❇️ . Some questions:
|
hi, i do agree we should publish the missing APIs (which we also call component config API, btw). on here i'm asking a few questions to @tengqm. my primary questions are around process, since i did not understand why are we using godoc to generate these ideally we should use the same process for generating the swagger docs as for the core kubernetes APIs, hosted at: |
kubernetes/kubernetes#88919 would indeed be kube-scheduler part of this. This API is for configuring kube-scheduler at startup. It is read from a file. We also discussed some more here: kubernetes-sigs/reference-docs#138
That seems directly obtained from the code, which is what we want. We just never got a contributor to work on the integration of generation scripts to the website. |
@tengqm @alculquicondor during the weekend i played with generating swagger.js from our API types and producing a page similar to: here kubernetes-sigs/reference-docs#138 i see you've discussed the tool https://github.com/ahmetb/gen-crd-api-reference-docs. i have not tried it by everything else did not work for me, or was simply poorly documented - including kube-openapi. so i wrote yet another parser for go types-> swagger.js once i had a swagger.js i tried feeding it in https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-apidocs, but soon realized that gen-apidocs is making a number of hardcoded assumptions and only works for core APIs. minimal patches were required... my vote goes for producing swagger json and adapting gen-apidocs to support any component's API and publishing it potentially at a separate page or unifying all component-config API under the same page. other things we need to consider:
|
I don't have an opinion on what tools are best. I'll leave the decision to sig-docs. |
@neolit123 Actually you don't need a swagger/OpenAPI spec for this kind of types. What we are trying to document are some configuration structures rather than fully fledged RESTful APIs. In a swagger/OpenAPI, peopled define not only the structural representations that flow between the server and the client, they define other things such as API path, HTTP verbs to use, content-type to negotiate, query strings to accept, status code for each API, etc. The swagger json file is generated by the kube-apiserver today. Behind the scene there are some preprocessing logics that parse the Go source code and generates some intermediate files containing half-baked API specification. When you inquire an API server for the swagger spec, the API server goes through all those struct definitions and yield a JSON result for you. There is no magic. At the end of the day, it is all about The genref tool I'm proposing skips all the unnecessary conversions and generate the HTML output directly. If needed, we can easily tune it to generate markdowns. As for tuning kubeadm comments to generate better docs, that is a different topic. The "kubeadm embdded authored contents" doesn't look very ugly if we are taking care of the format with some tweakings: https://tengqm.github.io/doc/kubeadm-config.v1beta1.html The output was generated from exactly the code in the PR I proposed to kubeadm source code. |
while kubeadm currently doesn't serve anything, the components like kubelet, kube-scheduler, kube-controller-manager and kube-proxy do expose endpoints which are currently mostly undocumented. the openapi format can help with that. so i slightly disagree if we are planning to discard openapi.
yes, i figured that out. except i still cannot make the kube-openapi generate the structs.
the output looks nice, but i think we should close the kubeadm PR and move these changes on the side of the generation tool as mutations. also, all the authored content in the kubeadm doc.go feels like should be moved to a MD file (this was discussed a few times already with the kubeadm maintainers) |
@neolit123 Alright. If kubeadm decides to generate fully fledged OpenAPI/swagger specs, that is great. We can wait for that to happen. We have to clone the kubeadm code in order to generate the struct definitions today; that is another tech debt. Moving content out for the doc.go into a markdown file is a good idea. I'm all for it. |
@kbhawkey Sorry for the late response.
We cannot decide how the development team (SIGs) want to call them. Some are actually just configuration data structures, others are exposed by the API endpoint of the component in question. For example, in kubelet, it is called a config, and the config is separated from kubelet apis where most APIs are only defined for protobuf rather than RESTful clients.
That is doable and can be done easily. We have some Go templates for rendering the HTML output, just for show cases purpose. We can have templates for markdowns.
It really depends. However, I do believe each SIG is tracking changes to these types as official APIs, I mean, they are following the versioning practices. Since these types are bound to the binaries (e.g.
Yes. Only (exposed) resource types are included. If another type definition
My original thought is just links. Point readers to the rendered HTML pages rather than source code or Go docs.
Yes, I think so. Maybe a subsection under reference.
The overall trend is to deprecate all command line flags in favor of config files. Most of the so called "unpublished" APIs are actually about the config file format. So ... maybe we need both today so people know ... if I'm specifying this as command line flag, I should use |
@tengqm
the tooling should just parse the
as mentioned above, kubeadm has the least need for OpenAPI/swagger specs. it's the other components that may want to document all of their endpoints / requests / responses.
what is SIG Docs' preference? instead of having content in doc.go file should we start adding i'm leaning towards moving this to a k8s.io page. some history on this topic is that in the past SIG Docs objected to the kubeadm maintainers adding documentation in a doc.go file, but the API was moving too fast and it was a bit hard to maintain it at k8s.io. |
The tool is doing exactly that. The problem is about the comment lines, from which the docs (including swagger spec) are generated.
Is it possible to paste that doc.go content into a markdown and find a place for it in website? Referencing docs at website from source code is an acceptable practice, maybe? |
this is a problem here too: so instead of adapting all APIs to follow a new style, we should make the tooling post-process the comments.
->
we can certainly do that. wanted to see if someone has objections, this also means we have to link to the new page from kubeadm docs (also from k/kubeadm), so potentially we should make this after 1.20 releases. |
@neolit123 I did considered that possibility -- having the post processing tool to make the comments more user friendly. However, it turned to be impractical. Let me give you a few examples where we will need an NLP (natural language processing) engine to correctly figure out what the text means: Example 1 // Expires specifies the timestamp when this token expires. Defaults to being set
// dynamically at runtime based on the TTL. Expires and TTL are mutually exclusive.
Expires *metav1.Time `json:"expires,omitempty"` Example 2 // TLSBootstrapToken is a token used for TLS bootstrapping.
// If .BootstrapToken is set, this field is defaulted to .BootstrapToken.Token, but can be overridden.
// If .File is set, this field **must be set** in case the KubeConfigFile does not contain any other authentication information
TLSBootstrapToken string `json:"tlsBootstrapToken,omitempty"` |
Unless Go adopts a (strong) convention for Markdown, or other formatting, in comments, I recommend against automatically inferring formatting from comments. |
it can be a problem in general. but it feels like in k8s we should adopt a style. @tengqm i think one way to solve this is if field references in comments are always prefixed with
|
Maybe a KEP? It does need buy-in. |
it does. until then we can leave the field descriptions unprocessed, but continue to think how to publish this documentation. |
Doesn't block either PR but |
ABAC policy is also mentioned in #23885 |
which is more appropriate for the swagger format, because there is (planned) inter-component communication with requests / responses. |
https://coveooss.github.io/json-schema-for-humans/ might have some ideas about either the styling, a mechanism for documentation generation, or both. |
Remove reference in favor of kubernetes#23889
Issues go stale after 90d of inactivity. If this issue is safe to close now please do so with Send feedback to sig-contributor-experience at kubernetes/community. |
/remove-lifecycle stale |
/priority important-longterm |
Remove reference in favor of kubernetes#23889
Issues go stale after 90d of inactivity. If this issue is safe to close now please do so with Send feedback to sig-contributor-experience at kubernetes/community. |
Stale issues rot after 30d of inactivity. If this issue is safe to close now please do so with Send feedback to sig-contributor-experience at kubernetes/community. |
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /close |
@k8s-triage-robot: Closing this issue. In response to this:
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. |
This is a Feature Request
What would you like to be added
There are a few APIs that are not published as RESTful resources. Here are some examples:
kubelet
configuration: https://github.com/kubernetes/kubernetes/blob/master/pkg/kubelet/apis/config/types.go#L75kube-scheduler
configuration: https://github.com/kubernetes/kubernetes/blob/master/pkg/scheduler/apis/config/types.go#L55kube-controller-manager
configuration: https://github.com/kubernetes/kubernetes/blob/master/pkg/controller/apis/config/types.go#L49kube-proxy
configuration: https://github.com/kubernetes/kubernetes/blob/master/pkg/proxy/apis/config/types.go#L108For these definitions, there may and may not be API paths associated with them, simply generate documentation for the struct definition would be very helpful.
Why is this needed
These types are not designed to be operated through the API server using CRUD operations. However, an administrator needs to understand their definitions in order to better configure and manage a Kubernetes cluster.
Comments
This needs some tooling effort to parse the Go source file. The tool can go to kubernetes-sigs/reference-docs repo.
The text was updated successfully, but these errors were encountered: