Kubernetes: reconfiguration, networking, tests, and documentation

[ArshSSandhu]

Parent: #441

Depends on: Kubernetes workload lifecycle and status

Summary

Complete the initial Kubernetes integration by supporting workload reconfiguration, handling Kubernetes networking semantics, adding end-to-end testing, and documenting local setup and RBAC.

Reconfiguration

Update an existing Kubernetes Deployment when Manager configuration changes.

Support:

• environment variables
• entrypoint/command
• CPU
• memory

Patch the existing Deployment's Pod template rather than replacing the Manager workload identity.

Allow Kubernetes Deployment rollout behavior to replace Pods.

Rollout waiting

After modifying the Deployment:

• wait for the updated generation to be observed
• wait for the desired replica to become available
• use a bounded timeout
• report useful rollout failure information

Networking

Kubernetes networking differs from Proxmox.

A Kubernetes workload must not require a stable MAC address.

For Kubernetes:

macAddress = null

must be valid.

Creation and reconfiguration must not fail solely because a MAC address is unavailable.

Pod IP

Manager may discover and expose the current Ready Pod's IP.

However, Pod IP must be treated as ephemeral because it may change after:

• restart
• rescheduling
• rollout
• node failure

Do not use Pod identity or Pod IP as the permanent Manager workload identity.

Shared provider cleanup

Refactor shared creation/reconfiguration logic so it does not universally assume:

• stable MAC address
• stable IP address
• Proxmox VMID
• Proxmox task IDs
• Proxmox storage
• LXC configuration

Avoid unnecessary Kubernetes-specific branches in shared jobs.

NetBox and DNS

Do not register an ephemeral Kubernetes Pod IP as permanent infrastructure state.

For the initial integration, skip unsupported NetBox/DNS behavior when no stable Kubernetes network endpoint exists.

Stable Service/Ingress networking should be handled separately.

RBAC documentation

Document least-privilege permissions required by Manager.

Manager should not require cluster-admin.

Prefer namespace-scoped permissions for workload operations.

Document any cluster-scoped node discovery permission separately.

Only grant access to Kubernetes resources actually required by the implementation.

Local integration test

Document and test the complete flow using Docker Desktop Kubernetes or kind.

Test using an image such as:

nginx:latest

Flow:

1. Configure Kubernetes node.
2. Validate Kubernetes API connection.
3. Create Manager container.
4. Verify Deployment.
5. Verify Ready Pod.
6. Verify Manager reports running.
7. Stop workload.
8. Verify replicas = 0.
9. Start workload.
10. Verify replicas = 1.
11. Change environment variable.
12. Verify Deployment rollout.
13. Change CPU/memory.
14. Verify Deployment rollout.
15. Read current Pod IP.
16. Confirm MAC may remain null.
17. Delete workload.
18. Verify Deployment and Pods are removed.

Automated tests

Add tests covering:

• reconfiguration patches
• environment updates/removal
• entrypoint updates
• CPU updates
• memory updates
• rollout waiting
• rollout timeout
• Pod discovery
• Pod IP handling
• nullable MAC behavior
• provider-neutral network behavior
• existing provider regression cases

Normal CI should not require a real Kubernetes cluster.

Documentation

Document:

• Kubernetes architecture
• node configuration
• kubeconfig usage
• namespace behavior
• local Kubernetes setup
• workload lifecycle
• reconfiguration
• RBAC
• networking limitations
• ephemeral Pod IP behavior
• unsupported features

Acceptance criteria

• Environment changes update the Deployment.
• Entrypoint changes update the Deployment.
• CPU changes update the Deployment.
• Memory changes update the Deployment.
• Reconfiguration waits for Kubernetes rollout completion.
• Rollout waiting has a bounded timeout.
• Kubernetes workloads may have macAddress = null.
• Pod IP can be discovered when available.
• Pod IP is treated as ephemeral.
• Shared jobs no longer universally require Proxmox-style network information.
• Kubernetes does not persist misleading ephemeral NetBox/DNS state.
• Least-privilege RBAC documentation exists.
• Local Kubernetes setup documentation exists.
• Full create/start/stop/reconfigure/delete test succeeds.
• Automated tests pass.
• Existing Proxmox, Docker, and Dummy functionality remains working.

Non-goals

The initial integration does not include:

• Kubernetes Services
• Ingress
• LoadBalancers
• NodePorts
• PersistentVolumes
• StatefulSets
• DaemonSets
• Jobs/CronJobs
• Helm
• autoscaling
• multi-container Pods
• arbitrary replica management
• pod exec/log streaming
• Kubernetes cluster creation