Deploying Unreal Engine 4 Pixel Streaming on Azure

A short tutorial describing how to set up Pixel Streaming for Unreal Engine 4 on Microsoft Azure

Choose your operating system:

Windows

macOS

Linux

Google has informed developers of a vulnerability in versions (earlier than M102) of WebRTC. Impacts, workarounds, and updates can be found here.

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 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.

While the Unreal Pixel Streaming solution is available at no cost, the resulting Azure resources do have an associated cost. If your account is linked to your employer or another party, check that they are prepared to accept responsibility for the costs involved before setting up your deployment instance. For a more accurate estimate of your cost, review the pricing information on the Virtual Machine Pricing page, filter by desired region, and search for the "NV12s v3" to see the "pay as you go" pricing.

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 WindowsNoEditor folder in to a .zip file.

Compressing the Windows No Editor folder as 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.

    The Unreal Pixel Streaming offer page hosted in the Azure marketplace

  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.

    The Azure Marketplace sign-in page

  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.

    The Get It Now button close up

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

    Confirm information and create the app

  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.

    Click Create to begin configuring the 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.

    Click the Create new link to create a new resource group

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

    Default instance 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 the .zip file containing your Pixel Streaming app. Use the Browse button to open the Storage Accounts for your selected subscription.

    Browse to your pixel streaming app package

    Create a new storage account

    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.

    Adding details about your new storage account

  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.

    Click the + Container button and name your new container

  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.

    Uploading the app to the container

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

    Select the file in the container

  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.

    Custom mods checkbox

  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.

    Access credentials for the Virtual Machines

Once 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.

We recommend that you start with a smaller, simpler deployment to test your application and avoid high billing costs. Creating large numbers of virtual machines in a large number of regions will have an exponential impact on how much your subscription is charged.

  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.

    Select regions to deploy your Virtual Machines

  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.

    Sliders controlling number of streams and virtual machine instances

  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.

    Using the Run with Azure Spot discount options

  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.

    Enable auto-scaling

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

Parameter

Description

Percent Buffer Required Before Scale

The percentage of streams (UE App instances) that must be available, otherwise a scale-out operation will occur to maintain this buffer. This helps prevent new users from waiting for a new VM to spin up during times of increased load. Choose 0 to ignore this policy. Default is 25%.

Instance Count Buffer Required Before Scale

The number of streams (UE App instances) that must be available, otherwise a scale-out operation will occur to maintain this buffer. This helps prevent new users from waiting for a new VM to spin up during times of increased load. Set to 0 to ignore this policy. Default is 1.

Idle Minutes Before Scale-Down

The number of minutes when a new scale-up operation hasn't occurred before evaluating scaling down to a minimum buffer count. Default is 60.

Scale Down Amount

The maximum number of nodes to scale down by, in case a scale down occurs. Default is 1.

Min Instance Count While Idle

The minimum number of streams (UE App Instances) that the solution will scale down to during an idle period (i.e., low activity periods like night time). Default is 1.

Max Node Scale Count

The maximum number of GPU VMs containing the streams (UE App instances) that will be scaled out. Default is 20. Be sure to check your quota to support this number of instances.

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.

    Adjust the app resolution and frame rate

  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.

    Enable using a custom domain

    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.

    Enable auth on the signalling server

  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.

    Configuring the STUN and TURN server options

  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.

    App registation for the admin dashboard

    Enable the admin dashboard

  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.

    Click go to resource group after the deployment is complete

Connecting to Your Streaming Instances

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

    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.

    Copy traffic manager DNS name

    A pixel streaming app in a browser

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.

    Open the dashboard app service

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

    The resource URL

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

    Add a redirect URI

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

    Add a Web platform

  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.

    Configure the Web platform redirect URI

  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.

    Implicit grant and hybrid flows checkboxes

  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.

    The pixel streaming admin dashboard

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 compress the WindowsNoEditor folder of your app in to a .zip file.

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

    Select the storage account

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

    Upload your zip file to the container

  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.

    Click Add New Version in the Settings

    Add New Version details

  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 is 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.

Add an authenticated account

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.

    The Log Analytics workspace resource

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

    Logs option in the General section

  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.

    Disable the Always Show Queries toggle

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

    Click the double arrow icon to expand the Schema and Filter panel

  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.

    The armlog_newline_CL item under Custom Logs

  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.

    Run your query

  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."

    The output of your query of the logs

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.

An example of typical resource groups for a pixel streaming application

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.

The Tag in the Essentials area

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.

Delete a resource group

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

Tags
Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss