feat(): initial untested implementation

README.md

@@ -1,2 +1,95 @@
 # k8s-cilium-node-label
 
+## Description
+
+- Purpose: Small controller/tool that discovers Cilium L2 announcement leases in the `kube-system` namespace and labels the corresponding Kubernetes nodes. Useful to mark nodes that are announcing L2 services (for example, to drive MetalLB or other consumers).
+- Where: Core logic lives in [internal/kube.go](internal/kube.go).
+
+## Features
+
+- Discover leases: Finds leases with the `cilium-l2announce*` prefix.
+- Parse holder identity: Extracts node names from lease `spec.holderIdentity`.
+- Label nodes: Labels nodes with a configurable label when they are announcing L2 addresses.
+
+## Requirements
+
+- Go 1.20+ (or the version used in your environment).
+- Kubernetes cluster (the binary is intended to run in-cluster by default).
+- RBAC: a ServiceAccount with permissions to list/watch `leases` (coordination.k8s.io) and get/update `nodes`.
+
+## Configuration
+
+- By default the code uses in-cluster configuration (`rest.InClusterConfig()`), so run it as a Pod.
+- The label key used for nodes is configurable in the code (`Config.CiliumLabel` in callers).
+
+## Build
+
+Build locally:
+
+```bash
+go build ./...
+```
+
+Run directly:
+
+```bash
+# Run from the repository root (may require KUBECONFIG for out-of-cluster testing)
+go run ./cmd
+```
+
+## Running in-cluster
+
+- Create a small Deployment with a ServiceAccount that has RBAC permitting access to `leases` and `nodes`.
+- Example RBAC (high-level):
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: cilium-node-labeler
+rules:
+  - apiGroups: ["coordination.k8s.io"]
+    resources: ["leases"]
+    verbs: ["list", "watch"]
+  - apiGroups: [""]
+    resources: ["nodes"]
+    verbs: ["get", "update"]
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: cilium-node-labeler-binding
+subjects:
+  - kind: ServiceAccount
+    name: <service-account-name>
+    namespace: <namespace>
+roleRef:
+  kind: ClusterRole
+  name: cilium-node-labeler
+  apiGroup: rbac.authorization.k8s.io
+```
+
+## Development
+
+- Main source: [internal/kube.go](internal/kube.go). The informer-based lease discovery is implemented in `GetCiliumL2Leases()`.
+- CLI entrypoint: [cmd/main.go](cmd/main.go).
+
+## Testing
+
+- Run unit tests:
+
+```bash
+go test ./...
+```
+
+## Next steps / TODOs
+
+- Add CI/CD gitea workflows.
+- Add Helm Chart for easy deployment.
+- Add integration tests that run against a kind cluster to validate in-cluster behaviour.
+- Add a long-running informer with event handlers to react to lease changes instead of polling.
+
+## License
+
+- See the `LICENSE` file in this repository.