########## Amazon 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:: /_static/images/cloud-aws-keypair-01.png - 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:: /_static/images/cloud-aws-keypair-02.png - Configure Key Pair: """""""""" - **Name**: Enter a descriptive name for the key pair, e.g., ``vyos-keypair``. .. note:: The key name can include up to 255 ASCII characters. It cannot include leading or trailing spaces. - **Select Key Pair Type**: - For **Linux instances**: Choose either **RSA** or **ED25519**. - For **Windows instances**: Choose **RSA**. .. note:: ED25519 keys are not supported for Windows instances. - **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., `vyos-keypair.pem`), with the extension determined by the format you chose. .. figure:: /_static/images/cloud-aws-keypair-03.png .. figure:: /_static/images/cloud-aws-keypair-04.png **Important Notes** - **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: .. code-block:: 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** .. code-block:: none ssh -i vyos-keypair.pem vyos@ 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:: /_static/images/cloud-aws-vpc-01.png - **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:: /_static/images/cloud-aws-vpc-02.png .. figure:: /_static/images/cloud-aws-vpc-03.png 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:: /_static/images/cloud-aws-subnet-01.png - 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:: /_static/images/cloud-aws-subnet-02.png .. figure:: /_static/images/cloud-aws-subnet-03.png 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:: /_static/images/cloud-aws-sg-01.png - **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:: /_static/images/cloud-aws-sg-02.png - (Optional) Add tags to identify the security group: - **Key**: `Name`, **Value**: `VyOS-Public-SG`. - Choose **Create Security Group**. .. figure:: /_static/images/cloud-aws-sg-03.png 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:: /_static/images/cloud-aws-sg-04.png - (Optional) Add tags to identify the security group: - **Key**: ``Name``, **Value**: ``VyOS-Private-SG``. - Choose **Create Security Group**. .. figure:: /_static/images/cloud-aws-sg-05.png 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:: /_static/images/cloud-aws-eni-01.png 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:: /_static/images/cloud-aws-eni-02.png 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:: /_static/images/cloud-aws-igw-01.png 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 `VyOS-VPC` (the VPC you created earlier). - Choose **Attach Internet Gateway**. .. figure:: /_static/images/cloud-aws-igw-02.png 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:: /_static/images/cloud-aws-route-01.png - **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:: /_static/images/cloud-aws-route-02.png - **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:: /_static/images/cloud-aws-route-03.png 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:: /_static/images/cloud-aws-eip-01.png 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:: /_static/images/cloud-aws-eip-02.png **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:: /_static/images/cloud-aws-vyos-01.png - **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:: /_static/images/cloud-aws-vyos-02.png .. figure:: /_static/images/cloud-aws-vyos-03.png - **Instance Type**: - Select the instance type that fits your workload. For example: - ``c5n.large`` (or larger recommended for VyOS). .. figure:: /_static/images/cloud-aws-vyos-04.png - **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:: /_static/images/cloud-aws-vyos-05.png - **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:: /_static/images/cloud-aws-vyos-09.png - **Advanced network configuration** - **Network interface 1** select ``VyOS-Public-ENI`` .. figure:: /_static/images/cloud-aws-vyos-07.png - Click to the **Add network interface** button - **Network interface 2** select ``VyOS-Private-ENI`` .. figure:: /_static/images/cloud-aws-vyos-08.png - In **Subnet** deselect subnet .. figure:: /_static/images/cloud-aws-vyos-10.png - Review the instance configuration in the **Summary** panel and choose **Launch Instance**. - Wait until the instance status changes to **Running**. .. figure:: /_static/images/cloud-aws-vyos-11.png 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: .. code-block:: 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 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 :ref:`configuration_creation`. 1. Create an :abbr:`IAM (Identity and Access Management)` role for the :abbr:`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 :abbr:`EC2 (Elastic Compute Cloud)` instance. 3. Ensure that amazon-cloudwatch-agent package is installed. .. code-block:: none $ sudo apt list --installed | grep amazon-cloudwatch-agent .. note:: The amazon-cloudwatch-agent package is normally included in VyOS 1.3.3+ and 1.4+ 3. Retrieve an existing CloudWatch Agent configuration from the :abbr:`SSM (Systems Manager)` Parameter Store. .. code-block:: none $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm: This step also enables systemd service and runs it. .. note:: The VyOS platform-specific scripts feature is under development. Thus, this step should be repeated manually after changing system image (:doc:`/installation/update`) .. _configuration_creation: CloudWatch SSM Configuration creation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Creating the Amazon Cloudwatch Agent Configuration in Amazon :abbr:`SSM (Systems Manager)` Parameter Store. 1. Create an :abbr:`IAM (Identity and Access Management)` role for your :abbr:`EC2 (Elastic Compute Cloud)` instance to access the CloudWatch service. Name it CloudWatchAgentAdminRole. The role should contain at two default policies: CloudWatchAgentAdminPolicy and AmazonSSMManagedInstanceCore. .. note:: 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. 2. Run Cloudwatch configuration wizard. .. code-block:: 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