Using custom domain names for an application

All applications that are deployed on the Playground and make use of the napptive-ingress trait are exposed to the Internet with an autogenerated public DNS name in the form of *-.apps.playground.napptive.dev*. This guide will help you make the application accessible through a custom domain (e.g., *my.domain.com*).

Pre-requirements

Before you continue, make sure you have

  • An Application that will be exposed through a custom domain.
  • Access to your domain name registrar account. The required instructions are compatible will all major providers: Google Domains, GoDaddy, Namecheap, AWS Route53, Azure DNS, and many more.

Obtaining the application

Any application that exposes an endpoint to the Internet can benefit from this functionality. If you do not have an application yet, or want to try this feature out easily, we recommend to start with the nginx application that is already available in the catalog. To download the application use:

playground catalog pull napptive/nginx:1.20.0

and decompress the application with:

tar xvzf nginx.tgz

Modifying the application

Edit the application file (e.g., nginx.application.yaml if your are using the example application downloaded in the previous paragraph) and locate the napptive-ingress trait. In the previous application that will be equivalent to:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: nginx-app
...
spec:
  components:
    - name: nginx
      type: webservice
      properties:
        ...
      traits:
      - type: napptive-ingress
        properties:
          name: nginx-ingress
          port: 80
          path: /

And include a new property named extraDNSName in the napptive-ingress trait configuration. Assuming this application will also be exposed on my.custom.domain the edited application will be:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: nginx-app
...
spec:
  components:
    - name: nginx
      type: webservice
      properties:
        ...
      traits:
      - type: napptive-ingress
        properties:
          name: nginx-ingress
          port: 80
          path: /
          extraDNSName: "my.custom.domain"

Now deploy the application either by using the CLI, or uploading a new catalog application. With the CLI use:

playground apps deploy nginx.application.yaml

Wait for the application to start and report a running state before proceeding to the next step.

Obtaining the default endpoint address

Once the application is running, get the default endpoint address using the Web UI or the CLI:

  • With the Web UI, select the application and navigate to the Endpoints section

Application endpoints

and copy the target link address, which in this case is nginx-ingress-11223344556677889900.apps.playground.napptive.dev

  • With the CLI, use the command apps info to obtain the endpoints
$ playground apps info nginx-app
Target environment: <account>/<environment>
NAME         STATUS
nginx-app    RUNNING

COMPONENT    STATUS     SCOPES    TRAITS
nginx        RUNNING              napptive-ingress

COMPONENT    INGRESSES
nginx        nginx-ingress-11223344556677889900.apps.playground.napptive.dev,my.custom.domain

and copy the first address.

Modifying your DNS entries

In this step we will modify your DNS entries to make my.custom.domain an alias of nginx-ingress-11223344556677889900.apps.playground.napptive.dev. To do that, go to your Domain Registrar (Google Domains, GoDaddy, Namecheap, AWS Route53, Azure DNS, etc.) and navigate to your domain.

To make the alias you will need to create a new CNAME record. A CNAME or “Canonical Name” record maps an alias name to a canonical domain name. In this way, when a client navigates to https://my.custom.domain it will be transparently redirected to https://nginx-ingress-11223344556677889900.apps.playground.napptive.dev.

The new record will have the following properties, substituting my.custom.domain with your subdomain of choice, and nginx-ingress-11223344556677889900.apps.playground.napptive.dev with the result given when obtaining the endpoint address.

Record Type Name Target TTL
CNAME my.custom.domain nginx-ingress-11223344556677889900.apps.playground.napptive.dev 600

When introducing the name of the registry, check your provider documentation as some may only require entering the subdomain which in this example will be my when editing the DNS records for custom.domain. For more information, check the major provider guides on adding CNAME records:

Once the change is save in the DNS, wait some minutes for the changes to be propagated. The process is automatically executed, and typically takes 10 minutes once the DNS records have been propagated. Once everything is ready, navigate to my.custom.domain and you will be greeted by the default nginx home page.

What’s next

  • Something did not work out/behave as expected? Contact support or contact us via the Community Slack so we can help you.