Cloud Assess

This is the official repository of Cloud Assess.

What is Cloud Assess?

Cloud Assess is an open-source tool to automate the assessment of the environmental impacts of cloud services.

Table of Contents

1. Getting Started
2. First Assessment
3. How does it work?
   • Trusted Library
   • Adapt the models to your taste
4. License
5. About us

Getting Started

First, you need to clone this repository:

git checkout git@github.com:kleis-technology/cloud-assess.git
cd cloud-assess

All the commands in the sections below are to be run from the root of this repository. We assume that you will run these commands in bash. If you are using another shell, please adapt the commands accordingly.

Docker-compose

You can run the server using docker-compose.

docker compose up -d

The API specification is available in the folder openapi. For a more interactive visualisation of the API, the docker-compose also spins up a swagger ui instance. Visit this page to explore the endpoints, DTOs and run example queries.

Local build and run

Requirements

To build the server, you will need

• Java 17 (temurin) environment

A GitHub personal access token (classic) with the permission read:packages to download packages from GitHub Package Registry.

Then, set up the following environment variables.

export GITHUB_ACTOR=<your GitHub username>
export GITHUB_TOKEN=<the token you just created>

Procedure

From the root of the git repository, run

./gradlew build

To run the server locally

./gradlew bootRun

The server should start listening for requests on localhost:8080.

Note that, if you are on Windows, use the command ./gradlew.bat instead of ./gradlew.

First Assessment

Each functional unit is associated with a specific API endpoint. For instance, say we want to assess the environmental impact of using a virtual machine. The request takes the following form:

{
  "period": {
    "amount": 1.0,
    "unit": "hour"
  },
  "virtual_machines": [
    {
      "id": "c1",
      "pool_id": "client_vm",
      "vcpu": {
        "amount": 1.0,
        "unit": "vCPU"
      },
      "ram": {
        "amount": 32.0,
        "unit": "GB"
      },
      "storage": {
        "amount": 1024.0,
        "unit": "GB"
      },
      "meta": {
        "region": "sofia",
        "env": "production"
      }
    }
  ]
}

In this request, we specify the usage of our virtual machine in terms of the quantity of resources used (ram, storage and vCPU).

Running this request yields an impact assessment with the common LCA indicators. Of course, in this example, we ran the assessment for a single virtual machine, but nothing stops you from assessing as many virtual machines as you want.

How does it work?

Trusted Library

The ambition of Cloud Assess is to offer a library of transparent, PCR-compliant and executable LCA models in the sector of digital services. More precisely, this work builds on the existing PCR for data center and cloud services. The PCR defines 11 functional units, covering the hosting infrastructure (physical datacenter) up to more abstract FUs, e.g., Software Services. Cloud Assess aims at covering all functional units, but also FU that are not explicitly covered by the PCR

These models are specified under the folder trusted_library.

The library also contains intermediate/generic models, e.g.,

which can be used for specific purposes, e.g., a mail service running on a dedicated infrastructure.

Adapt the models to your taste

Structure

The models are written in the LCA as CODE language. This is a domain-specific language designed for the need of lifecycle analysis. The models under the folder trusted_library are directly loaded in the server to perform the assessments. A tutorial is available if you want to learn more about the language itself. The source repository is available here.

The folder trusted_library is organized as follows.

• 01-hardware : this folder contains the PCR models for the functional units 1 to 4.
• 02-pooling : this folder contains the PCR models for the functional units 5 to 8.
• 03-services : this folder contains the PCR models for functional units 9 and 10.

Here is an illustration of this layering structure.

Configuring the models

You can read and edit the models in trusted_library with any text editor. Unless you need to customize one of the functional units, there is no need to actually modify the models.

The folder trusted_library/data contains inventory files (in CSV format), and associated emission factors. To adapt Cloud Assess you must fill in, at least, the following inventories

• data/01-hardware/dc_inventory.csv : this file lists the available datacenters.
• data/01-hardware/hw_inventory.csv : this file lists the available hardware equipments.

The following files should be filled with the relevant emission factors:

• data/01-hardware/dc_impacts.csv
• data/01-hardware/hw_impacts.csv
• data/01-hardware/electricity_mix.csv

Note that the emission factors presented in this repository are mock values.

License

The content of this repository is subject to Apache 2 license.

About us

Cloud Assess is a joint-venture of Resilio and Kleis Technology.

If you have any questions related to Cloud Assess, be it about the LCA methodology or ways to automate the assessments, feel free to reach out to us at contact@resilio.tech.

&