aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/report/introduction/methodology_aws/aws_ami.rst72
-rw-r--r--docs/report/introduction/methodology_aws/aws_instances.rst79
-rw-r--r--docs/report/introduction/methodology_aws/aws_terraform.rst114
-rw-r--r--docs/report/introduction/methodology_aws/index.rst4
4 files changed, 150 insertions, 119 deletions
diff --git a/docs/report/introduction/methodology_aws/aws_ami.rst b/docs/report/introduction/methodology_aws/aws_ami.rst
index 0eebdf9d9c..264da01a1f 100644
--- a/docs/report/introduction/methodology_aws/aws_ami.rst
+++ b/docs/report/introduction/methodology_aws/aws_ami.rst
@@ -1,35 +1,40 @@
-Amazon Machine Images
----------------------
-
-An :abbr:`AMI (Amazon Machine Image)` provides the information required to
-launch an instance. CSIT is using Amazon :abbr:`EBS (Elastic Block Store)` where
-the root device for an instance launched from the AMI is a volume created from
-an Amazon EBS snapshot.
-
-A the TG and SUT instances have slightly different software requirements,
-we are defining two AMIs for TG and SUT separately. AMI details examples:
-
-TG:
-- AMI Name: csit_c5n_ubuntu_focal_tg
-- Platform details: Linux/UNIX
-- Architecture: x86_64
-- Usage operation: RunInstances
-- Image Type: machine
-- Virtualization type: hvm
-- Description: CSIT TG image based on Ubuntu Focal
-- Root Device Name: /dev/sda1
-- Root Device Type: ebs
-
-SUT:
-- AMI Name: csit_c5n_ubuntu_focal_sut
-- Platform details: Linux/UNIX
-- Architecture: x86_64
-- Usage operation: RunInstances
-- Image Type: machine
-- Virtualization type: hvm
-- Description: CSIT SUT image based on Ubuntu Focal
-- Root Device Name: /dev/sda1
-- Root Device Type: ebs
+.. _csit_ami:
+
+CSIT Amazon Machine Images
+--------------------------
+
+An Amazon Machine Image (AMI) provides the information required to
+launch an instance. CSIT is using Amazon Elastic Block Store (EBS) where
+the root device for an instance launched from the AMI is a volume
+created from an Amazon EBS snapshot.
+
+A the TG and SUT instances have slightly different software
+requirements, we are defining two AMIs for TG and SUT separately. AMI
+details examples:
+
+- TG:
+
+ - AMI Name: csit_c5n_ubuntu_focal_tg
+ - Platform details: Linux/UNIX
+ - Architecture: x86_64
+ - Usage operation: RunInstances
+ - Image Type: machine
+ - Virtualization type: hvm
+ - Description: CSIT TG image based on Ubuntu Focal
+ - Root Device Name: /dev/sda1
+ - Root Device Type: ebs
+
+- SUT:
+
+ - AMI Name: csit_c5n_ubuntu_focal_sut
+ - Platform details: Linux/UNIX
+ - Architecture: x86_64
+ - Usage operation: RunInstances
+ - Image Type: machine
+ - Virtualization type: hvm
+ - Description: CSIT SUT image based on Ubuntu Focal
+ - Root Device Name: /dev/sda1
+ - Root Device Type: ebs
Both TG and SUT AMIs are created manually before launching topology and are not
part of automated scripts. To create CSIT AMIs:
@@ -42,4 +47,5 @@ part of automated scripts. To create CSIT AMIs:
Building AMIs requires Hashicorp Packer with Amazon plugin installed.
-.. [aws_ami] `Amazon Machine Images <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html>`_
+For more information, see
+`Amazon Machine Images <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html>`_.
diff --git a/docs/report/introduction/methodology_aws/aws_instances.rst b/docs/report/introduction/methodology_aws/aws_instances.rst
index 0df0321c5f..18ae659de3 100644
--- a/docs/report/introduction/methodology_aws/aws_instances.rst
+++ b/docs/report/introduction/methodology_aws/aws_instances.rst
@@ -1,22 +1,40 @@
-Instances
----------
+AWS Performance Testbeds
+------------------------
-CSIT is using C5n instances for high compute applications that can take
-advantage of improved network throughput and packet rate performance. C5n
-instances offers up to 100 Gbps network bandwidth and increased memory over
-comparable C5 instances [aws_it]_.
+CSIT implements two virtual machine topology types running in AWS EC2:
-Features:
+- **2-Node Topology**: Consists of one EC2 instance as a System Under
+ Test (SUT) and one EC2 instance acting as a Traffic Generator
+ (TG), with both instances connected into a ring topology. Used for
+ executing tests that require frame encapsulations supported by TG.
-- 3.0 GHz Intel Xeon Platinum processors with Intel Advanced Vector Extension
- 512 (AVX-512) instruction set.
-- Sustained all core Turbo frequency of up to 3.4GHz, and single core turbo
- frequency of up to 3.5 GHz.
-- Requires HVM AMIs that include drivers for ENA and NVMe [aws_ena]_.
-- Network bandwidth increases to up to 100 Gbps, delivering increased
- performance for network intensive applications.
-- Powered by the AWS Nitro System, a combination of dedicated hardware and
- lightweight hypervisor.
+- **3-Node Topology**: Consists of two EC2 instances acting as a Systems
+ Under Test (SUTs) and one EC2 instance acting as a Traffic Generator
+ (TG), with all instances connected into a ring topology. Used for
+ executing tests that require frame encapsulations not supported by TG
+ e.g. certain overlay tunnel encapsulations and IPsec.
+
+AWS EC2 Instances
+-----------------
+
+CSIT is using AWS EC2 C5n instances as System Under Test and TG virtual
+machines. C5n instances got selected to take advantage of high network
+throughput and packet rate performance. C5n instances offer up to 100
+Gbps network bandwidth and increased memory over comparable C5
+instances. For more information, see
+`Instance types <https://aws.amazon.com/ec2/instance-types/>`_.
+
+C5n features:
+
+- 3.0 GHz Intel Xeon Platinum (Skylake) processors with Intel AVX-512
+ instructions.
+- Sustained all core Turbo frequency of up to 3.4GHz, and single core
+ turbo frequency of up to 3.5 GHz.
+- Requires HVM AMIs (Amazon Machine Images) that include drivers for ENA
+ and NVMe. See :ref:`csit_ami` for more information.
+- Network bandwidth to up to 100 Gbps.
+- Powered by the AWS Nitro System, a combination of dedicated hardware
+ and lightweight hypervisor.
+-------------+------+--------------+------------------------+-----------------------------+----------------------+
| Model | vCPU | Memory (GiB) | Instance Storage (GiB) | Network Bandwidth (Gbps)*** | EBS Bandwidth (Mbps) |
@@ -36,21 +54,24 @@ Features:
|c5n.metal | 72 | 192 | EBS-Only | 100 | 19,000 |
+-------------+------+--------------+------------------------+-----------------------------+----------------------+
-CSIT is configured by default to use `c5n.4xlarge` in `eu-central-1` AWS region
-due to allocation stability issues with `c5n.9xlarge` in `eu-central-1` region.
+CSIT is configured by default to use `c5n.4xlarge` in `eu-central-1` AWS
+region due to allocation stability issues with `c5n.9xlarge` in
+`eu-central-1` region.
-AWS Elastic Network Adapter (ENA)
----------------------------------
+AWS EC2 Networking
+------------------
-Enhanced networking uses single root I/O virtualization (SR-IOV) to provide
-high-performance networking capabilities on supported instance types. SR-IOV is
-a method of device virtualization that provides higher I/O performance and lower
-CPU utilization when compared to traditional virtualized network interfaces
-[aws_ena]_.
+CSIT EC2 instances are equipped with AWS Elastic Network Adapter
+(ENA) supporting AWS enhanced networking. Enhanced networking uses
+single root I/O virtualization (SR-IOV) to provide high-performance
+networking capabilities. For more information, see
+`Elastic Network Adapter <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking-ena.html>`_.
-Current advertised limits are captured in [aws_limits]_.
+For more information about the current advertised AWS ENA performance
+limits, see
+`Computed optimized instances <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/compute-optimized-instances.html>`_.
-.. [aws_it] `Instance types <https://aws.amazon.com/ec2/instance-types/>`_
-.. [aws_ena] `Elastic Network Adapter <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/enhanced-networking-ena.html>`_
-.. [aws_limits] `<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/compute-optimized-instances.html>`_ \ No newline at end of file
+CSIT DUTs make use of AWS ENA DPDK driver supplied by AWS and specified
+in
+`amzn drivers dpdk <https://github.com/amzn/amzn-drivers/tree/master/userspace/dpdk>`_.
diff --git a/docs/report/introduction/methodology_aws/aws_terraform.rst b/docs/report/introduction/methodology_aws/aws_terraform.rst
index 7c73e04b20..ebbef9000a 100644
--- a/docs/report/introduction/methodology_aws/aws_terraform.rst
+++ b/docs/report/introduction/methodology_aws/aws_terraform.rst
@@ -1,11 +1,12 @@
-Terraform-aws-csit modules
---------------------------
+AWS Deployments
+---------------
-Terraform-aws-csit module is IaaC - infrastructure as a code. Module uses the
-Amazon Web Services (AWS) provider to interact with resources provided by AWS
-to orchestrate virtual environment for running CSIT tests.
-
-- `aws <https://registry.terraform.io/providers/hashicorp/aws/latest/>`_.
+CSIT performance testbed deployments in AWS rely on
+Infrastructure-as-a-C (IaaC) Terraform AWS providers. Terraform
+providers specified in CSIT interact with resources provided by AWS to
+orchestrate virtual environment for running CSIT performance tests. For
+more information, see
+`Terraform Registry aws <https://registry.terraform.io/providers/hashicorp/aws/latest/>`_.
Compatibility
~~~~~~~~~~~~~
@@ -21,72 +22,72 @@ Compatibility
Requirements
~~~~~~~~~~~~
-Required modules and provider
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- Required Modules and Providers
-- `aws <https://registry.terraform.io/providers/hashicorp/aws/latest>`_.
-- `null <https://registry.terraform.io/providers/hashicorp/null/latest>`_.
-- `tls <https://registry.terraform.io/providers/hashicorp/tls>`_.
-- `vault <https://registry.terraform.io/providers/hashicorp/vault>`_.
+ - `Terraform Registry aws <https://registry.terraform.io/providers/hashicorp/aws/latest>`_.
+ - `Terraform Registry null <https://registry.terraform.io/providers/hashicorp/null/latest>`_.
+ - `Terraform Registry tls <https://registry.terraform.io/providers/hashicorp/tls>`_.
+ - `Terraform Registry vault <https://registry.terraform.io/providers/hashicorp/vault>`_.
-Required software
-^^^^^^^^^^^^^^^^^
+- Required software
-- `Vault <https://releases.hashicorp.com/vault/>`_ service available on
- specified ip/port.
+ - `Vault <https://releases.hashicorp.com/vault/>`_ service available
+ on specified ip/port.
Usage
~~~~~
- OPTIONAL: Enable logging
- Terraform does not have logging enabled by default, to enable logging
- to stderr, set up TF_LOG variable with specified loglevel:
- Available loglevels: TRACE, DEBUG, INFO, WARN, ERROR
- ::
+ - Terraform does not have logging enabled by default, to enable logging
+ to stderr, set up TF_LOG variable with specified loglevel.
+ - Available loglevels: TRACE, DEBUG, INFO, WARN, ERROR:
- export TF_LOG="LOGLEVEL"
+ ::
- It is also possible to store logged output to a file by setting up
- TF_LOG_PATH variable:
+ export TF_LOG="LOGLEVEL"
- ::
+ - It is also possible to store logged output to a file by setting up
+ TF_LOG_PATH variable:
- export TF_LOG_PATH="path/to/logfile"
+ ::
+
+ export TF_LOG_PATH="path/to/logfile"
- Run Terraform in a given root module folder depending on chosen testbed
- topology. Terraform will deploy and configure instances and other resources,
- all of these resources can be later identified on AWS via Environment tag.
- By default, Environment tag "CSIT-AWS" is used.
- Example:
+ topology.
- ::
+ - Terraform will deploy and configure instances and other resources,
+ all of these resources can be later identified on AWS via
+ Environment tag.
+ - By default, Environment tag "CSIT-AWS" is used. Example:
- cd fdio.infra.terraform/2n_aws_c5n/
- terraform init
- terraform plan
- terraform apply
+ ::
- This will deploy environment with default values, you can check the defaults
- in ./2n_aws_c5n/main.tf and ./2n_aws_c5n/variables.tf files
+ cd fdio.infra.terraform/2n_aws_c5n/
+ terraform init
+ terraform plan
+ terraform apply
- If you would like to change some of these values, you can:
+ - This will deploy environment with default values, you can check the
+ defaults in `./2n_aws_c5n/main.tf` and `./2n_aws_c5n/variables.tf`
+ files.
+ - If you would like to change some of these values, you can:
- 1. Set up TF_VAR_* environment variables prior to running 'terraform apply':
+ - Set up TF_VAR_* environment variables prior to running 'terraform apply':
- ::
+ ::
- export TF_VAR_testbed_name="testbed1"
+ export TF_VAR_testbed_name="testbed1"
- 2. Use '-var=varname=value' flag when running 'terraform apply':
+ - Use '-var=varname=value' flag when running 'terraform apply':
- ::
+ ::
- terraform apply -var=testbed_name=testbed1
+ terraform apply -var=testbed_name=testbed1
- Note:
- Only variables defined in variables.tf file of the root module can be
- changed using these methods.
+ - Note: Only variables defined in `variables.tf` file of the root
+ module can be changed using these methods.
- To clean up the AWS environment and remove all used resources, run:
@@ -94,12 +95,14 @@ Usage
terraform destroy
-Example usage
-~~~~~~~~~~~~~
+Deployment Example
+~~~~~~~~~~~~~~~~~~
-These are the default values for the AWS modules. The following example is
-2n topology (3n topology variant is very similar). Few variables are defined in
-a `variable.tf` file.
+Following is an example of a
+`Terraform deploy module <https://git.fd.io/csit/tree/fdio.infra.terraform/2n_aws_c5n/main.tf>`_
+for a CSIT 2-Node testbed topology with AWS variables set to default
+values. A number of variables is also defined in a
+`separate Terraform variable file <https://git.fd.io/csit/tree/fdio.infra.terraform/2n_aws_c5n/variables.tf>`_.
::
@@ -163,9 +166,10 @@ Secrets & Credentials
Set credentials manually
^^^^^^^^^^^^^^^^^^^^^^^^
-To set the credentials manually you first need to tell the module to not fetch
-credentials from Vault. To do that, set `provider "aws"` `access_key` and
-`secret_key` to custom value or use credentials file as a source.
+To set the credentials manually you first need to tell the module to not
+fetch credentials from Vault. To do that, set `provider "aws"`
+`access_key` and `secret_key` to custom value or use credentials file
+as a source.
::
diff --git a/docs/report/introduction/methodology_aws/index.rst b/docs/report/introduction/methodology_aws/index.rst
index 5da5253ccf..3e247dc6ce 100644
--- a/docs/report/introduction/methodology_aws/index.rst
+++ b/docs/report/introduction/methodology_aws/index.rst
@@ -1,5 +1,5 @@
-Amazon Web Services
-===================
+Testing in AWS EC2
+==================
.. toctree::