search

kubernetes / cloud-provider-aws

Cloud provider for AWS
https://cloud-provider-aws.sigs.k8s.io/
Apache License 2.0
376 stars 300 forks source link

Improve documentation #844

Open der-eismann opened 5 months ago

der-eismann commented 5 months ago

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 commented 5 months ago

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](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
cartermckinnon commented 5 months ago

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 commented 5 months ago

Rarely might be true, but it does happen :slightly_smiling_face: 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 commented 3 months ago

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 commented 2 months ago

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+.