Add a simulated dev/test environment and simulator-based e2e CI

[vishesh92]

Fixes #4

What this does

Issue #4 asked for documentation on running kube-apiserver and
cloudstack-simulator locally, "preferring containers so automated test
workloads can be implemented later." This does both halves.

make e2e-up brings up a complete, unmocked stack in about seven minutes: a
kind cluster, the CloudStack simulator with its advanced zone deployed,
CloudStack VMs matching the kind nodes, and the CCM built from the checkout.
docs/development.md walks through the same steps manually, so the environment
can be understood and debugged rather than just invoked.

make e2e-up
kubectl create deployment web --image=nginx
kubectl expose deployment web --port=80 --type=LoadBalancer
kubectl get svc web -w      # EXTERNAL-IP arrives from 192.168.2.0/24
make test-e2e
make e2e-down

Why it is worth the files

EnsureLoadBalancer, UpdateLoadBalancer and EnsureLoadBalancerDeleted had
no tests. Only their helpers did, and those mostly pass gomock.Any() for
request parameters, so what the CCM actually sends to CloudStack was largely
unverified. The new suite is 15 tests covering load balancer lifecycle, node
initialization, annotations and session affinity, and the VPC/network ACL path
against a real management server.

It lives in test/e2e behind the e2e build tag, so it stays out of
make test and go build ./..., and it needs no new module dependencies.

Two bugs this found

Both affect anyone running the CCM against a CloudStack project, and both
are fixed here:

• updateNetworkACL fetched the network and its ACL list without project
  scoping. On a VPC owned by a project, every LoadBalancer service failed with
  error fetching Network with ID: ... No match found and never received an
  ingress address.
• getNetworkIDFromIPAddress had the same omission on two calls, which breaks
  load balancer deletion for projects.

The fix is four added cloudstack.WithProject(...) arguments, matching what
the neighbouring call sites already do. Note this is distinct from the
could not find network case in the Troubleshooting section, which is in
associatePublicIPAddress and was already scoped correctly.

CI

.github/workflows/e2e-simulator.yml runs on pull requests and pushes to
main, as a 2x2 matrix:

Kubernetes	CloudStack
v1.37.0, v1.36.4	4.22.1.0, 4.20.2.0

The CloudStack axis buys branch coverage, not just version coverage: 4.22+
updates a rule's CIDR list in place, 4.20 deletes and recreates it. A shared
build job compiles the image once and the four cells run in parallel, so the
workflow takes roughly as long as a single run (~15 minutes). Failures upload
simulator logs, CCM logs, node and service dumps, and CloudStack-side state.

Not added as a required check in .asf.yaml yet — worth letting it prove
itself stable first.

Known limitation

kind starts kubelet with --provider-id=kind://..., and Kubernetes only lets a
provider ID be set once, so the CCM never assigns
external-cloudstack://<uuid> in this environment. TestNode_ProviderID
detects that, logs the value it would have assigned, and reports itself as
skipped, so the gap stays visible instead of quietly passing. It is called out
in the docs.

Notes for reviewers

• The README's Debugging section moved to docs/development.md, where the
  launch.json snippet now points at the harness-generated
  cloud-config-host and kubeconfig. The README keeps a pointer to it.
• The stale cloudstack/simulator Docker Hub link is corrected to
  apache/cloudstack-simulator.
• .gitignore now covers the local cloud-config, cmk-config and
  kube-config files. They hold live credentials and were previously
  untracked but not ignored.
• Mock expectations in cloudstack_loadbalancer_test.go gained a
  gomock.Any() argument for the new variadic project option, matching the
  existing project-scoped call sites.

Testing

Ran the full harness locally against apache/cloudstack-simulator:

• 12/13 phase-1 e2e tests pass, 1 informative skip (provider ID, above)
• both VPC-phase tests pass, and failed before the project-scoping fix
• make test, golangci-lint run and go build ./... are clean
• artifact collection and teardown verified; teardown leaves nothing behind

The CCM's k8s.io/* v0.24 libraries worked fine against a v1.37 API server.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 76.19048% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 50.56%. Comparing base (151452f) to head (f5f9f69).

Files with missing lines	Patch %	Lines
cloudstack_loadbalancer.go	70.58%	4 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #105      +/-   ##
==========================================
+ Coverage   50.05%   50.56%   +0.50%     
==========================================
  Files           4        4              
  Lines         975      981       +6     
==========================================
+ Hits          488      496       +8     
+ Misses        473      471       -2     
  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]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 4 comments.

Suppressed comments (1)

cloudstack_loadbalancer.go:487

• The netErr branch returns the wrong error variable (it returns err from the previous GetPublicIpAddressByID call). If the first call succeeded (err==nil) but GetNetworkByID fails, this currently returns a nil error and masks the failure.

		network, _, netErr := cs.client.Network.GetNetworkByID(ip.Associatednetworkid, cloudstack.WithProject(cs.projectID))
		if netErr != nil {
			klog.Errorf("Failed to fetch the network for id: %v", ip.Associatednetworkid)
			return "", err
		}

[Copilot]

Pull request overview

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

[Copilot]

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.

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 5 comments.

[Copilot]

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.

Pull request overview

Copilot reviewed 26 out of 27 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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