Document kubectl config file format

[mleonhard]

What would you like to be added:

Documentation of kubectl YAML config files

Why is this needed:

So I can understand, write, and maintain kubectl config files.

Expressing frustration:

I'm learning Kubernetes. I went through the tutorials - thanks. Now I'm trying to set up services to run on minikube and my hosting provider. The kubectl command apparently takes a YAML config file. I searched for 15 mins and found no documentation for it at all. I found a helpful blog post complaining about the missing documentation. There are examples: guestbook-all-in-one.yaml, a deployment, a service, a replica set, and a replication controller. The "Getting Start / Production Environment" documentation contains no guidance on using config files to define application deployments.

Should I deploy my code with bash scripts that call kubectl create deployment ... ? Is that how Google engineers work? No, they write borgcfg files. And they learned how to write borgcfg by reading the borgcfg docs. There's even a codelab (tutorial) on writing such files. Imagine trying to onboard new Googler SWEs without letting them read the borgcfg documentation or teaching them how to write borgcfg files. Nobody would do that. Yet Google wants us to use Kubernetes, to deploy on Google Cloud, and doesn't provide this basic doc.

The kubectl config file is crucial information that everyone learning Kubernetes must learn. Please don't make us hunt for this information, guess at the meanings of examples, and read unreliable Stack Overflow answers and blog posts. Just provide usable documentation. Please?

[mleonhard]

/sig docs

[mleonhard]

Terraform's kubernetes provider has some usable documentation. Presumably its config keys and values have the same meanings as those used by kubectl, although the file format is different.

[neolit123]

https://vsupalov.com/yaml-kubernetes-examples-docs-spec/

this blog post mentions kubectl explain, which is the dynamic way of obtaining documentation.

https://kubernetes.io/docs/reference/kubectl/overview/#resource-types
also you can use kubectl api-resources and then based on the APIGroup column you can find the structures and fields you are interested in, in the go docs at:
https://godoc.org/k8s.io/api

i think the documentation you are asking for is examples based, and it's missing because some of the APIs are changing and keeping examples in sync-with all of them is going to be problematic. i doubt there are enough people to help with this effort.

what can be potentially added to kubectl one day is the generation of examples, but this is up to the group that maintains is.

if you want to discuss this in chat try joining the k8s slack channel #sig-cli
/sig cli

[mleonhard]

i think the documentation you are asking for is examples based, and it's missing because some of the APIs are changing and keeping examples in sync-with all of them is going to be problematic. i doubt there are enough people to help with this effort.

Examples-based documentation is fine if there are comprehensive examples with comments explaining what each option means and the available values. Kubernetes does not have that kind of documentation.

The APIs I need to use are not changing. I'm not doing anything complicated.

Kubernetes is an example of API Practices If You Hate Your Customers - Technique kubernetes/kubernetes#4: Hide the API docs from Search Engines and Technique kubernetes/kubernetes#7: Maintain documentation manually. Google, VMWare, and other members of the Kubernetes group: Get this done and you will earn more money. You win when more companies move to cloud tech.

There are engineers with plenty of Kubernetes experience. Thirty pull requests were submitted yesterday alone. I think you can mobilize them to build out usable documentation. You just need to try.

For now, I give up on Kubernetes. I deleted my Kubernetes cluster and will implement our deployments with Terraform + Docker.

[sftim]

also
/sig cli

[hypdeb]

Is there really NO reference to what this config file should contain ? If yes, I support this request for documentation. I would like to help but I'm here exactly because I know nothing about kubectl :)

[sftim]

https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/ exists
It would be great if https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/ could hyperlink to a reference document explaining .kubeconfig as a reference.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[cpxPratik]

/remove-lifecycle rotten

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[cpxPratik]

/remove-lifecycle rotten

[kunal-kushwaha]

I'd like to take this one 😄
/assign

[cpxPratik]

/remove-lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

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:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[cpxPratik]

/remove-lifecycle rotten

[sftim]

(on behalf of SIG Docs)
/lifecycle frozen

[sftim]

/transfer website

[sftim]

/priority important-longterm
/triage accepted

[sftim]

• https://kubernetes.io/docs/reference/config-api/ doesn't yet mention kubectl.
• https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#what-s-next has no link to learn about the format

[tengqm]

There is nothing like a config API for this purpose. The website has some useful information here: https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/

The page could use some improvement because kubeconfig file is not just for accessing multiple clusters.

[sftim]

I'd like to add a reference that is similar to the pages within https://kubernetes.io/docs/reference/config-api/
I can make a quick mockup (if that'd help?)

We don't need to generate the new page automatically. It is useful if the references are consistent, though.

[sftim]

Done: https://kubernetes.io/docs/reference/config-api/kubeconfig.v1/

/close

[k8s-ci-robot]

@sftim: Closing this issue.

In response to this:

Done: https://kubernetes.io/docs/reference/config-api/kubeconfig.v1/

/close

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.

[mleonhard]

Thanks for adding docs about how to configure kubectl command auth to k8s clusters.Is there also documentation for defining pods, servers, ingress, and data storage? I still can’t find it. That’s what new k8s users need.. That’s what this ticket is about.Please re-open./open/reopen/re-open

[sftim]

@mleonhard this issue is resolved.

If you would like to request further improvements, you are welcome to file further issues. It's best to use a new issue for each logically separate improvement.
If you are considering making a suggestion, please check to see whether it has already been requested; if so, you could upvote the existing issue.

I recommend that you read tips for writing a good issue; even if you have already read a similar guide, it's worth having a fresh idea of how open source projects encourage contributors to act.

[mleonhard]

@sftim You linked to docs that are different than what this ticket asked for. The sidebar is not visible at all on mobile, making it hard to find the needed docs. On desktop, I was able to find them: https://kubernetes.io/docs/reference/kubernetes-api/ . Thank you!

There is still a lot of room for improvement. This ticket is about docs for new users, specifically how to set up services to run in a k8s cluster. The docs now have that info, but put it under "Kubernetes API". I've been doing software for 15 years, including stints at AWS and Google infrastructure. To me, "Kubernetes API" is the RPC interface for controlling a Kubernetes cluster. I would read that when I work on Kubernetes management tools.

But I just want to make my server run on a Kubernetes cluster, using existing tools. I just need to know what to put in the @#%$@ config file. That's what this ticket is about.

So all new Kubernetes users must first learn that the info about "what to put in the config file" is under "Kubernetes API". Finding that info will take time. This is time that most new users will waste. Please fix this. And next time you write or change documentation or user interfaces, please try harder to consider the needs of the users.