Improve documentation

[der-eismann]

What would you like to be added:

This project has a complete lack of documentation, which is a bit surprising to me when thinking about the importance to Kubernetes users on AWS. It really needs to be improved.

1. There's nowhere explained how to install it, apart from a hidden kubectl apply line in getting started. I saw there is a release for a helm template, how do I use it? Do I have to download the tarball locally or is there a repo somewhere?
2. What exactly does it do and can I only use parts of it? In the readme it says the following, however I don't want any NLBs or routes on AWS, all I care about are node labels and lifecycles.

The controller loops that are migrating out of the kube controller manager include the route controller, the service controller, the node controller, and the node lifecycle controller.

3. In the components section it only mentions the service controller, what about the remaining components?
4. No explanation for the required IAM permissions. It says Adjust these based on your needs, but what are my needs? (see 2.)
5. Changelog in the docs is broken as well and unmaintained
6. Missing/wrong defaults in the --help section. --allocate-node-cidrs has no default value and --controllers states '*' enables all on-by-default controllers and then Disabled-by-default controllers: tagging (default [*]). So is tagging disabled or are all enabled by default as * would suggest?

Why is this needed:

So people can make use of it and know what they are doing.

/kind feature

[k8s-ci-robot]

This issue is currently awaiting triage.

If cloud-provider-aws contributors determine this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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.

[cartermckinnon]

Totally agree that the docs could be improved. In practice, this component is rarely deployed or configured by an end-user directly. For example, a tool like kOps will set it up for you, and it's included in EKS control planes. Documentation in this area hasn't been a priority as a result.

I don't want any NLBs or routes on AWS, all I care about are node labels and lifecycles.

It sounds like you just want the cloud-node-controller and cloud-node-lifecycle-cpontroller, which are implemented here: https://github.com/kubernetes/kubernetes/tree/master/staging/src/k8s.io/cloud-provider/controllers

[der-eismann]

Rarely might be true, but it does happen 🙂 We started ages ago with our own bootstrapped kubelet and never migrated to a managed distribution like EKS, but it feels like we really should because stuff like this is becoming unmanageable.

Anyhow, IMHO this software is a really important piece with Kubernetes on AWS and I think the docs deserve some more time and love.

[thefirstofthe300]

Totally agree that the docs could be improved. In practice, this component is rarely deployed or configured by an end-user directly. For example, a tool like kOps will set it up for you, and it's included in EKS control planes. Documentation in this area hasn't been a priority as a result.

With CAPI, the exact opposite is true. CAPI does not provide any out of the box AWS cloud controller manager configuration as CAPI is meant to be a build your own cluster type project. I'm trying to get an AWS cluster stood up with Flannel and I'm suspecting my issues with DNS are caused by the coredns pods having an IP address which the VPC does not know how to route.

[et304383]

I cannot believe this isn't the number one upvoted issue. The documentation (or lack thereof) is appalling and quite frankly embarrassing considering this is a critical component if you want to use K8s 1.27+.

[k8s-triage-robot]

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle stale
• Close this issue 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.

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

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

/lifecycle rotten