Karbonetes

Karbonetes is a Kubernetes-based system for carbon-aware batch scheduling with Karpenter. It focuses on run-to-completion workloads in Phase 1 and decides whether a Job should run now, wait for a greener time window, or fall back to a default node pool after a maximum delay.

The current repository contains a demo-ready Phase 1 implementation built with Go, controller-runtime style reconciliation, a mutating admission webhook, a mock carbon signal service, Helm packaging, and sample Karpenter manifests.

Phase 1 scope

• Single Kubernetes cluster
• Karpenter-managed node provisioning
• Two NodePools: default and green-batch
• Run-to-completion workloads only: Job and CronJob
• No live migration of running pods
• No multi-region orchestration
• Mock carbon signal source based on static green windows

Desired behavior

1. Carbon-aware Jobs are marked with carbon-aware.io/enabled: "true".
2. If the current carbon window is green, the admission webhook injects scheduling preferences so the workload prefers the green-batch NodePool.
3. If the current carbon window is not green, the Job is suspended until either a green window arrives or the configured maxDelay expires.
4. If maxDelay expires, the controller releases the Job to the fallback pool.
5. Non-carbon-aware Jobs bypass the system and run immediately.

CronJobs participate indirectly: the webhook and controller operate on the Jobs created by the CronJob controller. To make generated Jobs carbon-aware, place annotations on spec.jobTemplate.metadata.annotations.

System components

• cmd/controller: the main controller manager process
• internal/webhook: mutating admission webhook for batch/v1 Job CREATE
• internal/controller: reconcile loop for suspended carbon-aware Jobs
• cmd/signal: mock carbon signal HTTP service
• api/v1alpha1: CarbonAwarePolicy CRD types
• charts/karbonetes: Helm chart for controller, webhook, signal, RBAC, and CRDs
• config/samples: Karpenter, policy, and workload examples for demos

Documentation

• Architecture
• Implementation Plan
• Roadmap
• Evaluation Guide
• Release Process
• Risks and Tradeoffs
• Monitoring Assets

Quick start

Local verification

make test
make test-envtest
make build
make helm-lint
make helm-template

Example monitoring stack

kubectl apply -k monitoring
kubectl port-forward -n monitoring svc/prometheus 9090:9090
kubectl port-forward -n monitoring svc/grafana 3000:3000

Install CRDs

kubectl apply -f config/crd/bases/

Deploy with Helm

helm upgrade --install karbonetes charts/karbonetes \
  --namespace karbonetes-system \
  --create-namespace

Apply demo resources

kubectl apply -f config/samples/00-namespace.yaml
kubectl apply -f config/samples/karpenter-nodeclass.yaml
kubectl apply -f config/samples/karpenter-nodepool-default.yaml
kubectl apply -f config/samples/karpenter-nodepool-green-batch.yaml
kubectl apply -f config/samples/carbonawarepolicy-default.yaml

Submit sample workloads

kubectl apply -f config/samples/job-plain.yaml
kubectl apply -f config/samples/job-carbon-aware.yaml
kubectl apply -f config/samples/job-carbon-aware-strict.yaml
kubectl apply -f config/samples/cronjob-carbon-aware.yaml

The Makefile also includes demo helpers such as make demo-green-on, make demo-green-off, make demo-submit, make demo-status, and make demo-signal.

Release model

The repository is set up for production-style CI/CD:

• pull requests and main pushes run verification in GitHub Actions
• you decide the semantic version and create the release tag manually
• pushing the tag publishes binaries, multi-arch container images, and the Helm chart through CI/CD
• release artifacts are attached to the GitHub release and pushed to GHCR

See docs/RELEASES.md for the manual tag workflow and GitHub repository settings.

Repository layout

• api/: CRD API types
• cmd/: controller and signal binaries
• internal/carbon/: carbon signal provider interface and adapters
• internal/controller/: Job reconciliation logic
• internal/webhook/: admission webhook mutation logic
• internal/policy/: policy resolution from CRDs and annotations
• internal/metrics/: Prometheus collectors
• charts/karbonetes/: production-style Helm chart
• config/crd/bases/: installable CRD manifests
• config/samples/: demo manifests for policies, NodePools, Jobs, and CronJobs

Current status

Phase 1 is implemented as a hybrid webhook + controller design:

• Jobs are intercepted at creation time
• Green windows trigger immediate green-pool preference
• Non-green windows trigger suspend-and-wait behavior
• Suspended Jobs are later resumed by the controller
• CronJob-owned Jobs are unsuspended in place to preserve CronJob ownership

The next layers of work are mainly hardening, richer carbon signals, stronger state management, and broader scheduling scope.