IF architecture

[jmcook1186]

@kaito-kameda @YaSuenag

[YaSuenag]

CC: @nttDamien

[YaSuenag]

Summary

I'd like to discuss about implementing Web API for if-run.

Purpose

We want to use IF on Kubernetes, and to leverage it as a part of monitoring system.

IF is useful tool to calculate environmental values like energy consumption or carbon emission. We can use it for both realtime and historical data. It will make monitoring stack more powerful, and we can evaluate them easily with GSF standards like SCI.

Currently IF provides CLI tools only, so it is difficult to integrate to online system like a micro service architecture. We need to create "invoker" of IF CLI tools to handle stdin/stdout/stderr as a parent process.

Proposal

1. Implement Web API for if-run

Implement if-run as a web application.

if-run is a core component of IF. We can use it to calculate manifest, So the Web API endpoint accepts manifest YAML, and then returns the output to the client.

We can implement API endpoint with Express, and it proxies if-run module. It should be much better than spawning process due to performance reason.

Our API proposal is in below. You can see it on Swagger Editor if you copy and paste.

OpenAPI document

openapi: 3.0.3
info:
  title: Impact Framework Web API
  description: |-
    This API provides key feature of Impact Framework (IF) as a Web API.
  license:
    name: MIT license
    url: https://github.com/Green-Software-Foundation/if/blob/main/LICENSE
  version: 1.0.0
externalDocs:
  description: Find out more about Impact Framework
  url: https://if.greensoftware.foundation/
paths:
  /v1/run:
    post:
      summary: Execute `if-run` with given manifest.
      operationId: ifRun
      parameters:
        - in: query
          name: outputonly
          schema:
            type: boolean
          required: false
          description: "`true` if only `.tree.*.outputs` is needed."
      requestBody:
        description: IF Manifests
        content:
          application/vnd.if-manifest+yaml:
            example: |
              name: demo
              initialize:
                plugins:
                  double-a-value:
                    path: 'builtin'
                    method: Coefficient
                    config:
                      input-parameter: "cpu/utilization"
                      coefficient: 2
                      output-parameter: "cpu-utilization-doubled"
              tree:
                children:
                  child-0:
                    pipeline:
                      compute:
                        - double-a-value
                    inputs:
                      - timestamp: 2023-07-06T00:00
                        duration: 1
                        cpu/utilization: 20
                      - timestamp: 2023-07-06T00:01
                        duration: 1
                        cpu/utilization: 80
        required: true
      responses:
        '200':
          description: Successful operation.
          content:
            application/vnd.if-manifest+yaml:
              example: |
                name: demo
                initialize:
                  plugins:
                    double-a-value:
                      path: builtin
                      method: Coefficient
                      config:
                        input-parameter: cpu/utilization
                        coefficient: 2
                        output-parameter: cpu-utilization-doubled
                execution:
                  command: >-
                    /usr/bin/node-22 /home/yasuenag/work/if/node_modules/.bin/if-run --manifest
                    demo.yaml
                  environment:
                    if-version: 1.0.1
                    os: linux
                    os-version: 6.12.11-200.fc41.x86_64
                    node-version: 22.11.0
                    date-time: 2025-03-19T04:14:17.563Z (UTC)
                    dependencies:
                      - '@grnsft/[email protected]'
                  status: success
                tree:
                  children:
                    child-0:
                      pipeline:
                        compute:
                          - double-a-value
                      inputs:
                        - timestamp: 2023-07-06T00:00
                          duration: 1
                          cpu/utilization: 20
                        - timestamp: 2023-07-06T00:01
                          duration: 1
                          cpu/utilization: 80
                      outputs:
                        - timestamp: 2023-07-06T00:00
                          duration: 1
                          cpu/utilization: 20
                          cpu-utilization-doubled: 40
                        - timestamp: 2023-07-06T00:01
                          duration: 1
                          cpu/utilization: 80
                          cpu-utilization-doubled: 160
            application/vnd.if-manifest+json:
              example: |
                {
                  "name": "demo",
                  "initialize": {
                    "plugins": {
                      "double-a-value": {
                        "path": "builtin",
                        "method": "Coefficient",
                        "config": {
                          "input-parameter": "cpu/utilization",
                          "coefficient": 2,
                          "output-parameter": "cpu-utilization-doubled"
                        }
                      }
                    }
                  },
                  "execution": {
                    "command": "/usr/bin/node-22 /home/yasuenag/work/if/node_modules/.bin/if-run --manifest demo.yaml",
                    "environment": {
                      "if-version": "1.0.1",
                      "os": "linux",
                      "os-version": "6.12.11-200.fc41.x86_64",
                      "node-version": "22.11.0",
                      "date-time": "2025-03-19T04:14:17.563Z (UTC)",
                      "dependencies": [
                        "@grnsft/[email protected]"
                      ]
                    },
                    "status": "success"
                  },
                  "tree": {
                    "children": {
                      "child-0": {
                        "pipeline": {
                          "compute": [
                            "double-a-value"
                          ]
                        },
                        "inputs": [
                          {
                            "timestamp": "2023-07-06T00:00",
                            "duration": 1,
                            "cpu/utilization": 20
                          },
                          {
                            "timestamp": "2023-07-06T00:01",
                            "duration": 1,
                            "cpu/utilization": 80
                          }
                        ],
                        "outputs": [
                          {
                            "timestamp": "2023-07-06T00:00",
                            "duration": 1,
                            "cpu/utilization": 20,
                            "cpu-utilization-doubled": 40
                          },
                          {
                            "timestamp": "2023-07-06T00:01",
                            "duration": 1,
                            "cpu/utilization": 80,
                            "cpu-utilization-doubled": 160
                          }
                        ]
                      }
                    }
                  }
                }

