Streaming Gateway Appliance on AHV

The Nutanix Frame Streaming Gateway Appliance (SGA) is a secure reverse proxy that supports the Frame Remoting Protocol (FRP). The SGA allows organizations to securely grant users access to virtualized applications and/or desktops without requiring a VPN. This guide is intended for customers using Frame on Nutanix Acropolis Hypervisor (AHV) infrastructure wishing to install and configure the SGA on their AHV cluster. The document assumes that the customer has an established Frame customer or organization entity with a registered AHV Cloud Account, and at least one existing Frame account on the AHV cluster.

SGA Network Architecture

To deploy an SGA, the company’s network must allow Internet traffic to reach the SGA VM in the DMZ on tcp/443 (HTTPS and Secure WebSockets) and from the SGA VM to the workload VLAN containing the Frame-managed workloads (e.g., Sandbox, production pools, Utility Servers). This is illustrated in the following diagram:

../../_images/SGA_diagram.png

Please consult the network protocol and port summary for SGA on AHV to ensure that network routing requirements are satisfied before continuing.

Prerequisites

The following prerequisites must be met before starting SGA installation and configuration:

  1. Download the Frame SGA for AHV ISO from the Nutanix portal. This ISO is intended only Frame accounts using AHV infrastructure.
  2. Import the ISO into the Prism Central Image Service, as the SGA VM will be on an AHV cluster.
  3. Download the YAML configuration file template.

Overview

Setting up a Streaming Gateway Appliance on a Frame account consists of 6 major steps to be performed by the customer. A 7th step is performed by Nutanix Support to finalize the setup.

Step 1 Define the subdomain name (e.g., sga.company.com) and corresponding public IP address for the SGA.
Step 2 Obtain the SGA public key certificate.
Step 3 Paste the Certificate Bundle (SGA certificate, Intermediate Certificate Authority (CA) certificate, and then Trusted Root CA certificate), SGA private key, FQDN, and CIDR into SGA YAML template file.
Step 4 Create the SGA VM with the Nutanix Frame SGA ISO and YAML file in the DMZ.
Step 5 Configure the firewall (including NAT if required) and routing to enable HTTPS requests from the Internet to reach the SGA VM, and traffic originating from the SGA VM to reach the workload VLAN containing the Frame-managed workloads.
Step 6 Add the SGA subdomain as a wildcard DNS entry with the corresponding public IP address to the public DNS server.
Step 7 Nutanix Support configures the Frame Platform entry for the SGA subdomain for the Frame account.

Installation and Configuration

Step 1: Define the SGA subdomain and corresponding public IP address

End users’ browsers must be able to reach the SGA from the Internet. Since the SGA will be deployed behind your organization’s firewall, the end users’ HTTPS requests and Secure WebSocket connections (for streaming) must be able to resolve to a public IP address on the your organization’s firewall. From that public IP address on your organization’s firewall, the request would need to be forwarded to the private IP address of the SGA and then from the SGA to the workload VMs.

Each Frame-managed workload VM will have an FQDN based the SGA subdomain. Consequently, the SGA subdomain will need to be configured as a wildcard DNS A record. For example, a company would need to make sure that:

  1. *.sga.company.com resolves to the public IP of the SGA.
  2. The public IP address of the SGA is network address-translated to the private IP address of the SGA by the firewall.

Step 2: Obtain an SGA public key certificate

Generate the wildcard SSL certificate signing request and corresponding private key for the subdomain chosen in the previous step. If this SGA is intended for use in a production environment, please obtain a public wildcard certificate or Subject Alternate Name (SAN) certificate from the certificate authority of your choice, such as LetsEncrypt.

Warning

Be aware that Let’s Encrypt limits their certificates to ninety-day lifetimes.

The SSL certificate must match the DNS subdomain record. For example, if the wildcard SSL certificate is *.sga.company.com, then the DNS subdomain record must be sga.company.com (and not company.com).

Step 3: Prepare the YAML Configuration File

Danger

This configuration file contains the private key of your wildcard certificate, do not use online YAML validation tools. To safely validate your YAML file, use the methods listed below.

