Skip to content

Commit

Permalink
docs: implement contribution guides to add a cloud provider or cloud …
Browse files Browse the repository at this point in the history 
…instances

Should help with the following issues #66, #145, #228 and #249
  • Loading branch information
@samuelrince
samuelrince committed Nov 29, 2023
1 parent 14a705e commit ce45d89
Show file tree
Hide file tree
Showing 3 changed files with 78 additions and 0 deletions.
56 changes: 56 additions & 0 deletions docs/docs/contributing/cloud_instance.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Add a new cloud instance

This guide will you add a new cloud instances for a cloud provider that is already supported by BoaviztAPI.

## Cloud instances CSV file

All instances for one particular cloud provider are stored in a CSV file named after that cloud provider (e.g. `aws.csv` for AWS). These files are located at `boaviztapi/data/archetypes/cloud/`.

| Column name | Required | Description | Example |
|-------------------------------|--------------|---------------------------------------------------------------------|---------------------------|
| id | **Required** | Instance identifier | c5.2xlarge |
| manufacturer | **Required** | Cloud provider | AWS |
| CASE.type | | Type of enclosure (usually "rack") | rack |
| year | | ??? | 2016 |
| vcpu | **Required** | Number of vCPU | 8 |
| platform_vcpu | **Required** | Number of vCPU of the platform[^1] | 96 |
| CPU.units | | Number of physical CPU | 2 |
| CPU.name | | CPU name[^2] | Xeon Platinum 8124M |
| CPU.core_units | | Number of CPU cores per CPU | 24 |
| CPU.manufacturer | | CPU manufacturer | Intel |
| CPU.model_range | | CPU model range | Xeon Platinum |
| CPU.family | | CPU family | Skylake |
| CPU.tdp | | CPU TDP (in Watt) | 240 |
| CPU.manufacture_date | | CPU manufacture date | 2016 |
| instance.ram_capacity | **Required** | Instance RAM capacity (in GB) | 16 |
| RAM.units | | Number of RAM banks | 12 |
| RAM.capacity | | RAM bank capacity | 16 |
| SSD.units | | Number of SSD disks | 1 |
| SSD.capacity | | Capacity of SSD disk (in GB) | 512 |
| HDD.units | | Number of HDD disks | 1 |
| HDD.capacity | | Capacity of HDD disk (in GB) | 4096 |
| GPU.units | | Number of GPU cards | 4 |
| GPU.name | | GPU name | NVIDIA A10G |
| GPU.tdp | | GPU TDP value (in Watt) | 150 |
| GPU.memory_capacity | | GPU memory capacity (in GB) | 24 |
| POWER_SUPPLY.units | | Number of power supplies | 2 |
| POWER_SUPPLY.unit_weight | | Power supply weight (in kg) | 2.99;1;5 |
| USAGE.instance_per_server | | Number of instances hosted by the same platform | 12 |
| USAGE.time_workload | | Percentage of workload | 50;0;100 |
| USAGE.hours_life_time | | Number of hours of life time | 35040 _(=4 years)_ |
| USAGE.use_time_ratio | | Proportion of the time the instance is being used | 0.5 |
| USAGE.other_consumption_ratio | | Power consumption ratio of other components relative to RAM and CPU | 0.33;0.2;0.6 |
| USAGE.overcommited | | ??? | 0 |
| Warnings | | List of warnings separated by semi-colons (;) | RAM.capacity not verified |

[^1]: Number of vCPU of the platform usually corresponds to the total number of vCPU of the bare metal instance. For a bare metal instance with 2x 24 cores CPU the platform_vcpu is: 2 (CPU units) x 24 (core units) x 2 ("threads" per core) = 96 vCPU.

[^2]: If the CPU is missing from the `cpu_specs.csv` (located at `boaviztapi/data/crowdsourcing/`), please consider to add it there as well to enrich the internal database.

### Missing values

Some values that are not required can be left empty if unknown and will be auto-completed by the API. Try to fill all columns as much as possible.

### Value ranges

Some values can be inputted using ranges like the following: `default;min;max`. This can help modeling uncertain values like the weight of a power supply for instance. In the example above the default power supply weighs 2.99 kg, but can vary from 1 kg to 5 kg.
18 changes: 18 additions & 0 deletions docs/docs/contributing/cloud_provider.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Add a new cloud provider

This guide will you add a new cloud provider into BoaviztAPI.

## Register the cloud provider

To register the new cloud provider, you will need to update the `providers.csv` file and add new line with the following required information.

- `provider.name`: The provider short name (e.g. "aws"),
- `provider.description`: Full name of the provider (e.g. "Amazon Web Services").

The file `provided.csv` is located at `boaviztapi/data/archetypes/cloud/providers.csv`.

## Add cloud instances

Then you will need to add cloud instances for that provider into a new CSV that must created using the same name as `provider.name` (e.g. `aws.csv`). The file must be created in the same location as the `providers.csv` file. You will need to have the exact same columns in the new CSV file compared to others. You can copy and paste the content of already existent list of instances from another cloud provider and remove all rows, but the first one.

To add new cloud instances please refer to this documentation: [Add a cloud instance](cloud_instance.md)
4 changes: 4 additions & 0 deletions docs/mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ markdown_extensions:
- pymdownx.superfences
- admonition
- pymdownx.details
- footnotes

nav:
- Introduction: index.md
Expand Down Expand Up @@ -74,6 +75,9 @@ nav:
- Deploy: Reference/deploy.md
- Configuration: Reference/config.md
- Release notes: release_notes.md
- Contributing:
- 'Add a cloud provider': contributing/cloud_provider.md
- 'Add a cloud instance': contributing/cloud_instance.md

theme: material

Expand Down

0 comments on commit ce45d89

Please sign in to comment.