Green-Software-Foundation
diff --git a/‎CHANGELOG.md
Lines changed: 73 additions & 0 deletions b/‎CHANGELOG.md
Lines changed: 73 additions & 0 deletions
diff --git a/‎casdk-docs/docs/architecture/decisions/0016-watt-time-v3.md
Lines changed: 86 additions & 0 deletions b/‎casdk-docs/docs/architecture/decisions/0016-watt-time-v3.md
Lines changed: 86 additions & 0 deletions
diff --git a/‎casdk-docs/docs/tutorial-extras/carbon-aware-library.md
Lines changed: 1 addition & 1 deletion b/‎casdk-docs/docs/tutorial-extras/carbon-aware-library.md
Lines changed: 1 addition & 1 deletion
diff --git a/‎casdk-docs/docusaurus.config.js
Lines changed: 1 addition & 1 deletion b/‎casdk-docs/docusaurus.config.js
Lines changed: 1 addition & 1 deletion
diff --git a/‎samples/casdk-demo/README.md
Lines changed: 64 additions & 0 deletions b/‎samples/casdk-demo/README.md
Lines changed: 64 additions & 0 deletions
diff --git a/‎samples/casdk-demo/casdk-config.yaml.template
Lines changed: 6 additions & 0 deletions b/‎samples/casdk-demo/casdk-config.yaml.template
Lines changed: 6 additions & 0 deletions
diff --git a/‎samples/casdk-demo/demo.sh
Lines changed: 55 additions & 0 deletions b/‎samples/casdk-demo/demo.sh
Lines changed: 55 additions & 0 deletions
diff --git a/‎samples/casdk-demo/demo.yaml
Lines changed: 47 additions & 0 deletions b/‎samples/casdk-demo/demo.yaml
Lines changed: 47 additions & 0 deletions
diff --git a/‎samples/casdk-demo/nginx-rp.conf
Lines changed: 16 additions & 0 deletions b/‎samples/casdk-demo/nginx-rp.conf
Lines changed: 16 additions & 0 deletions
diff --git a/‎src/CarbonAware.CLI/test/integrationTests/Commands/EmissionsForecasts/EmissionsForecastsCommandTests.cs
Lines changed: 1 addition & 1 deletion b/‎src/CarbonAware.CLI/test/integrationTests/Commands/EmissionsForecasts/EmissionsForecastsCommandTests.cs
Lines changed: 1 addition & 1 deletion
diff --git a/‎src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMaps/mock/ElectricityMapDataSourceMocker.cs
Lines changed: 1 addition & 1 deletion b/‎src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMaps/mock/ElectricityMapDataSourceMocker.cs
Lines changed: 1 addition & 1 deletion
@@ -2,6 +2,79 @@
 
 All notable changes to the Carbon Aware SDK will be documented in this file.
 
