From b8b3044d3c3515d91de0f44785bfd965174867df Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 21:50:08 +0300 Subject: feat: flip swap mechanism on sagitta — MD as primary, RST as override MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror of #1899 (current) and #1900 (circinus) for sagitta. Same logic, same scripts, per-branch file set. Changes: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 210 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 210 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty - conf.py exclude_patterns flipped: rst-*.rst excluded by default - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt - scripts/swap_sources.py imported from current (post-#1899 rewrite, with inverted rename direction) - scripts/import_myst.py and tests/test_import_myst.py deleted (obsolete) - tests/test_swap_sources.py imported from current (post-#1899 rewrite) Side-effect: fixes the same 404 on /en/1.4/ View page source links that #1899 fixed for /en/rolling/ and #1900 fixed for /en/1.5/. Per-branch differences vs #1899: - sagitta has 210 stems vs current's 254 (sagitta has no vpp pages and fewer current-only features; cli + installation/cloud/aws are still RST-only on sagitta pending the title-level fix follow-up) - otherwise the script/conf.py/test changes are byte-identical with current Generated by robots https://vyos.io --- docs/installation/cloud/aws-ha.md | 135 +++++++++ docs/installation/cloud/aws-ha.rst | 154 ---------- docs/installation/cloud/aws-to-azure.md | 175 +++++++++++ docs/installation/cloud/aws-to-azure.rst | 189 ------------ docs/installation/cloud/azure-ha.md | 128 ++++++++ docs/installation/cloud/azure-ha.rst | 152 ---------- docs/installation/cloud/azure.md | 378 +++++++++++++++++++++++ docs/installation/cloud/azure.rst | 433 --------------------------- docs/installation/cloud/gcp.md | 260 ++++++++++++++++ docs/installation/cloud/gcp.rst | 277 ----------------- docs/installation/cloud/index.md | 14 + docs/installation/cloud/index.rst | 16 - docs/installation/cloud/md-aws-ha.md | 135 --------- docs/installation/cloud/md-aws-to-azure.md | 175 ----------- docs/installation/cloud/md-azure-ha.md | 128 -------- docs/installation/cloud/md-azure.md | 378 ----------------------- docs/installation/cloud/md-gcp.md | 260 ---------------- docs/installation/cloud/md-index.md | 14 - docs/installation/cloud/md-oracel.md | 5 - docs/installation/cloud/oracel.md | 5 + docs/installation/cloud/oracel.rst | 8 - docs/installation/cloud/rst-aws-ha.rst | 154 ++++++++++ docs/installation/cloud/rst-aws-to-azure.rst | 189 ++++++++++++ docs/installation/cloud/rst-azure-ha.rst | 152 ++++++++++ docs/installation/cloud/rst-azure.rst | 433 +++++++++++++++++++++++++++ docs/installation/cloud/rst-gcp.rst | 277 +++++++++++++++++ docs/installation/cloud/rst-index.rst | 16 + docs/installation/cloud/rst-oracel.rst | 8 + 28 files changed, 2324 insertions(+), 2324 deletions(-) create mode 100644 docs/installation/cloud/aws-ha.md delete mode 100755 docs/installation/cloud/aws-ha.rst create mode 100644 docs/installation/cloud/aws-to-azure.md delete mode 100755 docs/installation/cloud/aws-to-azure.rst create mode 100644 docs/installation/cloud/azure-ha.md delete mode 100755 docs/installation/cloud/azure-ha.rst create mode 100644 docs/installation/cloud/azure.md delete mode 100644 docs/installation/cloud/azure.rst create mode 100644 docs/installation/cloud/gcp.md delete mode 100644 docs/installation/cloud/gcp.rst create mode 100644 docs/installation/cloud/index.md delete mode 100644 docs/installation/cloud/index.rst delete mode 100644 docs/installation/cloud/md-aws-ha.md delete mode 100644 docs/installation/cloud/md-aws-to-azure.md delete mode 100644 docs/installation/cloud/md-azure-ha.md delete mode 100644 docs/installation/cloud/md-azure.md delete mode 100644 docs/installation/cloud/md-gcp.md delete mode 100644 docs/installation/cloud/md-index.md delete mode 100644 docs/installation/cloud/md-oracel.md create mode 100644 docs/installation/cloud/oracel.md delete mode 100644 docs/installation/cloud/oracel.rst create mode 100755 docs/installation/cloud/rst-aws-ha.rst create mode 100755 docs/installation/cloud/rst-aws-to-azure.rst create mode 100755 docs/installation/cloud/rst-azure-ha.rst create mode 100644 docs/installation/cloud/rst-azure.rst create mode 100644 docs/installation/cloud/rst-gcp.rst create mode 100644 docs/installation/cloud/rst-index.rst create mode 100644 docs/installation/cloud/rst-oracel.rst (limited to 'docs/installation/cloud') diff --git a/docs/installation/cloud/aws-ha.md b/docs/installation/cloud/aws-ha.md new file mode 100644 index 00000000..f32e2ab5 --- /dev/null +++ b/docs/installation/cloud/aws-ha.md @@ -0,0 +1,135 @@ +# VyOS High Availability (HA) Deployment on AWS + +This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. + +## Why Use HA on AWS? + +This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. + +Key Advantages: + +- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. + +- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. + +- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. + +- On failure: + + - Withdraws the failed peer’s routes from the RIB. + - Recomputes the optimal path in the FIB. + - Updates VPC route tables to point to the active instance. + +- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. + +This architecture supports: + +- Cloud edge routing with failover. +- Hybrid cloud resiliency. +- Rapid recovery during instance crashes, upgrades, or network disruptions. +- Continuity for mission-critical operations. + +## HA Architecture Diagram + +:::{figure} /_static/images/cloud-aws-ha-architecture.png +:alt: VyOS HA topology diagram +::: + +## Terraform Automation + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. +- VPC Route Server. +- Transit Gateway. +- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. + +To integrate with existing AWS infrastructure: + +- Remove the Data VPC, its subnets, and EC2 test instance. +- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. + +## Prerequisites + +AWS Environment: + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: +- Terraform installed: + +Set AWS credentials in your shell: + +```none +export AWS_ACCESS_KEY_ID="" +export AWS_SECRET_ACCESS_KEY="" +export AWS_SESSION_TOKEN="" +export AWS_DEFAULT_REGION="" # e.g., us-east-1 +``` + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +```none +aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table +``` + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +```none +ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +## Usage + +Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. + +Terraform Workflow: + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the management IP and connectivity test results. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh vyos@ -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform project and use them in your environment: + + diff --git a/docs/installation/cloud/aws-ha.rst b/docs/installation/cloud/aws-ha.rst deleted file mode 100755 index af125969..00000000 --- a/docs/installation/cloud/aws-ha.rst +++ /dev/null @@ -1,154 +0,0 @@ -########## -VyOS High Availability (HA) Deployment on AWS -########## - -This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. - -Why Use HA on AWS? ------------------- - -This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. - -Key Advantages: - -- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. - -- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. - -- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. - -- On failure: - - - Withdraws the failed peer’s routes from the RIB. - - - Recomputes the optimal path in the FIB. - - - Updates VPC route tables to point to the active instance. - -- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. - -This architecture supports: - -- Cloud edge routing with failover. - -- Hybrid cloud resiliency. - -- Rapid recovery during instance crashes, upgrades, or network disruptions. - -- Continuity for mission-critical operations. - -HA Architecture Diagram ------------------------- - -.. figure:: /_static/images/cloud-aws-ha-architecture.png - :alt: VyOS HA topology diagram - -Terraform Automation --------------------- - -To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. - -This Terraform project automates the deployment of: - -- Two VyOS instances in HA mode. - -- VPC Route Server. - -- Transit Gateway. - -- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. - -To integrate with existing AWS infrastructure: - -- Remove the Data VPC, its subnets, and EC2 test instance. - -- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. - -Prerequisites -------------- - -AWS Environment: - -- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). - -Local Environment: - -- AWS CLI installed: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html - -- Terraform installed: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli - -Set AWS credentials in your shell: - -.. code-block:: none - - export AWS_ACCESS_KEY_ID="" - export AWS_SECRET_ACCESS_KEY="" - export AWS_SESSION_TOKEN="" - export AWS_DEFAULT_REGION="" # e.g., us-east-1 - -Obtain VyOS AMI ID and Owner ID: - -Subscribe to VyOS via AWS Marketplace. Then run: - -.. code-block:: none - - aws ec2 describe-images \ - --owners aws-marketplace \ - --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ - --query 'Images[*].[ImageId,OwnerId,Name]' \ - --output table - -Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. - -Generate an SSH keypair (or use the included demo key): - -.. code-block:: none - - ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem - chmod 400 keys/vyos_custom_key.pem - -Usage ------ - -Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. - -Terraform Workflow: - -.. code-block:: none - - terraform init - terraform fmt - terraform validate - terraform plan - terraform apply - -On completion, run: - -.. code-block:: none - - terraform output - -This displays the management IP and connectivity test results. - -To clean up: - -.. code-block:: none - - terraform destroy - -Management ----------- - -SSH into VyOS: - -.. code-block:: none - - ssh vyos@ -i keys/vyos_custom_key.pem - - -GitHub Repository ------------------ - -You can clone or download the Terraform project and use them in your environment: - -https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/ha-instances-with-configs diff --git a/docs/installation/cloud/aws-to-azure.md b/docs/installation/cloud/aws-to-azure.md new file mode 100644 index 00000000..246df5f3 --- /dev/null +++ b/docs/installation/cloud/aws-to-azure.md @@ -0,0 +1,175 @@ +# VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity + +This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. +It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, +automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) +are also deployed for connectivity validation. + +## Why Cloud-to-Cloud Connectivity? + +Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: + +- **Inter-Cloud Connectivity** + + Enable secure and reliable communication between workloads in different clouds + (for example, AWS applications connecting to Azure-hosted identity services). + +- **Cloud-to-Cloud Migration** + + During migration projects, workloads may temporarily run in both clouds. + Direct tunnels ensure smooth transition and synchronization. + +- **Testing and Validation** + + Labs and proof-of-concepts often simulate multi-cloud architectures. + A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. + +## Architecture + +The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. +BGP is used for dynamic routing between the clouds, allowing for seamless communication. + +:::{figure} /_static/images/cloud-aws-to-azure.png +:alt: VyOS Cloud-to-Cloud topology diagram +::: + +## Terraform Automation + +To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. +These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. + +In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. +These serve as test endpoints to validate connectivity between the cloud environments. + +## Prerequisites + +### AWS Environment + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: +- Terraform installed: + +Set AWS credentials in your shell: + +```none +export AWS_ACCESS_KEY_ID="" +export AWS_SECRET_ACCESS_KEY="" +export AWS_SESSION_TOKEN="" +export AWS_DEFAULT_REGION="" # e.g., us-east-1 +``` + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +```none +aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table +``` + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +```none +ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +### Azure Environment + +- Active Azure subscription: + +```none +az account set --subscription "" +``` + +- Azure CLI installed: + + + +- Logged in with Azure credentials: + +```none +az version +az login +``` + +- Azure Resource Group (RG) created: + +```none +az group create --name demoResourceGroup --location westus +az group list +az group show --name demoResourceGroup +``` + +- Terraform installed: + + + +- SSH key generated: + +```none +ssh-keygen -t rsa -b 4096 -f keys/id_rsa +chmod 400 keys/id_rsa +``` + +## Usage + +### AWS + +All variables needed for customization are defined in `variables.tf`. +Adjust them according to your requirements, such as EC2 instance type and networking configurations. + +Before deployment, ensure you check `aws_region`, `availability_zone`, and update `vyos_ami_id` as necessary. + +### Azure + +All variables needed for customization are defined in `variables.tf`. +Adjust them according to your requirements, such as VM size and networking configurations. + +Before deployment, ensure you check `azure_region`, `availability_zone`, and update `subscription_id` and `resource_group_name` as necessary. + +### Terraform Workflow + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the public IP addresses of the VyOS instances. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh vyos@ -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform projects and use them in your environment: + + diff --git a/docs/installation/cloud/aws-to-azure.rst b/docs/installation/cloud/aws-to-azure.rst deleted file mode 100755 index 81651feb..00000000 --- a/docs/installation/cloud/aws-to-azure.rst +++ /dev/null @@ -1,189 +0,0 @@ -########## -VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity -########## - -This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. -It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, -automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) -are also deployed for connectivity validation. - -Why Cloud-to-Cloud Connectivity? --------------------------------- - -Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: - -- **Inter-Cloud Connectivity** - - Enable secure and reliable communication between workloads in different clouds - (for example, AWS applications connecting to Azure-hosted identity services). - -- **Cloud-to-Cloud Migration** - - During migration projects, workloads may temporarily run in both clouds. - Direct tunnels ensure smooth transition and synchronization. - -- **Testing and Validation** - - Labs and proof-of-concepts often simulate multi-cloud architectures. - A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. - -Architecture ------------- - -The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. -BGP is used for dynamic routing between the clouds, allowing for seamless communication. - -.. figure:: /_static/images/cloud-aws-to-azure.png - :alt: VyOS Cloud-to-Cloud topology diagram - -Terraform Automation --------------------- - -To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. -These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. - -In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. -These serve as test endpoints to validate connectivity between the cloud environments. - -Prerequisites -------------- - -AWS Environment -^^^^^^^^^^^^^^^ - -- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). - -Local Environment: - -- AWS CLI installed: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html - -- Terraform installed: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli - -Set AWS credentials in your shell: - -.. code-block:: none - - export AWS_ACCESS_KEY_ID="" - export AWS_SECRET_ACCESS_KEY="" - export AWS_SESSION_TOKEN="" - export AWS_DEFAULT_REGION="" # e.g., us-east-1 - -Obtain VyOS AMI ID and Owner ID: - -Subscribe to VyOS via AWS Marketplace. Then run: - -.. code-block:: none - - aws ec2 describe-images \ - --owners aws-marketplace \ - --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ - --query 'Images[*].[ImageId,OwnerId,Name]' \ - --output table - -Alternatively, set the ``vyos_ami_id`` variable directly in ``variables.tf``. - -Generate an SSH keypair (or use the included demo key): - -.. code-block:: none - - ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem - chmod 400 keys/vyos_custom_key.pem - -Azure Environment -^^^^^^^^^^^^^^^^^ - -- Active Azure subscription: - -.. code-block:: none - - az account set --subscription "" - -- Azure CLI installed: - - https://learn.microsoft.com/en-us/cli/azure/install-azure-cli - -- Logged in with Azure credentials: - -.. code-block:: none - - az version - az login - -- Azure Resource Group (RG) created: - -.. code-block:: none - - az group create --name demoResourceGroup --location westus - az group list - az group show --name demoResourceGroup - -- Terraform installed: - - https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli - -- SSH key generated: - -.. code-block:: none - - ssh-keygen -t rsa -b 4096 -f keys/id_rsa - chmod 400 keys/id_rsa - -Usage ------ - -AWS -^^^ - -All variables needed for customization are defined in ``variables.tf``. -Adjust them according to your requirements, such as EC2 instance type and networking configurations. - -Before deployment, ensure you check ``aws_region``, ``availability_zone``, and update ``vyos_ami_id`` as necessary. - -Azure -^^^^^ - -All variables needed for customization are defined in ``variables.tf``. -Adjust them according to your requirements, such as VM size and networking configurations. - -Before deployment, ensure you check ``azure_region``, ``availability_zone``, and update ``subscription_id`` and ``resource_group_name`` as necessary. - -Terraform Workflow -^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - terraform init - terraform fmt - terraform validate - terraform plan - terraform apply - -On completion, run: - -.. code-block:: none - - terraform output - -This displays the public IP addresses of the VyOS instances. - -To clean up: - -.. code-block:: none - - terraform destroy - -Management ----------- - -SSH into VyOS: - -.. code-block:: none - - ssh vyos@ -i keys/vyos_custom_key.pem - -GitHub Repository ------------------ - -You can clone or download the Terraform projects and use them in your environment: - -https://github.com/vyos/vyos-automation/tree/main/Terraform/Cloud-to-Cloud diff --git a/docs/installation/cloud/azure-ha.md b/docs/installation/cloud/azure-ha.md new file mode 100644 index 00000000..fa94c222 --- /dev/null +++ b/docs/installation/cloud/azure-ha.md @@ -0,0 +1,128 @@ +# VyOS High Availability (HA) Deployment on Azure + +This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. + +## Why Use HA on Azure? + +This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: + +- Rapid deployment of cloud edge routers. +- Full control over BGP route advertisement and filtering. +- Realistic HA and disaster recovery simulations. +- Seamless integration with hybrid or multi-cloud infrastructure. + +The architecture includes: + +- Two VyOS routers in a Transit VNet, configured with BGP. +- Azure Route Server for dynamic route distribution. +- Site-to-Site VPN connections to a simulated on-premises VyOS router. +- An Ubuntu VM for connectivity and routing validation. +- A Data VNet for testing and diagnostics. + +## Key Features + +- **High Availability**: Dual VyOS routers for redundancy and failover. +- **Dynamic Routing**: BGP-based routing via Azure Route Server. +- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. +- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. +- **Modular & Flexible**: Easily configurable via variables. + +## HA Architecture Diagram + +:::{figure} /_static/images/cloud-azure-ha-architecture.png +:alt: VyOS HA topology diagram +::: + +This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. + +## Terraform Automation + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. +- Azure Route Server. +- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. + +## Prerequisites + +Ensure you have: + +- Active Azure subscription: + +```none +az account set --subscription "" +``` + +- Azure CLI installed: + + + +- Logged in with Azure credentials: + +```none +az version +az login +``` + +- Azure Resource Group (RG) created: + +```none +az group create --name demoResourceGroup --location westus +az group list +az group show --name demoResourceGroup +``` + +- Terraform installed: + + + +- SSH key generated: + +```none +ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem +chmod 400 keys/vyos_custom_key.pem +``` + +## Usage + +All variables are defined in `variables.tf`. Adjust them to match your environment. + +Terraform Workflow: + +```none +terraform init +terraform fmt +terraform validate +terraform plan +terraform apply +``` + +On completion, run: + +```none +terraform output +``` + +This displays the management IP and connectivity test results. + +To clean up: + +```none +terraform destroy +``` + +## Management + +SSH into VyOS: + +```none +ssh adminuser@ -i keys/vyos_custom_key.pem +``` + +## GitHub Repository + +You can clone or download the Terraform project and use them in your environment: + + diff --git a/docs/installation/cloud/azure-ha.rst b/docs/installation/cloud/azure-ha.rst deleted file mode 100755 index e943b550..00000000 --- a/docs/installation/cloud/azure-ha.rst +++ /dev/null @@ -1,152 +0,0 @@ -########## -VyOS High Availability (HA) Deployment on Azure -########## - - -This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. - -Why Use HA on Azure? --------------------- - -This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: - -- Rapid deployment of cloud edge routers. - -- Full control over BGP route advertisement and filtering. - -- Realistic HA and disaster recovery simulations. - -- Seamless integration with hybrid or multi-cloud infrastructure. - -The architecture includes: - -- Two VyOS routers in a Transit VNet, configured with BGP. - -- Azure Route Server for dynamic route distribution. - -- Site-to-Site VPN connections to a simulated on-premises VyOS router. - -- An Ubuntu VM for connectivity and routing validation. - -- A Data VNet for testing and diagnostics. - -Key Features ------------- - -- **High Availability**: Dual VyOS routers for redundancy and failover. - -- **Dynamic Routing**: BGP-based routing via Azure Route Server. - -- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. - -- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. - -- **Modular & Flexible**: Easily configurable via variables. - -HA Architecture Diagram ------------------------ - -.. figure:: /_static/images/cloud-azure-ha-architecture.png - :alt: VyOS HA topology diagram - -This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. - -Terraform Automation --------------------- - -To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. - -This Terraform project automates the deployment of: - -- Two VyOS instances in HA mode. - -- Azure Route Server. - -- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. - -Prerequisites -------------- - -Ensure you have: - -- Active Azure subscription: - -.. code-block:: none - - az account set --subscription "" - -- Azure CLI installed: - - https://learn.microsoft.com/en-us/cli/azure/install-azure-cli - -- Logged in with Azure credentials: - -.. code-block:: none - - az version - az login - -- Azure Resource Group (RG) created: - -.. code-block:: none - - az group create --name demoResourceGroup --location westus - az group list - az group show --name demoResourceGroup - -- Terraform installed: - - https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli - -- SSH key generated: - -.. code-block:: none - - ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem - chmod 400 keys/vyos_custom_key.pem - -Usage ------ - -All variables are defined in ``variables.tf``. Adjust them to match your environment. - -Terraform Workflow: - -.. code-block:: none - - terraform init - terraform fmt - terraform validate - terraform plan - terraform apply - -On completion, run: - -.. code-block:: none - - terraform output - -This displays the management IP and connectivity test results. - -To clean up: - -.. code-block:: none - - terraform destroy - -Management ----------- - -SSH into VyOS: - -.. code-block:: none - - ssh adminuser@ -i keys/vyos_custom_key.pem - - -GitHub Repository ------------------ - -You can clone or download the Terraform project and use them in your environment: - -https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure/azure-ha-deployment-with-configs diff --git a/docs/installation/cloud/azure.md b/docs/installation/cloud/azure.md new file mode 100644 index 00000000..aa577aa1 --- /dev/null +++ b/docs/installation/cloud/azure.md @@ -0,0 +1,378 @@ +# VyOS Deployment on Azure + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. + +## Prerequisites for Deploying VyOS on Azure + +### Azure Account + +Ensure you have an active Azure subscription. + +### Microsoft Entra ID Permissions + +To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. + +**Reference Documentation:** + + + + + + + +## Deployment Steps + +### Step 1: Create a Resource Group + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. + +#### Create resource groups + +- Go to the Azure Portal . +- Sign in with your Azure account credentials. +- In the portal, search for and select **Resource groups**. +- Select **Create**. + +:::{figure} /_static/images/cloud-azure-rg-01.png +::: + +- Enter the following values: +- **Subscription**: Select your Azure subscription. +- **Resource group**: Enter a new resource group name, e.g., `VyOSResourceGroup`. +- **Region**: Select an Azure location, such as Central US. +- Select **Review + Create** +- Select **Create**. It takes a few seconds to create a resource group. + +:::{figure} /_static/images/cloud-azure-rg-02.png +::: + +### Step 2: Create a Virtual Network (VNet) and Subnets + +Sign in to the Azure portal with your Azure account + +- In the portal, search for and select **Virtual networks**. +- On the **Virtual networks** page, select **+ Create**. +- On the **Basics** tab of **Create virtual network**, enter, or select the following information: +- **Subscription**: Select your Subscription +- **Resource Group**: Select e.g., `VyOSResourceGroup` +- **Name**: e.g., `VyOS-VirtualNetwork` +- **Region**: e.g., `West Europe`. + +:::{figure} /_static/images/cloud-azure-vnet-01.png +::: + +**IP addresses**: + +- Address Space: `10.1.0.0/16` + +:::{figure} /_static/images/cloud-azure-vnet-02.png +::: + +**Add two subnets**: + +- Name: e.g., `VyOS-Private-Subnet` + + Starting address: e.g., `10.1.1.0` + + Size: `/24` + +- Name: e.g., `VyOS-Public-Subnet` + + Starting address: e.g., `10.1.11.0` + + Size: `/24` + +:::{figure} /_static/images/cloud-azure-vnet-03.png +::: + +:::{figure} /_static/images/cloud-azure-vnet-04.png +::: + +:::{figure} /_static/images/cloud-azure-vnet-05.png +::: + +- Click **Review + Create** and then **Create**. + +### Step 3: Create and configure Network Security Group (NSG) + +- In the Azure Portal, search for and select **Network Security Groups**. +- On the **Network Security Groups** page, select **+ Create**. + +Enter the details: + +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Name**: e.g., `VyOS-SecurityGroup` +- **Region**: e.g., `West Europe`. + +:::{figure} /_static/images/cloud-azure-sg-01.png +::: + +- Click **Review + Create** and then **Create**. + +**Add inbound rules**: + +- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** + +:::{figure} /_static/images/cloud-azure-sg-02.png +::: + +**Add Rule Example:** + +- **Rule 1**: AllowSSH + + > - **Port**: 22 + > - **Protocol**: TCP + > - **Source**: Any + > - **Priority**: 1001 + +**Add Additional Rules**: + +You can add inbound rules based on your specific services, such as: + +> - ESP +> - OpenVPN +> - WireGuard, etc. + +:::{figure} /_static/images/cloud-azure-sg-03.png +::: + +**Associate subnets**: + +- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: + +:::{figure} /_static/images/cloud-azure-sg-04.png +::: + +### Step 4: Create Public IP Address + +- In the Azure Portal, search for and select **Public IP Addresses**. +- On the **Public IP Addresses** page, select **+ Create**. +- Provide the following details: +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Region**: `West Europe` + +:::{figure} /_static/images/cloud-azure-pub-ip-01.png +::: + +- **Name**: `VyOS-Pub-IP` +- **IP Version**: `IPv4` +- **SKU**: `Standard` +- **Availability zone**: Select Availability Zone + +:::{figure} /_static/images/cloud-azure-pub-ip-02.png +::: + +- **IP address assignment**: `Static` +- **Idle timeout (minutes)** `30` (max) + +:::{figure} /_static/images/cloud-azure-pub-ip-03.png +::: + +- Click **Review + Create**, then **Create**. + +### Step 5: Deploy the VyOS Network Virtual Machine (NVA) + +- In the Azure Portal, search for and select **Virtual Machines**. +- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. +- Provide the following details: +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Virtual machine name**: e.g., `VyOS` +- **Region**: e.g., `West Europe` +- **Security type**: `Standard` +- **Image**: `VyOS` (On the marketplace search `VyOS` and choose the appropriate subscription). + +:::{figure} /_static/images/cloud-azure-vm-01.png +::: + +- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. + +:::{figure} /_static/images/cloud-azure-vm-02.png +::: + +- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. +- **Username**: The administrator username for the VM, e.g., `vyos`. +- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. + +:::{figure} /_static/images/cloud-azure-vm-03.png +::: + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. +- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`. + +:::{figure} /_static/images/cloud-azure-vm-04.png +::: + +- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`. + +:::{figure} /_static/images/cloud-azure-vm-05.png +::: + +- Click **Review + Create**, then **Create**. +- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. + +:::{figure} /_static/images/cloud-azure-vm-06.png +::: + +- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. + +:::{figure} /_static/images/cloud-azure-vm-07.png +::: + +### Step 6: Access the VyOS instance + +- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: + + ```none + $ ssh vyos@51.124.120.235 -i vyos_key.pem + vyos@VyOS:~$ + ``` + +### Step 7: Enable IP Forwarding in Network Interface + +This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. + +- On the **Virtual Machines** page, select `VyOS` VM, under **Networking** tab select **Network settings**, click network interface. + +:::{figure} /_static/images/cloud-azure-vm-12.png +::: + +- Enable IP forwarding and click the **Apply** button. + +:::{figure} /_static/images/cloud-azure-vm-13.png +::: + +### Step 8: Create and attach the second network interface (optional) + +Now instance has been deployed with one **eth0** `WAN` interface and want to add +new one. To add new interface an example **eth1** `LAN` you need shutdown the +instance. Attach the interface in the Azure portal and then start the instance. + +:::{note} +Azure does not allow you attach interface when the instance in the +**Running** state. +::: + +#### Create network interface: + +- In the Azure Portal, search for and select **Network Interfaces**. +- On the **Network Interfaces** page, select **+ Create**. + +:::{figure} /_static/images/cloud-azure-nic-01.png +::: + +- **Subscription**: Select your Subscription +- **Resource Group**: Select `VyOSResourceGroup` +- **Name**: `VyOS-PRIV-NIC` +- **Subnet**: `VyOS-Private-Subnet` +- **Private IP**: `Dynamic` +- Click **Review + Create**, then **Create** + +:::{figure} /_static/images/cloud-azure-nic-02.png +::: + +- Enable **IP Forwarding** +- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC` + +:::{figure} /_static/images/cloud-azure-nic-03.png +::: + +- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. + +:::{figure} /_static/images/cloud-azure-nic-04.png +::: + +#### Attach reate network interface: + +- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button + +:::{figure} /_static/images/cloud-azure-vm-08.png +::: + +- Go to **Networking** select **Network settings** and then select **Attach network interface** + +:::{figure} /_static/images/cloud-azure-vm-09.png +::: + +- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button. + +:::{figure} /_static/images/cloud-azure-vm-10.png +::: + +- Now you have attached second interface to your instance and you can start Virtual Machine. +- Go to **Overview** and click the **Start** button. + +:::{figure} /_static/images/cloud-azure-vm-11.png +::: + +### Setp 8: Absorbing Routes + +To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. + +- Step-by-Step Instructions: +- Navigate to **Route Tables** and click **+ Create**. + +Provide the following details: + +> - **Subscription**: Select your Subscription +> - **Resource Group**: Select `VyOSResourceGroup` +> - **Name**: `Route-VyOS` +> - **Region**: e.g., `West Europe` + +:::{figure} /_static/images/cloud-azure-route-01.png +::: + +- Click **Review + Create**, then **Create**. + +**Add a Route**: + +- Navigate to **Route Tables** and click the new created route (`Route-VyOS`). +- Go to **Routes** and click **+ Add** button. + +:::{figure} /_static/images/cloud-azure-route-02.png +::: + +Add following parameters: + +- **Name**: `Default-Route` +- **Destination type**: `IP Addresses` +- **Destination IP addresses/CIDR ranges**: `0.0.0.0/0` +- **Next Hop Type**: `Virtual Appliance` +- **Next Hop IP Address**: `10.1.11.4` (The private Network Interface Card IP Address) + +:::{figure} /_static/images/cloud-azure-route-03.png +::: + +- Click the **Add** button. + +**Associate the Route Table with subnet**: + +- Navigate to **Route Tables** and click the new created route (`VyOSResourceGroup`). +- Go to **Subnets** and click **+ Associate** button. + +:::{figure} /_static/images/cloud-azure-route-04.png +::: + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. + +:::{figure} /_static/images/cloud-azure-route-05.png +::: + +:::{note} +If you want to create a new default route for VMs on the subnet, use **Address Prefix** `0.0.0.0/0` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the `WAN` interface. +::: + +### Deploy VyOS Instance and Required Resources Automatically (via Terraform) + +You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. +All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. + +You can also edit/change these parameters based on your requirements. + +- Download/Clone the Repository following GitHub repository: + + diff --git a/docs/installation/cloud/azure.rst b/docs/installation/cloud/azure.rst deleted file mode 100644 index 563fcb19..00000000 --- a/docs/installation/cloud/azure.rst +++ /dev/null @@ -1,433 +0,0 @@ -########## -VyOS Deployment on Azure -########## - - -This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. - -Prerequisites for Deploying VyOS on Azure -======== - -Azure Account ------------ - -Ensure you have an active Azure subscription. - -Microsoft Entra ID Permissions ------------ - -To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. - -**Reference Documentation:** - -https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal - -https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal - -https://learn.microsoft.com/en-us/azure/role-based-access-control/overview - -Deployment Steps -======== - -Step 1: Create a Resource Group ------------ - -A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. - -Create resource groups -^^^^^^^^^^^^^^ - -- Go to the Azure Portal https://portal.azure.com/. - -- Sign in with your Azure account credentials. - -- In the portal, search for and select **Resource groups**. - -- Select **Create**. - -.. figure:: /_static/images/cloud-azure-rg-01.png - -- Enter the following values: - -- **Subscription**: Select your Azure subscription. - -- **Resource group**: Enter a new resource group name, e.g., ``VyOSResourceGroup``. - -- **Region**: Select an Azure location, such as Central US. - -- Select **Review + Create** - -- Select **Create**. It takes a few seconds to create a resource group. - -.. figure:: /_static/images/cloud-azure-rg-02.png - - -Step 2: Create a Virtual Network (VNet) and Subnets ------------ - -Sign in to the Azure portal with your Azure account https://portal.azure.com/ - -- In the portal, search for and select **Virtual networks**. - -- On the **Virtual networks** page, select **+ Create**. - -- On the **Basics** tab of **Create virtual network**, enter, or select the following information: - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select e.g., ``VyOSResourceGroup`` - -- **Name**: e.g., ``VyOS-VirtualNetwork`` - -- **Region**: e.g., ``West Europe``. - -.. figure:: /_static/images/cloud-azure-vnet-01.png - -**IP addresses**: - -- Address Space: ``10.1.0.0/16`` - -.. figure:: /_static/images/cloud-azure-vnet-02.png - -**Add two subnets**: - -- Name: e.g., ``VyOS-Private-Subnet`` - - Starting address: e.g., ``10.1.1.0`` - - Size: ``/24`` - -- Name: e.g., ``VyOS-Public-Subnet`` - - Starting address: e.g., ``10.1.11.0`` - - Size: ``/24`` - -.. figure:: /_static/images/cloud-azure-vnet-03.png - -.. figure:: /_static/images/cloud-azure-vnet-04.png - -.. figure:: /_static/images/cloud-azure-vnet-05.png - -- Click **Review + Create** and then **Create**. - - -Step 3: Create and configure Network Security Group (NSG) ------------ - -- In the Azure Portal, search for and select **Network Security Groups**. - -- On the **Network Security Groups** page, select **+ Create**. - -Enter the details: - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select ``VyOSResourceGroup`` - -- **Name**: e.g., ``VyOS-SecurityGroup`` - -- **Region**: e.g., ``West Europe``. - -.. figure:: /_static/images/cloud-azure-sg-01.png - -- Click **Review + Create** and then **Create**. - -**Add inbound rules**: - -- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** - -.. figure:: /_static/images/cloud-azure-sg-02.png - -**Add Rule Example:** - -- **Rule 1**: AllowSSH - - - **Port**: 22 - - - **Protocol**: TCP - - - **Source**: Any - - - **Priority**: 1001 - -**Add Additional Rules**: - -You can add inbound rules based on your specific services, such as: - - - ESP - - - OpenVPN - - - WireGuard, etc. - -.. figure:: /_static/images/cloud-azure-sg-03.png - -**Associate subnets**: - -- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: - -.. figure:: /_static/images/cloud-azure-sg-04.png - - -Step 4: Create Public IP Address ------------ - -- In the Azure Portal, search for and select **Public IP Addresses**. - -- On the **Public IP Addresses** page, select **+ Create**. - -- Provide the following details: - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select ``VyOSResourceGroup`` - -- **Region**: ``West Europe`` - -.. figure:: /_static/images/cloud-azure-pub-ip-01.png - -- **Name**: ``VyOS-Pub-IP`` - -- **IP Version**: ``IPv4`` - -- **SKU**: ``Standard`` - -- **Availability zone**: Select Availability Zone - -.. figure:: /_static/images/cloud-azure-pub-ip-02.png - -- **IP address assignment**: ``Static`` - -- **Idle timeout (minutes)** ``30`` (max) - -.. figure:: /_static/images/cloud-azure-pub-ip-03.png - -- Click **Review + Create**, then **Create**. - - -Step 5: Deploy the VyOS Network Virtual Machine (NVA) ------------ - -- In the Azure Portal, search for and select **Virtual Machines**. - -- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. - -- Provide the following details: - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select ``VyOSResourceGroup`` - -- **Virtual machine name**: e.g., ``VyOS`` - -- **Region**: e.g., ``West Europe`` - -- **Security type**: ``Standard`` - -- **Image**: ``VyOS`` (On the marketplace search ``VyOS`` and choose the appropriate subscription). - -.. figure:: /_static/images/cloud-azure-vm-01.png - -- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. - -.. figure:: /_static/images/cloud-azure-vm-02.png - -- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. - -- **Username**: The administrator username for the VM, e.g., ``vyos``. - -- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. - -.. figure:: /_static/images/cloud-azure-vm-03.png - -- **Virtual network**: Select ``VyOS-VirtualNetwork``. - -- **Subnet**: Select ``VyOS-Public-Subnet``. - -- **Public IP**: Select public IP address which created before ``VyOS-Pub-IP``. - -.. figure:: /_static/images/cloud-azure-vm-04.png - -- **Configure network security group**: Select existing Security Group ``VyOS-SecurityGroup``. - -.. figure:: /_static/images/cloud-azure-vm-05.png - -- Click **Review + Create**, then **Create**. - -- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. - -.. figure:: /_static/images/cloud-azure-vm-06.png - -- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. - -.. figure:: /_static/images/cloud-azure-vm-07.png - - -Step 6: Access the VyOS instance ------------ - -- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: - - .. code-block:: none - - $ ssh vyos@51.124.120.235 -i vyos_key.pem - vyos@VyOS:~$ - -Step 7: Enable IP Forwarding in Network Interface ------------ - -This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. - -- On the **Virtual Machines** page, select ``VyOS`` VM, under **Networking** tab select **Network settings**, click network interface. - -.. figure:: /_static/images/cloud-azure-vm-12.png - -- Enable IP forwarding and click the **Apply** button. - -.. figure:: /_static/images/cloud-azure-vm-13.png - -Step 8: Create and attach the second network interface (optional) -------------- - -Now instance has been deployed with one **eth0** ``WAN`` interface and want to add -new one. To add new interface an example **eth1** ``LAN`` you need shutdown the -instance. Attach the interface in the Azure portal and then start the instance. - -.. note:: Azure does not allow you attach interface when the instance in the - **Running** state. - - -Create network interface: -^^^^^^^^^^^^^^ - -- In the Azure Portal, search for and select **Network Interfaces**. - -- On the **Network Interfaces** page, select **+ Create**. - -.. figure:: /_static/images/cloud-azure-nic-01.png - -- **Subscription**: Select your Subscription - -- **Resource Group**: Select ``VyOSResourceGroup`` - -- **Name**: ``VyOS-PRIV-NIC`` - -- **Subnet**: ``VyOS-Private-Subnet`` - -- **Private IP**: ``Dynamic`` - -- Click **Review + Create**, then **Create** - -.. figure:: /_static/images/cloud-azure-nic-02.png - -- Enable **IP Forwarding** - -- Navigate to **Network Interfaces** select ``VyOS-PRIV-NIC`` - -.. figure:: /_static/images/cloud-azure-nic-03.png - -- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. - -.. figure:: /_static/images/cloud-azure-nic-04.png - - -Attach reate network interface: -^^^^^^^^^^^^^^ - -- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button - -.. figure:: /_static/images/cloud-azure-vm-08.png - -- Go to **Networking** select **Network settings** and then select **Attach network interface** - -.. figure:: /_static/images/cloud-azure-vm-09.png - -- Select existing (before created) network interface ``VyOS-PRIV-NIC`` and click the **OK** button. - -.. figure:: /_static/images/cloud-azure-vm-10.png - -- Now you have attached second interface to your instance and you can start Virtual Machine. - -- Go to **Overview** and click the **Start** button. - -.. figure:: /_static/images/cloud-azure-vm-11.png - - -Setp 8: Absorbing Routes ----------------- - -To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. - -- Step-by-Step Instructions: - -- Navigate to **Route Tables** and click **+ Create**. - -Provide the following details: - - - **Subscription**: Select your Subscription - - - **Resource Group**: Select ``VyOSResourceGroup`` - - - **Name**: ``Route-VyOS`` - - - **Region**: e.g., ``West Europe`` - -.. figure:: /_static/images/cloud-azure-route-01.png - -- Click **Review + Create**, then **Create**. - -**Add a Route**: - -- Navigate to **Route Tables** and click the new created route (``Route-VyOS``). - -- Go to **Routes** and click **+ Add** button. - -.. figure:: /_static/images/cloud-azure-route-02.png - -Add following parameters: - -- **Name**: ``Default-Route`` - -- **Destination type**: ``IP Addresses`` - -- **Destination IP addresses/CIDR ranges**: ``0.0.0.0/0`` - -- **Next Hop Type**: ``Virtual Appliance`` - -- **Next Hop IP Address**: ``10.1.11.4`` (The private Network Interface Card IP Address) - -.. figure:: /_static/images/cloud-azure-route-03.png - -- Click the **Add** button. - -**Associate the Route Table with subnet**: - -- Navigate to **Route Tables** and click the new created route (``VyOSResourceGroup``). - -- Go to **Subnets** and click **+ Associate** button. - -.. figure:: /_static/images/cloud-azure-route-04.png - -- **Virtual network**: Select ``VyOS-VirtualNetwork``. - -- **Subnet**: Select ``VyOS-Public-Subnet``. - -.. figure:: /_static/images/cloud-azure-route-05.png - -.. note:: If you want to create a new default route for VMs on the subnet, use **Address Prefix** ``0.0.0.0/0`` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the ``WAN`` interface. - - -Deploy VyOS Instance and Required Resources Automatically (via Terraform) --------------- - -You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. -All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. - -You can also edit/change these parameters based on your requirements. - -- Download/Clone the Repository following GitHub repository: - -https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure - - diff --git a/docs/installation/cloud/gcp.md b/docs/installation/cloud/gcp.md new file mode 100644 index 00000000..7144f083 --- /dev/null +++ b/docs/installation/cloud/gcp.md @@ -0,0 +1,260 @@ +# VyOS Deployment on Google Cloud Platform + +This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). + +## Prerequisites + +Before proceeding, ensure the following: + +- A GCP account with billing enabled. +- Permissions to deploy Marketplace images. +- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). +- An SSH key pair for VyOS instance access. +- GA Google Cloud Project. + +## Deployment Steps + +### Step 1: Add SSH Key + +1. If you don’t already have SSH keys, generate an SSH key pair of type `ssh-rsa` on your local machine: + +> Example: +> +> ```none +> ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" +> ``` + +:::{note} +In the comment `vyos@mypc`, the username must start with vyos. +This is because the default user in the VyOS image is `vyos`, and the Google Cloud API uses this value for SSH access. +::: + +2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose + **SSH Keys**. + +:::{figure} /_static/images/cloud-gcp-01.png +::: + +3. Click **edit** and **Add item**. +4. Paste your public ssh key and **Save**. + +:::{figure} /_static/images/cloud-gcp-02.png +::: + +For more information, please visit the official Google Cloud documentation: + + + + + +### Step 2: Create a Service Account (If You Don't Have One) + +1. In the Google Cloud console **IAM & Admin > Service Accounts**. +2. Select select a project. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. Click **Create Service Account**: + + - Name: e.g., `vyos-test` + - Service account ID: e.g., `vyos-test` + - Description: e.g., `VyOS Test Service Account` + +4. Click **Done**. + +:::{figure} /_static/images/cloud-gcp-svc.png +::: + +For more information, please visit the official Google Cloud documentation: + + + + + +### Step 3: Create VPC Networks and Subnets + +1. In the Google Cloud console **VPC Network > VPC Networks** +2. Select select a project. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. Click **Create VPC Network**. + + **Public VPC**: + + - Name: e.g., `vyos-public-vpc` + - Subnet creation mode: `Custom` + - Subnet name: e.g., `vyos-public-subnet` + - Region: e.g., `europe-west1` + - IP range: e.g., `10.0.1.0/24` + - Leave all other settings at default, then click **Create**. + +:::{figure} /_static/images/cloud-gcp-vpc-01.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-02.png +**Private VPC**: + +- Name: `vyos-private-vpc` +- Subnet creation mode: `Custom` +- Subnet name: `vyos-private-subnet` +- Region: e.g., `europe-west1` +- IP range: `10.0.11.0/24` +- Leave all other settings at default, then click **Create**. +::: + +:::{figure} /_static/images/cloud-gcp-vpc-03.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-04.png +::: + +4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. + +:::{figure} /_static/images/cloud-gcp-vpc-05.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-06.png +::: + +:::{figure} /_static/images/cloud-gcp-vpc-07.png +::: + +For more information, please visit the official Google Cloud documentation: + + + +### Step 4: Deploy VyOS instance from Marketplace + +1. Go to the Google Cloud Marketplace page in the Google Cloud console +2. Choose the project where you want to deploy the VyOS instance. + +:::{figure} /_static/images/cloud-gcp-proj.png +::: + +3. In the search bar, type `vyos` to find the VyOS image in the Marketplace. + +:::{figure} /_static/images/cloud-gcp-market-01.png +::: + +:::{figure} /_static/images/cloud-gcp-market-02.png +::: + +4. On the next page, review details such as support, pricing, and other details. + +:::{figure} /_static/images/cloud-gcp-market-03.png +::: + +5. Click the `GET STARTED` button to start deployment process. + +:::{figure} /_static/images/cloud-gcp-market-04.png +::: + +:::{figure} /_static/images/cloud-gcp-market-05.png +::: + +6. General settings. + + - Deployment name: e.g., `vyos-test-vm` + - Select a Service Account: Select the service account created earlier. + - Image: Select VyOS image for deployment. + - Zone: e.g., `europe-west1-b` + - Machine type: Choose based on performance and resource needs. + +:::{figure} /_static/images/cloud-gcp-vm-01.png +::: + +:::{figure} /_static/images/cloud-gcp-vm-02.png +::: + +7. Configure the network interfaces. + + **Public Network interface:** + + Edit the first (default) network interface and select following settings: + + > - Network: `vyos-public-vpc` + > - Subnetwork: `vyos-public-subnet` + > - External IP: `Ephemeral` + > - Private Network interface: + + **Private Network Interface:** + + Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: + + > - Network: `vyos-private-vpc` + > - Subnetwork: `vyos-private-subnet` + > - External IP: `None` + +:::{figure} /_static/images/cloud-gcp-vm-03.png +::: + +8. Deployment automation. + + - You can use `cloud-init` `User Data` to automatically inject specific configuration commands into the VyOS instance during deployment. + - Example: + +> ```none +> #cloud-config +> vyos_config_commands: +> - set system host-name 'VyOS-for-GCP' +> - set system login banner pre-login 'Welcome to the VyOS for on GCP' +> - set interfaces ethernet eth0 description 'WAN' +> - set interfaces ethernet eth1 description 'LAN' +> - set interfaces ethernet eth1 address 'dhcp' +> - set interfaces ethernet eth1 dhcp-options no-default-route +> ``` + +For more information, please visit the documentation: + + + +:::{figure} /_static/images/cloud-gcp-vm-09.png +::: + +9. Click `Deploy` button. + +:::{figure} /_static/images/cloud-gcp-vm-06.png +::: + +:::{figure} /_static/images/cloud-gcp-vm-07.png +::: + +### Connect to the VyOS instance + +To connect to the VyOS instance, use the SSH key that was generated in the first step. + +To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** + +:::{figure} /_static/images/cloud-gcp-vm-08.png +::: + +Example: + +> ```none +> ssh vyos@35.233.97.132 -i .ssh/vyos_gcp +> +> The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. +> ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. +> This key is not known by any other names +> Are you sure you want to continue connecting (yes/no/[fingerprint])? yes +> Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. +> Welcome to the VyOS for on GCP +> Welcome to VyOS! +> +> ┌── ┐ +> . VyOS 1.4.2 +> └ ──┘ sagitta +> +> * Documentation: https://docs.vyos.io/en/sagitta +> * Project news: https://blog.vyos.io +> * Bug reports: https://vyos.dev +> +> You can change this banner using "set system login banner post-login" command. +> +> VyOS is a free software distribution that includes multiple components, +> you can check individual component licenses under /usr/share/doc/*/copyright +> vyos@VyOS-for-GCP:~$ +> ``` diff --git a/docs/installation/cloud/gcp.rst b/docs/installation/cloud/gcp.rst deleted file mode 100644 index 0c23353e..00000000 --- a/docs/installation/cloud/gcp.rst +++ /dev/null @@ -1,277 +0,0 @@ -##################### -VyOS Deployment on Google Cloud Platform -##################### - -This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). - -Prerequisites -======== - -Before proceeding, ensure the following: - -- A GCP account with billing enabled. -- Permissions to deploy Marketplace images. -- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). -- An SSH key pair for VyOS instance access. -- GA Google Cloud Project. - -Deployment Steps -======== - -Step 1: Add SSH Key -------------------- - -1. If you don’t already have SSH keys, generate an SSH key pair of type ``ssh-rsa`` on your local machine: - - Example: - - .. code-block:: none - - ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" - - -.. note:: In the comment ``vyos@mypc``, the username must start with vyos. - This is because the default user in the VyOS image is ``vyos``, and the Google Cloud API uses this value for SSH access. - -2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose - **SSH Keys**. - -.. figure:: /_static/images/cloud-gcp-01.png - - -3. Click **edit** and **Add item**. - -4. Paste your public ssh key and **Save**. - -.. figure:: /_static/images/cloud-gcp-02.png - -For more information, please visit the official Google Cloud documentation: - -https://cloud.google.com/compute/docs/connect/add-ssh-keys - -https://cloud.google.com/compute/docs/connect/create-ssh-keys - - -Step 2: Create a Service Account (If You Don't Have One) -------------------------------- - -1. In the Google Cloud console **IAM & Admin > Service Accounts**. - -2. Select select a project. - -.. figure:: /_static/images/cloud-gcp-proj.png - -3. Click **Create Service Account**: - - - Name: e.g., ``vyos-test`` - - - Service account ID: e.g., ``vyos-test`` - - - Description: e.g., ``VyOS Test Service Account`` - -4. Click **Done**. - -.. figure:: /_static/images/cloud-gcp-svc.png - -For more information, please visit the official Google Cloud documentation: - -https://cloud.google.com/iam/docs/service-accounts-create - -https://cloud.google.com/iam/docs/service-account-overview - - -Step 3: Create VPC Networks and Subnets -------------------------------- - -1. In the Google Cloud console **VPC Network > VPC Networks** https://console.cloud.google.com/networking/networks/list - -2. Select select a project. - -.. figure:: /_static/images/cloud-gcp-proj.png - -3. Click **Create VPC Network**. - - **Public VPC**: - - - Name: e.g., ``vyos-public-vpc`` - - - Subnet creation mode: ``Custom`` - - - Subnet name: e.g., ``vyos-public-subnet`` - - - Region: e.g., ``europe-west1`` - - - IP range: e.g., ``10.0.1.0/24`` - - - Leave all other settings at default, then click **Create**. - -.. figure:: /_static/images/cloud-gcp-vpc-01.png - -.. figure:: /_static/images/cloud-gcp-vpc-02.png - - **Private VPC**: - - - Name: ``vyos-private-vpc`` - - - Subnet creation mode: ``Custom`` - - - Subnet name: ``vyos-private-subnet`` - - - Region: e.g., ``europe-west1`` - - - IP range: ``10.0.11.0/24`` - - - Leave all other settings at default, then click **Create**. - -.. figure:: /_static/images/cloud-gcp-vpc-03.png - -.. figure:: /_static/images/cloud-gcp-vpc-04.png - -4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. - -.. figure:: /_static/images/cloud-gcp-vpc-05.png - -.. figure:: /_static/images/cloud-gcp-vpc-06.png - -.. figure:: /_static/images/cloud-gcp-vpc-07.png - -For more information, please visit the official Google Cloud documentation: - -https://cloud.google.com/vpc/docs/create-modify-vpc-networks - - -Step 4: Deploy VyOS instance from Marketplace ---------- - -1. Go to the Google Cloud Marketplace page in the Google Cloud console https://console.cloud.google.com/marketplace - -2. Choose the project where you want to deploy the VyOS instance. - -.. figure:: /_static/images/cloud-gcp-proj.png - -3. In the search bar, type ``vyos`` to find the VyOS image in the Marketplace. - -.. figure:: /_static/images/cloud-gcp-market-01.png - -.. figure:: /_static/images/cloud-gcp-market-02.png - -4. On the next page, review details such as support, pricing, and other details. - -.. figure:: /_static/images/cloud-gcp-market-03.png - -5. Click the ``GET STARTED`` button to start deployment process. - -.. figure:: /_static/images/cloud-gcp-market-04.png - -.. figure:: /_static/images/cloud-gcp-market-05.png - -6. General settings. - - - Deployment name: e.g., ``vyos-test-vm`` - - - Select a Service Account: Select the service account created earlier. - - - Image: Select VyOS image for deployment. - - - Zone: e.g., ``europe-west1-b`` - - - Machine type: Choose based on performance and resource needs. - -.. figure:: /_static/images/cloud-gcp-vm-01.png - -.. figure:: /_static/images/cloud-gcp-vm-02.png - -7. Configure the network interfaces. - - **Public Network interface:** - - Edit the first (default) network interface and select following settings: - - - Network: ``vyos-public-vpc`` - - - Subnetwork: ``vyos-public-subnet`` - - - External IP: ``Ephemeral`` - - - Private Network interface: - - **Private Network Interface:** - - Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: - - - Network: ``vyos-private-vpc`` - - - Subnetwork: ``vyos-private-subnet`` - - - External IP: ``None`` - -.. figure:: /_static/images/cloud-gcp-vm-03.png - -8. Deployment automation. - - - You can use ``cloud-init`` ``User Data`` to automatically inject specific configuration commands into the VyOS instance during deployment. - - - Example: - - .. code-block:: none - - #cloud-config - vyos_config_commands: - - set system host-name 'VyOS-for-GCP' - - set system login banner pre-login 'Welcome to the VyOS for on GCP' - - set interfaces ethernet eth0 description 'WAN' - - set interfaces ethernet eth1 description 'LAN' - - set interfaces ethernet eth1 address 'dhcp' - - set interfaces ethernet eth1 dhcp-options no-default-route - -For more information, please visit the documentation: - -https://docs.vyos.io/en/stable/automation/cloud-init.html#module-vyos-userdata - -.. figure:: /_static/images/cloud-gcp-vm-09.png - -9. Click ``Deploy`` button. - -.. figure:: /_static/images/cloud-gcp-vm-06.png - -.. figure:: /_static/images/cloud-gcp-vm-07.png - - -Connect to the VyOS instance ------------ - -To connect to the VyOS instance, use the SSH key that was generated in the first step. - -To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** https://console.cloud.google.com/compute/instances?project=vyos-images - -.. figure:: /_static/images/cloud-gcp-vm-08.png - -Example: - - .. code-block:: none - - ssh vyos@35.233.97.132 -i .ssh/vyos_gcp - - The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. - ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. - This key is not known by any other names - Are you sure you want to continue connecting (yes/no/[fingerprint])? yes - Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. - Welcome to the VyOS for on GCP - Welcome to VyOS! - - ┌── ┐ - . VyOS 1.4.2 - └ ──┘ sagitta - - * Documentation: https://docs.vyos.io/en/sagitta - * Project news: https://blog.vyos.io - * Bug reports: https://vyos.dev - - You can change this banner using "set system login banner post-login" command. - - VyOS is a free software distribution that includes multiple components, - you can check individual component licenses under /usr/share/doc/*/copyright - vyos@VyOS-for-GCP:~$ - - diff --git a/docs/installation/cloud/index.md b/docs/installation/cloud/index.md new file mode 100644 index 00000000..f64883fc --- /dev/null +++ b/docs/installation/cloud/index.md @@ -0,0 +1,14 @@ +# Running VyOS in Cloud Environments + +```{eval-rst} +.. toctree:: + :caption: Content + + aws + aws-ha + azure + azure-ha + aws-to-azure + gcp + oracle +``` diff --git a/docs/installation/cloud/index.rst b/docs/installation/cloud/index.rst deleted file mode 100644 index 7a17f18d..00000000 --- a/docs/installation/cloud/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -################################## -Running VyOS in Cloud Environments -################################## - - - -.. toctree:: - :caption: Content - - aws - aws-ha - azure - azure-ha - aws-to-azure - gcp - oracle \ No newline at end of file diff --git a/docs/installation/cloud/md-aws-ha.md b/docs/installation/cloud/md-aws-ha.md deleted file mode 100644 index f32e2ab5..00000000 --- a/docs/installation/cloud/md-aws-ha.md +++ /dev/null @@ -1,135 +0,0 @@ -# VyOS High Availability (HA) Deployment on AWS - -This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. - -## Why Use HA on AWS? - -This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. - -Key Advantages: - -- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. - -- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. - -- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. - -- On failure: - - - Withdraws the failed peer’s routes from the RIB. - - Recomputes the optimal path in the FIB. - - Updates VPC route tables to point to the active instance. - -- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. - -This architecture supports: - -- Cloud edge routing with failover. -- Hybrid cloud resiliency. -- Rapid recovery during instance crashes, upgrades, or network disruptions. -- Continuity for mission-critical operations. - -## HA Architecture Diagram - -:::{figure} /_static/images/cloud-aws-ha-architecture.png -:alt: VyOS HA topology diagram -::: - -## Terraform Automation - -To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. - -This Terraform project automates the deployment of: - -- Two VyOS instances in HA mode. -- VPC Route Server. -- Transit Gateway. -- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. - -To integrate with existing AWS infrastructure: - -- Remove the Data VPC, its subnets, and EC2 test instance. -- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. - -## Prerequisites - -AWS Environment: - -- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). - -Local Environment: - -- AWS CLI installed: -- Terraform installed: - -Set AWS credentials in your shell: - -```none -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -export AWS_SESSION_TOKEN="" -export AWS_DEFAULT_REGION="" # e.g., us-east-1 -``` - -Obtain VyOS AMI ID and Owner ID: - -Subscribe to VyOS via AWS Marketplace. Then run: - -```none -aws ec2 describe-images \ - --owners aws-marketplace \ - --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ - --query 'Images[*].[ImageId,OwnerId,Name]' \ - --output table -``` - -Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. - -Generate an SSH keypair (or use the included demo key): - -```none -ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem -chmod 400 keys/vyos_custom_key.pem -``` - -## Usage - -Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. - -Terraform Workflow: - -```none -terraform init -terraform fmt -terraform validate -terraform plan -terraform apply -``` - -On completion, run: - -```none -terraform output -``` - -This displays the management IP and connectivity test results. - -To clean up: - -```none -terraform destroy -``` - -## Management - -SSH into VyOS: - -```none -ssh vyos@ -i keys/vyos_custom_key.pem -``` - -## GitHub Repository - -You can clone or download the Terraform project and use them in your environment: - - diff --git a/docs/installation/cloud/md-aws-to-azure.md b/docs/installation/cloud/md-aws-to-azure.md deleted file mode 100644 index 246df5f3..00000000 --- a/docs/installation/cloud/md-aws-to-azure.md +++ /dev/null @@ -1,175 +0,0 @@ -# VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity - -This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. -It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, -automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) -are also deployed for connectivity validation. - -## Why Cloud-to-Cloud Connectivity? - -Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: - -- **Inter-Cloud Connectivity** - - Enable secure and reliable communication between workloads in different clouds - (for example, AWS applications connecting to Azure-hosted identity services). - -- **Cloud-to-Cloud Migration** - - During migration projects, workloads may temporarily run in both clouds. - Direct tunnels ensure smooth transition and synchronization. - -- **Testing and Validation** - - Labs and proof-of-concepts often simulate multi-cloud architectures. - A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. - -## Architecture - -The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. -BGP is used for dynamic routing between the clouds, allowing for seamless communication. - -:::{figure} /_static/images/cloud-aws-to-azure.png -:alt: VyOS Cloud-to-Cloud topology diagram -::: - -## Terraform Automation - -To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. -These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. - -In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. -These serve as test endpoints to validate connectivity between the cloud environments. - -## Prerequisites - -### AWS Environment - -- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). - -Local Environment: - -- AWS CLI installed: -- Terraform installed: - -Set AWS credentials in your shell: - -```none -export AWS_ACCESS_KEY_ID="" -export AWS_SECRET_ACCESS_KEY="" -export AWS_SESSION_TOKEN="" -export AWS_DEFAULT_REGION="" # e.g., us-east-1 -``` - -Obtain VyOS AMI ID and Owner ID: - -Subscribe to VyOS via AWS Marketplace. Then run: - -```none -aws ec2 describe-images \ - --owners aws-marketplace \ - --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ - --query 'Images[*].[ImageId,OwnerId,Name]' \ - --output table -``` - -Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. - -Generate an SSH keypair (or use the included demo key): - -```none -ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem -chmod 400 keys/vyos_custom_key.pem -``` - -### Azure Environment - -- Active Azure subscription: - -```none -az account set --subscription "" -``` - -- Azure CLI installed: - - - -- Logged in with Azure credentials: - -```none -az version -az login -``` - -- Azure Resource Group (RG) created: - -```none -az group create --name demoResourceGroup --location westus -az group list -az group show --name demoResourceGroup -``` - -- Terraform installed: - - - -- SSH key generated: - -```none -ssh-keygen -t rsa -b 4096 -f keys/id_rsa -chmod 400 keys/id_rsa -``` - -## Usage - -### AWS - -All variables needed for customization are defined in `variables.tf`. -Adjust them according to your requirements, such as EC2 instance type and networking configurations. - -Before deployment, ensure you check `aws_region`, `availability_zone`, and update `vyos_ami_id` as necessary. - -### Azure - -All variables needed for customization are defined in `variables.tf`. -Adjust them according to your requirements, such as VM size and networking configurations. - -Before deployment, ensure you check `azure_region`, `availability_zone`, and update `subscription_id` and `resource_group_name` as necessary. - -### Terraform Workflow - -```none -terraform init -terraform fmt -terraform validate -terraform plan -terraform apply -``` - -On completion, run: - -```none -terraform output -``` - -This displays the public IP addresses of the VyOS instances. - -To clean up: - -```none -terraform destroy -``` - -## Management - -SSH into VyOS: - -```none -ssh vyos@ -i keys/vyos_custom_key.pem -``` - -## GitHub Repository - -You can clone or download the Terraform projects and use them in your environment: - - diff --git a/docs/installation/cloud/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md deleted file mode 100644 index fa94c222..00000000 --- a/docs/installation/cloud/md-azure-ha.md +++ /dev/null @@ -1,128 +0,0 @@ -# VyOS High Availability (HA) Deployment on Azure - -This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. - -## Why Use HA on Azure? - -This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: - -- Rapid deployment of cloud edge routers. -- Full control over BGP route advertisement and filtering. -- Realistic HA and disaster recovery simulations. -- Seamless integration with hybrid or multi-cloud infrastructure. - -The architecture includes: - -- Two VyOS routers in a Transit VNet, configured with BGP. -- Azure Route Server for dynamic route distribution. -- Site-to-Site VPN connections to a simulated on-premises VyOS router. -- An Ubuntu VM for connectivity and routing validation. -- A Data VNet for testing and diagnostics. - -## Key Features - -- **High Availability**: Dual VyOS routers for redundancy and failover. -- **Dynamic Routing**: BGP-based routing via Azure Route Server. -- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. -- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. -- **Modular & Flexible**: Easily configurable via variables. - -## HA Architecture Diagram - -:::{figure} /_static/images/cloud-azure-ha-architecture.png -:alt: VyOS HA topology diagram -::: - -This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. - -## Terraform Automation - -To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. - -This Terraform project automates the deployment of: - -- Two VyOS instances in HA mode. -- Azure Route Server. -- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. - -## Prerequisites - -Ensure you have: - -- Active Azure subscription: - -```none -az account set --subscription "" -``` - -- Azure CLI installed: - - - -- Logged in with Azure credentials: - -```none -az version -az login -``` - -- Azure Resource Group (RG) created: - -```none -az group create --name demoResourceGroup --location westus -az group list -az group show --name demoResourceGroup -``` - -- Terraform installed: - - - -- SSH key generated: - -```none -ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem -chmod 400 keys/vyos_custom_key.pem -``` - -## Usage - -All variables are defined in `variables.tf`. Adjust them to match your environment. - -Terraform Workflow: - -```none -terraform init -terraform fmt -terraform validate -terraform plan -terraform apply -``` - -On completion, run: - -```none -terraform output -``` - -This displays the management IP and connectivity test results. - -To clean up: - -```none -terraform destroy -``` - -## Management - -SSH into VyOS: - -```none -ssh adminuser@ -i keys/vyos_custom_key.pem -``` - -## GitHub Repository - -You can clone or download the Terraform project and use them in your environment: - - diff --git a/docs/installation/cloud/md-azure.md b/docs/installation/cloud/md-azure.md deleted file mode 100644 index aa577aa1..00000000 --- a/docs/installation/cloud/md-azure.md +++ /dev/null @@ -1,378 +0,0 @@ -# VyOS Deployment on Azure - -This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. - -## Prerequisites for Deploying VyOS on Azure - -### Azure Account - -Ensure you have an active Azure subscription. - -### Microsoft Entra ID Permissions - -To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. - -**Reference Documentation:** - - - - - - - -## Deployment Steps - -### Step 1: Create a Resource Group - -A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. - -#### Create resource groups - -- Go to the Azure Portal . -- Sign in with your Azure account credentials. -- In the portal, search for and select **Resource groups**. -- Select **Create**. - -:::{figure} /_static/images/cloud-azure-rg-01.png -::: - -- Enter the following values: -- **Subscription**: Select your Azure subscription. -- **Resource group**: Enter a new resource group name, e.g., `VyOSResourceGroup`. -- **Region**: Select an Azure location, such as Central US. -- Select **Review + Create** -- Select **Create**. It takes a few seconds to create a resource group. - -:::{figure} /_static/images/cloud-azure-rg-02.png -::: - -### Step 2: Create a Virtual Network (VNet) and Subnets - -Sign in to the Azure portal with your Azure account - -- In the portal, search for and select **Virtual networks**. -- On the **Virtual networks** page, select **+ Create**. -- On the **Basics** tab of **Create virtual network**, enter, or select the following information: -- **Subscription**: Select your Subscription -- **Resource Group**: Select e.g., `VyOSResourceGroup` -- **Name**: e.g., `VyOS-VirtualNetwork` -- **Region**: e.g., `West Europe`. - -:::{figure} /_static/images/cloud-azure-vnet-01.png -::: - -**IP addresses**: - -- Address Space: `10.1.0.0/16` - -:::{figure} /_static/images/cloud-azure-vnet-02.png -::: - -**Add two subnets**: - -- Name: e.g., `VyOS-Private-Subnet` - - Starting address: e.g., `10.1.1.0` - - Size: `/24` - -- Name: e.g., `VyOS-Public-Subnet` - - Starting address: e.g., `10.1.11.0` - - Size: `/24` - -:::{figure} /_static/images/cloud-azure-vnet-03.png -::: - -:::{figure} /_static/images/cloud-azure-vnet-04.png -::: - -:::{figure} /_static/images/cloud-azure-vnet-05.png -::: - -- Click **Review + Create** and then **Create**. - -### Step 3: Create and configure Network Security Group (NSG) - -- In the Azure Portal, search for and select **Network Security Groups**. -- On the **Network Security Groups** page, select **+ Create**. - -Enter the details: - -- **Subscription**: Select your Subscription -- **Resource Group**: Select `VyOSResourceGroup` -- **Name**: e.g., `VyOS-SecurityGroup` -- **Region**: e.g., `West Europe`. - -:::{figure} /_static/images/cloud-azure-sg-01.png -::: - -- Click **Review + Create** and then **Create**. - -**Add inbound rules**: - -- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** - -:::{figure} /_static/images/cloud-azure-sg-02.png -::: - -**Add Rule Example:** - -- **Rule 1**: AllowSSH - - > - **Port**: 22 - > - **Protocol**: TCP - > - **Source**: Any - > - **Priority**: 1001 - -**Add Additional Rules**: - -You can add inbound rules based on your specific services, such as: - -> - ESP -> - OpenVPN -> - WireGuard, etc. - -:::{figure} /_static/images/cloud-azure-sg-03.png -::: - -**Associate subnets**: - -- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: - -:::{figure} /_static/images/cloud-azure-sg-04.png -::: - -### Step 4: Create Public IP Address - -- In the Azure Portal, search for and select **Public IP Addresses**. -- On the **Public IP Addresses** page, select **+ Create**. -- Provide the following details: -- **Subscription**: Select your Subscription -- **Resource Group**: Select `VyOSResourceGroup` -- **Region**: `West Europe` - -:::{figure} /_static/images/cloud-azure-pub-ip-01.png -::: - -- **Name**: `VyOS-Pub-IP` -- **IP Version**: `IPv4` -- **SKU**: `Standard` -- **Availability zone**: Select Availability Zone - -:::{figure} /_static/images/cloud-azure-pub-ip-02.png -::: - -- **IP address assignment**: `Static` -- **Idle timeout (minutes)** `30` (max) - -:::{figure} /_static/images/cloud-azure-pub-ip-03.png -::: - -- Click **Review + Create**, then **Create**. - -### Step 5: Deploy the VyOS Network Virtual Machine (NVA) - -- In the Azure Portal, search for and select **Virtual Machines**. -- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. -- Provide the following details: -- **Subscription**: Select your Subscription -- **Resource Group**: Select `VyOSResourceGroup` -- **Virtual machine name**: e.g., `VyOS` -- **Region**: e.g., `West Europe` -- **Security type**: `Standard` -- **Image**: `VyOS` (On the marketplace search `VyOS` and choose the appropriate subscription). - -:::{figure} /_static/images/cloud-azure-vm-01.png -::: - -- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. - -:::{figure} /_static/images/cloud-azure-vm-02.png -::: - -- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. -- **Username**: The administrator username for the VM, e.g., `vyos`. -- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. - -:::{figure} /_static/images/cloud-azure-vm-03.png -::: - -- **Virtual network**: Select `VyOS-VirtualNetwork`. -- **Subnet**: Select `VyOS-Public-Subnet`. -- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`. - -:::{figure} /_static/images/cloud-azure-vm-04.png -::: - -- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`. - -:::{figure} /_static/images/cloud-azure-vm-05.png -::: - -- Click **Review + Create**, then **Create**. -- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. - -:::{figure} /_static/images/cloud-azure-vm-06.png -::: - -- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. - -:::{figure} /_static/images/cloud-azure-vm-07.png -::: - -### Step 6: Access the VyOS instance - -- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: - - ```none - $ ssh vyos@51.124.120.235 -i vyos_key.pem - vyos@VyOS:~$ - ``` - -### Step 7: Enable IP Forwarding in Network Interface - -This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. - -- On the **Virtual Machines** page, select `VyOS` VM, under **Networking** tab select **Network settings**, click network interface. - -:::{figure} /_static/images/cloud-azure-vm-12.png -::: - -- Enable IP forwarding and click the **Apply** button. - -:::{figure} /_static/images/cloud-azure-vm-13.png -::: - -### Step 8: Create and attach the second network interface (optional) - -Now instance has been deployed with one **eth0** `WAN` interface and want to add -new one. To add new interface an example **eth1** `LAN` you need shutdown the -instance. Attach the interface in the Azure portal and then start the instance. - -:::{note} -Azure does not allow you attach interface when the instance in the -**Running** state. -::: - -#### Create network interface: - -- In the Azure Portal, search for and select **Network Interfaces**. -- On the **Network Interfaces** page, select **+ Create**. - -:::{figure} /_static/images/cloud-azure-nic-01.png -::: - -- **Subscription**: Select your Subscription -- **Resource Group**: Select `VyOSResourceGroup` -- **Name**: `VyOS-PRIV-NIC` -- **Subnet**: `VyOS-Private-Subnet` -- **Private IP**: `Dynamic` -- Click **Review + Create**, then **Create** - -:::{figure} /_static/images/cloud-azure-nic-02.png -::: - -- Enable **IP Forwarding** -- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC` - -:::{figure} /_static/images/cloud-azure-nic-03.png -::: - -- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. - -:::{figure} /_static/images/cloud-azure-nic-04.png -::: - -#### Attach reate network interface: - -- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button - -:::{figure} /_static/images/cloud-azure-vm-08.png -::: - -- Go to **Networking** select **Network settings** and then select **Attach network interface** - -:::{figure} /_static/images/cloud-azure-vm-09.png -::: - -- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button. - -:::{figure} /_static/images/cloud-azure-vm-10.png -::: - -- Now you have attached second interface to your instance and you can start Virtual Machine. -- Go to **Overview** and click the **Start** button. - -:::{figure} /_static/images/cloud-azure-vm-11.png -::: - -### Setp 8: Absorbing Routes - -To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. - -- Step-by-Step Instructions: -- Navigate to **Route Tables** and click **+ Create**. - -Provide the following details: - -> - **Subscription**: Select your Subscription -> - **Resource Group**: Select `VyOSResourceGroup` -> - **Name**: `Route-VyOS` -> - **Region**: e.g., `West Europe` - -:::{figure} /_static/images/cloud-azure-route-01.png -::: - -- Click **Review + Create**, then **Create**. - -**Add a Route**: - -- Navigate to **Route Tables** and click the new created route (`Route-VyOS`). -- Go to **Routes** and click **+ Add** button. - -:::{figure} /_static/images/cloud-azure-route-02.png -::: - -Add following parameters: - -- **Name**: `Default-Route` -- **Destination type**: `IP Addresses` -- **Destination IP addresses/CIDR ranges**: `0.0.0.0/0` -- **Next Hop Type**: `Virtual Appliance` -- **Next Hop IP Address**: `10.1.11.4` (The private Network Interface Card IP Address) - -:::{figure} /_static/images/cloud-azure-route-03.png -::: - -- Click the **Add** button. - -**Associate the Route Table with subnet**: - -- Navigate to **Route Tables** and click the new created route (`VyOSResourceGroup`). -- Go to **Subnets** and click **+ Associate** button. - -:::{figure} /_static/images/cloud-azure-route-04.png -::: - -- **Virtual network**: Select `VyOS-VirtualNetwork`. -- **Subnet**: Select `VyOS-Public-Subnet`. - -:::{figure} /_static/images/cloud-azure-route-05.png -::: - -:::{note} -If you want to create a new default route for VMs on the subnet, use **Address Prefix** `0.0.0.0/0` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the `WAN` interface. -::: - -### Deploy VyOS Instance and Required Resources Automatically (via Terraform) - -You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. -All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. - -You can also edit/change these parameters based on your requirements. - -- Download/Clone the Repository following GitHub repository: - - diff --git a/docs/installation/cloud/md-gcp.md b/docs/installation/cloud/md-gcp.md deleted file mode 100644 index 7144f083..00000000 --- a/docs/installation/cloud/md-gcp.md +++ /dev/null @@ -1,260 +0,0 @@ -# VyOS Deployment on Google Cloud Platform - -This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). - -## Prerequisites - -Before proceeding, ensure the following: - -- A GCP account with billing enabled. -- Permissions to deploy Marketplace images. -- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). -- An SSH key pair for VyOS instance access. -- GA Google Cloud Project. - -## Deployment Steps - -### Step 1: Add SSH Key - -1. If you don’t already have SSH keys, generate an SSH key pair of type `ssh-rsa` on your local machine: - -> Example: -> -> ```none -> ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" -> ``` - -:::{note} -In the comment `vyos@mypc`, the username must start with vyos. -This is because the default user in the VyOS image is `vyos`, and the Google Cloud API uses this value for SSH access. -::: - -2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose - **SSH Keys**. - -:::{figure} /_static/images/cloud-gcp-01.png -::: - -3. Click **edit** and **Add item**. -4. Paste your public ssh key and **Save**. - -:::{figure} /_static/images/cloud-gcp-02.png -::: - -For more information, please visit the official Google Cloud documentation: - - - - - -### Step 2: Create a Service Account (If You Don't Have One) - -1. In the Google Cloud console **IAM & Admin > Service Accounts**. -2. Select select a project. - -:::{figure} /_static/images/cloud-gcp-proj.png -::: - -3. Click **Create Service Account**: - - - Name: e.g., `vyos-test` - - Service account ID: e.g., `vyos-test` - - Description: e.g., `VyOS Test Service Account` - -4. Click **Done**. - -:::{figure} /_static/images/cloud-gcp-svc.png -::: - -For more information, please visit the official Google Cloud documentation: - - - - - -### Step 3: Create VPC Networks and Subnets - -1. In the Google Cloud console **VPC Network > VPC Networks** -2. Select select a project. - -:::{figure} /_static/images/cloud-gcp-proj.png -::: - -3. Click **Create VPC Network**. - - **Public VPC**: - - - Name: e.g., `vyos-public-vpc` - - Subnet creation mode: `Custom` - - Subnet name: e.g., `vyos-public-subnet` - - Region: e.g., `europe-west1` - - IP range: e.g., `10.0.1.0/24` - - Leave all other settings at default, then click **Create**. - -:::{figure} /_static/images/cloud-gcp-vpc-01.png -::: - -:::{figure} /_static/images/cloud-gcp-vpc-02.png -**Private VPC**: - -- Name: `vyos-private-vpc` -- Subnet creation mode: `Custom` -- Subnet name: `vyos-private-subnet` -- Region: e.g., `europe-west1` -- IP range: `10.0.11.0/24` -- Leave all other settings at default, then click **Create**. -::: - -:::{figure} /_static/images/cloud-gcp-vpc-03.png -::: - -:::{figure} /_static/images/cloud-gcp-vpc-04.png -::: - -4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. - -:::{figure} /_static/images/cloud-gcp-vpc-05.png -::: - -:::{figure} /_static/images/cloud-gcp-vpc-06.png -::: - -:::{figure} /_static/images/cloud-gcp-vpc-07.png -::: - -For more information, please visit the official Google Cloud documentation: - - - -### Step 4: Deploy VyOS instance from Marketplace - -1. Go to the Google Cloud Marketplace page in the Google Cloud console -2. Choose the project where you want to deploy the VyOS instance. - -:::{figure} /_static/images/cloud-gcp-proj.png -::: - -3. In the search bar, type `vyos` to find the VyOS image in the Marketplace. - -:::{figure} /_static/images/cloud-gcp-market-01.png -::: - -:::{figure} /_static/images/cloud-gcp-market-02.png -::: - -4. On the next page, review details such as support, pricing, and other details. - -:::{figure} /_static/images/cloud-gcp-market-03.png -::: - -5. Click the `GET STARTED` button to start deployment process. - -:::{figure} /_static/images/cloud-gcp-market-04.png -::: - -:::{figure} /_static/images/cloud-gcp-market-05.png -::: - -6. General settings. - - - Deployment name: e.g., `vyos-test-vm` - - Select a Service Account: Select the service account created earlier. - - Image: Select VyOS image for deployment. - - Zone: e.g., `europe-west1-b` - - Machine type: Choose based on performance and resource needs. - -:::{figure} /_static/images/cloud-gcp-vm-01.png -::: - -:::{figure} /_static/images/cloud-gcp-vm-02.png -::: - -7. Configure the network interfaces. - - **Public Network interface:** - - Edit the first (default) network interface and select following settings: - - > - Network: `vyos-public-vpc` - > - Subnetwork: `vyos-public-subnet` - > - External IP: `Ephemeral` - > - Private Network interface: - - **Private Network Interface:** - - Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: - - > - Network: `vyos-private-vpc` - > - Subnetwork: `vyos-private-subnet` - > - External IP: `None` - -:::{figure} /_static/images/cloud-gcp-vm-03.png -::: - -8. Deployment automation. - - - You can use `cloud-init` `User Data` to automatically inject specific configuration commands into the VyOS instance during deployment. - - Example: - -> ```none -> #cloud-config -> vyos_config_commands: -> - set system host-name 'VyOS-for-GCP' -> - set system login banner pre-login 'Welcome to the VyOS for on GCP' -> - set interfaces ethernet eth0 description 'WAN' -> - set interfaces ethernet eth1 description 'LAN' -> - set interfaces ethernet eth1 address 'dhcp' -> - set interfaces ethernet eth1 dhcp-options no-default-route -> ``` - -For more information, please visit the documentation: - - - -:::{figure} /_static/images/cloud-gcp-vm-09.png -::: - -9. Click `Deploy` button. - -:::{figure} /_static/images/cloud-gcp-vm-06.png -::: - -:::{figure} /_static/images/cloud-gcp-vm-07.png -::: - -### Connect to the VyOS instance - -To connect to the VyOS instance, use the SSH key that was generated in the first step. - -To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** - -:::{figure} /_static/images/cloud-gcp-vm-08.png -::: - -Example: - -> ```none -> ssh vyos@35.233.97.132 -i .ssh/vyos_gcp -> -> The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. -> ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. -> This key is not known by any other names -> Are you sure you want to continue connecting (yes/no/[fingerprint])? yes -> Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. -> Welcome to the VyOS for on GCP -> Welcome to VyOS! -> -> ┌── ┐ -> . VyOS 1.4.2 -> └ ──┘ sagitta -> -> * Documentation: https://docs.vyos.io/en/sagitta -> * Project news: https://blog.vyos.io -> * Bug reports: https://vyos.dev -> -> You can change this banner using "set system login banner post-login" command. -> -> VyOS is a free software distribution that includes multiple components, -> you can check individual component licenses under /usr/share/doc/*/copyright -> vyos@VyOS-for-GCP:~$ -> ``` diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md deleted file mode 100644 index f64883fc..00000000 --- a/docs/installation/cloud/md-index.md +++ /dev/null @@ -1,14 +0,0 @@ -# Running VyOS in Cloud Environments - -```{eval-rst} -.. toctree:: - :caption: Content - - aws - aws-ha - azure - azure-ha - aws-to-azure - gcp - oracle -``` diff --git a/docs/installation/cloud/md-oracel.md b/docs/installation/cloud/md-oracel.md deleted file mode 100644 index 9ed07ff9..00000000 --- a/docs/installation/cloud/md-oracel.md +++ /dev/null @@ -1,5 +0,0 @@ -# Oracle - -## References - - diff --git a/docs/installation/cloud/oracel.md b/docs/installation/cloud/oracel.md new file mode 100644 index 00000000..9ed07ff9 --- /dev/null +++ b/docs/installation/cloud/oracel.md @@ -0,0 +1,5 @@ +# Oracle + +## References + + diff --git a/docs/installation/cloud/oracel.rst b/docs/installation/cloud/oracel.rst deleted file mode 100644 index 72c40127..00000000 --- a/docs/installation/cloud/oracel.rst +++ /dev/null @@ -1,8 +0,0 @@ -###### -Oracle -###### - - -References ----------- -https://www.oracle.com/cloud/ \ No newline at end of file diff --git a/docs/installation/cloud/rst-aws-ha.rst b/docs/installation/cloud/rst-aws-ha.rst new file mode 100755 index 00000000..af125969 --- /dev/null +++ b/docs/installation/cloud/rst-aws-ha.rst @@ -0,0 +1,154 @@ +########## +VyOS High Availability (HA) Deployment on AWS +########## + +This document describes how to deploy VyOS in a High Availability (HA) configuration on AWS using Terraform and a VPC Route Server to provide sub-second failover. + +Why Use HA on AWS? +------------------ + +This solution helps organizations achieve **high availability** routing with dynamic connectivity to multiple AWS VPCs or hybrid environments. + +Key Advantages: + +- Utilizes **AWS VPC Route Server** to manage BGP routes dynamically. + +- Deploys two VyOS EC2 instances as BGP peers connected to the Route Server. Although both participate, one is typically preferred as the next-hop. + +- Employs **Bidirectional Forwarding Detection (BFD)** for rapid failure detection. + +- On failure: + + - Withdraws the failed peer’s routes from the RIB. + + - Recomputes the optimal path in the FIB. + + - Updates VPC route tables to point to the active instance. + +- Enables **sub-second failover** (< 1 s), outperforming AWS API-based route table failover. + +This architecture supports: + +- Cloud edge routing with failover. + +- Hybrid cloud resiliency. + +- Rapid recovery during instance crashes, upgrades, or network disruptions. + +- Continuity for mission-critical operations. + +HA Architecture Diagram +------------------------ + +.. figure:: /_static/images/cloud-aws-ha-architecture.png + :alt: VyOS HA topology diagram + +Terraform Automation +-------------------- + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on AWS. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. + +- VPC Route Server. + +- Transit Gateway. + +- A Transit VPC and a Data VPC containing a test Amazon Linux EC2 instance for connectivity validation. + +To integrate with existing AWS infrastructure: + +- Remove the Data VPC, its subnets, and EC2 test instance. + +- Update `main.tf`, `network.tf`, `transit_gateway.tf`, `variables.tf`, and `outputs.tf` accordingly. + +Prerequisites +------------- + +AWS Environment: + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html + +- Terraform installed: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli + +Set AWS credentials in your shell: + +.. code-block:: none + + export AWS_ACCESS_KEY_ID="" + export AWS_SECRET_ACCESS_KEY="" + export AWS_SESSION_TOKEN="" + export AWS_DEFAULT_REGION="" # e.g., us-east-1 + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +.. code-block:: none + + aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table + +Alternatively, set the `vyos_ami_id` variable directly in `variables.tf`. + +Generate an SSH keypair (or use the included demo key): + +.. code-block:: none + + ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem + chmod 400 keys/vyos_custom_key.pem + +Usage +----- + +Configure variables in `variables.tf`, including instance type, region, and `vyos_ami_id`. + +Terraform Workflow: + +.. code-block:: none + + terraform init + terraform fmt + terraform validate + terraform plan + terraform apply + +On completion, run: + +.. code-block:: none + + terraform output + +This displays the management IP and connectivity test results. + +To clean up: + +.. code-block:: none + + terraform destroy + +Management +---------- + +SSH into VyOS: + +.. code-block:: none + + ssh vyos@ -i keys/vyos_custom_key.pem + + +GitHub Repository +----------------- + +You can clone or download the Terraform project and use them in your environment: + +https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/ha-instances-with-configs diff --git a/docs/installation/cloud/rst-aws-to-azure.rst b/docs/installation/cloud/rst-aws-to-azure.rst new file mode 100755 index 00000000..81651feb --- /dev/null +++ b/docs/installation/cloud/rst-aws-to-azure.rst @@ -0,0 +1,189 @@ +########## +VyOS Deployment on AWS and Azure for Secure Cloud-to-Cloud Connectivity +########## + +This document provides step-by-step guidance for deploying VyOS routers on both AWS and Azure. +It describes how to establish secure inter-cloud connectivity using IPsec tunnels with BGP, +automated through Terraform. Example workloads (Amazon Linux EC2 on AWS and Ubuntu VM on Azure) +are also deployed for connectivity validation. + +Why Cloud-to-Cloud Connectivity? +-------------------------------- + +Cloud-to-cloud connectivity is needed in modern multi-cloud environments for several reasons: + +- **Inter-Cloud Connectivity** + + Enable secure and reliable communication between workloads in different clouds + (for example, AWS applications connecting to Azure-hosted identity services). + +- **Cloud-to-Cloud Migration** + + During migration projects, workloads may temporarily run in both clouds. + Direct tunnels ensure smooth transition and synchronization. + +- **Testing and Validation** + + Labs and proof-of-concepts often simulate multi-cloud architectures. + A VyOS-based tunnel lets teams test routing, encryption, and failover before production rollout. + +Architecture +------------ + +The architecture consists of VyOS routers deployed in both AWS and Azure, connected via secure IPsec tunnels. +BGP is used for dynamic routing between the clouds, allowing for seamless communication. + +.. figure:: /_static/images/cloud-aws-to-azure.png + :alt: VyOS Cloud-to-Cloud topology diagram + +Terraform Automation +-------------------- + +To streamline and standardize the deployment process, a set of **Terraform projects** has been developed. +These projects automate the provisioning of **VyOS instances** and the required networking resources across **AWS** and **Azure**. + +In addition to deploying VyOS, these projects also provision an **Amazon Linux EC2 instance** on AWS and an **Ubuntu VM** on Azure. +These serve as test endpoints to validate connectivity between the cloud environments. + +Prerequisites +------------- + +AWS Environment +^^^^^^^^^^^^^^^ + +- Active AWS account with permissions for EC2, VPC, Transit Gateway, Route Server, and IAM (for keypair and role management). + +Local Environment: + +- AWS CLI installed: https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html + +- Terraform installed: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli + +Set AWS credentials in your shell: + +.. code-block:: none + + export AWS_ACCESS_KEY_ID="" + export AWS_SECRET_ACCESS_KEY="" + export AWS_SESSION_TOKEN="" + export AWS_DEFAULT_REGION="" # e.g., us-east-1 + +Obtain VyOS AMI ID and Owner ID: + +Subscribe to VyOS via AWS Marketplace. Then run: + +.. code-block:: none + + aws ec2 describe-images \ + --owners aws-marketplace \ + --filters "Name=product-code,Values=8wqdkv3u2b9sa0y73xob2yl90" \ + --query 'Images[*].[ImageId,OwnerId,Name]' \ + --output table + +Alternatively, set the ``vyos_ami_id`` variable directly in ``variables.tf``. + +Generate an SSH keypair (or use the included demo key): + +.. code-block:: none + + ssh-keygen -b 2048 -t rsa -m PEM -f keys/vyos_custom_key.pem + chmod 400 keys/vyos_custom_key.pem + +Azure Environment +^^^^^^^^^^^^^^^^^ + +- Active Azure subscription: + +.. code-block:: none + + az account set --subscription "" + +- Azure CLI installed: + + https://learn.microsoft.com/en-us/cli/azure/install-azure-cli + +- Logged in with Azure credentials: + +.. code-block:: none + + az version + az login + +- Azure Resource Group (RG) created: + +.. code-block:: none + + az group create --name demoResourceGroup --location westus + az group list + az group show --name demoResourceGroup + +- Terraform installed: + + https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli + +- SSH key generated: + +.. code-block:: none + + ssh-keygen -t rsa -b 4096 -f keys/id_rsa + chmod 400 keys/id_rsa + +Usage +----- + +AWS +^^^ + +All variables needed for customization are defined in ``variables.tf``. +Adjust them according to your requirements, such as EC2 instance type and networking configurations. + +Before deployment, ensure you check ``aws_region``, ``availability_zone``, and update ``vyos_ami_id`` as necessary. + +Azure +^^^^^ + +All variables needed for customization are defined in ``variables.tf``. +Adjust them according to your requirements, such as VM size and networking configurations. + +Before deployment, ensure you check ``azure_region``, ``availability_zone``, and update ``subscription_id`` and ``resource_group_name`` as necessary. + +Terraform Workflow +^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + terraform init + terraform fmt + terraform validate + terraform plan + terraform apply + +On completion, run: + +.. code-block:: none + + terraform output + +This displays the public IP addresses of the VyOS instances. + +To clean up: + +.. code-block:: none + + terraform destroy + +Management +---------- + +SSH into VyOS: + +.. code-block:: none + + ssh vyos@ -i keys/vyos_custom_key.pem + +GitHub Repository +----------------- + +You can clone or download the Terraform projects and use them in your environment: + +https://github.com/vyos/vyos-automation/tree/main/Terraform/Cloud-to-Cloud diff --git a/docs/installation/cloud/rst-azure-ha.rst b/docs/installation/cloud/rst-azure-ha.rst new file mode 100755 index 00000000..e943b550 --- /dev/null +++ b/docs/installation/cloud/rst-azure-ha.rst @@ -0,0 +1,152 @@ +########## +VyOS High Availability (HA) Deployment on Azure +########## + + +This document describes how to deploy VyOS in a High Availability (HA) configuration on Azure using Terraform and Azure Route Server to provide sub-second failover. + +Why Use HA on Azure? +-------------------- + +This module provides a robust, repeatable foundation for building **resilient network architectures** in Azure. By combining VyOS routing features with Terraform and Azure-native services, it enables: + +- Rapid deployment of cloud edge routers. + +- Full control over BGP route advertisement and filtering. + +- Realistic HA and disaster recovery simulations. + +- Seamless integration with hybrid or multi-cloud infrastructure. + +The architecture includes: + +- Two VyOS routers in a Transit VNet, configured with BGP. + +- Azure Route Server for dynamic route distribution. + +- Site-to-Site VPN connections to a simulated on-premises VyOS router. + +- An Ubuntu VM for connectivity and routing validation. + +- A Data VNet for testing and diagnostics. + +Key Features +------------ + +- **High Availability**: Dual VyOS routers for redundancy and failover. + +- **Dynamic Routing**: BGP-based routing via Azure Route Server. + +- **Hybrid Connectivity**: Site-to-Site VPN integration with a simulated on-prem VyOS. + +- **Testing Environment**: Includes Ubuntu VM for verification and diagnostics. + +- **Modular & Flexible**: Easily configurable via variables. + +HA Architecture Diagram +----------------------- + +.. figure:: /_static/images/cloud-azure-ha-architecture.png + :alt: VyOS HA topology diagram + +This deployment architecture simulates a real-world enterprise network scenario for testing and validation purposes. + +Terraform Automation +-------------------- + +To streamline and standardize the process, we developed a Terraform project that automates the deployment of VyOS in High Availability (HA) mode on Azure. + +This Terraform project automates the deployment of: + +- Two VyOS instances in HA mode. + +- Azure Route Server. + +- A Transit VNet and a Data VNet containing a test Ubuntu VM for connectivity validation. + +Prerequisites +------------- + +Ensure you have: + +- Active Azure subscription: + +.. code-block:: none + + az account set --subscription "" + +- Azure CLI installed: + + https://learn.microsoft.com/en-us/cli/azure/install-azure-cli + +- Logged in with Azure credentials: + +.. code-block:: none + + az version + az login + +- Azure Resource Group (RG) created: + +.. code-block:: none + + az group create --name demoResourceGroup --location westus + az group list + az group show --name demoResourceGroup + +- Terraform installed: + + https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli + +- SSH key generated: + +.. code-block:: none + + ssh-keygen -t rsa -b 4096 -f keys/vyos_custom_key.pem + chmod 400 keys/vyos_custom_key.pem + +Usage +----- + +All variables are defined in ``variables.tf``. Adjust them to match your environment. + +Terraform Workflow: + +.. code-block:: none + + terraform init + terraform fmt + terraform validate + terraform plan + terraform apply + +On completion, run: + +.. code-block:: none + + terraform output + +This displays the management IP and connectivity test results. + +To clean up: + +.. code-block:: none + + terraform destroy + +Management +---------- + +SSH into VyOS: + +.. code-block:: none + + ssh adminuser@ -i keys/vyos_custom_key.pem + + +GitHub Repository +----------------- + +You can clone or download the Terraform project and use them in your environment: + +https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure/azure-ha-deployment-with-configs diff --git a/docs/installation/cloud/rst-azure.rst b/docs/installation/cloud/rst-azure.rst new file mode 100644 index 00000000..563fcb19 --- /dev/null +++ b/docs/installation/cloud/rst-azure.rst @@ -0,0 +1,433 @@ +########## +VyOS Deployment on Azure +########## + + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (Virtual Networks, Network Interfaces, Subnets, Security Groups) on Azure via the Azure Portal. + +Prerequisites for Deploying VyOS on Azure +======== + +Azure Account +----------- + +Ensure you have an active Azure subscription. + +Microsoft Entra ID Permissions +----------- + +To manage resources in **Azure Entra ID** (formerly Azure AD), you need appropriate permissions to handle **Virtual Networks**, **Public IP Addresses**, **Subnets**, and **Virtual Machines**. + +**Reference Documentation:** + +https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal + +https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-portal + +https://learn.microsoft.com/en-us/azure/role-based-access-control/overview + +Deployment Steps +======== + +Step 1: Create a Resource Group +----------- + +A resource group is a container that holds related resources for an Azure solution. The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. + +Create resource groups +^^^^^^^^^^^^^^ + +- Go to the Azure Portal https://portal.azure.com/. + +- Sign in with your Azure account credentials. + +- In the portal, search for and select **Resource groups**. + +- Select **Create**. + +.. figure:: /_static/images/cloud-azure-rg-01.png + +- Enter the following values: + +- **Subscription**: Select your Azure subscription. + +- **Resource group**: Enter a new resource group name, e.g., ``VyOSResourceGroup``. + +- **Region**: Select an Azure location, such as Central US. + +- Select **Review + Create** + +- Select **Create**. It takes a few seconds to create a resource group. + +.. figure:: /_static/images/cloud-azure-rg-02.png + + +Step 2: Create a Virtual Network (VNet) and Subnets +----------- + +Sign in to the Azure portal with your Azure account https://portal.azure.com/ + +- In the portal, search for and select **Virtual networks**. + +- On the **Virtual networks** page, select **+ Create**. + +- On the **Basics** tab of **Create virtual network**, enter, or select the following information: + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select e.g., ``VyOSResourceGroup`` + +- **Name**: e.g., ``VyOS-VirtualNetwork`` + +- **Region**: e.g., ``West Europe``. + +.. figure:: /_static/images/cloud-azure-vnet-01.png + +**IP addresses**: + +- Address Space: ``10.1.0.0/16`` + +.. figure:: /_static/images/cloud-azure-vnet-02.png + +**Add two subnets**: + +- Name: e.g., ``VyOS-Private-Subnet`` + + Starting address: e.g., ``10.1.1.0`` + + Size: ``/24`` + +- Name: e.g., ``VyOS-Public-Subnet`` + + Starting address: e.g., ``10.1.11.0`` + + Size: ``/24`` + +.. figure:: /_static/images/cloud-azure-vnet-03.png + +.. figure:: /_static/images/cloud-azure-vnet-04.png + +.. figure:: /_static/images/cloud-azure-vnet-05.png + +- Click **Review + Create** and then **Create**. + + +Step 3: Create and configure Network Security Group (NSG) +----------- + +- In the Azure Portal, search for and select **Network Security Groups**. + +- On the **Network Security Groups** page, select **+ Create**. + +Enter the details: + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select ``VyOSResourceGroup`` + +- **Name**: e.g., ``VyOS-SecurityGroup`` + +- **Region**: e.g., ``West Europe``. + +.. figure:: /_static/images/cloud-azure-sg-01.png + +- Click **Review + Create** and then **Create**. + +**Add inbound rules**: + +- Navigate to the **Network Security Groups** select **VyOS-SecurityGroup** go to **Inbound security rules** under **Settings** + +.. figure:: /_static/images/cloud-azure-sg-02.png + +**Add Rule Example:** + +- **Rule 1**: AllowSSH + + - **Port**: 22 + + - **Protocol**: TCP + + - **Source**: Any + + - **Priority**: 1001 + +**Add Additional Rules**: + +You can add inbound rules based on your specific services, such as: + + - ESP + + - OpenVPN + + - WireGuard, etc. + +.. figure:: /_static/images/cloud-azure-sg-03.png + +**Associate subnets**: + +- Navigate to the **Network Security Groups**, select **Subnets** click **+ Associate** button. Then select your virtual network and the subnet to which you want to associate the NSG. Select **OK**: + +.. figure:: /_static/images/cloud-azure-sg-04.png + + +Step 4: Create Public IP Address +----------- + +- In the Azure Portal, search for and select **Public IP Addresses**. + +- On the **Public IP Addresses** page, select **+ Create**. + +- Provide the following details: + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select ``VyOSResourceGroup`` + +- **Region**: ``West Europe`` + +.. figure:: /_static/images/cloud-azure-pub-ip-01.png + +- **Name**: ``VyOS-Pub-IP`` + +- **IP Version**: ``IPv4`` + +- **SKU**: ``Standard`` + +- **Availability zone**: Select Availability Zone + +.. figure:: /_static/images/cloud-azure-pub-ip-02.png + +- **IP address assignment**: ``Static`` + +- **Idle timeout (minutes)** ``30`` (max) + +.. figure:: /_static/images/cloud-azure-pub-ip-03.png + +- Click **Review + Create**, then **Create**. + + +Step 5: Deploy the VyOS Network Virtual Machine (NVA) +----------- + +- In the Azure Portal, search for and select **Virtual Machines**. + +- On the **Virtual Machines** page, click **+ Create** and select **Azure virtual machine**. + +- Provide the following details: + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select ``VyOSResourceGroup`` + +- **Virtual machine name**: e.g., ``VyOS`` + +- **Region**: e.g., ``West Europe`` + +- **Security type**: ``Standard`` + +- **Image**: ``VyOS`` (On the marketplace search ``VyOS`` and choose the appropriate subscription). + +.. figure:: /_static/images/cloud-azure-vm-01.png + +- **Size**: Select a VM size to support the workload that you want to run. The size that you choose then determines factors such as processing power, memory, and storage capacity. + +.. figure:: /_static/images/cloud-azure-vm-02.png + +- **Password/SSH Key**: Choose whether the administrator account will use username/password or SSH keys for authentication. + +- **Username**: The administrator username for the VM, e.g., ``vyos``. + +- **SSH Key**: You can use your existing SSH key pair or Azure automatically generates it for you and allows you to store it for future use. + +.. figure:: /_static/images/cloud-azure-vm-03.png + +- **Virtual network**: Select ``VyOS-VirtualNetwork``. + +- **Subnet**: Select ``VyOS-Public-Subnet``. + +- **Public IP**: Select public IP address which created before ``VyOS-Pub-IP``. + +.. figure:: /_static/images/cloud-azure-vm-04.png + +- **Configure network security group**: Select existing Security Group ``VyOS-SecurityGroup``. + +.. figure:: /_static/images/cloud-azure-vm-05.png + +- Click **Review + Create**, then **Create**. + +- Click **Download the private key and create resource** this will download private key to your computer and start creating Virtual Machine. + +.. figure:: /_static/images/cloud-azure-vm-06.png + +- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. + +.. figure:: /_static/images/cloud-azure-vm-07.png + + +Step 6: Access the VyOS instance +----------- + +- Access the VyOS instance using **SSH** protocol, **Public IP Address**, **Private Key**: + + .. code-block:: none + + $ ssh vyos@51.124.120.235 -i vyos_key.pem + vyos@VyOS:~$ + +Step 7: Enable IP Forwarding in Network Interface +----------- + +This option allows the virtual machine on this network interface to act as a router and receive traffic addressed to other destinations. + +- On the **Virtual Machines** page, select ``VyOS`` VM, under **Networking** tab select **Network settings**, click network interface. + +.. figure:: /_static/images/cloud-azure-vm-12.png + +- Enable IP forwarding and click the **Apply** button. + +.. figure:: /_static/images/cloud-azure-vm-13.png + +Step 8: Create and attach the second network interface (optional) +------------- + +Now instance has been deployed with one **eth0** ``WAN`` interface and want to add +new one. To add new interface an example **eth1** ``LAN`` you need shutdown the +instance. Attach the interface in the Azure portal and then start the instance. + +.. note:: Azure does not allow you attach interface when the instance in the + **Running** state. + + +Create network interface: +^^^^^^^^^^^^^^ + +- In the Azure Portal, search for and select **Network Interfaces**. + +- On the **Network Interfaces** page, select **+ Create**. + +.. figure:: /_static/images/cloud-azure-nic-01.png + +- **Subscription**: Select your Subscription + +- **Resource Group**: Select ``VyOSResourceGroup`` + +- **Name**: ``VyOS-PRIV-NIC`` + +- **Subnet**: ``VyOS-Private-Subnet`` + +- **Private IP**: ``Dynamic`` + +- Click **Review + Create**, then **Create** + +.. figure:: /_static/images/cloud-azure-nic-02.png + +- Enable **IP Forwarding** + +- Navigate to **Network Interfaces** select ``VyOS-PRIV-NIC`` + +.. figure:: /_static/images/cloud-azure-nic-03.png + +- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. + +.. figure:: /_static/images/cloud-azure-nic-04.png + + +Attach reate network interface: +^^^^^^^^^^^^^^ + +- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button + +.. figure:: /_static/images/cloud-azure-vm-08.png + +- Go to **Networking** select **Network settings** and then select **Attach network interface** + +.. figure:: /_static/images/cloud-azure-vm-09.png + +- Select existing (before created) network interface ``VyOS-PRIV-NIC`` and click the **OK** button. + +.. figure:: /_static/images/cloud-azure-vm-10.png + +- Now you have attached second interface to your instance and you can start Virtual Machine. + +- Go to **Overview** and click the **Start** button. + +.. figure:: /_static/images/cloud-azure-vm-11.png + + +Setp 8: Absorbing Routes +---------------- + +To route traffic from your Virtual Network (VNET) through the LAN interface of your VyOS Network Virtual Appliance (NVA), you need to create and configure a custom route table in Azure. + +- Step-by-Step Instructions: + +- Navigate to **Route Tables** and click **+ Create**. + +Provide the following details: + + - **Subscription**: Select your Subscription + + - **Resource Group**: Select ``VyOSResourceGroup`` + + - **Name**: ``Route-VyOS`` + + - **Region**: e.g., ``West Europe`` + +.. figure:: /_static/images/cloud-azure-route-01.png + +- Click **Review + Create**, then **Create**. + +**Add a Route**: + +- Navigate to **Route Tables** and click the new created route (``Route-VyOS``). + +- Go to **Routes** and click **+ Add** button. + +.. figure:: /_static/images/cloud-azure-route-02.png + +Add following parameters: + +- **Name**: ``Default-Route`` + +- **Destination type**: ``IP Addresses`` + +- **Destination IP addresses/CIDR ranges**: ``0.0.0.0/0`` + +- **Next Hop Type**: ``Virtual Appliance`` + +- **Next Hop IP Address**: ``10.1.11.4`` (The private Network Interface Card IP Address) + +.. figure:: /_static/images/cloud-azure-route-03.png + +- Click the **Add** button. + +**Associate the Route Table with subnet**: + +- Navigate to **Route Tables** and click the new created route (``VyOSResourceGroup``). + +- Go to **Subnets** and click **+ Associate** button. + +.. figure:: /_static/images/cloud-azure-route-04.png + +- **Virtual network**: Select ``VyOS-VirtualNetwork``. + +- **Subnet**: Select ``VyOS-Public-Subnet``. + +.. figure:: /_static/images/cloud-azure-route-05.png + +.. note:: If you want to create a new default route for VMs on the subnet, use **Address Prefix** ``0.0.0.0/0`` Also note that if you want to use this as a typical edge device, you'll want masquerade NAT for the ``WAN`` interface. + + +Deploy VyOS Instance and Required Resources Automatically (via Terraform) +-------------- + +You can deploy a VyOS instance and its associated resources in **Azure** using Terraform modules available in the GitHub repository. +All necessary parameters will be configured automatically, and you will receive **management and access information** from the outputs. + +You can also edit/change these parameters based on your requirements. + +- Download/Clone the Repository following GitHub repository: + +https://github.com/vyos/vyos-automation/tree/main/Terraform/Azure + + diff --git a/docs/installation/cloud/rst-gcp.rst b/docs/installation/cloud/rst-gcp.rst new file mode 100644 index 00000000..0c23353e --- /dev/null +++ b/docs/installation/cloud/rst-gcp.rst @@ -0,0 +1,277 @@ +##################### +VyOS Deployment on Google Cloud Platform +##################### + +This guide provides step-by-step instructions for deploying a VyOS instance with two NICs and the required resources on Google Cloud Platform (GCP). + +Prerequisites +======== + +Before proceeding, ensure the following: + +- A GCP account with billing enabled. +- Permissions to deploy Marketplace images. +- Access to enable APIs and create resources (e.g., Compute Engine Admin, Network Admin). +- An SSH key pair for VyOS instance access. +- GA Google Cloud Project. + +Deployment Steps +======== + +Step 1: Add SSH Key +------------------- + +1. If you don’t already have SSH keys, generate an SSH key pair of type ``ssh-rsa`` on your local machine: + + Example: + + .. code-block:: none + + ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" + + +.. note:: In the comment ``vyos@mypc``, the username must start with vyos. + This is because the default user in the VyOS image is ``vyos``, and the Google Cloud API uses this value for SSH access. + +2. Open GCP console and navigate to the **Compute Engine** > **Metadata** > **SSH Keys**. Choose + **SSH Keys**. + +.. figure:: /_static/images/cloud-gcp-01.png + + +3. Click **edit** and **Add item**. + +4. Paste your public ssh key and **Save**. + +.. figure:: /_static/images/cloud-gcp-02.png + +For more information, please visit the official Google Cloud documentation: + +https://cloud.google.com/compute/docs/connect/add-ssh-keys + +https://cloud.google.com/compute/docs/connect/create-ssh-keys + + +Step 2: Create a Service Account (If You Don't Have One) +------------------------------- + +1. In the Google Cloud console **IAM & Admin > Service Accounts**. + +2. Select select a project. + +.. figure:: /_static/images/cloud-gcp-proj.png + +3. Click **Create Service Account**: + + - Name: e.g., ``vyos-test`` + + - Service account ID: e.g., ``vyos-test`` + + - Description: e.g., ``VyOS Test Service Account`` + +4. Click **Done**. + +.. figure:: /_static/images/cloud-gcp-svc.png + +For more information, please visit the official Google Cloud documentation: + +https://cloud.google.com/iam/docs/service-accounts-create + +https://cloud.google.com/iam/docs/service-account-overview + + +Step 3: Create VPC Networks and Subnets +------------------------------- + +1. In the Google Cloud console **VPC Network > VPC Networks** https://console.cloud.google.com/networking/networks/list + +2. Select select a project. + +.. figure:: /_static/images/cloud-gcp-proj.png + +3. Click **Create VPC Network**. + + **Public VPC**: + + - Name: e.g., ``vyos-public-vpc`` + + - Subnet creation mode: ``Custom`` + + - Subnet name: e.g., ``vyos-public-subnet`` + + - Region: e.g., ``europe-west1`` + + - IP range: e.g., ``10.0.1.0/24`` + + - Leave all other settings at default, then click **Create**. + +.. figure:: /_static/images/cloud-gcp-vpc-01.png + +.. figure:: /_static/images/cloud-gcp-vpc-02.png + + **Private VPC**: + + - Name: ``vyos-private-vpc`` + + - Subnet creation mode: ``Custom`` + + - Subnet name: ``vyos-private-subnet`` + + - Region: e.g., ``europe-west1`` + + - IP range: ``10.0.11.0/24`` + + - Leave all other settings at default, then click **Create**. + +.. figure:: /_static/images/cloud-gcp-vpc-03.png + +.. figure:: /_static/images/cloud-gcp-vpc-04.png + +4. Add firewall rules to allow specific network traffic from the Internet if needed. By default, all incoming traffic from outside the network is blocked. Typically, a VyOS deployment from the GCP Marketplace configures this automatically, ensuring that SSH access is enabled after deployment. + +.. figure:: /_static/images/cloud-gcp-vpc-05.png + +.. figure:: /_static/images/cloud-gcp-vpc-06.png + +.. figure:: /_static/images/cloud-gcp-vpc-07.png + +For more information, please visit the official Google Cloud documentation: + +https://cloud.google.com/vpc/docs/create-modify-vpc-networks + + +Step 4: Deploy VyOS instance from Marketplace +--------- + +1. Go to the Google Cloud Marketplace page in the Google Cloud console https://console.cloud.google.com/marketplace + +2. Choose the project where you want to deploy the VyOS instance. + +.. figure:: /_static/images/cloud-gcp-proj.png + +3. In the search bar, type ``vyos`` to find the VyOS image in the Marketplace. + +.. figure:: /_static/images/cloud-gcp-market-01.png + +.. figure:: /_static/images/cloud-gcp-market-02.png + +4. On the next page, review details such as support, pricing, and other details. + +.. figure:: /_static/images/cloud-gcp-market-03.png + +5. Click the ``GET STARTED`` button to start deployment process. + +.. figure:: /_static/images/cloud-gcp-market-04.png + +.. figure:: /_static/images/cloud-gcp-market-05.png + +6. General settings. + + - Deployment name: e.g., ``vyos-test-vm`` + + - Select a Service Account: Select the service account created earlier. + + - Image: Select VyOS image for deployment. + + - Zone: e.g., ``europe-west1-b`` + + - Machine type: Choose based on performance and resource needs. + +.. figure:: /_static/images/cloud-gcp-vm-01.png + +.. figure:: /_static/images/cloud-gcp-vm-02.png + +7. Configure the network interfaces. + + **Public Network interface:** + + Edit the first (default) network interface and select following settings: + + - Network: ``vyos-public-vpc`` + + - Subnetwork: ``vyos-public-subnet`` + + - External IP: ``Ephemeral`` + + - Private Network interface: + + **Private Network Interface:** + + Click **ADD A NETWORK INTERFACE** button to create a second (private) interface, and select following settings: + + - Network: ``vyos-private-vpc`` + + - Subnetwork: ``vyos-private-subnet`` + + - External IP: ``None`` + +.. figure:: /_static/images/cloud-gcp-vm-03.png + +8. Deployment automation. + + - You can use ``cloud-init`` ``User Data`` to automatically inject specific configuration commands into the VyOS instance during deployment. + + - Example: + + .. code-block:: none + + #cloud-config + vyos_config_commands: + - set system host-name 'VyOS-for-GCP' + - set system login banner pre-login 'Welcome to the VyOS for on GCP' + - set interfaces ethernet eth0 description 'WAN' + - set interfaces ethernet eth1 description 'LAN' + - set interfaces ethernet eth1 address 'dhcp' + - set interfaces ethernet eth1 dhcp-options no-default-route + +For more information, please visit the documentation: + +https://docs.vyos.io/en/stable/automation/cloud-init.html#module-vyos-userdata + +.. figure:: /_static/images/cloud-gcp-vm-09.png + +9. Click ``Deploy`` button. + +.. figure:: /_static/images/cloud-gcp-vm-06.png + +.. figure:: /_static/images/cloud-gcp-vm-07.png + + +Connect to the VyOS instance +----------- + +To connect to the VyOS instance, use the SSH key that was generated in the first step. + +To retrieve the public IP address, go to the **Google Cloud Console** and navigate to: **Compute Engine** > **VM instances** https://console.cloud.google.com/compute/instances?project=vyos-images + +.. figure:: /_static/images/cloud-gcp-vm-08.png + +Example: + + .. code-block:: none + + ssh vyos@35.233.97.132 -i .ssh/vyos_gcp + + The authenticity of host '35.233.97.132 (35.233.97.132)' can't be established. + ED25519 key fingerprint is SHA256:KCsCnwCGhwX2ba5RcPUAO3ZUSNzS4sXIkujFoScCd0g. + This key is not known by any other names + Are you sure you want to continue connecting (yes/no/[fingerprint])? yes + Warning: Permanently added '35.233.97.132' (ED25519) to the list of known hosts. + Welcome to the VyOS for on GCP + Welcome to VyOS! + + ┌── ┐ + . VyOS 1.4.2 + └ ──┘ sagitta + + * Documentation: https://docs.vyos.io/en/sagitta + * Project news: https://blog.vyos.io + * Bug reports: https://vyos.dev + + You can change this banner using "set system login banner post-login" command. + + VyOS is a free software distribution that includes multiple components, + you can check individual component licenses under /usr/share/doc/*/copyright + vyos@VyOS-for-GCP:~$ + + diff --git a/docs/installation/cloud/rst-index.rst b/docs/installation/cloud/rst-index.rst new file mode 100644 index 00000000..7a17f18d --- /dev/null +++ b/docs/installation/cloud/rst-index.rst @@ -0,0 +1,16 @@ +################################## +Running VyOS in Cloud Environments +################################## + + + +.. toctree:: + :caption: Content + + aws + aws-ha + azure + azure-ha + aws-to-azure + gcp + oracle \ No newline at end of file diff --git a/docs/installation/cloud/rst-oracel.rst b/docs/installation/cloud/rst-oracel.rst new file mode 100644 index 00000000..72c40127 --- /dev/null +++ b/docs/installation/cloud/rst-oracel.rst @@ -0,0 +1,8 @@ +###### +Oracle +###### + + +References +---------- +https://www.oracle.com/cloud/ \ No newline at end of file -- cgit v1.2.3