From ce45d899553582ec9df844a8854baafc5dd6cccc Mon Sep 17 00:00:00 2001 From: Samuel Rince Date: Wed, 29 Nov 2023 22:56:39 +0100 Subject: [PATCH] docs: implement contribution guides to add a cloud provider or cloud instances Should help with the following issues #66, #145, #228 and #249 --- docs/docs/contributing/cloud_instance.md | 56 ++++++++++++++++++++++++ docs/docs/contributing/cloud_provider.md | 18 ++++++++ docs/mkdocs.yml | 4 ++ 3 files changed, 78 insertions(+) create mode 100644 docs/docs/contributing/cloud_instance.md create mode 100644 docs/docs/contributing/cloud_provider.md diff --git a/docs/docs/contributing/cloud_instance.md b/docs/docs/contributing/cloud_instance.md new file mode 100644 index 00000000..229113a8 --- /dev/null +++ b/docs/docs/contributing/cloud_instance.md @@ -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. diff --git a/docs/docs/contributing/cloud_provider.md b/docs/docs/contributing/cloud_provider.md new file mode 100644 index 00000000..04a35ec4 --- /dev/null +++ b/docs/docs/contributing/cloud_provider.md @@ -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) \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 2675917f..9ca564e3 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -17,6 +17,7 @@ markdown_extensions: - pymdownx.superfences - admonition - pymdownx.details + - footnotes nav: - Introduction: index.md @@ -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