2. Containerize

Containerization gives benefits that the user can use IF Web API with single command like docker run, and it would be portable. So we propose to create Dockerfile for Web API.

Kubernetes has been leveraged in modern system. We can delegate container lifecycle to Kubernetes if we deploy the app on it. Thus we would also like to propose to create Helm chart for Web API container.

3. Publish official images

It is better to publish "official" container image and Helm chart from GSF.

In Carbon Aware SDK, official both Web API container image and Helm chart has been provided from GitHub Container Registry ( ghcr.io ). We can use that registry for IF.

Both container image and Helm chart for Carbon Aware SDK would be generated / published by GHA workflow. IF already has GHA workflow for new release. We can integrate new workflow for container image / Helm chart to it.

[jmcook1186]

@narekhovhannisyan

[narekhovhannisyan]

@jmcook1186 @YaSuenag As I mentioned during the monthly call, we can expose if-run as a function from the package, and freely use it in express application.

Example:

import {ifRun} from '@grnsft/if'
import {Router} from "express";

const router = Router();

router.post('/calculate-emissions', async (request, response, next) => {
  const { <PARAMS-HERE> } = request.body
  
  cons outputManifest = await ifRun({ <PARAMS-HERE> })
  
  return response.status(200).send(outputManifest)
})

[jawache]

Thanks for the detailed explanation @YaSuenag. I have some questions regarding dockerisation, does it change the default behavior of IF?

One of the tradeoffs regarding how Carbon Aware SDK was implemented is that it "required" docker to be able to run.

Is the change above you are proposing to add additional optional configuration to make it easier to people to run IF as a web deamon inside a container? Or is it a proposal to make docker and if-run as a web-api the default option?

[YaSuenag]

does it change the default behavior of IF?

No, we are planning to add separate endpoint for WebAPI like to add if-web command. It is isolated with other implementation (if-run and so on), thus it does not affect current commands / behavior.

One of the tradeoffs regarding how Carbon Aware SDK was implemented is that it "required" docker to be able to run.

No, Carbon Aware SDK WebAPI does not mandatory any containerization, you can run it with dotnet run on the OS directly.
We are planning to implement similar way for IF WebAPI - the user can run it on the command (npm or exec shell like if-run), and the user can containerize it of course.
In our use case, we want to run it on Kubernetes, so we propose both containerization and Helm chart for deploying.

Is the change above you are proposing to add additional optional configuration to make it easier to people to run IF as a web deamon inside a container? Or is it a proposal to make docker and if-run as a web-api the default option?

As I said in above, we propose to implement WebAPI as another command like if-web, so it does not affect any current behavior / command line options. We are thinking to implement like @narekhovhannisyan shares.

[jmcook1186]

Hi @jawache @YaSuenag @narekhovhannisyan

Given that this doesn't affect our current users and only adds an additional export, I think it's safe to move forward with this, targeting merging the code into IF.

I sent the link to this proposal to our IF community mailing list for visibility, so let's leave it until the end of the week to see if anyone has objections - if not, I think move to PR.

[nttDamien]

