Carbon Aware Scheduler

A Kubernetes-native scheduler that optimizes job execution based on carbon intensity forecasts from WattTime API. This scheduler helps reduce the carbon footprint of your workloads by scheduling them during periods of lower carbon intensity.

Features

• Carbon-aware job scheduling based on WattTime API forecasts
• Support for multiple cloud regions and time windows
• Calculation of carbon savings compared to worst-case, naive, and median scheduling options
• Kubernetes-native deployment via Helm chart

Installation

Prerequisites

• Kubernetes cluster (v1.19+)
• Helm v3+
• WattTime API credentials

Installing from Chart Repository

You can install the carbon-aware scheduler via Helm:

# Add the carbon-aware Helm repository
helm repo add carbon-aware https://carbon-aware.github.io/charts

# Update your Helm repositories
helm repo update

# Install the scheduler chart (replace <namespace> with your target namespace)
helm install ca-scheduler -n <namespace> carbon-aware/scheduler

Installing from Local Chart

To install the chart from a local clone of this repository:

# Clone the repository
git clone https://github.com/carbon-aware/scheduler.git
cd scheduler

# Install the chart
helm install ca-scheduler -n <namespace> ./helm/scheduler

Configuration

Ensure you've included WattTime credentials in a secret in your namespace. Create a secret with your WattTime credentials:

kubectl create secret generic watttime-credentials \
  --from-literal=username=your-username \
  --from-literal=password=your-password \
  -n <namespace>

Refer to the values.yaml file in the chart for additional configuration options.

Development

Prerequisites

• Python 3.13+
• Tilt
• kubectl
• kind
• ctlptl

Setting Up Development Environment

1. Clone the repository:

   git clone https://github.com/carbon-aware/scheduler.git
   cd scheduler

2. Run the setup script to set up your development environment:

   # Make the script executable
   chmod +x scripts/setup-dev.sh
   # Run the setup script
   ./scripts/setup-dev.sh

   This script will:

   • Check for uv installation
   • Create and activate a Python virtual environment
   • Install project dependencies using uv sync
   • Set up pre-commit hooks

Local Development with Tilt

1. Start a kind cluster:

   ctlptl create cluster kind --name kind-ca-scheduler

2. Start Tilt:

   tilt up

3. Access the scheduler API at: http://localhost:8080

Running Tests

python -m pytest

Building the Docker Image

docker build -t carbon-aware/scheduler:dev ./scheduler

Region Mapping

The region mapping is generated by the scripts/codegen_regions.py script. This script fetches the region data from the ElectricityMaps GitHub repository and generates the region mapping file.

To run the script the following from the scheduler directory:

python -m scripts.codegen_regions

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.