+## [1.5.0] - 2024-05
+
+This is the WattTime v3 update.  Most notable changes that may require action are for deployment configuration, and these are minor.
+
+### Added 
+
+WattTime v3 API support.  This is an inplace upgrade for v2.
+
+- [PR #532] Watt Time v3 Support  ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/532)
+- [PR #340] Add example for 'podman play kube' ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/340)
+- [PR #536] Updated azure-regions.json with new regions ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/536)
+- [#519] Remove hackathon sentence from our website banner ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/519)
+- [#510] Gap Analysis for WattTime v3 ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/510)
+- [#262] [Feature Contribution]: Publish the docker file in a docker registry ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/262)
+
+### Removed
+
+WattTime v2 API support due to v3 in place replacement.
+
+### Fixed
+
+- [PR #522] Remove Hack mention from the Docs's banner ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/522)
+- [#535] [Bug]: Configuration for locations loads twice  ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/535)
+- [PR #516] Update published documentation to .NET 8 ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/516)
+- [PR #515] overview.md: Fixed three broken links Signed-off-by: joecus1 <joecusa… ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/pull/515)
+- [#506] Check our published documentation to identify any references to .NET7 ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/506)
+- [#512] [Bug]: Broken links in overview.md file ](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/512)
+
+### Changed
+
+Updates for WattTime v3 API endpoint from v2, details in the [ADR for WattTime v3 changes](./casdk-docs/docs/architecture//decisions/0016-watt-time-v3.md).
+
+#### API
+
+No changes
+
+#### API Deployment
+
+Due to the change for WattTime v3, there is change to the configuration for WattTime users.
+
+With some of the changes to the code, some of the configuration will also needs to change.
+
+| Config (v2)                   | Config (v3)                 | Description                  |
+|------------------------------------|----------------------------------|------------------------------|
+| `BalancingAuthorityCacheTTL`                                 | `RegionCacheTTL`                                 | This is the cache for regions data in seconds, and has a default value of 1 day.  This only needs updating if you set it |
+| n/a                        | `AuthenticationBaseUrl`                                | **NEW** This is the base URL for the WattTime Authentication API and defaults to `https://api.watttime.org/` if not set. |
+
+Example below if set (note they do not have to be set)
+```json
+"wattTime_no-proxy": {
+  "Type": "WattTime",
+  "Username": "the_username",
+  "Password": "super_secret_secret",
+  "BaseURL": "https://api.watttime.org/v3/",
+  "AutenticationBaseURL": "https://api.watttime.org", // This is new but not mandatory in config
+  "RegionCacheTTL": 86400, // This is changed but not mandatory in config
+  "Proxy": {
+    "UseProxy": false
+  }
+```
+
+#### SDK 
+
+No changes
+
+
+#### Other
+
+No changes
+
+
+For more details, checkout [https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/503](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/503) 
+
 
 ## [1.4.0] - 2024-05
 
 
@@ -0,0 +1,86 @@
+
+# 0015. WattTime v3 Changes
+
+## Status
+
+Proposed
+
+## Context
+As part of the update to Watt Time v3 we are proposing the changes to the underlying API calls.  This needs to be tracked so we understand the impacts, and if multiple options are available, which option was selected and why.
+
+This wll impact the `CarbonAware.DataSources.WattTime` project primarily - however all test will need changing where there are downstream tests that are impacted, and for example, if any initialization needs reconfiguring it will impact dependency injection and likely `Program.cs` in the WattTime API projects.
+
+## Decision
+
+The proposal is for the outlined WattTime API mapping and changes.
+
+## WattTime v2, v3 Mapping
+
+The following document and guidelines was used to understand the impact to the Carbon Aware SDK for the WattTime v3 updates.  https://docs.watttime.org/#tag/Transitioning-from-APIv2-to-APIv3 
+
+### Base URL
+The base URL will need to change.  This is configured in the `appsettings.config` and can be set from environment variables.
+
+|Base URL (v2) | Based URL (v3) | 
+|---|---|
+| /v2 | /v3 |
+
+
+### Paths
+The paths will also need to change. 
+
+The following is configured at  `CarbonAware.DataSources.WattTime/src/Constants/Paths.cs`
+
+All response types for emission data include a response/data object, and a `meta` object which contains information such as `region`.  As such historical data, forecast data, and historical forecast data objects will change significantly.  These will be moved across to their own `...Response` record objects to abstract any future changes in the response type.  Previously these objects had a lot of overlap so where the same class and this will cause significant rework of the code and tests, and breaking these out now will abstract them. 
+
+The `Login` is now at a different base URL, and to avoid any future issues a different HTTP client will be used for authentication, and the existing HTTP client will be used for API interaction.  These will still sit in the `WattTimeClient` and as such no impacts to the dependent classes/logic.
+
+| API Endpoint | Description | Path (v2) | Path (v3) | Notes |
+|--------------|-------------|-----------|-----------|---|
+| Data         | Get data    | /data     | /historical          |  _Request_ <li> `starttime` is now `start` and mandatory <li> `endtime` is now `end` and mandatory <li> `ba` is now `region` <li> `signal_type` added <br> _Response_ <li> `signal_type` added
+| Forecast     | Get forecast| /forecast | /forecast   | <br> No longer be used for historical data <br> _Request_ <li> `ba` is now `region` <li> `extended_forecast` removed <li> `horizon_hours` added  <li> `signal_type` added <li> Historical forecasts are now at `/forecast/historical` <br> _Response_ <li> `signal_type` added 
+| Historical   | Get historical forecast data | /historical (?) | /forecast/historical (?)           | This changed signficantly.  <br> _Request_ <li> `ba` is now `region` <li> `starttime` is now `start` and mandatory <li> `endtime` is now `end` and mandatory <li> `signal_type` added <br> _Response_ <li> `signal_type` added 
+| Balancing Authority From Location | Get balancing authority from location | /ba-from-loc | /region-from-loc          | Check if the CA SDK uses BA at all <br><br> _Request_ <li> `name` is now `region_full_name` <li> `abbrev` is now `region` <li> `signal_type` added <br> _Response_ <li> `id` removed <li> `signal_type` added  | 
+| Login        | User login  | https://api2.watttime.org/v2/login    | https://api.watttime.org/login | Path has changed from being version specific to being no longer related to the API version.  <br><br> Updated in `WattTimeClient` to now have 2 HTTP clients to decouple versions from the login. 
+
+### Query Strings
+
+#### Signal Type
+Everything call takes an optional `signal_type` parameter that defaults to `co2_moer`.  
+
+The following comes from `CarbonAware.DataSources.WattTime/src/Constants/QueryStrings.cs` and the changes are consistent with the discussion above.
+
+| Query String (v2)                   | Query String if Changed (v3)                 | Description                  |
+|------------------------------------|----------------------------------|------------------------------|
+| `ba`                                 | `region`                                 | Balancing Authority / Region |
+| `starttime`                          | `start`                                | Start Time                       |
+| `endtime`                            | `end`                                 | End Time                         |
+| `latitude`                           | -                                 | Latitude                         |
+| `longitude`                          | -                                 | Longitude                        |
+| `username`                           | -                                 | Username                         |
+
+## Update Changes
+With some of the changes to the code, some of the configuration will also needs to change.
+
+| Config (v2)                   | Config (v3)                 | Description                  |
+|------------------------------------|----------------------------------|------------------------------|
+| `BalancingAuthorityCacheTTL`                                 | `RegionCacheTTL`                                 | This is the cache for regions data in seconds, and has a default value of 1 day. |
+| n/a                        | `AuthenticationBaseUrl`                                | **NEW** This is the base URL for the WattTime Authentication API and defaults to `https://api.watttime.org/` if not set. |
+
+Example below if set (note they do not have to be set)
+```json
+"wattTime_no-proxy": {
+  "Type": "WattTime",
+  "Username": "the_username",
+  "Password": "super_secret_secret",
+  "BaseURL": "https://api.watttime.org/v3/",
+  "AutenticationBaseURL": "https://api.watttime.org", // This is new but not mandatory
+  "RegionCacheTTL": 86400, // This is new but not mandatory
+  "Proxy": {
+    "UseProxy": false
+  }
+```
+## Green Impact  
+
+Neutral
+
@@ -423,7 +423,7 @@ EmissionsForecast()
 #### Locations
 
 Each WattTime emissions data point is associated with a particular named
-balancing authority. For transparency, this value is also used in
+region often referred to as a balancing authority. For transparency, this value is also used in
 `EmissionsData` response objects. It is not overwritten to match the named
 datacenter provided by any request.
 
 
@@ -130,7 +130,7 @@ const config = {
         id: 'announcementBar-0', // Increment on change
         // content: `⭐️ If you like Docusaurus, give it a star on <a target="_blank" rel="noopener noreferrer" href="https://github.com/facebook/docusaurus">GitHub</a> and follow us on <a target="_blank" rel="noopener noreferrer" href="https://twitter.com/docusaurus">Twitter ${TwitterSvg}</a>`,
         //content: `🎉️ <b><a target="_blank" href="https://docusaurus.io/blog/releases/3.0">Docusaurus v3.0</a> is now out!</b> 🥳️`,
-        content:`<strong>\u26A0 Graduated Project: This project is a Graduated Project, supported by the Green Software Foundation. The publicly available version documented in the README is trusted by the GSF. New versions of the project may be released, or it may move to the Maintained or Archived Stage. <br><br> 🎉️ We are running a Hackathon! CarbonHack is open to all, including software practitioners and those with a passion for Green Software. Find out more on the <a href="https://grnsft.org/hack/github">CarbonHack website</a> </strong>`,
+        content:`<strong>\u26A0 Graduated Project: This project is a Graduated Project, supported by the Green Software Foundation. The publicly available version documented in the README is trusted by the GSF. New versions of the project may be released, or it may move to the Maintained or Archived Stage.</strong> `,
         backgroundColor:'#EBF2D7',
         textColor:'#00524f'
       },
 
@@ -0,0 +1,64 @@
+# Carbon Aware SDK demonstration on Podman
+
+This folder contains an example for Carbon Aware SDK and Swagger UI for the SDK. The user can demonstrate Carbon Aware SDK via Swagger UI with just one command.
+
+This demonstration uses `podman play kube` to deploy apps like a Kubernetes application. Deployment is defined in [demo.yaml](demo.yaml).
+
+## Requirements
+
+- Podman
+
+## Ports to open
+
+Podman creates virtual network, then all of containers in the deployment would be located flatten. So Each containers can access each other as a `localhost`. We need to consider TCP port:
+
+* 8080: Carbon Aware SDK
+* 8081: Swagger UI
+* 8082: NGINX (for reverse proxy)
+
+NGINX is a reverse proxy to both Carbon Aware SDK and Swagger UI. To avoid CORS error, you can access Swagger UI via NGINX ( http://localhost:8082/swagger-ui/ ).
+
+## Reverse proxy rule
+
+See [nginx-rp.conf](nginx-rp.conf)
+
+/ -> Carbon Aware SDK  
+/swagger.yaml -> OpenAPI document provided by Carbon Aware SDK  
+/swagger-ui/ -> Swagger UI for Carbon Aware SDK
+
+## How to run
+
+1. Set environment variables prefixed with `CASDK_`: e.g. `CASDK_DataSources__EmissionsDataSource`
+
+2. Start demonstration
+
+```
+./demo.sh start
+```
+
+:::warning
+
+* [demo.sh](demo.sh) would create `/tmp/casdk-config.yaml` which may contain credentials (e.g. API token of backend service). This file would be removed by `./demo.sh stop`.
+* [demo.sh](demo.sh) would change security context of [nginx-rp.conf](nginx-rp.conf) to `container_file_t` if SELinux is enabled. It would not recover in `./demo.sh stop`, so you need to recover manually via `restorecon` if need.
+
+:::
+
+3. Access endpoints (e.g. http://localhost:8082/swagger-ui/ )
+
+4. Stop demonstration
+
+```
+./demo.sh stop
+```
+
+## Example
+
+Run demonstration with ElectricityMapsFree datasource
+
+```
+export CASDK_DataSources__EmissionsDataSource=ElectricityMapsFree
+export CASDK_DataSources__Configurations__ElectricityMapsFree__Type=ElectricityMapsFree
+export CASDK_DataSources__Configurations__ElectricityMapsFree__token=YOUR_SECRET_TOKEN
+
+./demo.sh start
+```
@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: casdk-config
+data:
+  # Environment variables would be added by demo.sh
@@ -0,0 +1,55 @@
+#!/bin/sh
+
+THISFILE=$0
+BASEDIR=$(dirname $THISFILE)
+SUBCMD=$1
+CONFIGMAP=/tmp/casdk-config.yaml
+
+help_and_exit () {
+  echo "Usage:"
+  echo "  $THISFILE [start|stop]"
+
+  rm -f $CONFIGMAP
+  exit 1
+}
+
+start () {
+  # Create ConfigMap for envvars in CASDK container
+  cp -f $BASEDIR/casdk-config.yaml.template $CONFIGMAP
+  for CASDK_ENV in `env | grep CASDK_`; do
+    KEY=`echo $CASDK_ENV | cut -d '=' -f 1 | sed -e 's/^CASDK_//'`
+    VALUE=`echo $CASDK_ENV | cut -d '=' -f '2'`
+
+    echo "  $KEY: $VALUE" >> $CONFIGMAP
+  done
+
+
+  # Change security context of nginx-rp.conf because it would be mounted by
+  # NGINX container in demo.yaml.
+  SELINUX_MODE=`getenforce 2>/dev/null`
+  if [ "$SELINUX_MODE" = 'Enforcing' ]; then
+    chcon -t container_file_t $BASEDIR/nginx-rp.conf
+  fi
+
+  # Start Podman
+  # Move to BASEDIR because demo.yaml should refer nginx-rp.conf in that dir.
+  pushd $BASEDIR > /dev/null 2>&1
+  podman play kube --configmap=$CONFIGMAP demo.yaml
+  popd > /dev/null 2>&1
+}
+
+stop () {
+  podman play kube --down $BASEDIR/demo.yaml
+  rm -f $CONFIGMAP
+}
+
+case "$SUBCMD" in
+  start)
+    start;;
+
+  stop)
+    stop;;
+
+  *)
+    help_and_exit;;
+esac
@@ -0,0 +1,47 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: casdk-demo
+  labels:
+    app: casdk-demo
+spec:
+  selector:
+    matchLabels:
+      app: casdk-demo
+  template:
+    metadata:
+      labels:
+        app: casdk-demo
+    spec:
+      containers:
+      - name: carbon-aware-sdk
+        image: ghcr.io/green-software-foundation/carbon-aware-sdk:pre
+        envFrom:
+        - configMapRef:
+            name: casdk-config
+        ports:
+        - containerPort: 8080
+          hostPort: 8080
+      - name: swagger-ui
+        image: swaggerapi/swagger-ui
+        env:
+        - name: SWAGGER_JSON_URL
+          value: /swagger.yaml
+        - name: PORT
+          value: "8081"
+        ports:
+        - containerPort: 8081
+          hostPort: 8081
+      - name: nginx
+        image: nginx
+        ports:
+        - containerPort: 8082
+          hostPort: 8082
+        volumeMounts:
+        - name: rp-config
+          mountPath: /etc/nginx/conf.d/default.conf
+      volumes:
+      - name: rp-config
+        hostPath:
+          path: nginx-rp.conf
+          type: File
@@ -0,0 +1,16 @@
+server {
+  listen 8082;
+
+  location / {
+    proxy_pass http://localhost:8080;
+  }
+
+  location /swagger.yaml {
+    proxy_pass http://localhost:8080/api/v1/swagger.yaml;
+  }
+
+  location /swagger-ui/ {
+    proxy_pass http://localhost:8081/;
+  }
+
+}
@@ -99,7 +99,7 @@ public async Task EmissionsForecasts_RequestedAtOptions_ReturnsExpectedData()
         IgnoreTestForDataSource("data source does not implement '--requested-at'", DataSourceType.ElectricityMaps);
 
         // Arrange
-        _dataSourceMocker.SetupBatchForecastMock();
+        _dataSourceMocker.SetupHistoricalBatchForecastMock();
 
         // Act
         var exitCode = await InvokeCliAsync($"emissions-forecasts -l eastus -r 2022-09-01");
 
@@ -126,7 +126,7 @@ public void SetupDataMock(DateTimeOffset start, DateTimeOffset end, string locat
         SetupResponseGivenGetRequest(Paths.PastRange, pastRange);
     }
 
-    public void SetupBatchForecastMock()
+    public void SetupHistoricalBatchForecastMock()
     {
         throw new NotImplementedException();
     }
Original file line number	Diff line number	Diff line change
`@@ -126,7 +126,7 @@ public void SetupDataMock(DateTimeOffset start, DateTimeOffset end, string locat`
`126`	`126`	`SetupResponseGivenGetRequest(Paths.PastRange, pastRange);`
`127`	`127`	`}`
`128`	`128`
`129`		`- public void SetupBatchForecastMock()`
	`129`	`+ public void SetupHistoricalBatchForecastMock()`
`130`	`130`	`{`
`131`	`131`	`throw new NotImplementedException();`
`132`	`132`	`}`