PSWattTime

PowerShell Module for WattTime emission data

This PowerShell module is intended for retrieving emissions data from WattTime for a supplied Azure Region during resource deployments. This is a lightweight solution making use of only the limited functionality available with a free account at WattTime. This means the module is only able to get near-realtime emissions data and no prodictive values. This means this module is not a real solution for reduced carbon deployments and -software. It does however provide some nice realtime values so you can simulate the beheaviour of deployments and software based on emissions data without the cost of a paid account for such data. For example in lab- or proof of concept environments.

The intended use of this module is for setting the Location parameter on Azure IaC deployments in GitHub workflows using the included GitHub action.

For a real-world solution with a commercial data provider, check out the carbon-aware-sdk by the Green Software Foundation

Usage

PowerShell Module

To get started with this module you will need an account on WattTime. See the manual on registering an account. The module provides a function New-WattTimeAccount to create an account if you do not yet have one.

You will also need the Az.Resources PowerShell Module for Azure installed and connected to your Azure account. See the installation manual for the Az module for instructions.

To install the module from the PowerShell Gallery.

Install-Module -Name PSWattTime

To register an account with WattTime:

New-WattTimeAccount -Username <YOUR_USERNAME> `
  -Password '<YOUR_PASSWORD>' `
  -Email '<you@domain.com>' `
  -Organization <YOUR_ORGANIZATION>

Authenticate to the WattTime API:

 $token = Get-WattTimeAuthToken -Username '<YOUR_WATTTIME_USERNAME>' `
  -Password '<YOUR_WATTTIME_PASSWORD>'

Get current percentage of energy with emissions the 'westeurope' Azure region:

PS C:\> Get-WattTimeForAzureRegion -Region westeurope -AuthToken $token

ba         : NL
freq       : 300
percent    : 94
point_time : 5-3-2023 13:15:00
region     : westeurope

Determine the lowest emissions for the list of northeurope, westeurope, francecentral and uksouth Azure regions:

PS C:\> Get-AzureRegionWithLowestWattTime -Regions westeurope,uksouth,northeurope,francecentral -AuthToken $token

ba         : IE
freq       : 300
percent    : 69
point_time : 5-3-2023 14:15:00
region     : northeurope

Module Functions

• ConvertFrom-AzureRegion
• Get-AzureRegionWithLowestWattTime
• Get-WattTime
• Get-WattTimeAuthToken
• Get-WattTimeForAzureRegion
• New-WattTimeAccount

GitHub Action

This PowerShell module also comes with a GitHub Action you can use in your GitHub workflows. Again you will need a pre-existing account for WattTime and an Azure CLI/PowerShell secret configured in your repo

Example

on:
  pull_request:
    branches:
      - 'main'
      - 'releases/**'

name: Deploy to region with lowest emissions

jobs:
  deploy-to-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Get region with lowest emissions
        uses: cloudyspells/PSWattTime@main
        id: watttime_action # Set step id for using output in deployment
        with:
          azure_credential: ${{ secrets.AZURE_CREDENTIALS }}
          watttime_username: ${{ secrets.WATTTIMEUSERNAME }}
          watttime_password: ${{ secrets.WATTTIMEPASSWORD }}
          regions: '"westeurope","northeurope","uksouth","francecentral","germanynorth"'

      - name: Login to Az PowerShell Module
        uses: azure/login@v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
          enable-AzPSSession: true

      - uses: azure/arm-deploy@v1
        name: Run Bicep deployment
        with:
          subscriptionId: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
          scope: subscription
          region: ${{ steps.watttime_action.outputs.region }} # The region output from PSWattTime
          template: src/bicep/main.bicep