diff options
| -rw-r--r-- | docs/automation/terraform/index.rst | 26 | ||||
| -rw-r--r-- | docs/automation/terraform/terraformAWS.rst | 195 | ||||
| -rw-r--r-- | docs/automation/terraform/terraformAZ.rst | 206 | ||||
| -rw-r--r-- | docs/automation/terraform/terraformGoogle.rst | 134 | ||||
| -rw-r--r-- | docs/automation/terraform/terraformvSphere.rst | 133 | ||||
| -rw-r--r-- | docs/automation/terraform/terraformvyos.rst | 39 |
6 files changed, 401 insertions, 332 deletions
diff --git a/docs/automation/terraform/index.rst b/docs/automation/terraform/index.rst index 42af58bd..364a00b7 100644 --- a/docs/automation/terraform/index.rst +++ b/docs/automation/terraform/index.rst @@ -1,14 +1,32 @@ +:lastproofread: 2026-03-23 + ############## VyOS Terraform ############## + +VyOS supports development infrastructure via Terraform and provisioning +via Ansible. +Terraform allows you to automate the deployment of instances on a number of +cloud and virtual platforms. This section shows how to deploy VyOS on +multiple platforms: AWS, Microsoft Azure, Google Cloud Platform (GCP), +and VMware vSphere. +For more information, see the +official documentation for Terraform_ and Ansible_. + + + .. toctree:: :maxdepth: 1 - :caption: Content + :caption: Guides - terraformvyos terraformAWS terraformAZ - terraformvSphere terraformGoogle - + terraformvSphere + +.. stop_vyoslinter +.. _Terraform: https://developer.hashicorp.com/terraform/intro +.. _Ansible: https://docs.ansible.com +.. _install: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/automation/terraform/terraformAWS.rst b/docs/automation/terraform/terraformAWS.rst index e068377d..057f3513 100644 --- a/docs/automation/terraform/terraformAWS.rst +++ b/docs/automation/terraform/terraformAWS.rst @@ -1,12 +1,13 @@ -:lastproofread: 2024-01-11 +:lastproofread: 2026-03-16 .. _terraformAWS: -Deploying VyOS in the AWS cloud -=============================== +Deploy VyOS on AWS with Terraform and Ansible +============================================= -With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the AWS cloud. If necessary, the infrastructure can be removed using terraform. -Also we will make provisioning using Ansible. +You can use Terraform to quickly deploy VyOS-based infrastructure +on AWS and remove infrastructure when it's no longer needed. +Additionally, you can use Ansible for provisioning. .. image:: /_static/images/aws.png @@ -14,28 +15,33 @@ Also we will make provisioning using Ansible. :align: center :alt: Network Topology Diagram -In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the AWS cloud and make provisioning using Ansible. +On this page you'll learn how to: +* Create the necessary files for Terraform and Ansible. +* Use Terraform to create a single instance on AWS and use Ansible for + provisioning. -Preparation steps for deploying VyOS on AWS -------------------------------------------- -How to create a single instance and install your configuration using Terraform+Ansible+AWS -Step by step: +Prepare to deploy VyOS with Terraform on AWS +-------------------------------------------- + +To create a single instance and install your configuration using +Terraform, Ansible, and AWS, follow these steps: AWS +^^^ -1 Create an account with AWS and get your "access_key", "secret key" +1. Create an account with AWS and get your ``access_key`` and ``secret_key``. -2 Create a key pair_ and download your .pem key +2. Create a key pair_ and download your ``.pem`` key. .. image:: /_static/images/keypairs.png :width: 50% :align: center :alt: Network Topology Diagram -3 Create a security group_ for the new VyOS instance and open all traffic +3. Create a security group_ for the new VyOS instance and open all traffic. .. image:: /_static/images/sg.png :width: 50% @@ -49,57 +55,71 @@ AWS :alt: Network Topology Diagram Terraform +^^^^^^^^^ +1. Create an UNIX or Windows instance. - 1 Create an UNIX or Windows instance +2. Download and install + `Terraform <https://developer.hashicorp.com/terraform/install>`__. - 2 Download and install Terraform +3. Create a folder, for example ``/root/awsterraform``: - 3 Create the folder for example /root/awsterraform + .. code-block:: none -.. code-block:: none + mkdir /root/awsterraform - mkdir /root/awsterraform +.. stop_vyoslinter - 4 Copy all files into your Terraform project "/root/awsterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for AWS`_ +4. Copy all files into your Terraform project + (``vyos.tf``, ``var.tf``, ``terraform.tfvars``, ``version.tf``). + See `Structure of files in Terraform for AWS <#structure-of-files-in-terraform-for-aws>`__ for more details. - 5 Type the commands : +.. start_vyoslinter + +5. Run the following commands: .. code-block:: none - cd /<your folder> + cd /<your folder> terraform init - Ansible +^^^^^^^ - 1 Create an UNIX instance whenever you want (local, cloud, and so on) +1. Create a UNIX instance whenever you need. - 2 Download and install Ansible +2. Download and install Ansible - 3 Create the folder for example /root/aws/ +3. Create a folder, for example ``/root/aws/``. - 4 Copy all files into your Ansible project "/root/aws/" (ansible.cfg, instance.yml, mykey.pem and "all"), more detailed see `Structure of files Ansible for AWS`_ +.. stop_vyoslinter -mykey.pem you have to get using step 1.2 +4. Copy all files into your Ansible project + (``ansible.cfg``, ``instance.yml``, + ``mykey.pem``, and ``all``). + See `Structure of files in Ansible for AWS <#structure-of-files-in-ansible-for-aws>`__ for more details. + You can obtain ``mykey.pem`` by creating a key pair_ in AWS and + downloading your ``.pem`` key. +.. start_vyoslinter -Start +Deploy with Terraform +^^^^^^^^^^^^^^^^^^^^^ -Type the commands on your Terrafom instance: +Run the following commands on your Terraform instance: .. code-block:: none cd /<your folder> - terraform plan - terraform apply + terraform plan + terraform apply yes -Start creating an AWS instance and check the result ---------------------------------------------------- +Create an AWS instance and check its configuration +-------------------------------------------------- .. code-block:: none @@ -252,8 +272,9 @@ Start creating an AWS instance and check the result -After executing all the commands you will have your VyOS instance on the AWS cloud with your configuration, it's a very convenient desition. -If you need to delete the instance please type the command: +After running all the commands, your VyOS instance is deployed on +AWS with your specified configuration. +To delete the instance, type the following command: .. code-block:: none @@ -263,26 +284,29 @@ If you need to delete the instance please type the command: Troubleshooting --------------- -1 Ansible doesn't connect via SSH to your AWS instance: you have to check that your SSH key has copied into the path /root/aws/. -Also, increase the time in the file instance.yml from 300 sec to 500 sec or more. (It depends on your location). -Make sure that you have opened access to the instance in the security group. +1. If Ansible doesn't connect via SSH to your AWS instance, verify that + your SSH key is in the path ``/root/aws/``. You might need to + increase the timeout in ``instance.yml`` from 300 seconds to 500 + seconds or more, depending on your location. Make sure that the + security group allows access to the instance. - 2 Terraform doesn't connect via SSH to your Ansible instance: you have to check the correct login and password in the part of the file VyOS. tf +2. If Terraform doesn't connect via SSH to your Ansible instance, + verify the correct login and password in the ``VyOS.tf`` file. -.. code-block:: none + .. code-block:: none - connection { - type = "ssh" - user = "root" # open root access using login and password on your Ansible - password = var.password # check password in the file terraform.tfvars isn't empty - host = var.host # check the correct IP address of your Ansible host - } + connection { + type = "ssh" + user = "root" # open root access using login and password on your Ansible + password = var.password # check password in the file terraform.tfvars isn't empty + host = var.host # check the correct IP address of your Ansible host + } -Make sure that Ansible is pinging from Terrafom. +Make sure Ansible can ping from Terraform. -Structure of files Terrafom for AWS ------------------------------------ +Structure of files in Terraform for AWS +--------------------------------------- .. code-block:: none @@ -293,20 +317,20 @@ Structure of files Terrafom for AWS └── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) - -File contents of Terrafom for AWS ---------------------------------- +File contents of Terraform for AWS +---------------------------------- -vyos.tf +``vyos.tf`` .. code-block:: none ############################################################################## - # Build an VyOS VM from the Marketplace - # To finde nessesery AMI image_ in AWS + # Build a VyOS VM from the Marketplace. + # Find the necessary AMI image_ in AWS. # - # In the script vyos.tf we'll use default values (you can chang it as you need) + # The vyos.tf script uses default values (you can change them as + # needed) # AWS Region = "us-east-1" # AMI = "standard AMI of VyOS from AWS Marketplace" # Size of VM = "t2.micro" @@ -349,9 +373,9 @@ vyos.tf } ############################################################################## - # specific variable (to getting type "terraform plan"): + # Specific variable (to getting type "terraform plan"): # aws_instance.myVyOSec2.public_ip - the information about public IP address - # of our instance, needs for provisioning and ssh connection from Ansible + # of our instance, needs for provisioning and SSH connection from Ansible ############################################################################## output "my_IP"{ @@ -359,11 +383,9 @@ vyos.tf } ############################################################################## - # - # IP of aws instance copied to a file ip.txt in local system Terraform - # ip.txt looks like: - # cat ./ip.txt - # ххх.ххх.ххх.ххх + # The IP address of the AWS instance is copied to the ip.txt file + # on the local Terraform system. The ip.txt file contains the public + # IP address in the format: xxx.xxx.xxx.xxx ############################################################################## resource "local_file" "ip" { @@ -374,7 +396,8 @@ vyos.tf #connecting to the Ansible control node using SSH connection ############################################################################## - # Steps "SSHconnection1" and "SSHconnection2" need to get file ip.txt from the terraform node and start remotely the playbook of Ansible. + # The "SSHconnection1" and "SSHconnection2" steps retrieve ip.txt + # from the Terraform node and run the Ansible playbook remotely. ############################################################################## resource "null_resource" "SSHconnection1" { @@ -386,8 +409,8 @@ vyos.tf host = var.host } - #copying the ip.txt file to the Ansible control node from local system - + # Copy the ip.txt file to the Ansible control node from the local + # system provisioner "file" { source = "ip.txt" destination = "/root/aws/ip.txt" # The folder of your Ansible project @@ -402,7 +425,7 @@ vyos.tf password = var.password host = var.host } - #command to run Ansible playbook on remote Linux OS + # Run Ansible playbook on remote Linux OS provisioner "remote-exec" { inline = [ "cd /root/aws/", @@ -412,7 +435,7 @@ vyos.tf } -var.tf +``var.tf`` .. code-block:: none @@ -436,7 +459,7 @@ var.tf sensitive = true } -versions.tf +``versions.tf`` .. code-block:: none @@ -449,7 +472,7 @@ versions.tf } } -terraform.tfvars +``terraform.tfvars`` .. code-block:: none @@ -459,8 +482,8 @@ terraform.tfvars secret = "" # secret_key for AWS -Structure of files Ansible for AWS ----------------------------------- +Structure of files in Ansible for AWS +------------------------------------- .. code-block:: none @@ -475,7 +498,7 @@ Structure of files Ansible for AWS File contents of Ansible for AWS -------------------------------- -ansible.cfg +``ansible.cfg`` .. code-block:: none @@ -485,14 +508,14 @@ ansible.cfg private_key_file = /root/aws/awsterraform.pem # check the name remote_user=vyos -mykey.pem +``mykey.pem`` .. code-block:: none Copy your key.pem from AWS -instance.yml +``instance.yml`` @@ -500,9 +523,11 @@ instance.yml ############################################################################## # About tasks: - # "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds - # "Configure general settings for the VyOS hosts group" - make provisioning into AWS VyOS node - # You have to add all necessary cammans of VyOS under the block "lines:" + # "Wait 300 seconds, but only start checking after 60 seconds" - + # attempts SSH connection every 60 seconds until 300 seconds + # "Configure general settings for the VyOS hosts group" - + # provisions the AWS VyOS node + # Add all necessary VyOS commands under the "lines:" block ############################################################################## @@ -525,7 +550,7 @@ instance.yml true -group_vars/all +``group_vars/all`` .. code-block:: none @@ -533,15 +558,19 @@ group_vars/all ansible_network_os: vyos.vyos.vyos ansible_user: vyos -Sourse files for AWS from GIT ------------------------------ +Source files on GitHub +---------------------- -All files about the article can be found here_ +All files related to deploying VyOS on AWS with Terraform and Ansible +can be found in the vyos-automation_ repository. +.. stop_vyoslinter .. _link: https://developer.hashicorp.com/terraform/intro .. _install: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli .. _pair: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html .. _group: https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-sg.html .. _image: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main
\ No newline at end of file +.. _vyos-automation: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/AWS_terraform_ansible_single_vyos_instance-main + +.. start_vyoslinter diff --git a/docs/automation/terraform/terraformAZ.rst b/docs/automation/terraform/terraformAZ.rst index a0fea023..9e094aea 100644 --- a/docs/automation/terraform/terraformAZ.rst +++ b/docs/automation/terraform/terraformAZ.rst @@ -1,69 +1,88 @@ -:lastproofread: 2024-03-03 +:lastproofread: 2026-03-19 .. _terraformAZ: -Deploying VyOS in the Azure cloud -================================= +Deploy VyOS on Microsoft Azure with Terraform and Ansible +========================================================= -With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the Azure cloud. If necessary, the infrastructure can be removed using terraform. -Also we will make provisioning using Ansible. +You can use Terraform to quickly deploy VyOS-based infrastructure +on Microsoft Azure (hereafter referred to as *Azure*) and remove +infrastructure when it's no longer needed. +Additionally, you can use Ansible for provisioning. -In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the Azure cloud and make provisioning using Ansible. +On this page you'll learn how to: -Preparation steps for deploying VyOS on Azure ---------------------------------------------- +* Create the necessary files for Terraform and Ansible. +* Use Terraform to create a single instance on Azure and use Ansible for + provisioning. -How to create a single instance and install your configuration using Terraform+Ansible+Azure -Step by step: +Prepare to deploy VyOS with Terraform on Azure +---------------------------------------------- + +To create a single instance and install your configuration using +Terraform, Ansible, and Azure, follow these steps: Azure +^^^^^ - 1 Create an account with Azure +1. Create an `Azure account <https://azure.microsoft.com/>`__. Terraform +^^^^^^^^^ - 1 Create an UNIX or Windows instance +1. Create an UNIX or Windows instance. - 2 Download and install Terraform +2. Download and install + `Terraform <https://developer.hashicorp.com/terraform/install>`__. - 3 Create the folder for example /root/azvyos/ +3. Create the folder for example ``/root/azvyos/``. .. code-block:: none - mkdir /root/azvyos + mkdir /root/azvyos - 4 Copy all files into your Terraform project "/root/azvyos" (vyos.tf, var.tf, terraform.tfvars), more detailed see `Structure of files Terrafom for Azure`_ +.. stop_vyoslinter - 5 Login with Azure using the command +4. Copy all files into your Terraform project "/root/azvyos" + (``vyos.tf``, ``var.tf``, ``terraform.tfvars``). For more details, see + `Structure of files in Terraform for Azure <#structure-of-files-in-terraform-for-azure>`_. -.. code-block:: none +.. start_vyoslinter - az login +5. Log in to Azure using the command: -2.6 Type the commands : + .. code-block:: none -.. code-block:: none + az login + +6. Run the following commands to initialize Terraform: + + .. code-block:: none - cd /<your folder> - terraform init + cd /<your folder> + terraform init Ansible +^^^^^^^ - 1 Create an UNIX instance whenever you want (local, cloud, and so on) +1. Create an UNIX instance either locally or in the cloud. - 2 Download and install Ansible +2. Download and install Ansible - 3 Create the folder for example /root/az/ +3. Create a folder, for example ``/root/az/``. - 4 Copy all files into your Ansible project "/root/az/" (ansible.cfg, instance.yml,"all"), more detailed see `Structure of files Ansible for Azure`_ +4. Copy all files into your Ansible project ``/root/az/`` (``ansible.cfg``, + ``instance.yml``, ``all``). For more details, see + `Structure of files in Ansible for Azure`_ -Start +Deploy with Terraform +^^^^^^^^^^^^^^^^^^^^^ -Type the commands on your Terrafom instance: +Run the following commands on your Terraform instance: .. code-block:: none @@ -72,27 +91,29 @@ Type the commands on your Terrafom instance: terraform apply yes -After executing all the commands you will have your VyOS instance on the Azure cloud with your configuration, it's a very convenient desition. -If you need to delete the instance please type the command: +After executing all the commands, your VyOS instance is deployed to +Azure with your configuration. +If you need to delete the instance, run the following command: .. code-block:: none terraform destroy -Structure of files Terrafom for Azure -------------------------------------- +Structure of files in Terraform for Azure +----------------------------------------- .. code-block:: none . ├── vyos.tf # The main script - ├── var.tf # File for the changing version of Terraform. - └── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) + ├── var.tf # File for the Terraform version. + └── terraform.tfvars # Values for all variables (passwords, + # login, IP addresses, etc.) -File contents of Terrafom for Azure ------------------------------------ +File contents of Terraform for Azure +------------------------------------ -vyos.tf +``vyos.tf`` .. code-block:: none @@ -101,18 +122,18 @@ vyos.tf # HashiCorp Guide to Using Terraform on Azure # This Terraform configuration will create the following: # Resource group with a virtual network and subnet - # An VyOS server without ssh key (only login+password) + # A VyOS server without SSH key (only login+password) ############################################################################## - # Chouse a provider + # Choose a provider provider "azurerm" { features {} } - # Create a resource group. In Azure every resource belongs to a - # resource group. - + # Create a resource group. In Azure, every resource belongs to a + # resource group. + resource "azurerm_resource_group" "azure_vyos" { name = "${var.resource_group}" location = "${var.location}" @@ -126,8 +147,8 @@ vyos.tf address_space = ["${var.address_space}"] resource_group_name = "${var.resource_group}" } - - # Build a subnet to run our VMs in. + + # Build a subnet to run your VMs. resource "azurerm_subnet" "subnet" { name = "${var.prefix}subnet" @@ -137,20 +158,21 @@ vyos.tf } ############################################################################## - # Build an VyOS VM from the Marketplace - # To finde nessesery image use the command: + # Build a VyOS VM from the Marketplace. + # To find the necessary image, use the command: # # az vm image list --offer vyos --all # - # Now that we have a network, we'll deploy an VyOS server. - # An Azure Virtual Machine has several components. In this example we'll build - # a security group, a network interface, a public ip address, a storage - # account and finally the VM itself. Terraform handles all the dependencies - # automatically, and each resource is named with user-defined variables. + # Now that you have a network, you can deploy a VyOS server. + # An Azure Virtual Machine has several components. In this example, + # you build a security group, a network interface, a public IP + # address, a storage account, and finally the VM itself. Terraform + # handles all the dependencies automatically, and each resource is + # named with user-defined variables. ############################################################################## - # Security group to allow inbound access on port 22 (ssh) + # Security group to allow inbound access on port 22 (SSH) resource "azurerm_network_security_group" "vyos-sg" { name = "${var.prefix}-sg" @@ -194,8 +216,9 @@ vyos.tf allocation_method = "Dynamic" } - # Build a virtual machine. This is a standard VyOS instance from Marketplace. - + # Build a virtual machine. This is a standard VyOS instance from + # Marketplace. + resource "azurerm_virtual_machine" "vyos" { name = "${var.hostname}-vyos" location = "${var.location}" @@ -204,8 +227,8 @@ vyos.tf network_interface_ids = ["${azurerm_network_interface.vyos-nic.id}"] delete_os_disk_on_termination = "true" - - # To finde an information about the plan use the command: + + # To find information about the plan, use the command: # az vm image list --offer vyos --all plan { @@ -247,27 +270,28 @@ vyos.tf output "public_ip_address" { value = data.azurerm_public_ip.example.ip_address } - - # IP of AZ instance copied to a file ip.txt in local system - + + # IP of AZ instance copied to a file ip.txt in the local system. + resource "local_file" "ip" { content = data.azurerm_public_ip.example.ip_address filename = "ip.txt" } - - #Connecting to the Ansible control node using SSH connection - + + # Connect to the Ansible control node via SSH + resource "null_resource" "nullremote1" { - depends_on = ["azurerm_virtual_machine.vyos"] + depends_on = ["azurerm_virtual_machine.vyos"] connection { type = "ssh" user = "root" password = var.password host = var.host } - - # Copying the ip.txt file to the Ansible control node from local system - + + # Copy the ip.txt file to the Ansible control node from the local + # system + provisioner "file" { source = "ip.txt" destination = "/root/az/ip.txt" @@ -282,9 +306,9 @@ vyos.tf password = var.password host = var.host } - - # Command to run ansible playbook on remote Linux OS - + + # Run the Ansible playbook on the remote Linux OS + provisioner "remote-exec" { inline = [ @@ -295,15 +319,14 @@ vyos.tf } -var.tf +``var.tf`` .. code-block:: none ############################################################################## # Variables File # - # Here is where we store the default values for all the variables used in our - # Terraform code. + # Default values for all variables used in Terraform code. ############################################################################## variable "resource_group" { @@ -351,7 +374,7 @@ var.tf default = "LRS" } - # The most chippers size + # The most cost-effective size variable "vm_size" { description = "Specifies the size of the virtual machine." @@ -402,7 +425,7 @@ var.tf description = "IP of my Ansible" } -terraform.tfvars +``terraform.tfvars`` .. code-block:: none @@ -410,8 +433,8 @@ terraform.tfvars host = "" # IP of my Ansible -Structure of files Ansible for Azure ------------------------------------- +Structure of files in Ansible for Azure +--------------------------------------- .. code-block:: none @@ -425,7 +448,7 @@ Structure of files Ansible for Azure File contents of Ansible for Azure ---------------------------------- -ansible.cfg +``ansible.cfg`` .. code-block:: none @@ -435,16 +458,18 @@ ansible.cfg remote_user=vyos -instance.yml +``instance.yml`` .. code-block:: none ############################################################################## # About tasks: - # "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds - # "Configure general settings for the VyOS hosts group" - make provisioning into Azure VyOS node - # You have to add all necessary cammans of VyOS under the block "lines:" + # "Wait 300 seconds, but only start checking after 60 seconds" - Tries + # to make SSH connection every 60 seconds until 300 seconds. + # "Configure general settings for the VyOS hosts group" - Provision + # the Azure VyOS node. + # Add all necessary commands for VyOS under the block "lines:" ############################################################################## @@ -467,7 +492,7 @@ instance.yml true -group_vars/all +``group_vars/all`` .. code-block:: none @@ -478,11 +503,12 @@ group_vars/all ansible_user: vyos ansible_ssh_pass: Vyos0! -Sourse files for Azure from GIT -------------------------------- - -All files about the article can be found here_ - -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main - +Source files on GitHub +---------------------- +All files related to deploying VyOS on Azure with Terraform and Ansible +can be found in the vyos-automation_ repository. + +.. stop_vyoslinter +.. _vyos-automation: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Azure_terraform_ansible_single_vyos_instance-main +.. start_vyoslinter diff --git a/docs/automation/terraform/terraformGoogle.rst b/docs/automation/terraform/terraformGoogle.rst index 41a484c5..4bcb9898 100644 --- a/docs/automation/terraform/terraformGoogle.rst +++ b/docs/automation/terraform/terraformGoogle.rst @@ -1,32 +1,38 @@ -:lastproofread: 2024-03-25 +:lastproofread: 2026-03-23 .. _terraformgoogle: -Deploying VyOS in the Google Cloud -================================== +Deploy VyOS on Google Cloud with Terraform and Ansible +====================================================== -With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the Google Cloud. If necessary, the infrastructure can be removed using terraform. -Also we will make provisioning using Ansible. +Using Terraform, you can quickly deploy VyOS-based infrastructure on +Google Cloud Platform (GCP) and remove the +infrastructure when it's no longer needed. +Additionally, you can use Ansible for provisioning. -In this case, we'll create the necessary files for Terraform and Ansible. Next, using Terraform, we'll create a single instance on the Google Cloud and make provisioning using Ansible. +On this page you'll learn how to: +* Create the necessary files for Terraform and Ansible. +* Use Terraform to create a single instance on GCP and use Ansible for +provisioning. -Preparation steps for deploying VyOS on Google ----------------------------------------------- +Prepare to deploy VyOS with Terraform on GCP +-------------------------------------------- -How to create a single instance and install your configuration using Terraform+Ansible+Google -Step by step: +To create a single instance and install your configuration using +Terraform, Ansible, and GCP, follow these steps: -Google Cloud +GCP +^^^ -1 Create an account with Google Cloud and a new project +1. Create an account with GCP and a new project. .. image:: /_static/images/project.png :width: 50% :align: center :alt: Network Topology Diagram -2 Create a service aacount and download your key (.JSON) +2. Create a service account and download your key (a JSON file). .. image:: /_static/images/service.png :width: 50% @@ -38,7 +44,8 @@ Google Cloud :align: center :alt: Network Topology Diagram -The .JSON file download automaticly after creating and will look like: +The .JSON file downloads automatically after you create it and looks +like the following: .. image:: /_static/images/json.png :width: 50% @@ -47,21 +54,29 @@ The .JSON file download automaticly after creating and will look like: Terraform +^^^^^^^^^ -1 Create an UNIX or Windows instance +1. Create an UNIX or Windows instance. -2 Download and install Terraform +2. Download and install + `Terraform <https://developer.hashicorp.com/terraform/install>`__. -3 Create the folder for example /root/google +3. Create the folder. For example, ``/root/google``. .. code-block:: none mkdir /root/google + +.. stop_vyoslinter +4. Copy all files into your Terraform project ``/root/google`` + (``vyos.tf``, ``var.tf``, ``terraform.tfvars``, ``mykey.json``). + For more details, + see `Structure of files Terraform for Google Cloud <#structure-of-files-in-terraform-for-google-cloud>`_ -4 Copy all files into your Terraform project "/root/google" (vyos.tf, var.tf, terraform.tfvars, .JSON), more detailed see `Structure of files Terrafom for google cloud`_ +.. start_vyoslinter -5 Type the commands : +5. Run the following commands: .. code-block:: none @@ -71,23 +86,27 @@ Terraform Ansible +^^^^^^^ +1. Create an UNIX instance either locally or in the cloud. -1 Create an UNIX instance whenever you want (local, cloud, and so on) +2. Download and install Ansible -2 Download and install Ansible +3. Create the folder for example /root/google/ -3 Create the folder for example /root/google/ +4. Copy all files into your Ansible project ``/root/google/`` + (``ansible.cfg``, ``instance.yml``, ``mykey.json``, and ``all``). For more + details, see `Structure of files in Ansible for Google Cloud`_ -4 Copy all files into your Ansible project "/root/google/" (ansible.cfg, instance.yml, mykey.json and "all"), more detailed see `Structure of files Ansible for Google Cloud`_ +You obtain ``mykey.json`` when you create a service account in GCP +and download the key (a JSON file). -mykey.json you have to get using step 2 of the Google Cloud +Deploy with Terraform +^^^^^^^^^^^^^^^^^^^^^ -Start - -Type the commands on your Terraform instance: +Run the following commands on your Terraform instance: .. code-block:: none @@ -97,8 +116,8 @@ Type the commands on your Terraform instance: yes -Start creating a Google Cloud instance and check the result. ------------------------------------------------------------ +Create a GCP instance and check its configuration +------------------------------------------------- .. code-block:: none @@ -330,8 +349,9 @@ Start creating a Google Cloud instance and check the result. -After executing all the commands, you will have your VyOS instance on the Google Cloud with your configuration; it's a very convenient decision. -If you need to delete the instance, please type the command: +After running all the commands, your VyOS instance is deployed on +GCP with your specified configuration. +To delete the instance, type the following command: .. code-block:: none @@ -341,10 +361,12 @@ If you need to delete the instance, please type the command: Troubleshooting --------------- -1 Increase the time in the file instance.yml from 300 sec to 500 sec or more. (It depends on your location). -Make sure that you have opened access to the instance in the security group. +1. Increase the timeout value in ``instance.yml`` from 300 seconds to + 500 seconds or more (depends on your location). Ensure that the + security group allows access to the instance. -2 Terraform doesn't connect via SSH to your Ansible instance: you have to check the correct login and password in the part of the file VyOS.tf +2. If Terraform doesn't connect via SSH to your Ansible instance: + Check the correct login and password in the ``VyOS.tf`` file. .. code-block:: none @@ -356,25 +378,25 @@ Make sure that you have opened access to the instance in the security group. } -Make sure that Ansible is pinging from Terrafom. +Verify that Ansible can ping from Terraform. -Structure of files Terrafom for Google Cloud --------------------------------------------- +Structure of files in Terraform for Google Cloud +------------------------------------------------ .. code-block:: none . ├── vyos.tf # The main script - ├── ***.JSON # The credential file from Google Cloud + ├── ***.JSON # The credential file from GCP ├── var.tf # The file of all variables in "vyos.tf" └── terraform.tfvars # The value of all variables (passwords, login, IP addresses and so on) -File contents of Terrafom for Google Cloud ------------------------------------------- +File contents of Terraform for Google Cloud +------------------------------------------- -vyos.tf +``vyos.tf`` .. code-block:: none @@ -535,7 +557,7 @@ vyos.tf } -var.tf +``var.tf`` .. code-block:: none @@ -553,7 +575,7 @@ var.tf } ############################################################################## - # You can choose more chipper type than n2-highcpu-4 + # You can choose a lower cost machine type than n2-highcpu-4 ############################################################################## variable "machine_type" { @@ -620,7 +642,7 @@ var.tf } -terraform.tfvars +``terraform.tfvars`` .. code-block:: none @@ -635,8 +657,8 @@ terraform.tfvars host = "" # IP of my Ansible -Structure of files Ansible for Google Cloud -------------------------------------------- +Structure of files in Ansible for Google Cloud +---------------------------------------------- .. code-block:: none @@ -650,7 +672,7 @@ Structure of files Ansible for Google Cloud File contents of Ansible for Google Cloud ----------------------------------------- -ansible.cfg +``ansible.cfg`` .. code-block:: none @@ -659,7 +681,7 @@ ansible.cfg host_key_checking= False remote_user=vyos -instance.yml +``instance.yml`` .. code-block:: none @@ -667,7 +689,7 @@ instance.yml # About tasks: # "Wait 300 seconds, but only start checking after 60 seconds" - try to make ssh connection every 60 seconds until 300 seconds # "Configure general settings for the VyOS hosts group" - make provisioning into Google Cloud VyOS node - # You have to add all necessary cammans of VyOS under the block "lines:" + # Add all necessary VyOS commands under the "lines:" block ############################################################################## @@ -690,7 +712,7 @@ instance.yml true -group_vars/all +``group_vars/all`` .. code-block:: none @@ -699,10 +721,12 @@ group_vars/all ansible_user: vyos ansible_ssh_pass: vyos -Sourse files for Google Cloud from GIT --------------------------------------- - -All files about the article can be found here_ +Source files on GitHub +---------------------- +All files related to deploying VyOS on Google Cloud Platform with +Terraform and Ansible can be found in the vyos-automation_ repository. -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Google_terraform_ansible_single_vyos_instance-main +.. stop_vyoslinter +.. _vyos-automation: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Google_terraform_ansible_single_vyos_instance-main +.. start_vyoslinter diff --git a/docs/automation/terraform/terraformvSphere.rst b/docs/automation/terraform/terraformvSphere.rst index 5a9aa8f5..1866fa8e 100644 --- a/docs/automation/terraform/terraformvSphere.rst +++ b/docs/automation/terraform/terraformvSphere.rst @@ -1,53 +1,61 @@ -:lastproofread: 2024-03-03 +:lastproofread: 2026-03-23 .. _terraformvSphere: -Deploying VyOS in the vSphere infrastructure -============================================ +Deploy VyOS on VMware vSphere with Terraform and Ansible +======================================================== -With the help of Terraform, you can quickly deploy VyOS-based -infrastructure in the vSphere. -Also we will make provisioning using Ansible. +You can use Terraform to quickly deploy VyOS-based infrastructure +on VMware vSphere (hereafter referred to as *vSphere*) and remove +infrastructure when it's no longer needed. +Additionally, you can use Ansible for provisioning. -In this case, we'll create the necessary files for Terraform and -Ansible next using Terraform we'll create a single instance on the -vSphere cloud and make provisioning using Ansible. +On this page you'll learn how to: -Preparation steps for deploying VyOS on vSphere ------------------------------------------------ +* Create the necessary files for Terraform and Ansible. +* Use Terraform to create a single instance on Azure and use Ansible for + provisioning. -How to create a single instance and install your configuration using -Terraform+Ansible+vSphere -Step by step: +Prepare to deploy VyOS with Terraform on vSphere +------------------------------------------------ +To create a single instance and install your configuration using +Terraform, Ansible, and vSphere, follow these steps: vSphere +^^^^^^^ - 1 Collect all data in to file "terraform.tfvars" and create - resources for example "terraform" +.. stop_vyoslinter + +1. Add all necessary data to the ``terraform.tfvars`` + `file <https://github.com/vyos/vyos-automation/blob/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main/terraform.tfvars>`__ + and create resources. +.. start_vyoslinter Terraform +^^^^^^^^^ - 1 Create an UNIX or Windows instance +1. Create an UNIX or Windows instance. - 2 Download and install Terraform +2. Download and install + `Terraform <https://developer.hashicorp.com/terraform/install>`__. - 3 Create the folder for example /root/vsphereterraform +3. Create the folder for example ``/root/vsphereterraform``. .. code-block:: none mkdir /root/vsphereterraform - 4 Copy all files into your Terraform project - "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars, - version.tf), more detailed see - `Structure of files Terraform for vSphere`_ +4. Copy all files into your Terraform project ``/root/vsphereterraform`` + (``vyos.tf``, ``var.tf``, ``terraform.tfvars``, ``version.tf``). + For more details, + see `Structure of files in Terraform for vSphere`_ - 5 Type the commands : +5. Run the following commands: .. code-block:: none @@ -56,23 +64,25 @@ Terraform Ansible +^^^^^^^ - 1 Create an UNIX instance whenever you want (local, cloud, and so on) +1. Create an UNIX instance either locally or in the cloud. - 2 Download and install Ansible +2. Download and install Ansible. - 3 Create the folder for example /root/vsphereterraform/ +3. Create the folder. For example, ``/root/vsphereterraform/``. - 4 Copy all files into your Ansible project - "/root/vsphereterraform/" (ansible.cfg, instance.yml, "all"), - more detailed see `Structure of files Ansible for vSphere`_ +4. Copy all files into your Ansible project ``/root/vsphereterraform/`` + (``ansible.cfg``, ``instance.yml``, ``all``). For more details, see + `Structure of files in Ansible for vSphere`_ -Start +Deploy with Terraform +^^^^^^^^^^^^^^^^^^^^^ -Type the commands on your Terraform instance: +Run the following commands on your Terraform instance: .. code-block:: none @@ -82,31 +92,31 @@ Type the commands on your Terraform instance: yes -After executing all the commands you will have your VyOS instance on -the vSphere with your configuration, it's a very convenient decision. -If you need to delete the instance please type the command: - +After executing these commands, your VyOS instance is deployed to +vSphere with your configuration. +If you need to delete the instance, run the following command: .. code-block:: none terraform destroy -Structure of files Terraform for vSphere ---------------------------------------- +Structure of files in Terraform for vSphere +------------------------------------------- .. code-block:: none . - ├── vyos.tf # The main script - ├── versions.tf # File for the changing version of Terraform. - ├── var.tf # File for the changing version of Terraform. - └── terraform.tfvars # The value of all variables + ├── vyos.tf # The main script. + ├── versions.tf # File for Terraform version. + ├── var.tf # File for Terraform version. + └── terraform.tfvars # Values for all variables (passwords, + # login, IP addresses, etc.). File contents of Terraform for vSphere -------------------------------------- +-------------------------------------- -vyos.tf +``vyos.tf`` .. code-block:: none @@ -231,7 +241,7 @@ vyos.tf } -versions.tf +``versions.tf`` .. code-block:: none @@ -247,7 +257,7 @@ versions.tf } } -var.tf +``var.tf`` .. code-block:: none @@ -291,17 +301,17 @@ var.tf } variable "host" { - description = "name if yor host" + description = "Name of your host" type = string } variable "remotename" { - description = "the name of you VM" + description = "The name of your VM" type = string } variable "url_ova" { - description = "the URL to .OVA file or cloude store" + description = "The URL to the .OVA file or cloud storage" type = string } @@ -315,7 +325,7 @@ var.tf type = string } -terraform.tfvars +``terraform.tfvars`` .. code-block:: none @@ -333,8 +343,8 @@ terraform.tfvars remotename = "" -Structure of files Ansible for vSphere --------------------------------------- +Structure of files in Ansible for vSphere +----------------------------------------- .. code-block:: none @@ -348,7 +358,7 @@ Structure of files Ansible for vSphere File contents of Ansible for vSphere ------------------------------------ -ansible.cfg +``ansible.cfg`` .. code-block:: none @@ -358,7 +368,7 @@ ansible.cfg remote_user=vyos -instance.yml +``instance.yml`` .. code-block:: none @@ -385,11 +395,12 @@ instance.yml vyos_config: lines: - set system name-server 192.0.2.1 + - set system name-server 192.0.2.1 save: true -group_vars/all +``group_vars/all`` .. code-block:: none @@ -402,14 +413,14 @@ group_vars/all ansible_ssh_pass: 12345678 -Sourse files for vSphere from GIT ---------------------------------- +Source files on GitHub +---------------------- -All files about the article can be found here_ +All files related to deploying VyOS on vSpherewith Terraform and Ansible +can be found in the vyos-automation_ repository. -.. stop_vyoslinter -.. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main +.. stop_vyoslinter +.. _vyos-automation: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main .. start_vyoslinter - diff --git a/docs/automation/terraform/terraformvyos.rst b/docs/automation/terraform/terraformvyos.rst deleted file mode 100644 index 42dc7492..00000000 --- a/docs/automation/terraform/terraformvyos.rst +++ /dev/null @@ -1,39 +0,0 @@ -:lastproofread: 2024-03-03 - -.. _terraformvyos: - -Terraform for VyOS -================== - -VyOS supports development infrastructure via Terraform and provisioning via Ansible. -Terraform allows you to automate the process of deploying instances on many cloud and virtual platforms. -In this article, we will look at using terraforms to deploy VyOS on platforms - AWS, Azure, and vSphere. -For more details about Terraform please have a look here link_. - -Need to install_ Terraform - -Structure of files in the standard Terraform project: - -.. code-block:: none - - . - ├── main.tf # The main script - ├── version.tf # File for the changing version of Terraform. - ├── variables.tf # The file of all variables in "main.tf" - └── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) - - -General commands that we will use for running Terraform scripts - - -.. code-block:: none - - cd /<your folder> # go to the Terrafom project - terraform init # install all addons and provider (aws az and so on) - terraform plan # show what is changing - terraform apply # run script - yes # apply running - - -.. _link: https://developer.hashicorp.com/terraform/intro -.. _install: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli
\ No newline at end of file |