Deploying Unreal Engine Pixel Streaming on Azure

Unreal Pixel Streaming is an Azure Marketplace offering, built by Microsoft in collaboration with Epic, that allows Azure subscribers to deploy and stream their UE app from remote GPU-enabled virtual machines ("VMs"). The solution takes a single .zip file of your packaged application and spins up anywhere from one to thousands of VM instances across multiple regions, providing a way for you to set up an auto-scaling deployment accessed through a single URL. This tutorial provides a step-by-step guide to deploying your first Pixel Streaming project on Azure.

Prerequisites

Azure Account and Subscription

You need an Azure account and at least one subscription for which you have the permissions to create resources. For information on creating a new subscription, refer to this guide. Subscriptions also require that you have a billing account set up.

Azure VM Quotas

Azure subscriptions have a limit for how many VM resources can be used at once, called Quotas. Follow Microsoft's documentation to make sure you have a sufficient quota for your desired VM family in each region you wish to deploy to.

The quota you need for the default configuration is Standard NVSv3 Family vCPUs, and each NV12s_v3 instance you use requires 12 vCPUs. For example, if you want 2 instances running in East US and 2 instances running in North Europe, you need to request a quota increase for 24 vCPUs for this family in both regions.

Packaging a Pixel Streaming Application

This Azure solution can only be used in conjunction with an existing Pixel Streaming application you have created. Make sure you've followed the Getting Started documentation and tested your app locally before proceeding to a cloud deployment.

By default, this solution will completely override all the web server files in your Samples folder. If you have made customizations to the webpage or servers, make sure you have downloaded the Azure modifications and merged your changes according to the included README.txt file before proceeding.

Once you have a packaged Pixel Streaming application, compress the entirety of the Windows folder in to a .zip file.

Using the Azure Portal and the Azure Marketplace

1. Log into your Azure account

2. The Unreal Pixel Streaming offer is hosted on the Azure marketplace. Navigate to the offer page here.

3. Sign in to the Azure Marketplace using the button at the top right. Use the same account you use for all other Azure services.

4. Click Get It Now below the Unreal Engine icon. You also can use the heart icon to save it to your favorites for later.

5. A dialog pops up asking you to confirm your information and add this app to your account. Fill it out and click Continue.

6. The Azure Portal will open to the Unreal Pixel Streaming product in your account. From here click on Create to begin the process of configuring your deployment.

Basics

The first tab of the creation page covers the essentials for the Pixel Streaming deployment, like subscription details, instance type, and uploading your application.

1. In the Basics tab, first choose the Subscription and an empty Resource Group where the global resources will be deployed to, like a Traffic Manager, Key Vault, and Admin Dashboard. You may need to use the Create new button.

2. Select your primary Region for the global resources. Then you may choose an instance size for both the matchmaker VMs and UE App VMs. This template defaults to the recommended sizes.

   Before continuing, check that you have the proper quota for the selected GPU VM size in your subscription as mentioned above. If you don't have a sufficient quota, this deployment will fail and you may need to start over.

3. Next, you must upload your zipped up Pixel Streaming app. Use the Browse button to open the Storage Accounts for your selected subscription.

   If you don't yet have a storage account, you can add one using the + Storage Account button at the top. Give it a Name, a Location, a new Resource Group, and click OK. After a few moments, your new storage account should be available in the list. Select a listed storage account to open it.

4. Any files you want to upload to an Azure storage account must go into a Container. If you do not have a container yet, you can add one using the + Container button at the top. Give it a Name and click Create. Select a container from the list to open it.

5. Inside the selected container, click the Upload button at the top and use the folder icon to browse for the .zip file of your application, then click Upload. Depending on project size and network bandwidth, the upload could take several minutes to finish.

   Once the app is finished uploading, select the file in the container and click Select.

6. If you have made custom modifications to the Matchmaker or Signalling server according to the included instructions, make sure to check the box below the prompt.

