diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml index d04a215..69269aa 100644 --- a/.github/workflows/wiki.yml +++ b/.github/workflows/wiki.yml @@ -1,10 +1,17 @@ # File: .github/workflows/wiki.yml on: + release: + types: + - "published" workflow_dispatch: name: Publish Wiki +permissions: + contents: write + pull-requests: write + jobs: build-publish-wiki: runs-on: ubuntu-22.04 @@ -17,24 +24,37 @@ jobs: - name: Checkout Wiki uses: actions/checkout@v3 with: - repository: cloudyspells/PSWattTime.wiki + repository: ${{github.repository}}.wiki path: wiki - - name: Copy README.md as quickstart.md + - name: Copy wiki base sources shell: bash run: | - cp ./main/README.md ./wiki/quickstart.md + cp ./main/docs/wiki-src/*.md ./wiki/ + + - name: Login to Az PowerShell Module + uses: azure/login@v1 + with: + creds: ${{ secrets.AZURE_CREDENTIALS }} + enable-AzPSSession: true - name: Generate Module docs shell: pwsh run: | + Set-PSRepository PSGallery -InstallationPolicy Trusted + Install-Module Az.Resources Install-Module PlatyPS Import-Module PlatyPS Import-Module ./main/src/PSWattTime - New-MarkdownHelp -Module PSWattTime -Force -OutputFolder ./wiki/ + New-MarkdownHelp -Module PSWattTime ` + -Verbose ` + -Force ` + -NoMetadata ` + -OutputFolder ./wiki/ - name: Commit and push changes to wiki shell: bash + working-directory: ./wiki run: | git config user.name github-actions git config user.email github-actions@github.com diff --git a/docs/ConvertFrom-AzureRegion.md b/docs/ConvertFrom-AzureRegion.md index c2c3998..8699406 100644 --- a/docs/ConvertFrom-AzureRegion.md +++ b/docs/ConvertFrom-AzureRegion.md @@ -1,10 +1,3 @@ ---- -external help file: PSWattTime-help.xml -Module Name: PSWattTime -online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/ConvertFrom-AzureRegion.md -schema: 2.0.0 ---- - # ConvertFrom-AzureRegion ## SYNOPSIS diff --git a/docs/Get-AzureRegionWithLowestWattTime.md b/docs/Get-AzureRegionWithLowestWattTime.md index eb70cba..c601162 100644 --- a/docs/Get-AzureRegionWithLowestWattTime.md +++ b/docs/Get-AzureRegionWithLowestWattTime.md @@ -1,10 +1,3 @@ ---- -external help file: PSWattTime-help.xml -Module Name: PSWattTime -online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-AzureRegionWithLowestWattTime.md -schema: 2.0.0 ---- - # Get-AzureRegionWithLowestWattTime ## SYNOPSIS diff --git a/docs/Get-WattTime.md b/docs/Get-WattTime.md index 56882e7..63069b5 100644 --- a/docs/Get-WattTime.md +++ b/docs/Get-WattTime.md @@ -1,10 +1,3 @@ ---- -external help file: PSWattTime-help.xml -Module Name: PSWattTime -online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md -schema: 2.0.0 ---- - # Get-WattTime ## SYNOPSIS diff --git a/docs/Get-WattTimeAuthToken.md b/docs/Get-WattTimeAuthToken.md index fcaaa1c..8b589cb 100644 --- a/docs/Get-WattTimeAuthToken.md +++ b/docs/Get-WattTimeAuthToken.md @@ -1,10 +1,3 @@ ---- -external help file: PSWattTime-help.xml -Module Name: PSWattTime -online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md -schema: 2.0.0 ---- - # Get-WattTimeAuthToken ## SYNOPSIS diff --git a/docs/Get-WattTimeForAzureRegion.md b/docs/Get-WattTimeForAzureRegion.md index 59dc273..f20c2f5 100644 --- a/docs/Get-WattTimeForAzureRegion.md +++ b/docs/Get-WattTimeForAzureRegion.md @@ -1,10 +1,3 @@ ---- -external help file: PSWattTime-help.xml -Module Name: PSWattTime -online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeForAzureRegion.md -schema: 2.0.0 ---- - # Get-WattTimeForAzureRegion ## SYNOPSIS diff --git a/docs/New-WattTimeAccount.md b/docs/New-WattTimeAccount.md index 94a60c7..187709b 100644 --- a/docs/New-WattTimeAccount.md +++ b/docs/New-WattTimeAccount.md @@ -1,10 +1,3 @@ ---- -external help file: PSWattTime-help.xml -Module Name: PSWattTime -online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/New-WattTimeAccount.md -schema: 2.0.0 ---- - # New-WattTimeAccount ## SYNOPSIS diff --git a/docs/wiki-src/Home.md b/docs/wiki-src/Home.md new file mode 100644 index 0000000..982bd2f --- /dev/null +++ b/docs/wiki-src/Home.md @@ -0,0 +1,30 @@ +PSWattTime Wiki +=============== + +PowerShell module for [WattTime.org](https://www.watttime.org/) API +------------------------------------------------------------------- + +[![PowerShell Module Quality Assurance](https://github.com/cloudyspells/PSWattTime/actions/workflows/qa.yml/badge.svg)](https://github.com/cloudyspells/PSWattTime/actions/workflows/qa.yml) +![GitHub release (latest by date)](https://img.shields.io/github/v/release/cloudyspells/PSWattTime) +![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/PSWattTime) +![PowerShell Gallery](https://img.shields.io/powershellgallery/dt/PSWattTime) + + +This PowerShell module is intended for retrieving emissions data from +[WattTime](https://www.watttime.org/) 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](https://github.com/Green-Software-Foundation/carbon-aware-sdk) +by the [Green Software Foundation](https://greensoftware.foundation/) diff --git a/docs/wiki-src/quickstart-github-action.md b/docs/wiki-src/quickstart-github-action.md new file mode 100644 index 0000000..6f9f175 --- /dev/null +++ b/docs/wiki-src/quickstart-github-action.md @@ -0,0 +1,52 @@ +Getting started with PSWattTime +=============================== + +Steps for using the 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 + +```yaml + +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@v1.0.4 + 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 +``` diff --git a/docs/wiki-src/quickstart-powershell.md b/docs/wiki-src/quickstart-powershell.md new file mode 100644 index 0000000..2c32eac --- /dev/null +++ b/docs/wiki-src/quickstart-powershell.md @@ -0,0 +1,75 @@ +Getting started with PSWattTime +=============================== + +Steps for using the module in PowerShell +---------------------------------------- + +To get started with this module you will need an account on +[WattTime](https://www.watttime.org/). See +[the manual](https://www.watttime.org/api-documentation/#register-new-user) +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](https://learn.microsoft.com/en-us/powershell/azure/install-az-ps) +for the _Az_ module for instructions. + +To install the module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/PSWattTime/). + +```powershell +Install-Module -Name PSWattTime +``` + +To register an account with _WattTime_: + +```powershell +New-WattTimeAccount -Username ` + -Password '' ` + -Email '' ` + -Organization +``` + + +Authenticate to the _WattTime_ API: + +```powershell + $token = Get-WattTimeAuthToken -Username '' ` + -Password '' +``` + +Get current percentage of energy with emissions the 'westeurope' Azure region: + +```powershell +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: + +```powershell +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](docs/ConvertFrom-AzureRegion.md) +- [Get-AzureRegionWithLowestWattTime](docs/Get-AzureRegionWithLowestWattTime.md) +- [Get-WattTime](docs/Get-WattTime.md) +- [Get-WattTimeAuthToken](docs/Get-WattTimeAuthToken.md) +- [Get-WattTimeForAzureRegion](docs/Get-WattTimeForAzureRegion.md) +- [New-WattTimeAccount](docs/New-WattTimeAccount.md)