Skip to content

Commit 6d75df3

Browse files
webtonizewebtonize
authored
Merge pull request #18 from cloudyspells/feature/wiki
Feature/wiki
2 parents 371664a + 4ae3117 commit 6d75df3

10 files changed

Lines changed: 181 additions & 46 deletions

‎.github/workflows/wiki.yml‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,17 @@
11
# File: .github/workflows/wiki.yml
22

33
on:
4+
release:
5+
types:
6+
- "published"
47
workflow_dispatch:
58

69
name: Publish Wiki
710

11+
permissions:
12+
contents: write
13+
pull-requests: write
14+
815
jobs:
916
build-publish-wiki:
1017
runs-on: ubuntu-22.04
@@ -17,24 +24,37 @@ jobs:
1724
- name: Checkout Wiki
1825
uses: actions/checkout@v3
1926
with:
20-
repository: cloudyspells/PSWattTime.wiki
27+
repository: ${{github.repository}}.wiki
2128
path: wiki
2229

23-
- name: Copy README.md as quickstart.md
30+
- name: Copy wiki base sources
2431
shell: bash
2532
run: |
26-
cp ./main/README.md ./wiki/quickstart.md
33+
cp ./main/docs/wiki-src/*.md ./wiki/
34+
35+
- name: Login to Az PowerShell Module
36+
uses: azure/login@v1
37+
with:
38+
creds: ${{ secrets.AZURE_CREDENTIALS }}
39+
enable-AzPSSession: true
2740

2841
- name: Generate Module docs
2942
shell: pwsh
3043
run: |
44+
Set-PSRepository PSGallery -InstallationPolicy Trusted
45+
Install-Module Az.Resources
3146
Install-Module PlatyPS
3247
Import-Module PlatyPS
3348
Import-Module ./main/src/PSWattTime
34-
New-MarkdownHelp -Module PSWattTime -Force -OutputFolder ./wiki/
49+
New-MarkdownHelp -Module PSWattTime `
50+
-Verbose `
51+
-Force `
52+
-NoMetadata `
53+
-OutputFolder ./wiki/
3554
3655
- name: Commit and push changes to wiki
3756
shell: bash
57+
working-directory: ./wiki
3858
run: |
3959
git config user.name github-actions
4060
git config user.email github-actions@github.com

‎docs/ConvertFrom-AzureRegion.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
---
2-
external help file: PSWattTime-help.xml
3-
Module Name: PSWattTime
4-
online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/ConvertFrom-AzureRegion.md
5-
schema: 2.0.0
6-
---
7-
81
# ConvertFrom-AzureRegion
92

103
## SYNOPSIS

‎docs/Get-AzureRegionWithLowestWattTime.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
---
2-
external help file: PSWattTime-help.xml
3-
Module Name: PSWattTime
4-
online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-AzureRegionWithLowestWattTime.md
5-
schema: 2.0.0
6-
---
7-
81
# Get-AzureRegionWithLowestWattTime
92

103
## SYNOPSIS

‎docs/Get-WattTime.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
---
2-
external help file: PSWattTime-help.xml
3-
Module Name: PSWattTime
4-
online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTime.md
5-
schema: 2.0.0
6-
---
7-
81
# Get-WattTime
92

103
## SYNOPSIS

‎docs/Get-WattTimeAuthToken.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
---
2-
external help file: PSWattTime-help.xml
3-
Module Name: PSWattTime
4-
online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeAuthToken.md
5-
schema: 2.0.0
6-
---
7-
81
# Get-WattTimeAuthToken
92

103
## SYNOPSIS

‎docs/Get-WattTimeForAzureRegion.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
---
2-
external help file: PSWattTime-help.xml
3-
Module Name: PSWattTime
4-
online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/Get-WattTimeForAzureRegion.md
5-
schema: 2.0.0
6-
---
7-
81
# Get-WattTimeForAzureRegion
92

103
## SYNOPSIS

‎docs/New-WattTimeAccount.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
---
2-
external help file: PSWattTime-help.xml
3-
Module Name: PSWattTime
4-
online version: https://github.com/cloudyspells/PSWattTime/blob/main/docs/New-WattTimeAccount.md
5-
schema: 2.0.0
6-
---
7-
81
# New-WattTimeAccount
92

103
## SYNOPSIS

‎docs/wiki-src/Home.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
PSWattTime Wiki
2+
===============
3+
4+
PowerShell module for [WattTime.org](https://www.watttime.org/) API
5+
-------------------------------------------------------------------
6+
7+
[![PowerShell Module Quality Assurance](https://github.com/cloudyspells/PSWattTime/actions/workflows/qa.yml/badge.svg)](https://github.com/cloudyspells/PSWattTime/actions/workflows/qa.yml)
8+
![GitHub release (latest by date)](https://img.shields.io/github/v/release/cloudyspells/PSWattTime)
9+
![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/PSWattTime)
10+
![PowerShell Gallery](https://img.shields.io/powershellgallery/dt/PSWattTime)
11+
12+
13+
This PowerShell module is intended for retrieving emissions data from
14+
[WattTime](https://www.watttime.org/) for a supplied Azure Region during
15+
resource deployments. This is a lightweight solution making use of only the
16+
limited functionality available with a free account at _WattTime_. This means
17+
the module is only able to get near-realtime emissions data and no prodictive
18+
values. This means this module is _not_ a real solution for reduced carbon
19+
deployments and -software. It _does_ however provide some nice realtime values
20+
so you can simulate the beheaviour of deployments and software based on
21+
emissions data without the cost of a paid account for such data. For example in
22+
lab- or proof of concept environments.
23+
24+
The intended use of this module is for setting the `Location` parameter
25+
on Azure IaC deployments in GitHub workflows using the included GitHub
26+
action.
27+
28+
For a real-world solution with a commercial data provider, check out
29+
the [carbon-aware-sdk](https://github.com/Green-Software-Foundation/carbon-aware-sdk)
30+
by the [Green Software Foundation](https://greensoftware.foundation/)

‎docs/wiki-src/quickstart-github-action.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
Getting started with PSWattTime
2+
===============================
3+
4+
Steps for using the GitHub Action
5+
---------------------------------
6+
7+
This PowerShell module also comes with a _GitHub Action_ you can use
8+
in your GitHub workflows. Again you will need a pre-existing account
9+
for _WattTime_ and an Azure CLI/PowerShell secret configured in your repo
10+
11+
### Example
12+
13+
```yaml
14+
15+
on:
16+
pull_request:
17+
branches:
18+
- 'main'
19+
- 'releases/**'
20+
21+
name: Deploy to region with lowest emissions
22+
23+
jobs:
24+
deploy-to-test:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v3
29+
30+
- name: Get region with lowest emissions
31+
uses: cloudyspells/PSWattTime@v1.0.4
32+
id: watttime_action # Set step id for using output in deployment
33+
with:
34+
azure_credential: ${{ secrets.AZURE_CREDENTIALS }}
35+
watttime_username: ${{ secrets.WATTTIMEUSERNAME }}
36+
watttime_password: ${{ secrets.WATTTIMEPASSWORD }}
37+
regions: '"westeurope","northeurope","uksouth","francecentral","germanynorth"'
38+
39+
- name: Login to Az PowerShell Module
40+
uses: azure/login@v1
41+
with:
42+
creds: ${{ secrets.AZURE_CREDENTIALS }}
43+
enable-AzPSSession: true
44+
45+
- uses: azure/arm-deploy@v1
46+
name: Run Bicep deployment
47+
with:
48+
subscriptionId: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
49+
scope: subscription
50+
region: ${{ steps.watttime_action.outputs.region }} # The region output from PSWattTime
51+
template: src/bicep/main.bicep
52+
```

‎docs/wiki-src/quickstart-powershell.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
Getting started with PSWattTime
2+
===============================
3+
4+
Steps for using the module in PowerShell
5+
----------------------------------------
6+
7+
To get started with this module you will need an account on
8+
[WattTime](https://www.watttime.org/). See
9+
[the manual](https://www.watttime.org/api-documentation/#register-new-user)
10+
on registering an account. The module provides a function `New-WattTimeAccount`
11+
to create an account if you do not yet have one.
12+
13+
You will also need the _Az.Resources_ PowerShell Module for Azure installed
14+
and connected to your Azure account. See
15+
[the installation manual](https://learn.microsoft.com/en-us/powershell/azure/install-az-ps)
16+
for the _Az_ module for instructions.
17+
18+
To install the module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/PSWattTime/).
19+
20+
```powershell
21+
Install-Module -Name PSWattTime
22+
```
23+
24+
To register an account with _WattTime_:
25+
26+
```powershell
27+
New-WattTimeAccount -Username <YOUR_USERNAME> `
28+
-Password '<YOUR_PASSWORD>' `
29+
-Email '<you@domain.com>' `
30+
-Organization <YOUR_ORGANIZATION>
31+
```
32+
33+
34+
Authenticate to the _WattTime_ API:
35+
36+
```powershell
37+
$token = Get-WattTimeAuthToken -Username '<YOUR_WATTTIME_USERNAME>' `
38+
-Password '<YOUR_WATTTIME_PASSWORD>'
39+
```
40+
41+
Get current percentage of energy with emissions the 'westeurope' Azure region:
42+
43+
```powershell
44+
PS C:\> Get-WattTimeForAzureRegion -Region westeurope -AuthToken $token
45+
46+
ba : NL
47+
freq : 300
48+
percent : 94
49+
point_time : 5-3-2023 13:15:00
50+
region : westeurope
51+
52+
```
53+
54+
Determine the lowest emissions for the list of northeurope,
55+
westeurope, francecentral and uksouth Azure regions:
56+
57+
```powershell
58+
PS C:\> Get-AzureRegionWithLowestWattTime -Regions westeurope,uksouth,northeurope,francecentral -AuthToken $token
59+
60+
ba : IE
61+
freq : 300
62+
percent : 69
63+
point_time : 5-3-2023 14:15:00
64+
region : northeurope
65+
66+
```
67+
68+
### Module Functions
69+
70+
- [ConvertFrom-AzureRegion](docs/ConvertFrom-AzureRegion.md)
71+
- [Get-AzureRegionWithLowestWattTime](docs/Get-AzureRegionWithLowestWattTime.md)
72+
- [Get-WattTime](docs/Get-WattTime.md)
73+
- [Get-WattTimeAuthToken](docs/Get-WattTimeAuthToken.md)
74+
- [Get-WattTimeForAzureRegion](docs/Get-WattTimeForAzureRegion.md)
75+
- [New-WattTimeAccount](docs/New-WattTimeAccount.md)

0 commit comments

Comments
 (0)