From 88957530a3e174bfc61e8358cb2b28fd8f1fbbb6 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 18:46:21 +0300 Subject: feat: import MyST swap mechanism + content for sagitta (replaces #1886) Replaces the broken #1886 with a fresh, properly-converted MyST set for the sagitta (1.4.x) docs, mirroring what landed for circinus via #1897. This PR: - Re-imports 210 md-*.md files for sagitta. Source: ran the pipelines rst-to-myst converter (chrisjsewell/rst-to-myst v0.4.0, with pandoc fallback) on sagittas RST. Post-processed via the pipelines postprocess stage (10 ordered fixes for blanks, admonitions, label hyphens, pandoc artifacts, structural blanks, linter markers). Compared to the broken #1886 content (which was left over from an earlier stage-1-only run): zero raw `
` remnants. - For 23 stems where sagittas RST is byte-identical with currents RST (mostly stable policy/protocol pages and the 404 page), reuses currents already-validated md-*.md content rather than re-converting. - Drops cli and installation/cloud/aws from sagittas swap set: their RST has SEVERE/4 "Title level inconsistent" errors that crash rst-to-myst; they need an independent RST-source fix and are kept as RST-only for now. - Adds the per-page swap mechanism: scripts/swap_sources.py, scripts/import_myst.py, the matching tests under tests/, _swap.txt with 210 stems, _ext/vyos.py MyST renderer fallback, Makefile swap-wrapped targets, .readthedocs.yml swap pre/post hooks. - Adds 187 .webp images and removes 235 superseded .jpg/.png/.jpeg static assets; flips html_logo to vyos-logo.webp. - Adds the MyST swap-related blocks to docs/conf.py only: myst_enable_extensions, myst_fence_as_directive, md-*.md exclude patterns, _swap_exclude.txt reader, _prefer_webp and _copy_md_sources setup hooks. github_version fallback set to 'sagitta' to match the branch (parallel to currents 'current' and circinuss 'circinus'). Deliberately excluded (per user direction): - llms.txt and sphinx-llms-txt / sphinx-sitemap config: these will land separately for sagitta via #1870 plus a new sagitta-specific llms.txt template PR. The conf.py here does not pull those extensions in, so the build does not depend on the new pip packages. Verification before pushing: - 210 md-*.md = 210 _swap.txt stems = 210 RST siblings on sagitta (1:1:1). - 0 files contain raw `
+- 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 new file mode 100644 index 00000000..246df5f3 --- /dev/null +++ b/docs/installation/cloud/md-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/md-azure-ha.md b/docs/installation/cloud/md-azure-ha.md new file mode 100644 index 00000000..fa94c222 --- /dev/null +++ b/docs/installation/cloud/md-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/md-azure.md b/docs/installation/cloud/md-azure.md new file mode 100644 index 00000000..aa577aa1 --- /dev/null +++ b/docs/installation/cloud/md-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/md-gcp.md b/docs/installation/cloud/md-gcp.md new file mode 100644 index 00000000..7144f083 --- /dev/null +++ b/docs/installation/cloud/md-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/md-index.md b/docs/installation/cloud/md-index.md new file mode 100644 index 00000000..f64883fc --- /dev/null +++ b/docs/installation/cloud/md-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/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 + + -- cgit v1.2.3