Reference

Using a custom domain

Overview

The steps required to use a custom domain name to expose the Scalable Pixel Streaming REST API or the signalling server for a specific Pixel Streaming application vary depending on whether the underlying cloud platform natively supports the use of custom domains.

Using a custom domain on cloud platforms with native support

Using a custom domain to expose the REST API

On cloud platforms that natively support the use of custom domain names, you can specify a custom domain for the REST API server when Scalable Pixel Streaming is first installed. You will then need to determine the appropriate DNS record details to ensure your domain name resolves to the IP address for the REST API server. The type of the DNS record (either A or CNAME) and the mechanism for determining the relevant details vary based on the cloud platform.

When installing Scalable Pixel Streaming on AWS the CloudFormation output will include the details of the required DNS record automatically if you specified a custom domain name in the input fields. Since AWS Application Load Balancers do not have static IP addresses by default, the DNS record type will always be CNAME.

Once you have determined the appropriate DNS record information, you will need to create a DNS record using the management tools supplied by your domain name registrar. Consult your registrar’s documentation for details on managing DNS records for your domain.

Using a custom domain to expose the signalling server

On cloud platforms that natively support the use of custom domain names, you can specify a custom domain name for the signalling server of a Pixel Streaming application when you deploy it via the CLI tool. The sps-client application create command allows you to specify a custom domain name for the signalling server using the --signallingServer.customDomainName flag.

Once you have deployed a Pixel Streaming application with a custom domain name specified, you will need to determine the appropriate DNS record details to ensure your domain name resolves to the IP address for the signalling server. The deployment tool used to deploy the Pixel Streaming application can be used to query this information via the CLI tool. The sps-client application info command queries the details for a Pixel Streaming application’s network ingress endpoints. If a custom domain name was specified when the application was deployed, then the output will include the details of the required DNS record.

Once you have determined the appropriate DNS record information, you will need to create a DNS record using the management tools supplied by your domain name registrar. Consult your registrar’s documentation for details on managing DNS records for your domain.

DNS Validation for TLS Support

Configuring DNS validation for the REST API on AWS

Once you have finished installing Scalable Pixel Streaming on AWS, you will need to create two CNAME records when using a custom domain name on AWS, both of which can be found in the outputs section of your CloudFormation stack:

• DNSValidationRecord: a CNAME record to validate domain ownership for the ACM certificate. See DNS Validation.

• LoadBalancerDNS: the value for a CNAME record pointing to the load balancer DNS. This directs traffic from your custom domain name to the load balancer.

It can take some time for AWS to validate and issue your ACM certificates once you have applied the relevant CNAME record for DNS Validation. In most cases it should take no more than 30 minutes after you have correctly applied the DNS validation CNAME record for DNS to propagate and your REST API or signalling server to come online. In the event that it takes longer, you can refer to troubleshooting DNS Validation on AWS

REST API: Once you have applied the appropriate DNS validation CNAME records for your custom domain name, you will know that your REST API endpoint has become readily available once the result of your Configuring REST API access details is successful.

Configuring DNS validation for the Signalling Server / HTTP Server on AWS

After you’ve deployed your application, in order to direct traffic to your custom domain, you will need to add CNAME records for DNS validation and general access to the load balancer. The DNS records that you need will be available via the application info subcommand of the client tool.

When the status of the application info subcommand reads CertificateValidating, this indicates that the DNS records need to be added.

An Example of DNS Records returned from the client tool

{
   "dnsRecords":[
      {
         "host":"myapp.example.com",
         "type":"CNAME",
         "value":"sps-myapp-310633015.ap-southeast-2.elb.amazonaws.com"
      },
      {
         "host":"_06e330d24c2474692355e3d5827b1219.myapp.example.com.",
         "type":"CNAME",
         "value":"_dd5a786ad76b54541f5a2bca2f6b959d.hqkbcmchgw.acm-validations.aws."
      }
   ]
}

When you’ve deployed your application and added your DNS Validation CNAME record to your domain name registrar, you can retrieve the details of your application and in the resulting JSON search for the status field for it to say Running. This will denote that your signalling server/application is up and running

Using a custom domain on cloud platforms without native support

On cloud platforms that do not natively support the use of custom domain names, the only way to make use of a custom domain is to deploy a reverse proxy external to Scalable Pixel Streaming that forwards requests to the target server. The setup process is the same for proxying to either the REST API server of a Scalable Pixel Streaming installation or the signalling server for an individual Pixel Streaming application:

1. Determine the endpoint URL for the target server, which will be using a DNS name automatically generated by the underlying cloud platform:

   • For the REST API server, the endpoint URL will be listed in the Kubeapps output when you install Scalable Pixel Streaming on CoreWeave. You can also view this information again at any time by navigating to the “Applications” tab of Kubeapps and clicking on the entry for Scalable Pixel Streaming.

   • For the signalling server, query the Pixel Streaming application’s network ingress endpoints using the instructions listed in the Using a custom domain to expose the signalling server section above. The WebSocket URL will be listed in the query output.

2. Configure your reverse proxy software of choice to forward requests to the endpoint URL. Popular options include NGINX and HAProxy, see the documentation for your chosen proxy software for configuration instructions. Note that the protocols being proxied will depend on the target server:

   • If you are forwarding to the REST API server, then you will be forwarding HTTP traffic.

   • If you are forwarding to the signalling server, then you will be forwarding WebSocket traffic, which starts as HTTP traffic and is then upgraded to a WebSocket connection.

3. Deploy the reverse proxy to a cloud platform that features native support for custom domain names, and configure your custom domain to resolve to the proxy. There are a number of potential deployment mechanisms that could be used for this, generally speaking, you should use whatever mechanism is most appropriate based on the existing infrastructure used to deploy your websites. As discussed on the security considerations page, it is strongly recommended that you configure TLS for the reverse proxy to ensure all connections are secure.