7. Lastly, set a username and password for the VMs. These credentials are used if you enable remote desktop on the instances, which can be helpful for debugging issues.

   If you're finished with the basics tab, click on Next : Scale.

Scale

This tab is where you specify the size and scope of your deployment. With Unreal Pixel Streaming on Azure, an app can automatically be set up to run on many instances in multiple regions around the world.

1. In the dropdown next to Select regions to deploy, choose up to 4 regions to deploy your UE app. Users who are connecting to your web URL will be directed to their nearest region (by lowest ping), so think about where users are most likely going to be located.

   Keep in mind that each region has its own VM quota that you need to manage ahead of time, as described above, or else the deployment will fail.

2. GPU VM Instances Per Region controls how many virtual machines get launched in the selected regions. If Auto-scaling is enabled as described below, this number will go up or down based on demand.

   Streams Per GPU VM is how many instances of the UE app are running on each VM, and is limited to 4. If your application is lightweight or doesn't require a high frame rate, sharing a GPU like this can be a good way to minimize cost. In general, sharing the VM resources between multiple running apps will have a negative impact on frame rates.

3. There is an option called Run with Azure Spot discount. Using spot instances provides significant cost savings by leveraging unused virtual machines at the tradeoff of not guaranteeing uninterrupted service. It can be a good option for testing or cost cutting, but VMs may be "evicted" at any time based on a number of settings you can learn more about.

4. Enabling Auto-scaling allows this deployment to spin up more GPU instances as more users are attempting to connect to your application, and spin them down when there are too many instances running idle. If you want a constant number of available instances, you can disable this feature. Review the options below before clicking Next : Stream Configs.

   Refer to the following table for information about the available scaling parameters.

Wrapping Up

1. In the Stream Configs tab, you can adjust the resolution and frame rate of your app. This can be helpful if you're optimizing for 2 streams per GPU.

2. In the Security tab, there is an option to use your own custom domain name from an existing Azure DNS resource, optionally with a HTTPS connection. This is disabled by default, but this documentation can get you started. To use HTTPS, you must have an Azure DNS resource enabled and have the public and private key pair in base64 encoded format.

   You can also Enable Auth on Signalling Server if HTTPS is configured, which redirects users to a login page when they first try to access the application on the browser. Once authenticated, the user is redirected to the application. If this setting is enabled, you also need to enable the Admin Dashboard in the next step to add user accounts.

3. In the Networking tab, there are some advanced settings you can configure. One key setting to be aware of is the STUN and TURN server configuration. The public Google STUN server used by default will be able to connect most end users to the WebRTC stream of your UE app. However, many corporate networks, VPNs, and cellular networks will not allow your app to stream properly without relaying the stream through a TURN server. Read more about these options in our Hosting and Networking Guide.

4. In the Admin Dashboard tab you can enable the Admin Dashboard, which provides a simple interface for seeing basic traffic analytics, granting user access (if enabled), uploading new versions of your app, and changing the auto-scale parameters.

   This feature requires an App Registration in Azure Active Directory, so you'll need the proper permissions in your organization. Follow this Microsoft documentation to create an app registration in another tab, and then copy-paste the Application (client) ID.

5. With all the settings configured, click Review + create. If it passes validation and everything looks correct, click Create to begin the deployment. It can take several minutes to create the necessary resources, especially the GPU VMs that need to boot up and download your app. When the deployment is complete, click Go to resource group.

Connecting to Your Streaming Instances

1. In the primary resource group of your deployment, select the Traffic Manager profile.

2. At the top right of the Essentials section will be the DNS name. This URL can be copied from here and pasted into a new browser tab. This is the universal URL by which all users can access the application. They will be re-routed to their nearest region's Matchmaker VM and redirected once more to the first available stream on a GPU instance.

Activating the Admin Dashboard

If you enabled the Admin Dashboard during the configuration, there is some extra setup required to activate it after all resources are deployed.

1. In the primary resource group, open the App Service with the "-dashboard" name.

2. In the top right of the Essentials section is the URL of this resource. Copy this address.