[celebrate] TIG ＲＯＵＸ Ｄａｍｉｅｎ/Roux, Damien (... reacted to your message:

…

________________________________ From: Joseph Cook ***@***.***> Sent: Tuesday, April 29, 2025 11:40:25 AM To: Green-Software-Foundation/if ***@***.***> Cc: TIG ＲＯＵＸ Ｄａｍｉｅｎ/Roux, Damien (NTT DATA) ***@***.***>; Mention ***@***.***> Subject: Re: [Green-Software-Foundation/if] IF architecture (Discussion #1129) Hi @jawache<https://urldefense.com/v3/__https://github.com/jawache__;!!GCTRfqYYOYGmgK_z!-GXgPD1mt28c_a2eTDkbZn30oZZHGaG1R_obonumRZ5uLmbGbq2bY3_vlwy6bS7QsLk0xcAuy6UOtiZ9d7kdAV_waUYIEQ$> @YaSuenag<https://urldefense.com/v3/__https://github.com/YaSuenag__;!!GCTRfqYYOYGmgK_z!-GXgPD1mt28c_a2eTDkbZn30oZZHGaG1R_obonumRZ5uLmbGbq2bY3_vlwy6bS7QsLk0xcAuy6UOtiZ9d7kdAV8cuPzm3A$> @narekhovhannisyan<https://urldefense.com/v3/__https://github.com/narekhovhannisyan__;!!GCTRfqYYOYGmgK_z!-GXgPD1mt28c_a2eTDkbZn30oZZHGaG1R_obonumRZ5uLmbGbq2bY3_vlwy6bS7QsLk0xcAuy6UOtiZ9d7kdAV9kresyLQ$> Given that this doesn't affect our current users and only adds an additional export, I think it's safe to move forward with this, targeting merging the code into IF. I sent the link to this proposal to our IF community mailing list for visibility, so let's leave it until the end of the week to see if anyone has objections - if not, I think move to PR. — Reply to this email directly, view it on GitHub<https://urldefense.com/v3/__https://github.com/Green-Software-Foundation/if/discussions/1129*discussioncomment-12978803__;Iw!!GCTRfqYYOYGmgK_z!-GXgPD1mt28c_a2eTDkbZn30oZZHGaG1R_obonumRZ5uLmbGbq2bY3_vlwy6bS7QsLk0xcAuy6UOtiZ9d7kdAV_lg53UuQ$>, or unsubscribe<https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/A55V7R6SEVUOG4FN2TS7T4D235QKTAVCNFSM6AAAAABZHXH6O6VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTEOJXHA4DAMY__;!!GCTRfqYYOYGmgK_z!-GXgPD1mt28c_a2eTDkbZn30oZZHGaG1R_obonumRZ5uLmbGbq2bY3_vlwy6bS7QsLk0xcAuy6UOtiZ9d7kdAV_T-U-92Q$>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[kariya-mitsuru]

I have summarized my opinions below. I would appreciate your comments.

The outputonly Option

From the philosophy of the Impact Framework, I don't think the query parameter outputonly seems particularly good, but if we were to support it, we need to decide how to specify which outputs to include, or if all outputs are included, what structure should be used. In any case, the output format would no longer be an IMP File (application/vnd.if-manifest+yaml), so we would also need to add output formats to the OpenAPI definition.

Also, although this is outside the scope of this discussion, from the perspective of overall consistency in the Impact Framework, we should add an option equivalent to outputonly to if-run as well.

Other Options in if-run

Since if-run has options like --observe, --regroup, and --compute, we should support these in the Web API too.

Additional Input Files

The builtin plugin CSV Import Plugin requires external file input, so we should support inputs that include files other than an IMP File. In that case, the input format would need to be either multipart/form-data or a YAML that contains an IMP File and csv files as child elements (or perhaps both?). Whether there are external files in the input can be determined from the Content-Type or Request Body.

Dockerfile and Official Container Image

Providing container images officially would lower the barrier to using the Impact Framework, which is a good thing.

However, an important philosophy of the Impact Framework is that users can freely create and use plugins.

Therefore, we should support the following two points:

• Make the Dockerfile allow the installation of external plugins when creating container images
• Not include external plugins in the official container image, but allow installation of external plugins when starting the image

Additionally, the container image would be useful not only when running the Web API but also when running the CLI, so we should include all commands.

Helm Chart

As mentioned above, if we enable the installation of external plugins when starting the official container image, we need to make it possible to specify a personal access token to allow installation from GitHub Packages.

(This is because even if you make a npm package public on GitHub Packages, a personal access token is still required)

[YaSuenag]

Hi all,

I filed the issue for implementing this: #1136

For some reason I could not create a subissue, but I think we can work with following tasks:

1. Implement Web API for if-run
2. Containerization (creates Dockerfile)
3. Create Helm Chart for Web API (OCI based)
4. Add GHA workflow to publish Web API container image to ghcr.io
5. Add GHA workflow to publish Helm Chart to ghcr.io

We need to determine API specification referring to comment from @kariya-mitsuru , but it can be worked in each sub issues. So I think we can ready to work.

[YaSuenag]

Hi all,

I and @kariya-mitsuru are preparing to create PR for Web API. For general use cases, we would like to reach consensus on the following topics:

• Can we disable both csv-import and csv-lookup builtin plugins in Web API? They have a potential to expose server internal files.
• Can we disable shell builtin plugin in Web API? They could allow remote code execution (RCE).
• Can we add a feature to disable arbitrary plugins (in above)? All of plugins would be enabled by default, so current IF behavior is not changed.
• Are there other builtin plugins (or features) which should we disable due to security issues? (e.g. exposure, RCE)

[YaSuenag]

All of tasks for Web API have been done! Thanks all for your help!

We should be able to get "official" Web API container image and Helm chart when next IF is released. So I'm looking forward to next release.

[jmcook1186]

@YaSuenag fantastic - thanks for all your work on this!