Greenhopper 1.0.0

dotnet add package Greenhopper --version 1.0.0                
NuGet\Install-Package Greenhopper -Version 1.0.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Greenhopper" Version="1.0.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Greenhopper --version 1.0.0                
#r "nuget: Greenhopper, 1.0.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Greenhopper as a Cake Addin
#addin nuget:?package=Greenhopper&version=1.0.0

// Install Greenhopper as a Cake Tool
#tool nuget:?package=Greenhopper&version=1.0.0                

Testing Update carbon-aware SDK

Nuget Publishment Nuget (with prereleases)

alternate text is missing from this package README image

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
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0 207 4/29/2023
0.6.6 169 4/29/2023
0.6.5 174 4/29/2023
0.6.4 177 4/28/2023
0.6.3 173 4/28/2023
0.6.2 179 4/28/2023
0.5.2 180 4/28/2023
0.5.0 164 4/28/2023
0.4.0 254 3/8/2023
0.3.4 303 12/23/2022
0.3.3 298 12/23/2022
0.3.1 288 12/23/2022
0.2.3 315 12/19/2022
0.2.2 288 12/18/2022
0.2.1 291 12/18/2022
0.2.0 299 12/18/2022
0.1.0 302 12/18/2022
0.0.5 308 12/16/2022
0.0.4 303 12/16/2022