3. Navigate back to the AAD App Registration you created for this dashboard. On the right column of Essentials, click Add a Redirect URI.

4. Click Add a platform. Click on Web from the pop-out blade.

5. Paste in the URL of the dashboard App Service into the Redirect URI, and append this text to the end of it: /.auth/login/aad/callback. Click Configure.

6. There is a section in the middle of the page called Implicit grant and hybrid flows. Check the two boxes here for issuing access tokens and ID tokens. Click Save at the bottom of the page.

7. After a few minutes, if you visit the original URL you pasted in, you'll be presented with the Admin Dashboard. This URL can be found at any time back in the App Service.

Updating Your Application

If the Admin Dashboard is enabled, you can follow the steps below to update the Pixel Streaming deployment with a new build of the UE app. Without the Admin Dashboard, the whole setup and configuration must be run again. The Dashboard method will leverage the existing resources and resource groups, but a new deployment will create all new resources and will not overwrite or delete existing deployments.

1. Follow the same prerequisite steps to zip up the WindowsNoEditor folder of your app.

2. Select the Storage Account in the global resource group.

3. In the left panel, select Containers and open the Uploads container. Then upload the zip file here.

4. Browse to your Admin Dashboard in the browser. Select Settings from the left hand navigation.

5. Click Add New Version and adjust settings as needed. Select the .zip file you uploaded to your Storage Account using Select blob. Click Add Version when you are finished.

6. The Matchmakers and Signalling Servers check for updates every 30 seconds and redeploy any new versions on the fly.

7. If you want to control exactly how many instances are running without scaling up or down, you can change the Min Idle Instance Count and Max Instance Scale Count to the same number of desired instances. You can also disable auto-scale and instead manually set the number of instances through the Scaling page of the Virtual machine scale set (VMSS) in each region.

Adding Authenticated Accounts

If Enable Auth on SignallingServer was properly configured in the Security tab during deployment, you must add user accounts that have access to the stream. In the Admin Dashboard, click on Accounts from the left hand navigation, then click Add Account. Users must use the credentials you provide to access the app.

Reviewing Logs

To assist with debugging any issues with your deployment, you can review detailed logs of all activity from the Matchmakers and SignallingServers.

1. In the global resource group, click the name of the **Log Analytic**s workspace resource.

2. In the General section of the left hand panel, click Logs.

3. You may be presented with a popup dialog showing available Queries that are not necessarily relevant. Toggle the Always show Queries option and then click the X to close the prompt.

4. Click the double arrow to expand the Schema and Filter panel inside of the default New Query tab.

5. Click the arrow next to the Custom Logs item to expand it. If you do not see an item under Custom Logs, your deployment may not have been active long enough to record any and you can check back in a few minutes.

   Double click on the armlog_newline_CL item. This adds it to your active Query.

6. Click the blue Run button to begin the query of the VM logs. Optionally, you can adjust the time range to some other value than the default 24 hours.

7. This produces a table of all the available logs from all the available VMs in your deployment, which can be quite verbose. You can sort the data by clicking on the columns, and you can search or filter the data by clicking on the magnifying glass at the top right of the table. Some relevant search terms might be "connected" or "download."

Deleting the Whole Deployment

To delete the Pixel Streaming deployment and stop all associated costs, you must delete the resource groups that were created. After the initial deployment you should have at least three resource groups in your subscription: one resource group for each region (for the GPU instances), one storage resource group (for the initial .zip file upload), and one global resource group (for the Traffic Manager and Admin Dashboard). The storage resource group can be reused for a future deployment.

The resource groups used for your deployment have a Tag in the Essentials area called RandomString: xyz. Clicking that tag shows only the relevant resource groups to make it easier to navigate and delete multiple groups.

To delete a resource group, first open it and then click the Delete resource group button at the top. You need to confirm your deletion. It may take several minutes for the deletion to fully process and remove the group from your subscription. Repeat as necessary for other resource groups.

If you set a custom domain, you also need to delete the records added to the DNS zone.