docs/report/introduction/methodology_aws/aws_terraform.rst

   1 AWS Deployments
   2 ---------------
   3
   4 CSIT performance testbed deployments in AWS rely on
   5 Infrastructure-as-a-C (IaaC) Terraform AWS providers. Terraform
   6 providers specified in CSIT interact with resources provided by AWS to
   7 orchestrate virtual environment for running CSIT performance tests. For
   8 more information, see
   9 `Terraform Registry aws <https://registry.terraform.io/providers/hashicorp/aws/latest/>`_.
  10
  11 Compatibility
  12 ~~~~~~~~~~~~~
  13
  14 +-----------+----------------+
  15 | Software  | OSS Version    |
  16 +===========+================+
  17 | Terraform | 1.0.3 or newer |
  18 +-----------+----------------+
  19 | Vault     | 1.8.4 or newer |
  20 +-----------+----------------+
  21
  22 Requirements
  23 ~~~~~~~~~~~~
  24
  25 - Required Modules and Providers
  26
  27   - `Terraform Registry aws <https://registry.terraform.io/providers/hashicorp/aws/latest>`_.
  28   - `Terraform Registry null <https://registry.terraform.io/providers/hashicorp/null/latest>`_.
  29   - `Terraform Registry tls <https://registry.terraform.io/providers/hashicorp/tls>`_.
  30   - `Terraform Registry vault <https://registry.terraform.io/providers/hashicorp/vault>`_.
  31
  32 - Required software
  33
  34   - `Vault <https://releases.hashicorp.com/vault/>`_ service available
  35     on specified ip/port.
  36
  37 Usage
  38 ~~~~~
  39
  40 - OPTIONAL: Enable logging
  41
  42   - Terraform does not have logging enabled by default, to enable logging
  43     to stderr, set up TF_LOG variable with specified loglevel.
  44   - Available loglevels: TRACE, DEBUG, INFO, WARN, ERROR:
  45
  46     ::
  47
  48       export TF_LOG="LOGLEVEL"
  49
  50   - It is also possible to store logged output to a file by setting up
  51     TF_LOG_PATH variable:
  52
  53     ::
  54
  55       export TF_LOG_PATH="path/to/logfile"
  56
  57 - Run Terraform in a given root module folder depending on chosen testbed
  58   topology.
  59
  60   - Terraform will deploy and configure instances and other resources,
  61     all of these resources can be later identified on AWS via
  62     Environment tag.
  63   - By default, Environment tag "CSIT-AWS" is used. Example:
  64
  65     ::
  66
  67       cd fdio.infra.terraform/2n_aws_c5n/
  68       terraform init
  69       terraform plan
  70       terraform apply
  71
  72   - This will deploy environment with default values, you can check the
  73     defaults in `./2n_aws_c5n/main.tf` and `./2n_aws_c5n/variables.tf`
  74     files.
  75   - If you would like to change some of these values, you can:
  76
  77     - Set up TF_VAR_* environment variables prior to running 'terraform apply':
  78
  79       ::
  80
  81         export TF_VAR_testbed_name="testbed1"
  82
  83     - Use '-var=varname=value' flag when running 'terraform apply':
  84
  85       ::
  86
  87         terraform apply -var=testbed_name=testbed1
  88
  89     - Note: Only variables defined in `variables.tf` file of the root
  90       module can be changed using these methods.
  91
  92 - To clean up the AWS environment and remove all used resources, run:
  93
  94   ::
  95
  96     terraform destroy
  97
  98 Deployment Example
  99 ~~~~~~~~~~~~~~~~~~
 100
 101 Following is an example of a
 102 `Terraform deploy module <https://git.fd.io/csit/tree/fdio.infra.terraform/2n_aws_c5n/main.tf>`_
 103 for a CSIT 2-Node testbed topology with AWS variables set to default
 104 values. A number of variables is also defined in a
 105 `separate Terraform variable file <https://git.fd.io/csit/tree/fdio.infra.terraform/2n_aws_c5n/variables.tf>`_.
 106
 107 ::
 108
 109   module "deploy" {
 110     source = "./deploy"
 111
 112     # Parameters starting with var. can be set using "TF_VAR_*" environment
 113     # variables or -var parameter when running "terraform apply", for default
 114     # values see ./variables.tf
 115     testbed_name          = var.testbed_name
 116     topology_name         = var.topology_name
 117     environment_name      = var.environment_name
 118     resources_name_prefix = var.resources_name_prefix
 119
 120     # AWS general
 121     region        = var.region
 122     avail_zone    = var.avail_zone
 123     instance_type = var.instance_type
 124     ami_image_tg  = var.ami_image_tg
 125     ami_image_sut = var.ami_image_sut
 126
 127     # AWS Network
 128     vpc_cidr_mgmt = "192.168.0.0/24"
 129     vpc_cidr_b    = "192.168.10.0/24"
 130     vpc_cidr_c    = "200.0.0.0/24"
 131     vpc_cidr_d    = "192.168.20.0/24"
 132
 133     tg_mgmt_ip   = "192.168.0.10"
 134     dut1_mgmt_ip = "192.168.0.11"
 135
 136     tg_if1_ip   = "192.168.10.254"
 137     tg_if2_ip   = "192.168.20.254"
 138     dut1_if1_ip = "192.168.10.11"
 139     dut1_if2_ip = "192.168.20.11"
 140
 141     trex_dummy_cidr_port_0 = "10.0.0.0/24"
 142     trex_dummy_cidr_port_1 = "20.0.0.0/24"
 143
 144     # Ansible
 145     ansible_python_executable = "/usr/bin/python3"
 146     ansible_file_path         = "../../fdio.infra.ansible/site.yaml"
 147     ansible_topology_path     = "../../fdio.infra.ansible/cloud_topology.yaml"
 148     ansible_provision_pwd     = "Csit1234"
 149
 150     # First run
 151     first_run_commands = [
 152       "sudo sed -i 's/^PasswordAuthentication/#PasswordAuthentication/' /etc/ssh/sshd_config",
 153       "sudo systemctl restart sshd",
 154       "sudo useradd --create-home -s /bin/bash provisionuser",
 155       "echo 'provisionuser:Csit1234' | sudo chpasswd",
 156       "echo 'provisionuser ALL = (ALL) NOPASSWD: ALL' | sudo tee -a /etc/sudoers",
 157       "sudo useradd --create-home -s /bin/bash testuser",
 158       "echo 'testuser:Csit1234' | sudo chpasswd",
 159       "echo 'testuser ALL = (ALL) NOPASSWD: ALL' | sudo tee -a /etc/sudoers"
 160     ]
 161   }
 162
 163 Secrets & Credentials
 164 ~~~~~~~~~~~~~~~~~~~~~
 165
 166 Set credentials manually
 167 ^^^^^^^^^^^^^^^^^^^^^^^^
 168
 169 To set the credentials manually you first need to tell the module to not
 170 fetch credentials from Vault. To do that, set `provider "aws"`
 171 `access_key` and `secret_key` to custom value or use credentials file
 172 as a source.
 173
 174 ::
 175
 176   provider "aws" {
 177     region     = var.region
 178     access_key = data.vault_aws_access_credentials.creds.access_key
 179     secret_key = data.vault_aws_access_credentials.creds.secret_key
 180   }