The YAML configuration file is used by Prism Central to configure the VM during the SGA VM creation. Formatting and indentation are very important. Copy the YAML Configuration File Template and edit the renamed file only in the following areas:

  • The certificate (Trusted Root, Intermediate, and Wildcard Certificate)
  • The private key
  • The public Fully Qualified Domain Name (FQDN) of the SGA that resolves in public DNS. (Example: sga.company.com)
  • The workload CIDR from the Frame Account (Example: 172.31.21.0/24)

Please validate the YAML file before loading the file into the SGA VM using Prism Central. Pay attention to the text left padding (8 spaces only) and the validity of the Workload VLAN CIDR range. Your Streaming Gateway Appliance will not function correctly if any of the four items listed above are incorrect. Refer to the YAML File Validation section for additional information on how to validate the YAML configuration file.

YAML Configuration File Template

See the areas highlighted in yellow.

../../_images/YAML_example.png

Step 4: SGA VM Creation

Upon editing the YAML configuration file with the appropriate formatting, follow the setup tasks below to configure the Streaming Gateway Appliance.

Description Example User Interface
  1. Create Virtual Machine: In Prism Central, create a new Virtual Machine and use UTC time zone.
vm_ahv1
  1. Configure Compute Details: SGA VMs should have at least two (2) vCPUs and 4GB RAM. This configuration should support up to 500 concurrent user sessions.
vm_ahv2
  1. ISO: Insert the SGA ISO into the VM’s CD-ROM drive.
vm_ahv3
  1. Disk: Create a 0.1 GB disk.
vm_ahv4
  1. Network Interface: Assign the appropriate VLAN to the new VM.
vm_ahv5
  1. Use the YAML file you created and validated: Enable Custom Script option and either upload your YAML file or paste it in. The certificates within your YAML file will be loaded into SGA once the VM is created.
vm_ahv6
  1. Save the VM and Create: Save the VM and Prism Central will create the VM using the SGA ISO.
vm_ahv7
  1. Power on the VM and configure a Static IP Address: Once Prism Central notifies you that the SGA VM has been created, power on the SGA. Open the VM console and the display will look similar to the example on the right. Log in to the SGA with the username netconfig (no password).
vm_ahv8
  1. Set the static IP address: Specify the address manually. Be sure to add the /24 at the end of the IP address.
vm_ahv9

Step 5: Configure Routing to the Workload VMs via the SGA

To ensure external users can reach the SGA and therefore the workload VMs in the private VLAN, verify the following:

  1. The firewall should be configured to forward port 443 from your SGA public IP address to the SGA private IP address.
  2. The VLAN that contains the SGA must forward port 443 from the SGA to the workload VLAN.

Step 6: Add SGA subdomain and associated public IP address in public DNS

Create an address (A) record in your public Domain Name Server associating your SGA subdomain with your SGA public IP address.

../../_images/step6_dns.png

Step 7: Submit a Support Case

To associate your Frame account(s) with your SGA, submit a support case through the Nutanix Support Portal. Provide the following information in the support ticket:

  • Customer name
  • Organization name
  • Account name(s)
  • Wildcard subdomain
  • SGA public IP address

SGA Sizing Recommendations

As stated previously, organizations can start with a VM configuration of 2 vCPUs and 4 GB RAM for the SGA. A 2 vCPU VM is able to process ~1 Gbps bandwidth of Frame Remoting Protocol data. Nutanix recommends a sizing target of 500 Mbps per 2 vCPUs to allow users to burst their bandwidth consumption.

The total number of concurrent users for the 500 Mbps bandwidth per 2 vCPU budget is dependent on the bandwidth consumed for the Frame sessions. Bandwidth consumption may be estimated based on user workload profiles:

  • 1 Mbps per Frame session for office productivity applications, CPU-only VMs, under 30 fps, 2K or less monitors
  • 5 Mbps per Frame session for CAD applications, GPU-backed VMs, up to 60 fps, 2K or less monitors
  • 10 Mbps or greater per Frame session for video editing/animation/sustained playback, GPU-backed VMs, up to 60 fps, 2K or less monitors

