Set up TLS for the Anbox Cloud Appliance

The Anbox Cloud Appliance uses a self-signed certificate to provide HTTPS services. If you want to serve the appliance over HTTPS using a valid SSL/TLS certificate, follow the steps in this document to generate and install a valid SSL/TLS certificate on the Anbox Cloud Appliance.

If you run the appliance on AWS, you can choose to use the AWS Certificate Manager. Otherwise, you must manage the certificate yourself manually.

Prerequisites

Before you start, make sure the following requirements are met:

• The Anbox Cloud Appliance is installed and initialised. See How to install the appliance on AWS and Initialise the appliance for instructions.

• If you want to use the AWS certificate manager, you should have a domain name for use with the Anbox Cloud Appliance registered, either through Amazon Route 53 (see Register a new domain in the Amazon Route 53 documentation) or through another domain provider.

Manage the certificate manually

To generate and install a certificate yourself, complete the following steps:

Add a DNS record

Setting up DNS redirection depends on your DNS provider. Refer to the documentation of your provider to create a DNS record pointing to the IP/DNS of the AWS instance where the Anbox Cloud Appliance is running.

Note

This option is experimental. It will be removed in a future release when a better replacement exists.

Configure the location

Configure the location for the appliance using the created DNS name. For the following configuration files need to be updated:

/var/snap/anbox-cloud-appliance/common/gateway/config.yaml

The configuration file needs to be changed to look as follows

...
endpoint:
  address: 192.168.11.195:9031
  public-address: 192.168.11.195
  # Add the location element here if it doesn't exist and set it to your
  # DNS name.
  location: your.dns.name
...

/var/snap/anbox-cloud-appliance/common/config.yaml

The configuration file needs to be changed to look as follows

log-level: error
listen-address: 192.168.11.195
location: your.dns.name
...
tls:
  # Drop or comment the following line
  # ca: /var/snap/anbox-cloud-appliance/common/tls/ca.crt

Generate an SSL certificate

There are many ways to create a valid SSL certificate. One way is to use Let’s Encrypt to generate a free SSL certificate.

First, connect and SSH into your appliance instance, and install the certbot snap:

sudo snap install --classic certbot

Before generating your certificate using certbot, stop the appliance service from listening on port 80 for the certificate creation:

sudo snap stop anbox-cloud-appliance.daemon

Then run the following command to generate your certificate:

sudo certbot certonly --standalone

This command prompts you to enter the domain name for the certificate to be generated. You will see the following message when the certificate is created successfully:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/<your domain name>/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/<your domain name>/privkey.pem
This certificate expires on yyyy-MM-dd.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.

Install the SSL certificate

Copy the generated certificate to the /var/snap/anbox-cloud-appliance/common/daemon directory:

sudo cp /etc/letsencrypt/live/<your domain name>/fullchain.pem /var/snap/anbox-cloud-appliance/common/daemon/server.crt
sudo cp /etc/letsencrypt/live/<your domain name>/privkey.pem /var/snap/anbox-cloud-appliance/common/daemon/server.key

Then start the appliance service:

sudo snap start anbox-cloud-appliance.daemon

With the certificate installed on the appliance, you now can access the appliance using the created domain name.

Renew the SSL certificate

The certbot snap packages installed on your machine already set up a systemd timer that will automatically renew your certificates before they expire. However, in order to get the certificate renewed successfully for the appliance, you must complete the following steps:

1. Stop the appliance service to release port 80 right before the certificate is going to be renewed. This can be done through the pre-hook:

   cat <<EOF | sudo tee /etc/letsencrypt/renewal-hooks/pre/001-stop-appliance.sh
   #!/bin/bash
   sudo snap stop anbox-cloud-appliance.daemon
   EOF
   sudo chmod +x /etc/letsencrypt/renewal-hooks/pre/001-stop-appliance.sh
   

2. Install the certificate right after it has been renewed and start the appliance service through the post-hook:

   cat <<EOF | sudo tee /etc/letsencrypt/renewal-hooks/post/001-start-appliance.sh
   #!/bin/bash
   sudo cp /etc/letsencrypt/live/<your domain name>/fullchain.pem /var/snap/anbox-cloud-appliance/common/daemon/server.crt
   sudo cp /etc/letsencrypt/live/<your domain name>/privkey.pem /var/snap/anbox-cloud-appliance/common/daemon/server.key
   sudo snap start anbox-cloud-appliance.daemon
   EOF
   sudo chmod +x /etc/letsencrypt/renewal-hooks/post/001-start-appliance.sh
   

In this way, the SSL certificate auto-renewal is in place.

Note

The appliance will face a short downtime during the renewal of the SSL certificate but will come back online once the process is completed.

Use the AWS Certificate Manager

If you run the Anbox Cloud Appliance on AWS, you can use the AWS Certificate Manager to provision and manage your TLS certificate.

