diff options
Diffstat (limited to 'docs/installation/cloud')
| -rw-r--r-- | docs/installation/cloud/md-aws-ha.md | 132 | ||||
| -rw-r--r-- | docs/installation/cloud/md-aws-to-azure.md | 177 | ||||
| -rw-r--r-- | docs/installation/cloud/md-aws.md | 722 | ||||
| -rw-r--r-- | docs/installation/cloud/md-azure-ha.md | 130 | ||||
| -rw-r--r-- | docs/installation/cloud/md-azure.md | 449 | ||||
| -rw-r--r-- | docs/installation/cloud/md-gcp.md | 298 | ||||
| -rw-r--r-- | docs/installation/cloud/md-index.md | 13 | ||||
| -rw-r--r-- | docs/installation/cloud/md-oracel.md | 5 |
8 files changed, 1926 insertions, 0 deletions
diff --git a/docs/installation/cloud/md-aws-ha.md b/docs/installation/cloud/md-aws-ha.md new file mode 100644 index 00000000..8cdfda44 --- /dev/null +++ b/docs/installation/cloud/md-aws-ha.md @@ -0,0 +1,132 @@ +\########## +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> +<img src="/_static/images/cloud-aws-ha-architecture.webp" alt="VyOS HA topology diagram" /> +</figure> + +# 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 <span class="title-ref">main.tf</span>, <span class="title-ref">network.tf</span>, <span class="title-ref">transit_gateway.tf</span>, <span class="title-ref">variables.tf</span>, and <span class="title-ref">outputs.tf</span> 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: + +``` none +export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>" +export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>" +export AWS_SESSION_TOKEN="<AWS_SESSION_TOKEN>" +export AWS_DEFAULT_REGION="<AWS_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 <span class="title-ref">vyos_ami_id</span> variable directly in <span class="title-ref">variables.tf</span>. + +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 <span class="title-ref">variables.tf</span>, including instance type, region, and <span class="title-ref">vyos_ami_id</span>. + +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@<vyos_public_ip> -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/md-aws-to-azure.md b/docs/installation/cloud/md-aws-to-azure.md new file mode 100644 index 00000000..87effb97 --- /dev/null +++ b/docs/installation/cloud/md-aws-to-azure.md @@ -0,0 +1,177 @@ +\########## +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> +<img src="/_static/images/cloud-aws-to-azure.webp" alt="VyOS Cloud-to-Cloud topology diagram" /> +</figure> + +# 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: + +``` none +export AWS_ACCESS_KEY_ID="<AWS_ACCESS_KEY_ID>" +export AWS_SECRET_ACCESS_KEY="<AWS_SECRET_ACCESS_KEY>" +export AWS_SESSION_TOKEN="<AWS_SESSION_TOKEN>" +export AWS_DEFAULT_REGION="<AWS_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 "<subscription ID or name>" +``` + +- Azure CLI installed: + + <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli> + +- 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: + + <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +- 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@<vyos_public_ip> -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/md-aws.md b/docs/installation/cloud/md-aws.md new file mode 100644 index 00000000..523fd280 --- /dev/null +++ b/docs/installation/cloud/md-aws.md @@ -0,0 +1,722 @@ +\########## +VyOS Deployment on AWS +\########## + +This manual provides detailed step-by-step instructions for deploying a VyOS instance and required resources (VPC, ENIs, Subnets, Security Groups) on AWS. + +Prerequisites +======== + +1\. AWS Account +----------- +Ensure you have an AWS account with administrative access. + +2\. IAM Permissions +----------- + +To deploy VyOS and related resources, the user must have the following permissions: + +- `ec2:` for managing EC2, ENIs, and EIPs. +- `vpc:` for creating VPCs, subnets, and route tables. +- `iam:` for attaching roles. + +3\. SSH Key Pair +----------- + +You can use Amazon EC2 to create your key pairs, or you can use a third-party tool to create your key pairs and then import them to Amazon EC2. +Amazon EC2 supports: + +- `2048-bit SSH-2 RSA keys` for Linux and Windows instances. +- `ED25519 keys` for Linux instances (not supported for Windows). + +When you create a key pair using Amazon EC2: + +- The `public key` is stored in Amazon EC2. +- You store the `private key` securely on your local machine. + +Steps to Create a Key Pair Using Amazon EC2 +^^^^^^^^^^^^^^ + +- Open the Amazon EC2 console <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, under `Network & Security`, choose `Key Pairs`. + +<figure> +<img src="/_static/images/cloud-aws-keypair-01.webp" /> +</figure> + +- Choose `Create key pair` and select `AWS region` at the top right corner of the windows where you plan to deploy the VyOS instance. + +<figure> +<img src="/_static/images/cloud-aws-keypair-02.webp" /> +</figure> + +\- Configure Key Pair: +"""""""""" + +> - **Name**: Enter a descriptive name for the key pair, e.g., `vyos-keypair`. +> +> > <div class="note"> +> > +> > <div class="title"> +> > +> > Note +> > +> > </div> +> > +> > The key name can include up to 255 ASCII characters. It cannot include leading or trailing spaces. +> > +> > </div> +> +> - **Select Key Pair Type**: +> - For **Linux instances**: Choose either **RSA** or **ED25519**. +> +> - For **Windows instances**: Choose **RSA**. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> ED25519 keys are not supported for Windows instances. +> +> </div> +> - **Private Key File Format**: +> - **PEM**: Choose this format if using OpenSSH or other SSH clients (e.g., on Linux/macOS). +> - **PPK**: Choose this format if using PuTTY on Windows. + +- **Optional**: Add tags to the key pair. Choose **Add tag** and provide the **key** and **value** for each tag. + +- Choose **Create key pair**. + +- The private key file will automatically download to your browser. + - The file name will match the name you provided (e.g., <span class="title-ref">vyos-keypair.pem</span>), with the extension determined by the format you chose. + +<figure> +<img src="/_static/images/cloud-aws-keypair-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-keypair-04.webp" alt="Important Notes" /> +<figcaption aria-hidden="true"><strong>Important Notes</strong></figcaption> +</figure> + +- **Save the private key file securely**: + This is your **only chance** to download the private key. If you lose it, you cannot connect to your instance. + +- If you are using SSH on a **macOS or Linux computer**, set the correct permissions for the private key file: + +``` none +chmod 400 vyos-keypair.pem +``` + +If permissions are not set to **400**, you will encounter an **"Unprotected private key file"** error when attempting to connect to the instance. + +> **Example Usage for SSH** + +``` none +ssh -i vyos-keypair.pem vyos@<Public/Elastic IP> +``` + +For more information, please visit the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-key-pairs.html#having-ec2-create-your-key-pair> + +4\. VyOS Subscription +----------- +- Go to the AWS Marketplace <https://aws.amazon.com/marketplace> and search for **VyOS**. +- Subscribe to the VyOS AMI. + +For more information, please visit: + +<https://aws.amazon.com/marketplace/seller-profile?id=7636d180-1710-48bc-acd6-d323c4a0429f> + +Create required resources +======== + +Certain resources need to be created in the AWS infrastructure before creating a VyOS instance, such as a VPC, Subnets, Elastic IPs, Route Tables, Security Groups, and others. + +Step 1: Create Virtual Private Cloud (VPC) and Subnets +----------- + +1\. Create a VPC +^^^^^^^^^^^^^^ + +To create a VPC for your AWS environment: + +- Go to the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. +- In the navigation pane, choose **Your VPCs**. +- Choose **Create VPC**. + +<figure> +<img src="/_static/images/cloud-aws-vpc-01.webp" /> +</figure> + +- **Configure VPC Settings**: + - **Name tag - optional**: Enter a descriptive name for your VPC, e.g., `VyOS-VPC`. + - **IPv4 CIDR Block**: Enter `10.0.0.0/16`. + +- Choose **Create VPC**. + +<figure> +<img src="/_static/images/cloud-aws-vpc-02.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-vpc-03.webp" /> +</figure> + +For more information, please visit the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html> + +2\. Create Subnets +^^^^^^^^^^^^^^ + +Subnets allow you to divide your VPC into smaller IP spaces. Follow these steps to create subnets for both **public** and **private** networks: + +- Go to the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. +- In the navigation pane, choose **Subnets**. +- Choose **Create Subnet**. + +<figure> +<img src="/_static/images/cloud-aws-subnet-01.webp" /> +</figure> + +\- Configure Subnet Settings: +"""""""""" + +> - **Public Subnet**: +> - **VPC**: Select `VyOS-VPC`. +> - **Name Tag**: `VyOS-Public-Subnet`. +> - **IPv4 CIDR Block**: `10.0.1.0/24`. +> - **Availability Zone**: Select an AZ, e.g., `us-east-1a`. +> - **Private Subnet**: +> - **VPC**: Select `VyOS-VPC`. +> - **Name Tag**: `VyOS-Private-Subnet`. +> - **IPv4 CIDR Block**: `10.0.2.0/24`. +> - **Availability Zone**: Select an AZ, e.g., `us-east-1a`. + +- Choose **Create Subnet**. + +<figure> +<img src="/_static/images/cloud-aws-subnet-02.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-aws-subnet-03.webp" /> +</figure> + +For additional information, please visit the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/create-subnets.html> + +For additional details about IP addressing for your VPC and subnets, refer to the AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/vpc-ip-addressing.html> + +Step 2: Create and Configure Security Groups +----------- + +1\. Create Public Security Group +^^^^^^^^^^^^^^ + +The **Public Security Group** is used for **outbound connectivity**. All external resources, systems, or networks will connect via this security group. + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, choose **Security Groups**. +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-01.webp" /> +</figure> + +- **Configure the Security Group**: + + > - **Name**: `VyOS-Public-SG`. + > - **Description**: "Public security group for outbound connectivity" + > - **VPC**: Select the VPC in which your VyOS instance resides. + +\- Inbound Rules: +"""""""""" + +> - **SSH**: Port `22`, Source `0.0.0.0/0` (Restrict to your IP for security). +> - **ICMP**: Allow for ping testing purposes. +> - **IPSec**: Allow port `500` (UDP) for ISAKMP (Phase 1 negotiation). +> - **NAT Traversal**: Allow port `4500` (UDP) for NAT-T support in IPsec. +> - **WireGuard**: Allow port `51820` (UDP). +> - **OpenVPN**: Allow port `1194` (UDP or TCP). + +<figure> +<img src="/_static/images/cloud-aws-sg-02.webp" /> +</figure> + +- (Optional) Add tags to identify the security group: + - **Key**: <span class="title-ref">Name</span>, **Value**: <span class="title-ref">VyOS-Public-SG</span>. + +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-03.webp" /> +</figure> + +2\. Create Private Security Group +^^^^^^^^^^^^^^ + +The **Private Security Group** is used for **internal connectivity** from internal or VPC-based resources. + +- Open the **Amazon EC2 Console**. +- In the navigation pane, choose **Security Groups**. +- Choose **Create Security Group**. + +\- Configure the Security Group: +"""""""""" + +> - **Name**: `VyOS-Private-SG`. +> - **Description**: "Private security group for internal connectivity" +> - **VPC**: Select the VPC in which your VyOS instance resides. + +\- Inbound Rules: +"""""""""" + +> - Allow **All Traffic** (`0.0.0.0/0`) for internal connectivity between resources, VPCs, and other trusted networks. + +<figure> +<img src="/_static/images/cloud-aws-sg-04.webp" /> +</figure> + +- (Optional) Add tags to identify the security group: + - **Key**: `Name`, **Value**: `VyOS-Private-SG`. + +- Choose **Create Security Group**. + +<figure> +<img src="/_static/images/cloud-aws-sg-05.webp" /> +</figure> + +For detailed instructions on creating a security group, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/creating-security-group.html> + +For more information, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html> + +Step 3: Create ENIs (Elastic Network Interfaces) +----------- + +Network Interfaces (ENIs) are essential for connecting instances to subnets and managing network traffic. Follow the steps below to create **Public** and **Private** ENIs. + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. +- In the navigation pane, choose **Network Interfaces**. +- Choose **Create Network Interface**. +- **Configure Network Interface Settings**: + +# Public ENI + +> - **Name**: `VyOS-Public-ENI`. +> - **Description**: "Network Interface for Public Subnet." +> - **Subnet**: Select the `VyOS-Public-Subnet` you created earlier. +> - **Private IPv4 Address**: Choose **Auto-assign** to let AWS pick an IP address from the subnet. +> - **Security Group**: Select the `VyOS-Public-SG`. +> +> \- (Optional) Add tags to identify the ENIs: +> **Key**: `Name`, **Value**: `VyOS-Public-ENI`. +> +> - Choose **Create Network Interface**. +> +> <figure> +> <img src="/_static/images/cloud-aws-eni-01.webp" /> +> </figure> + +Private ENI +"""""""""" +- **Name**: `VyOS-Private-ENI`. + +> - **Description**: "Network Interface for Private Subnet." +> - **Subnet**: Select the `VyOS-Private-Subnet` you created earlier. +> - **Private IPv4 Address**: Choose **Auto-assign** to let AWS pick an IP address from the subnet. +> - **Security Group**: Select the `VyOS-Private-SG`. +> +> \- (Optional) Add tags to identify the ENIs: +> **Key**: `Name`, **Value**: `VyOS-Private-ENI`. +> +> - Choose **Create Network Interface**. +> +> <figure> +> <img src="/_static/images/cloud-aws-eni-02.webp" /> +> </figure> + +Step 4: Configure Internet Gateway +----------- + +An **Internet Gateway** allows communication between your VPC and the internet. Follow the steps below to create and attach an Internet Gateway to your VPC. + +1\. Create an Internet Gateway +^^^^^^^^^^^^^^ + +- Open the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. + +- In the navigation pane, choose **Internet Gateways**. + +- Choose **Create Internet Gateway**. + +- **Configure Internet Gateway**: + - (Optional) **Name**: Enter a descriptive name, e.g., `VyOS-IGW`. + +- (Optional) Add a tag to identify the Internet Gateway: + - **Key**: `Name`, **Value**: `VyOS-IGW`. + +- Choose **Create Internet Gateway**. + +<figure> +<img src="/_static/images/cloud-aws-igw-01.webp" /> +</figure> + +2\. Attach the Internet Gateway to Your VPC +^^^^^^^^^^^^^^ + +To enable your VPC to access the internet, attach the Internet Gateway to your VPC: + +- After creating the Internet Gateway, select it from the **Internet Gateways** list. + +- Choose **Actions \> Attach to VPC**. + +- Select the VPC where you want to attach the Internet Gateway: + - Choose <span class="title-ref">VyOS-VPC</span> (the VPC you created earlier). + +- Choose **Attach Internet Gateway**. + +<figure> +<img src="/_static/images/cloud-aws-igw-02.webp" /> +</figure> + +For more details, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html>. + +Step 5: Configure Route Tables +----------- + +Route tables define the paths for network traffic within your VPC. In this step, we will configure **Public** and **Private** route tables to control traffic flow for their respective subnets. + +1\. Create and Configure the Public Route Table +^^^^^^^^^^^^^^ + +- **Go to the Route Tables Section:** + - Open the **Amazon VPC Console** at <https://console.aws.amazon.com/vpc/>. + - In the left navigation pane, choose **Route Tables**. + +- **Create a New Route Table:** + + > - In the **Route Tables** section, choose **Create Route Table**. + > - Configure the route table: + > - **Name**: `Public RT`. + > - **VPC**: Select the `VyOS-VPC`. + > - Click **Create Route Table**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-01.webp" /> + > </figure> + +- **Add a Route to the Internet Gateway:** + + > - Go to the **Routes** tab and click **Edit Routes**. + > - Click **Add Route** and enter: + > - **Destination**: `0.0.0.0/0` (Default route to all IPs). + > - **Target**: Select the **Internet Gateway** (`VyOS-IGW`) you created earlier. + > - Click **Save Routes**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-02.webp" /> + > </figure> + +- **Associate the Public Subnet:** + + > - Go to the **Subnet Associations** tab and click **Edit Subnet Associations**. + > - Select the **Public Subnet** (`VyOS-Public-Subnet`). + > - Click **Save associations**. + > + > <figure> + > <img src="/_static/images/cloud-aws-route-03.webp" /> + > </figure> + +Step 6: Allocate and Attach Elastic IP (EIP) +----------- + +An **Elastic IP (EIP)** is a static, public IPv4 address designed for dynamic cloud computing. Elastic IP addresses can help maintain consistent connectivity to instances, even if they are stopped, rebooted, or replaced. + +- Elastic IP addresses are **public IPv4 addresses** and are reachable from the internet. +- They can be quickly remapped to different instances or network interfaces within your AWS account to mask failures. + +For more details, refer to the official AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html>. + +Steps to Allocate and Attach Elastic IP +^^^^^^^^^^^^^^ + +1\. Allocate Elastic IP +"""""""""" + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. + +- In the navigation pane, choose **Elastic IPs**. + +- Choose **Allocate Elastic IP address**. + +- **Elastic IP address settings**: + - For **Public IPv4 address pool**, select **Amazon's pool of IPv4 addresses**. + +- (Optional) Add a tag: + - **Key**: `Name`, **Value**: `VyOS-EIP`. + +- Choose **Allocate**. + +<figure> +<img src="/_static/images/cloud-aws-eip-01.webp" /> +</figure> + +2\. Attach Elastic IP to Public ENI +"""""""""" + +- Go to **EC2 \> Elastic IPs**. + +- Select the **Elastic IP** you just allocated. + +- Choose **Actions \> Associate Elastic IP address**. + +- **Configure Association**: + + > - **Resource type**: Choose **Network Interface**. + > - **Network Interface**: Select the **VyOS-Public-ENI** created earlier. + > - **Private IPv4 Address**: Ensure it is correctly selected. + +- (Optional) Select **Allow the Elastic IP address to be reassociated** if the EIP is already associated with another resource. + +- Choose **Associate**. + +<figure> +<img src="/_static/images/cloud-aws-eip-02.webp" /> +</figure> + +**Why Use Elastic IP?** + +- **Consistency**: The EIP remains static, even if the instance stops or is replaced. +- **Failover**: If an instance fails, you can remap the EIP to a new instance to restore services quickly. +- **DNS Integration**: You can point your domain to the Elastic IP for consistent public access. + +For additional details, refer to the AWS documentation: + +<https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-eips.html> + +Launch VyOS Instance +======== + +Follow the detailed instructions below to launch a VyOS instance in your AWS environment with two ENIs (Public and Private). + +- Open the **Amazon EC2 Console** at <https://console.aws.amazon.com/ec2/>. + +- In the EC2 dashboard, choose **Launch Instance**. + +- **Configure Instance Details**: + + > - **Name and Tags**: + > + > - Under **Name and tags**, enter a descriptive name for your instance, e.g., `VyOS-Instance`. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-01.webp" /> + > </figure> + > + > - **Application and OS Images (AMI)**: + > + > - Choose **Browse more AMIs**. + > - Go to the **AWS Marketplace** tab and search for **VyOS**. + > - Choose the VyOS AMI that matches your requirements and click **Select**. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-02.webp" /> + > </figure> + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-03.webp" /> + > </figure> + > + > - **Instance Type**: + > + > - Select the instance type that fits your workload. For example: + > - `c5n.large` (or larger recommended for VyOS). + > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-04.webp" /> + > > </figure> + > + > - **Key pair (login)**: + > + > - For **Key pair name**, select the key pair you created earlier (`vyos-keypair`). + > - If you do not have a key pair, create a new one and download the private key file. + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-05.webp" /> + > </figure> + > + > - **Network Settings**: + > + > - **VPC**: Select `VyOS-VPC`. + > - **Subnet**: Select the **Public Subnet** (`VyOS-Public-Subnet`). + > - **Auto-assign Public IP**: **Disable**. + > - **Firewall (security groups)**: Select the **Select existing security group**. + > - **Common security groups**: Live empty (Do not select any security groups). + > + > <figure> + > <img src="/_static/images/cloud-aws-vyos-09.webp" /> + > </figure> + > + > - **Advanced network configuration** + > + > > - **Network interface 1** select `VyOS-Public-ENI` + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-07.webp" /> + > > </figure> + > > + > > - Click to the **Add network interface** button + > > - **Network interface 2** select `VyOS-Private-ENI` + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-08.webp" /> + > > </figure> + > > + > > - In **Subnet** deselect subnet + > > + > > <figure> + > > <img src="/_static/images/cloud-aws-vyos-10.webp" /> + > > </figure> + +- Review the instance configuration in the **Summary** panel and choose **Launch Instance**. + +- Wait until the instance status changes to **Running**. + +<figure> +<img src="/_static/images/cloud-aws-vyos-11.webp" /> +</figure> + +Connect to the VyOS instance +----------- + +> You can only connect to the VyOS instance via **SSH** protocol. Use the default username **vyos**, **Elastic IP** and **SSH Key Pair** to connect to the VyOS instance via SSH: +> +> ``` none +> ssh -i vyos-keypair.pem vyos@35.152.131.62 +> ``` + +Deployment of VyOS Instance and Required Resources via CloudFormation Template +======== + +These CloudFormation templates automate the deployment of a VyOS instance on AWS, configuring essential components such as: + +- VPC +- Public and private subnets +- Internet Gateway +- Route Tables +- Elastic IPs +- Security Groups + +You can download or clone these templates from the GitHub repository and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/CloudFormation> + +Deployment of VyOS Instance and Required Resources via Terraform +======== + +These Terraform projects automate the deployment of a VyOS instance on AWS, configuring essential components such as: + +- VPC +- Public and private subnets +- Internet Gateway +- Route Tables +- Elastic IPs +- Security Groups + +You can download or clone these templates from the GitHub repository and use them in your environment: + +<https://github.com/vyos/vyos-automation/tree/main/Terraform/AWS/> + +## Amazon CloudWatch Agent Usage + +To use Amazon CloudWatch Agent, configure it within the Amazon SSM Parameter Store. If you don't have a configuration yet, do `configuration_creation`. + +1. Create an `IAM (Identity and Access Management)` role for the `EC2 (Elastic Compute Cloud)` instance to access CloudWatch service, and name it CloudWatchAgentServerRole. The role should contain two default policies: CloudWatchAgentServerPolicy and AmazonSSMManagedInstanceCore. +2. Attach the created role to your VyOS `EC2 (Elastic Compute Cloud)` instance. +3. Ensure that amazon-cloudwatch-agent package is installed. + +> ``` none +> $ sudo apt list --installed | grep amazon-cloudwatch-agent +> ``` +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The amazon-cloudwatch-agent package is normally included in VyOS 1.3.3+ and 1.4+ +> +> </div> + +3. Retrieve an existing CloudWatch Agent configuration from the `SSM (Systems Manager)` Parameter Store. + +> ``` none +> $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm:<your-configuration-name> +> ``` +> +> This step also enables systemd service and runs it. +> +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> The VyOS platform-specific scripts feature is under development. Thus, this step should be repeated manually after changing system image (`/installation/update`) +> +> </div> + +### CloudWatch SSM Configuration creation + +Creating the Amazon Cloudwatch Agent Configuration in Amazon `SSM (Systems Manager)` Parameter Store. + +1. Create an `IAM (Identity and Access Management)` role for your `EC2 (Elastic Compute Cloud)` instance to access the CloudWatch service. Name it CloudWatchAgentAdminRole. The role should contain at two default policies: CloudWatchAgentAdminPolicy and AmazonSSMManagedInstanceCore. + +> <div class="note"> +> +> <div class="title"> +> +> Note +> +> </div> +> +> CloudWatchAgentServerRole is too permissive and should be used for single configuration creation and deployment. That's why after completion of step \#3 highly recommended to replace instance CloudWatchAgentAdminRole role with CloudWatchAgentServerRole. +> +> </div> + +2. Run Cloudwatch configuration wizard. + +> ``` none +> $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard +> ``` + +3. When prompted, answer "yes" to the question "Do you want to store the config in the SSM parameter store?". + +## References + +- <https://console.aws.amazon.com/> +- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-iam-roles-for-cloudwatch-agent.html> +- <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance-fleet.html> diff --git a/docs/installation/cloud/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md new file mode 100644 index 00000000..4a77565d --- /dev/null +++ b/docs/installation/cloud/md-azure-ha.md @@ -0,0 +1,130 @@ +\########## +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> +<img src="/_static/images/cloud-azure-ha-architecture.webp" alt="VyOS HA topology diagram" /> +</figure> + +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 "<subscription ID or name>" +``` + +- Azure CLI installed: + + <https://learn.microsoft.com/en-us/cli/azure/install-azure-cli> + +- 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: + + <https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli> + +- 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@<vyos_public_ip> -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/md-azure.md b/docs/installation/cloud/md-azure.md new file mode 100644 index 00000000..8489a532 --- /dev/null +++ b/docs/installation/cloud/md-azure.md @@ -0,0 +1,449 @@ +\########## +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> +<img src="/_static/images/cloud-azure-rg-01.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-rg-02.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-vnet-01.webp" /> +</figure> + +**IP addresses**: + +- Address Space: `10.1.0.0/16` + +<figure> +<img src="/_static/images/cloud-azure-vnet-02.webp" /> +</figure> + +**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> +<img src="/_static/images/cloud-azure-vnet-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-azure-vnet-04.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-azure-vnet-05.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-sg-01.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-sg-02.webp" /> +</figure> + +**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> +<img src="/_static/images/cloud-azure-sg-03.webp" /> +</figure> + +**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> +<img src="/_static/images/cloud-azure-sg-04.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-pub-ip-01.webp" /> +</figure> + +- **Name**: `VyOS-Pub-IP` +- **IP Version**: `IPv4` +- **SKU**: `Standard` +- **Availability zone**: Select Availability Zone + +<figure> +<img src="/_static/images/cloud-azure-pub-ip-02.webp" /> +</figure> + +- **IP address assignment**: `Static` +- **Idle timeout (minutes)** `30` (max) + +<figure> +<img src="/_static/images/cloud-azure-pub-ip-03.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-vm-01.webp" /> +</figure> + +- **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> +<img src="/_static/images/cloud-azure-vm-02.webp" /> +</figure> + +- **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> +<img src="/_static/images/cloud-azure-vm-03.webp" /> +</figure> + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. +- **Public IP**: Select public IP address which created before `VyOS-Pub-IP`. + +<figure> +<img src="/_static/images/cloud-azure-vm-04.webp" /> +</figure> + +- **Configure network security group**: Select existing Security Group `VyOS-SecurityGroup`. + +<figure> +<img src="/_static/images/cloud-azure-vm-05.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-vm-06.webp" /> +</figure> + +- Wait until deployment is complete. After the deployment complete navigate to **Virtual Machines** click new created Virtual Machine. Check **Public IP address**. + +<figure> +<img src="/_static/images/cloud-azure-vm-07.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-vm-12.webp" /> +</figure> + +- Enable IP forwarding and click the **Apply** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-13.webp" /> +</figure> + +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. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Azure does not allow you attach interface when the instance in the +**Running** state. + +</div> + +Create network interface: +^^^^^^^^^^^^^^ + +- In the Azure Portal, search for and select **Network Interfaces**. +- On the **Network Interfaces** page, select **+ Create**. + +<figure> +<img src="/_static/images/cloud-azure-nic-01.webp" /> +</figure> + +- **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> +<img src="/_static/images/cloud-azure-nic-02.webp" /> +</figure> + +- Enable **IP Forwarding** +- Navigate to **Network Interfaces** select `VyOS-PRIV-NIC` + +<figure> +<img src="/_static/images/cloud-azure-nic-03.webp" /> +</figure> + +- Go to **Settings**, select **IP configurations**. Enable IP Forwarding and select **Apply**. + +<figure> +<img src="/_static/images/cloud-azure-nic-04.webp" /> +</figure> + +Attach reate network interface: +^^^^^^^^^^^^^^ + +- Navigate to **Virtual Machines**, click new created Virtual Machine and click the **Stop** button + +<figure> +<img src="/_static/images/cloud-azure-vm-08.webp" /> +</figure> + +- Go to **Networking** select **Network settings** and then select **Attach network interface** + +<figure> +<img src="/_static/images/cloud-azure-vm-09.webp" /> +</figure> + +- Select existing (before created) network interface `VyOS-PRIV-NIC` and click the **OK** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-10.webp" /> +</figure> + +- Now you have attached second interface to your instance and you can start Virtual Machine. +- Go to **Overview** and click the **Start** button. + +<figure> +<img src="/_static/images/cloud-azure-vm-11.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-route-01.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-route-02.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-azure-route-03.webp" /> +</figure> + +- 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> +<img src="/_static/images/cloud-azure-route-04.webp" /> +</figure> + +- **Virtual network**: Select `VyOS-VirtualNetwork`. +- **Subnet**: Select `VyOS-Public-Subnet`. + +<figure> +<img src="/_static/images/cloud-azure-route-05.webp" /> +</figure> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +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/md-gcp.md b/docs/installation/cloud/md-gcp.md new file mode 100644 index 00000000..b30d6494 --- /dev/null +++ b/docs/installation/cloud/md-gcp.md @@ -0,0 +1,298 @@ +\##################### +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" +> ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +2. Open GCP console and navigate to the **Compute Engine** \> **Metadata** \> **SSH Keys**. Choose + **SSH Keys**. + +<figure> +<img src="/_static/images/cloud-gcp-01.webp" /> +</figure> + +3. Click **edit** and **Add item**. +4. Paste your public ssh key and **Save**. + +<figure> +<img src="/_static/images/cloud-gcp-02.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-svc.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vpc-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-02.webp" alt="Private VPC:" /> +<figcaption><strong>Private VPC</strong>: +<ul> +<li>Name: <code>vyos-private-vpc</code></li> +<li>Subnet creation mode: <code>Custom</code></li> +<li>Subnet name: <code>vyos-private-subnet</code></li> +<li>Region: e.g., <code>europe-west1</code></li> +<li>IP range: <code>10.0.11.0/24</code></li> +<li>Leave all other settings at default, then click <strong>Create</strong>.</li> +</ul></figcaption> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-03.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-04.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vpc-05.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-06.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vpc-07.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-proj.webp" /> +</figure> + +3. In the search bar, type `vyos` to find the VyOS image in the Marketplace. + +<figure> +<img src="/_static/images/cloud-gcp-market-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-market-02.webp" /> +</figure> + +4. On the next page, review details such as support, pricing, and other details. + +<figure> +<img src="/_static/images/cloud-gcp-market-03.webp" /> +</figure> + +5. Click the `GET STARTED` button to start deployment process. + +<figure> +<img src="/_static/images/cloud-gcp-market-04.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-market-05.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vm-01.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vm-02.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vm-03.webp" /> +</figure> + +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: + +<https://docs.vyos.io/en/stable/automation/cloud-init.html#module-vyos-userdata> + +<figure> +<img src="/_static/images/cloud-gcp-vm-09.webp" /> +</figure> + +9. Click `Deploy` button. + +<figure> +<img src="/_static/images/cloud-gcp-vm-06.webp" /> +</figure> + +<figure> +<img src="/_static/images/cloud-gcp-vm-07.webp" /> +</figure> + +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> +<img src="/_static/images/cloud-gcp-vm-08.webp" /> +</figure> + +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 new file mode 100644 index 00000000..1c1e1ed6 --- /dev/null +++ b/docs/installation/cloud/md-index.md @@ -0,0 +1,13 @@ +# Running VyOS in Cloud Environments + +<div class="toctree" caption="Content"> + +aws +aws-ha +azure +azure-ha +aws-to-azure +gcp +oracle + +</div> diff --git a/docs/installation/cloud/md-oracel.md b/docs/installation/cloud/md-oracel.md new file mode 100644 index 00000000..9ed07ff9 --- /dev/null +++ b/docs/installation/cloud/md-oracel.md @@ -0,0 +1,5 @@ +# Oracle + +## References + +<https://www.oracle.com/cloud/> |