Adding a custom domain and TLS certificates to the VotingApp

by | Mar 3, 2023

Spread the word

This is the fifth part in a series focused on teaching the fundamentals of building and developing applications using Acorn. In the previous step we detailed how to connect a CI/CD pipeline to Acorn. In this new post we will show how to expose the application using custom domains and TLS certificates.

Exposing the application on a custom domain

About Acorn default domain

When you run the VotingApp in the previous steps, you probably noticed that the http endpoints returned use the on-acorn.io domain.

Indeed, every time we run the VotingApp we get endpoints similar to the following ones:

  • voteui: http://voteui-vote-c7bc34b6.jy7jy0.alpha.on-acorn.io
  • resultui: http://resultui-vote-f1825499.jy7jy0.alpha.on-acorn.io

Using the dig command we could see both domain names are resolved to the IP address of your Ingress Controller:

Note: in the example used in this post, the underlying Kubernetes cluster is a one-node k3s running on a VM which IP is 89.145.160.110

By default, the http endpoints have the following format:

CONTAINER_NAME-APPLICATION_NAME-UNIQUE_HASH-CLUSTER_DOMAIN

In the current example, this can be broken down as follows:

  • container: voteui
  • application name: vote
  • unique hash: c7bc34b6
  • cluster domain: jy7jy0.alpha.on-acorn.io

Acorn allows defining a custom cluster domain as well as a custom format for the http endpoints as we will see below.

Defining a custom domain during Acorn installation

When installing Acorn we can specify our own domain instead of the default one (on-acorn.io) using the —custom-domain flag. At the same time we can disable the dns managed by Acorn as we don’t need it with our custom domain.

If we configure Acorn with the following command:

$ acorn install --cluster-domain k8sapps.xyz --acorn-dns disabled

and then run the application:

$ acorn run -n vote .

we will get endpoints with the following format:

  • voteui: http://voteui-vote-c7bc34b6.k8sapps.xyz
  • resultui: http://resultui-vote-f1825499.k8sapps.xyz

The endpoints still have the format CONTAINER_NAME-APPLICATION_NAME-UNIQUE_HASH-CLUSTER_DOMAIN but this time the domain is k8sapps.xyz  instead on-acorn.io.

Using the —http-endpoint-pattern flag in the Acorn installation command, we could define our own format for the http endpoints as well (this is described in the endpoint patterns documentation).

To illustrate this, let’s update the Acorn installation :

$ acorn install --http-endpoint-pattern="{{.Container}}.{{.App}}.{{.ClusterDomain}}"

Note: running the install command only sets the flag specified and keeps the values of the previously configured flags.

If we update the application we will notice voteui and resultui are now exposed on new endpoints:

  • voteui: http://voteui.vote.k8sapps.xyz
  • resultui: http://resultui.vote.k8sapps.xyz

On top of this, Acorn also allows to define a custom domain when running the app as we will see below.

Defining a custom domain at runtime

Acorn allows to specify the domain name of a given container when running the application. The following command updates the app using the -p,—publish flag in order to define the domains for both voteui and resultui containers:

$ acorn run -n vote -p vote.k8sapps.xyz:voteui -p result.k8sapps.xyz:resultui --update .

On top of the endpoints generated in the previous step we also get the new ones:

  • voteui is exposed on http://vote.k8sapps.xyz and http://voteui.vote.k8sapps.xyz
  • resultui is exposed on http://result.k8sapps.xyz and on http://resultui.vote.k8sapps.xyz

To access the application we need either to change the local /etc/hosts or to add a DNS record for both those subdomains.

voteui containers exposed on vote.k8sapps.xyz
resultui containers exposed on result.k8sapps.xyz

Exposing the application with a custom domain is straightforward as we’ve seen above. In the next part we will see how to add a TLS certificate.

Adding a TLS certificate

There are 2 ways to associate a TLS certificate to an Acorn application:

  • using cert-manager, a tool widely used in the ecosystem
  • using Acorn though its integration with Let’s Encrypt

In the following we will focus on the second approach.

Using Acorn Let’s Encrypt integration

In order to enabled the Let’s Encrypt integration, we need to modify the Acorn installation option as follows (the EMAIL_ADDRESS placeholder should be replaced with a real email address):

acorn install \
 --ingress-class-name traefik \
 --lets-encrypt=enabled \
 --lets-encrypt-tos-agree=true \
 --lets-encrypt-email=EMAIL_ADDRESS

Note: as we are running a one node k3s cluster, the –ingress-class-name refers to the IngressClass automatically created by Traefik Ingress Controller (deployed by default in k3s)

Enabling Let’s Encrypt in Acorn configuration

In order to use the subdomains vote.YOUR_DOMAIN and result.YOUR_DOMAIN with a TLS certificate, we first need to update the DNS entry so both subdomains are resolved against the IP of the cluster’s Ingress Controller. The screenshot below illustrates the configuration on CloudFlare where A records have been created for vote.k8sapps.xyz and result.k8sapps.xyz :

Adding DNS entries for vote.k8sapps.xyz and result.k8sapps.xyz subdomains

We can then update the application:

$ acorn run -n vote -p vote.k8sapps.xyz:voteui -p result.k8sapps.xyz:resultui --update .

We will be returned additional https endpoints to access both voteui and resultui frontends:

  • voteui: https://vote.k8sapps.xyz
  • resultui: https://result.k8sapps.xyz

We can now access both frontends using the custom domains over https:

voteui exposed on vote.k8sapps.xyz over tls
resultui exposed on result.k8sapps.xyz over tls

Wrapping up

In this post, we explained how the VotingApp can be hosted on a custom domain and served securely over TLS. This post concludes the VotingApp series. If you would like to further practice the steps covered in this series and explore additional features of Acorn, please consider following the new “Getting Started With Acorn Workshop“.

Luc Juggery is a software engineer with 18+ years of experience and co-founder of 2 startups located in Sophia-Antipolis, southern France. You can chat with him on Twitter, read more of his work on Medium, find his tutorials on YouTube, or take one of his Docker or Kubernetes training courses on Udemy.


Spread the word