In an office productivity use case, for example, where CPU-only VMs are used with standard 1920 x 1080 displays, the default (2 vCPU, 4 GB RAM) VM configuration could support 500 concurrent users. For 1,000 concurrent users, the same organization would need to leverage at least a 4 vCPU, 8 GB RAM VM. An 8 vCPU, 16 GB RAM VM could support 2,000 concurrent users for this use case.

Frame also supports smaller network CIDR blocks to segment Frame accounts. For more information, please contact Frame Solutions Architecture.

SGA High-Availability

../../_images/SGA_diagram3.png

The SGA can be configured for redundancy using a L2 to L4 load balancing solution. The recommended solution is comprised of two (2) Load Balancers, physical or virtual, creating a single inbound load balancer virtual IP address (LBVIP) balancing two (2) Streaming Gateway Appliances. The load balancing solution must have the following configured:

  • SSL Passthrough
  • Persistent Traffic to LBVIP1 or LBVIP2
  • Wildcard DNS entry to LBVIP

User Flow Example:

A Frame user logs in to the Frame Platform via their normal method. When the user clicks the desktop or application requested, Frame Platform directs the user’s browser to an FQDN based on the SGA subdomain, as configured by Nutanix Frame Support, for the Frame account.

For example, if the subdomain was sga.company.com and the workload VM had a private IP address of 10.2.1.3, the workload FQDN would be 10-2-1-3.sga.company.com. This FQDN points to the inbound LBVIP and the Application Load Balancer decides which SGA to send the traffic to.

Troubleshooting

Troubleshooting the SGA on AHV infrastructure should be started by assessing the public side of the solution, then moving to the SGA command line interface (CLI) to assess traffic flow from the SGA to the Frame workload VMs.

../../_images/SGA_AHV_troubleshooting.png

From the public Internet, verify the following to isolate the issue between user’s browser and company SGA:

  • Wildcard DNS points to the same FQDN as the Wildcard Certificate

    • Example: *.sga.company.com
  • Check the SGA certificate chain validates properly.

    • <Trusted, Intermediate, Server Certificate>
  • Is the SGA reachable at https://<anyhost>.sga.company.com>/index.html?

    • You should receive an HTTP Internal Server Error 500.

To verify that HTTPS/Secure WebSocket traffic is working properly from the SGA to the Frame workload VMs, login to SGA with the username:

  • Username: nutanix
  • Password: nutanix/4u

Then, on the command line:

  • Verify ngnix is running: sudo systemctl status nginx

  • Verify selinux is logging: sudo journalctl xte

    • If selinux is not running, execute the following to start it:
    sudo audit2allow -a -M nginx_allow
    sudo semodule -I nginx_allow.pp
    
  • Determine if SGA can reach the Frame Guest Agent by executing:

curl -k https://IP_OF_WORKLOAD/api/mf2/v2/common/SetInstanceData

Verify that the workload VMs are responding to tcp/443 by:

ping IP_OF_WORKLOAD

and

telnet IP_OF_WORKLOAD 443

YAML File Validation

To validate that you have a correctly formatted YAML file, you can use Ruby or Python on your local machine.

Danger

This configuration file contains the private key of your wildcard certificate, do not use online YAML validation tools. To safely validate your YAML file, use the methods listed below.

Ruby

If you have Ruby, running the command below will validate your YAML file. In this example, assuming you saved the YAML file as “config.yaml”:

ruby -ryaml -e "p YAML.load(STDIN.read)" < config.yaml

If you do not receive an error, your YAML file is correct. If you do receive an error, the output will tell you where the mistake is. For example:

(<unknown>): mapping values are not allowed in this context at line 2 column 8 (Psych::SyntaxError)

Python

If you have Python, you can verify your YAML file with Python with the following methods:

First, you need to install the Python YAML library. This is done via pip, and all Python versions greater than 2.7.9 have pip by default. Install the YAML library by running:

pip install pyyaml

From there, you can verify you have a correctly formatted YAML configuration with:

python -c 'import yaml, sys; print(yaml.safe_load(sys.stdin))' < config.yaml

There is another tool you can use called “yamllint.” Install yamllint by running:

pip install --user yamllint

Once installed, run:

yamllint my_file.yml