README.md

PSElectricityMaps

PowerShell Module for ElectricityMaps emission data

This PowerShell module is intended for retrieving emissions data from CO2 Signal for a supplied Azure Region during resource deployments. This is a lightweight solution making use of non-commercial functionality available with a free account at ElectricityMaps. 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

NOTE: ElectricityMaps is currently migrating from co2signal.com. Until migration is finished you will have to register a new account there. The module's API calls also still point to co2signal.com and will be updated by the author as migration proceeds.

Usage

PowerShell Module

To get started with this module you will need an account on ElectricityMaps. See the website for details on registering and the conditions that apply.

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 PSElectricityMaps

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

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

Region               : westeurope
FossilFuelPercentage : 29.37
CountryCode          : NL
CarbonIntensity      : 231
CarbonIntensityUnit  : gCO2eq/kWh
Timestamp            : 3/26/2023 8:00:00 AM

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

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

Region               : westeurope
FossilFuelPercentage : 29.37
CountryCode          : NL
CarbonIntensity      : 231
CarbonIntensityUnit  : gCO2eq/kWh
Timestamp            : 3/26/2023 8:00:00 AM

Module Functions

• Get-ElectricityMapsForAzureRegion
• Get-ElectricityMapsBestAzureRegion

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 ElectricityMaps 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/PSElectricityMaps@main
        id: signal_action # Set step id for using output in deployment
        with:
          azure_credential: ${{ secrets.AZURE_CREDENTIALS }}
          signal_token: ${{ secrets.SIGNALTOKEN }}
          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.signal_action.outputs.region }} # The region output from PSElectricityMaps
          template: src/bicep/main.bicep