Note

The screenshots in the following instructions use an example domain name that is not owned or controlled by Canonical. Replace it with your own domain name when following the setup instructions.

Configure routing information and name servers

Note

You can skip this step if you registered your domain name through Amazon Route 53.

If you want to use a domain name that was not registered through Amazon Route 53, you must manually create a public hosted zone for it, and then make your domain use Amazon Route 53 as its DNS service. A public hosted zone contains routing information for the domain, and Amazon Route 53 uses it to determine to which machine it should route the traffic to your domain.

In the case of the Anbox Cloud Appliance, we want the traffic routed to the AWS load balancer which we will set up later in this guide.

1. To create a public hosted zone, follow the instructions in Creating a public hosted zone in the Amazon Route 53 documentation.

   The following example shows a public hosted zone for an example domain name. The two DNS records are added automatically after creation:

   

2. To change the DNS service for your domain registration, you must specify the custom name servers that Amazon Route 53 allocated for the domain name. You can find them in the “NS” record for your public hosted zone.

   The following example shows the custom name servers for the example domain:

   

   Go to your domain provider and configure the DNS settings for your domain there. Specify the name servers listed in Amazon Route 53 as the custom name servers.

   The following example shows this configuration for the example domain:

   

Create a public certificate

To create a public certificate using the AWS Certificate Manager, you must first request a certificate and then validate that you own the domain that the certificate applies to.

1. To request the public certificate, follow the instructions in Requesting a public certificate in the AWS Certificate Manager documentation.

   The following example shows a certificate for the example domain name that is pending validation:

   

2. To validate the certificate, follow the instructions in Validating domain ownership in the AWS Certificate Manager documentation.

   Since you have a public hosted zone for your domain in Amazon Route 53 (see Configure routing information and name servers), you can follow the steps for creating records in Route 53.

DNS propagation usually takes a while. When it completes and the validation is successful, the status of the certificate changes to issued, and it is ready to use.

Create a load balancer

To use the Anbox Cloud Appliance through your domain name, AWS must route the HTTPS traffic for your domain to the Anbox Cloud Appliance. To ensure this, you must create a load balancer that listens for traffic and routes it to the appliance.

1. Go to the Load balancers page in the EC2 dashboard.

2. Click Create load balancer.

3. Choose Application Load Balancer as the load balancer type.

4. For the Basic configuration, keep the default options (scheme: internet-facing, IP address type: IPv4).

5. For the Network mapping, select the appropriate Availability Zones.

6. For the Security groups, use a new group with an inbound rule that allows only HTTPS traffic and the default outbound rule that allows all traffic.

7. For Listeners and routing, create a listener that will route traffic to the AWS instance that hosts the Anbox Cloud Appliance:

   1. Select HTTPS as the protocol.

   2. Click Create target group.

   3. Select Instances as the target type for the new target group.

   4. Enter a name for the target group.

   5. Select HTTPS as the protocol and specify port 443 (this is the destination port to which the traffic coming from the AWS load balancer is routed).

   6. For the remaining settings, leave the default values.

   7. Click Next to go to the Register targets page.

   8. Select the instance that runs the Anbox Cloud Appliance.

   9. Click Include as pending below.

   10. Review the target.

       The following example shows a target for the Anbox Cloud Appliance:

       

   11. Click Create target group to finish the target group creation.

8. Back in the Listeners and routing sections on the load balancer creation page, select the target group that you just created for the default action.

9. In the Secure listener settings section, select the public certificate that you created through the AWS Certificate Manager.

   

10. Check the Summary, and if everything looks correct, click Create load balancer.

Direct traffic from your domain to the load balancer

When the load balancer is created, AWS assigns it an automatic DNS name. The following example shows where to find it:

You now need to route the traffic that goes to your domain name to the load balancer.

1. Go to the Route 53 console.

2. Select your public hosted zone (which was created automatically if you registered your domain through Amazon Route 53, or which you created earlier in Configure routing information and name servers).

3. Create a type A DNS record that routes the traffic that from the public hosted zone to the load balancer:

   1. Click Create Record and select Simple routing.

   2. Click Define simple record.

   3. Select A - Route traffic to an IPv4 address and some AWS resources as the record type.

   4. For Value/Route traffic to, select Alias to the application and Classic load balancer, the region where the load balancer is located and the name of the load balancer.

   The following example shows the record creation for the example domain:

   

4. Click Define simple record to create the DNS record for your public hosted zone.

The following example shows the DNS record with type A for the example domain:

Configure the appliance to use the domain name

Finally, configure the Anbox Cloud Appliance to use the domain name that you prepared.

1. Use SSH to connect to the AWS instance where the Anbox Cloud Appliance is running.

2. Configure the location of the appliance as described in Configure the location

You can now use the new domain name to access the Anbox Cloud Appliance.

The following example shows the certificate for the example domain: