README.md

Greenhopper - Decarbonize your non-critical Azure workloads!

Greenhopper is a small >NET library that adds carbon aware capabilities to your Azure Function, converting your non-critical workload to a sustainable one that runs only when the region electricity is greener.

How it works

It uses emissions forecast from Carbon Aware SDK that predicts an optimal window of execution for an estimated workload of X minutes within a specified time frame and for a specific Azure Region. It then uses that prediction to decide if the current execution is within the optimal window and subsequently allows or not the workload execution to complete.

The question it answer is, "I want to run an Azure Function in region West US for 5 minutes sometime within the next 8 hours. Is now the time?"

Getting started

If you prefere a to get you started, he it is CarbonAware.AzureFunction.Sample

Getting started requires four steps:

1. Install the Greenhopper nuget package
2. Add or update your appsetings.json
3. Configure Greenhopper in Program.cs
4. Use DI to ask the question!

Add the nuget package to your project

Install the Greenhopper nuget package, using any of your favorite ways.

Add or update your appsetings.json

{
  "DataSources:ForecastDataSource": "WattTime",
  "DataSources:Configurations:WattTime:Type": "WattTime",
  "DataSources:Configurations:WattTime:Username": "greenhopper",
  "DataSources:Configurations:WattTime:Password": "$gr33nh0pp3r",
  "DataSources:Configurations:WattTime:BaseURL": "https://api2.watttime.org/v2/",
  "DataSources:Configurations:WattTime:Proxy:UseProxy": false,
  "greenhopper:EstimatedExecutionDurationInMinutes": 5, // my func will run for aprox X mins (searches for the optimal time to run an X mins payload)
  "greenhopper:ExecutionTimeFrameInHours": 8, // my func needs to run in the next X hours (searches the optimal time to run an X mins payload in the next X hours)
  "greenhopper:OnNoForecastContinue": false
}

For more configuration options, like using ElectricityMaps instead of WattTime or a test dataset, follow the Carbon Aware SDK appsettings template: https://github.com/Green-Software-Foundation/carbon-aware-sdk/blob/dev/src/CarbonAware.WebApi/src/appsettings.Development.json.template

Configure Greenhopper in Program.cs

using Greenhopper.HostingHostBuilderExtensions; // <-- Add the reference
using Microsoft.Extensions.Hosting;

new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureGreenhopper()                     // <-- Add the configuration
    .Build()
    .Run();

Use DI to ask the question!

public class CarbonAwareFunction1
{
    private readonly IGreenhopperService _greenhopper;

    public Function1(IGreenhopperService greenhopper)
    {
        _greenhopper = greenhopper;
    }

    [Function("CarbonAwareFunction1")]
    public async Task Run([TimerTrigger("0 */5 * * * *")] TimerInfo timerInfo)
    {
        //Reads the environment variable REGION_NAME 
        // from either the local environment variables or from Azure predefined ones
        // when deployed to Azure,
        // and the ExecutionTimeFrameInHours and EstimatedExecutionDurationInMinutes 
        // from either appsettings.json or Azure Function Configuration
        if (!await _greenhopper.IsOptimalWindowNowAsync())
        {
            return;
        }
        
        // - OR -
        
        //Reads the environment variable REGION_NAME internally
        // from either the local environment variables or from Azure predefined ones
        // when deployed to Azure
        if (!await _greenhopper.IsOptimalWindowNowAsync(ExecutionTimeFrameInHours:8, EstimatedExecutionDurationInMinutes:5))
        {
            return;
        }
        //Write your code here
    }
}

Testing vs Production

Carbon Aware SDK (and subsequently Greenhopper) is depended on 3rd party data providers such as WattTime or ElectricityMaps to get the emissions for the region your Azure Function is deployed. For testing and quick onboarding, Greenhopper uses WattTime that gives you unlimited access to one Azure Region ("West US") to try out the library and deploy your workloads.

The username/password included here is for testing only; for production you need to create your own account using the following POST request (there is no UI!):

POST /v2/register HTTP/1.1
Host: api2.watttime.org
Content-Type: application/json
Content-Length: 143

{
    "username": "YOUR USERNAME",
    "password": "YOUR PASSWORD ", //at least 8 characters, with at least 1 of each alpha, number and special characters
    "email": "YOUR EMAIL",
    "org": "YOUR NAME OR ORG"
}

You can also import this Postman Collection.

Ideation

The idea of using Carbon Aware SDK was born in Azure Developer Community Conference 2022. The first introduction was in the same conference during the "Sustainability: Carbon Aware Azure Functions Live Stream" session with a different name, and shortly after the implementation began.

References

1. Carbon Aware Azure Function Sample (Timer Trigger)
2. How to create an account in WattTime
3. Carbon Aware SDK repo
4. Azure Developer Community Conference 2022