Streaming Gateway Appliance on Public Cloud Infrastructure

Warning

SGA 2 will be deprecated by the end of 2022. Nutanix Frame strongly recommends using SGA 3 in your network configuration. SGA 2 documents are still available for reference, however, customers using SGA 2 should plan to move to SGA 3 in the near future.

This guide is intended for customers who wish to manually install and configure the SGA in public cloud infrastructure.

For customers who are using public cloud infrastructure, best practice is to use the Create Frame Account with Private Networking and SGA feature to automatically provision a Frame account with private networking and SGA. This eliminates the need for the customer to manage the SGA DNS record and certificate lifecycle. Refer to the step by step documentation for further details.

Note

If you wish to leverage the same SGA VM(s) for more than one Frame account, use an existing load balancer, or have users within your private network who need to access the workloads in a Frame account configured for a private network with an SGA for external use, manual SGA deployment is required.

Note

Before an SGA can be deployed, the customer must have an established Frame customer or organization entity with a registered public cloud account or AHV Cloud Account, plans to deploy the SGA in a DMZ network on public cloud infrastructure, and has at least one existing Frame account already created.

Prerequisites

The following prerequisites must be met before starting SGA installation and configuration on public cloud infrastructure:

  1. You have a working Frame account with at least one production pool of VMs in a workload network (e.g., VPC, VNET, or VLAN). The workload network has a non-overlapping CIDR block for routing between the SGA network and the workload network.

  2. You have have configured the SGA network with a non-overlapping CIDR block.

  3. Download the nginx.conf.j2 and gen_proxy_config.py.

  4. If you plan on using SGA for VM access with Frame, workload VLANs configured for those VMs must use a CIDR between /18 and /24.

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

If no DMZ network exists, create a separate DMZ network with a non-overlapping DMZ CIDR block for the SGA VM(s).

Step 4

Create and configure the SGA VM(s) in the DMZ network.

Step 5

Configure the firewall (including NAT if required) and routing to enable HTTPS requests from the Internet to reach the SGA VM(s) in the DMZ network, and traffic originating from the SGA VM(s) to reach the workload network 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.

Warning

Do not use the company domain as the SGA domain (e.g., company.com) and the company wildcard certificate (e.g., *.company.com) for the SGA certificate.

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. If the SGA is to be used for testing or a proof of concept environment, a free public wildcard certificate can be obtained from LetsEncrypt

Warning

Be aware that free Let’s Encrypt certificates have a 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 A record must be *.sga.company.com (and not company.com).

Step 3: Create the DMZ network

If a DMZ network does not exist, then create a network (e.g., VPC, VNET, or VLAN) that will contain the SGA VM(s). The CIDR block must not overlap with the Frame workload network CIDR block (and any other CIDR blocks that traffic is to route to).

Note

The CIDR must be between /18 and /24

Step 4: SGA VM Creation

Follow the setup tasks below to configure the Streaming Gateway Appliance.

Step

Description

Details

1

Create a CentOS Virtual Machine:

For public cloud infrastructure, CentOS images can be obtained from AWS, Azure or Google Cloud Platform Marketplace/Store. Be sure to accept the CentOS 7.x User Agreement, if required by the public IaaS provider, before provisioning the CentOS virtual machine.

2

Enable SSH access:

Customer enables SSH access in the CentOS VM in order to reach the SGA console. Consult with AWS, Azure, or GCP documentation on how to enable SSH access to the CentOS VM.

3

Upload files:

Upload the following files into the CentOS VM in the /home/<user> directory:

  • SSL certificate chain (SSL certificate, Intermediate CA certificate, and Root CA certificate) in .crt format

  • SSL private key in .key format

  • nginx.conf.j2

  • gen_proxy_config.py - Make sure gen_proxy_config.py is executable (chmod 755).

4

Install epel-release, nginx, dnsmasq, python, iptables and jinja:

Execute the following commands on the command line:

## setup nginx
sudo yum install epel-release
sudo yum install nginx
sudo systemctl start nginx
sudo systemctl enable nginx
sudo yum -y upgrade
sudo yum -y install epel-release
sudo yum -y install nginx

## setup dnsmasq
sudo yum -y install dnsmasq

## setup python env
sudo yum install python-pip
sudo pip install --upgrade pip
sudo pip install ipaddress
sudo pip install jinja2

5

Configure NGINX:

Execute the following commands on the command line to configure NGINX.

## Customer copies Certificate bundle and key from /home directory:
sudo cp /home/<user>/customer.crt /opt/server.crt
sudo cp /home/<user>/customer.key /opt/server.key

## Customer copies nginx.conf.j2 in /home directory to new /etc/nginx/nginx.conf:
cp /home/<user>/nginx.conf.j2 /etc/nginx/nginx.conf
chmod 644 /etc/nginx/nginx.conf

6

Configure dnsmasq:

Update the specific properties in the configuration file /etc/dnsmasq.conf as follows:

conf-dir=/etc/dnsmasq.d
interface=lo
bind-interfaces

Enable dnsmasq on the command line:

## Enable dnsmasq using systemctl
systemctl enable --now dnsmasq

7

Disable SELinux:

Edit /etc/sysconfig/selinux to disable SELinux.

## Disable SELinux
sudo vi /etc/sysconfig/selinux

and add SELINUX=disabled to the configuration file. Be sure to reboot the VM.

8

Configure SGA:

Execute the following two commands to configure SGA and restart NGINX. Make sure that the CIDR corresponds to the Frame account network CIDR.

sudo cd /home/<user> && ./gen_proxy_config.py --domain sga.company.com --cidr 10.0.1.0/24 > /etc/nginx/nginx.conf
sudo systemctl restart nginx

## Verify that nginx is now running
systemctl status nginx

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 network, 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 network that contains the SGA must forward port 443 from the SGA to the workload network.

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

Note

If you wish to have users within your private network access the Frame workloads behind your SGA, you should configure your internal DNS servers to resolve your SGA subdomain to your SGA private IP address.

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

Troubleshooting

Troubleshooting the SGA 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 the SGA VM:

  • 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 the SGA and:

  • Verify nginx is running: sudo systemctl status nginx

  • Determine if SGA can reach the Frame Guest Agent by executing the following steps:

    • Acquire the local IP address of the Sandbox VM.

    • Go to Frame Dashboard and start a session on the Sandbox.

    • Within 120 seconds after starting the session, execute on the Linux command line in the SGA VM the following:

curl -k https://IP_OF_WORKLOAD/

The reason for executing this sequence of steps is that Frame Guest Agent actively listens on port 443 only while Frame Guest Agent is waiting for a user to connect to the workload VM after the user’s browser has been redirected to the designated workload VM.