Skip to content

Update README to improve clarity and add troubleshooting and FAQs - #103

Merged
DaanHoogland merged 2 commits into
apache:mainfrom
shapeblue:update-readme
Aug 26, 2026
Merged

DaanHoogland merged 2 commits into
apache:mainfrom
shapeblue:update-readme

Conversation

@vishesh92

@vishesh92 vishesh92 commented Aug 25, 2026 •

Copy link
Copy Markdown
Member

Fixes #92 #100

Copilot AI lite review requested due to automatic review settings August 25, 2026 09:27
@vishesh92 vishesh92 linked an issue Aug 25, 2026 that may be closed by this pull request

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread README.md Resolved
Copilot AI review requested due to automatic review settings August 25, 2026 09:43

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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

Comment thread README.md Resolved
Comment thread README.md Resolved
Comment thread README.md Resolved
@codecov-commenter

codecov-commenter commented Aug 25, 2026 •

Copy link
Copy Markdown

Codecov Report

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

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 AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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

Comment thread README.md Resolved
Comment thread README.md Resolved
Copilot AI review requested due to automatic review settings August 26, 2026 11:20

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot AI review requested due to automatic review settings August 26, 2026 12:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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

Comment thread README.md Resolved
Comment thread README.md Resolved
Comment thread README.md Resolved
Copilot AI review requested due to automatic review settings August 26, 2026 13:09

@sureshanaparti sureshanaparti left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

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

Suppressed comments (2)

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

README.md:185

  • The description of service.beta.kubernetes.io/cloudstack-load-balancer-ip-associated-by-controller implies the annotation is set whenever the controller associates an IP that wasn’t already allocated, but the controller only sets it when it had to associate the user-specified spec.loadBalancerIP (so it can decide whether to disassociate that IP on deletion). Auto-allocated IPs are released without relying on this annotation, so the current wording is misleading.
**Description:** Set by the controller, not by you. When the controller associates a public IP that
was not already allocated, it records that fact on the service with this annotation. On deletion the
annotation determines whether the IP is disassociated again: an IP the controller allocated is
released, an IP that was already allocated before the service existed is left in place.

README.md:200

  • The table row for Network ACL rules shows a default of 0.0.0.0/0, but the controller does not create ACL rules when the network uses the default ACL lists (default_allow / default_deny). In those cases the effective default depends on the ACL list, so it’s worth qualifying this row to avoid implying the controller always opens ACLs to all sources.
| Network ACL rule — VPC networks without the Firewall service | Not configurable | `0.0.0.0/0` |

@DaanHoogland
DaanHoogland merged commit 151452f into apache:main Aug 26, 2026
5 checks passed
@DaanHoogland
DaanHoogland deleted the update-readme branch August 26, 2026 13:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

How customize loadbalancer config? Unclear infomation on service.beta.kubernetes.io/cloudstack-load-balancer-source-cidrs

5 participants