From edfd52b24d4896a0d462659b280db80b0d5e518c Mon Sep 17 00:00:00 2001 From: Roderick Bant <13252390+webtonize@users.noreply.github.com> Date: Tue, 7 Mar 2023 15:12:36 +0000 Subject: [PATCH] Work on a new release --- .gitattributes | 3 ++ .github/workflows/publish-on-release.yml | 20 ++++++++ .markdownlint.json | 3 ++ README.md | 58 ++++++++++++++++-------- src/PSWattTime/PSWattTime.psd1 | 12 ++--- src/PSWattTime/PSWattTime.psm1 | 2 +- 6 files changed, 71 insertions(+), 27 deletions(-) create mode 100644 .gitattributes create mode 100644 .github/workflows/publish-on-release.yml create mode 100644 .markdownlint.json diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..5dc46e6 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +* text=auto eol=lf +*.{cmd,[cC][mM][dD]} text eol=crlf +*.{bat,[bB][aA][tT]} text eol=crlf \ No newline at end of file diff --git a/.github/workflows/publish-on-release.yml b/.github/workflows/publish-on-release.yml new file mode 100644 index 0000000..7f1e826 --- /dev/null +++ b/.github/workflows/publish-on-release.yml @@ -0,0 +1,20 @@ +# File: .github/workflows/qa.yml + +on: + release: + +name: Publish Module to PSGallery + +jobs: + publish: + runs-on: ubuntu-22.04 + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Publish module + uses: pcgeek86/publish-powershell-module-action@v20 + id: publish-module + with: + NuGetApiKey: ${{ secrets.PS_GALLERY_KEY }} + modulePath: ./src/PSWattTime diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..09e83c0 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,3 @@ +{ + "MD003": {"style": "setext_with_atx" } +} \ No newline at end of file diff --git a/README.md b/README.md index 71967a7..8687980 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,31 @@ PSWattTime ========== -PowerShell Module for getting PSWattTime emission data ------------------------------------------------------- +PowerShell Module for PSWattTime emission data +---------------------------------------------- [![PowerShell Module Quality Assurance](https://github.com/cloudyspells/PSWattTime/actions/workflows/qa.yml/badge.svg)](https://github.com/cloudyspells/PSWattTime/actions/workflows/qa.yml) This PowerShell module is intended for retrieving emissions data from [WattTime](https://www.watttime.org/) for a -supplied Azure Region. +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/) This module is supplied as-is at the moment and not (yet) published through _PSGallery_. @@ -18,31 +35,32 @@ published through _PSGallery_. #### PowerShell Module To get started with this module you will need an account on -[WattTime](https://www.watttime.org/). See +[WattTime](https://www.watttime.org/). See [the manual](https://www.watttime.org/api-documentation/#register-new-user) on registering an account. NOTE: You can only register via the API. -Currently no GUI exists for registration. +Currently no GUI exists for registration. 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. +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. Import the module from a clone of this repository: -``` +```powershell Import-Module .\src\PSWattTime ``` 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 @@ -56,7 +74,7 @@ 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 @@ -73,7 +91,7 @@ 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** +##### Example ```yaml @@ -92,26 +110,26 @@ jobs: - name: Checkout uses: actions/checkout@v3 - - name: Login to Az PowerShell Module - uses: azure/login@v1 - with: - creds: ${{ secrets.AZURE_CREDENTIALS }} - enable-AzPSSession: true - - name: Get region with lowest emissions uses: cloudyspells/PSWattTime@main - id: watttime_action + 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 }} + region: ${{ steps.watttime_action.outputs.region }} # The region output from PSWattTime template: src/bicep/main.bicep ``` diff --git a/src/PSWattTime/PSWattTime.psd1 b/src/PSWattTime/PSWattTime.psd1 index 2581290..d1004e7 100644 --- a/src/PSWattTime/PSWattTime.psd1 +++ b/src/PSWattTime/PSWattTime.psd1 @@ -12,7 +12,7 @@ RootModule = 'PSWattTime.psm1' # Version number of this module. -ModuleVersion = '1.0.0.0' +ModuleVersion = '1.0.1.0' # Supported PSEditions # CompatiblePSEditions = @() @@ -30,7 +30,7 @@ CompanyName = 'Unknown' Copyright = '(c) Roderick Bant. All rights reserved.' # Description of the functionality provided by this module -# Description = '' +Description = 'Simple PowerShell interface getting WattTime emissions data for Azure regions' # Minimum version of the PowerShell engine required by this module # PowerShellVersion = '' @@ -95,19 +95,19 @@ PrivateData = @{ PSData = @{ # Tags applied to this module. These help with module discovery in online galleries. - # Tags = @() + Tags = @('Azure','Emissions','Carbon') # A URL to the license for this module. - # LicenseUri = '' + LicenseUri = 'https://github.com/cloudyspells/PSWattTime/blob/main/LICENSE.md' # A URL to the main website for this project. - # ProjectUri = '' + ProjectUri = 'https://github.com/cloudyspells/PSWattTime' # A URL to an icon representing this module. # IconUri = '' # ReleaseNotes of this module - # ReleaseNotes = '' + ReleaseNotes = 'Initial PSWattTime Release' # Prerelease string of this module # Prerelease = '' diff --git a/src/PSWattTime/PSWattTime.psm1 b/src/PSWattTime/PSWattTime.psm1 index 5da1490..7535a0a 100644 --- a/src/PSWattTime/PSWattTime.psm1 +++ b/src/PSWattTime/PSWattTime.psm1 @@ -48,7 +48,7 @@ function Get-WattTimeAuthToken { The ba to query for .EXAMPLE - Get-WattTime -ba 'AUS-NSW' -AuthToken $authToken + Get-WattTime -ba 'NL' -AuthToken $authToken #> function Get-WattTime { [CmdletBinding()]