Kubernetes Node Role Labeler

Kubernetes controller that automatically assigns node roles based on a configurable label value (e.g., nodeGroup=gpu-worker becomes node-role.kubernetes.io/gpu-worker).

By default, kubeadm enables the NodeRestriction admission controller that restricts what labels kubelet can self-apply on node registration. The node-role.kubernetes.io/* label is restricted and can't be set in cloud init scripts or during other node bootstrap processes.

1. Nodes are labeled with a source label (e.g., nodeGroup=gpu-worker).
2. The controller watches Node add/update events via a Kubernetes informer, scoped to nodes that carry the source label.
3. When a node has the source label, the controller patches it with node-role.kubernetes.io/<value> via a strategic merge patch with bounded exponential backoff.
4. In replace mode, any stale node-role.kubernetes.io/* labels (other than the desired one) are removed in the same patch.
5. Leader election via coordination.k8s.io/Lease ensures only one replica reconciles at a time when running with replicas >= 2.

Readiness (/readyz) returns 503 until the informer cache has synced — and, when leader election is enabled, until the replica is the active leader.

Example: A node with nodeGroup=gpu-worker gets node-role.kubernetes.io/gpu-worker.

The Helm chart and the prebuilt manifest install into different namespaces by default:

helm upgrade --install works for both fresh installs and upgrades:

helm upgrade --install node-role-controller \
  oci://ghcr.io/mchmarny/node-role-controller \
  -n node-role-controller --create-namespace

To schedule on tainted nodes, add tolerations:

helm upgrade --install node-role-controller \
  oci://ghcr.io/mchmarny/node-role-controller \
  -n node-role-controller --create-namespace \
  --set-json 'tolerations=[{"key":"dedicated","value":"system-workload","operator":"Equal","effect":"NoExecute"},{"key":"dedicated","value":"system-workload","operator":"Equal","effect":"NoSchedule"}]'

To enable Prometheus Operator scraping and a PodDisruptionBudget:

helm upgrade --install node-role-controller \
  oci://ghcr.io/mchmarny/node-role-controller \
  -n node-role-controller --create-namespace \
  --set replicas=2 \
  --set serviceMonitor.enabled=true \
  --set podDisruptionBudget.enabled=true

kubectl apply -f https://raw.githubusercontent.com/mchmarny/rolesetter/refs/heads/main/deployment/manifest.yaml

kubectl apply -k deployment/overlays/prod

The controller is configured via environment variables sourced from a ConfigMap. With Helm, set values directly:

helm upgrade --install node-role-controller \
  oci://ghcr.io/mchmarny/node-role-controller \
  -n node-role-controller --create-namespace \
  --set config.roleLabel=nodeGroup \
  --set config.roleReplace=true \
  --set config.logLevel=debug

Environment variables (when running the binary directly or via the manifests):

After changing configuration, restart to apply: kubectl -n node-role-controller rollout restart deployment node-role-controller

helm uninstall node-role-controller -n node-role-controller

Default port: 8080. Override with SERVER_PORT.

The binary prints build metadata injected at release time:

node-role-controller -version
# node-role-controller v0.7.0 (commit abcdef0, built 2026-06-06T12:34:56Z)

Every release includes SLSA provenance attestation:

export IMAGE=ghcr.io/mchmarny/node-role-controller:v0.6.0

cosign verify-attestation \
    --output json \
    --type slsaprovenance \
    --certificate-identity-regexp 'https://github.com/.*/.*/.github/workflows/.*' \
    --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
    $IMAGE

To enforce verification in-cluster with the Sigstore policy controller:

kubectl label namespace node-labeler policy.sigstore.dev/include=true
kubectl apply -f policy/clusterimagepolicy.yaml

See CONTRIBUTING.md. Run make pre before submitting PRs.

This is my personal project and it does not represent my employer. While I do my best to ensure that everything works, I take no responsibility for issues caused by this code.