Update README to improve clarity and add troubleshooting and FAQs

[vishesh92]

Fixes #92 #100

[Copilot]

Pull request overview

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Improves the README’s clarity and usefulness by expanding configuration documentation and adding operational guidance (FAQ + troubleshooting) for CloudStack Kubernetes CCM users.

Changes:

• Clarified project description and terminology (CloudStack/Kubernetes wording) and improved several existing sections.
• Documented new/expanded configuration behavior (e.g., region, zone auto-detection) and detailed LoadBalancer source restriction behavior across CloudStack layers/versions.
• Added FAQ and troubleshooting guidance for common operational issues (e.g., pending LoadBalancer services, image architecture mismatch).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 50.05%. Comparing base (0fdca7b) to head (47fc2be).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #103   +/-   ##
=======================================
  Coverage   50.05%   50.05%           
=======================================
  Files           4        4           
  Lines         975      975           
=======================================
  Hits          488      488           
  Misses        473      473           
  Partials       14       14           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

README.md:199

• This section says there are "two" layers, but the table lists three (LB rule, firewall rule, Network ACL). Also, the Network ACL row reads as if the controller always creates an allow-all ACL rule, but later the README notes the controller does not add ACL rules for default ACL lists.

Suggest updating the intro wording to "up to three" layers and clarifying that the controller-managed Network ACL rule is allow-all only when the controller is managing ACLs (custom ACL list).

This issue also appears on line 275 of the same file.

### Restricting Source Traffic

There are two independent layers, and they are configured separately:

| Layer | Configured by | Default |
| --- | --- | --- |
| CloudStack load balancer rule | `service.beta.kubernetes.io/cloudstack-load-balancer-source-cidrs` annotation | `0.0.0.0/0` |
| Firewall rule (isolated networks) | `spec.loadBalancerSourceRanges` | `0.0.0.0/0` |
| Network ACL (VPC networks) | Not configurable, always `0.0.0.0/0` | `0.0.0.0/0` |

README.md:314

• This implies the load balancer needs the node provider ID to find the CloudStack network. In the current implementation, the load balancer code derives the network ID by listing VMs and matching on node names (verifyHosts in cloudstack_loadbalancer.go), not via spec.providerID. Consider removing the claim that provider IDs are required for load balancer provisioning, and keep this as a general note about initialization.

Initialization is also what assigns a node its provider ID (`external-cloudstack://<instance UUID>`),
which the load balancer needs to find the CloudStack network to create rules in. If the nodes were
never initialized, LoadBalancer services stay in `<pending>` — see [Troubleshooting](#troubleshooting).

README.md:277

• This bullet says ACL rules are "always" created allowing 0.0.0.0/0, but the very next bullet says the controller does not add ACL rules for default ACL lists (default_allow/default_deny). Rewording the first bullet to make it conditional on the controller actually managing ACLs avoids the contradiction.

Two things to be aware of on a VPC:
* ACL rules are always created allowing `0.0.0.0/0`; `spec.loadBalancerSourceRanges` is not applied.
  Use the `cloudstack-load-balancer-source-cidrs` annotation to restrict sources.