diff --git a/samples/casdk-demo/README.md b/samples/casdk-demo/README.md new file mode 100644 index 000000000..168cd5abd --- /dev/null +++ b/samples/casdk-demo/README.md @@ -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 +``` diff --git a/samples/casdk-demo/casdk-config.yaml.template b/samples/casdk-demo/casdk-config.yaml.template new file mode 100644 index 000000000..2f468c0eb --- /dev/null +++ b/samples/casdk-demo/casdk-config.yaml.template @@ -0,0 +1,6 @@ +apiVersion: v1 +kind: ConfigMap +metadata: + name: casdk-config +data: + # Environment variables would be added by demo.sh diff --git a/samples/casdk-demo/demo.sh b/samples/casdk-demo/demo.sh new file mode 100755 index 000000000..aa5803577 --- /dev/null +++ b/samples/casdk-demo/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 diff --git a/samples/casdk-demo/demo.yaml b/samples/casdk-demo/demo.yaml new file mode 100644 index 000000000..1a753aa3a --- /dev/null +++ b/samples/casdk-demo/demo.yaml @@ -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 diff --git a/samples/casdk-demo/nginx-rp.conf b/samples/casdk-demo/nginx-rp.conf new file mode 100644 index 000000000..9efbc60ef --- /dev/null +++ b/samples/casdk-demo/nginx-rp.conf @@ -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/; + } + +}