Custom Domains & TLS Certificates

This document provides a comprehensive guide to managing custom domains and TLS certificates within your Alokai Cloud instances.

Default Domain

When you create an Alokai instance, it is automatically assigned a default domain. This domain follows the pattern: <instance-name>.<region>.<provider>.storefrontcloud.io.

For example, an instance named "my-store" created in the europe-west1 region on the Google Cloud Platform would have the default domain my-store.europe-west1.gcp.storefrontcloud.io.

Each instance has a TLS certificate configured out of the box. We use Let's Encrypt, a free and automated certificate authority, to issue certificates that provide a secure (HTTPS) connection to your application.

While the default domain is sufficient for initial setup and testing, using a custom domain will eventually be necessary for production, at least.

Adding a Custom Domain

You can add custom domains to your Alokai instance via the Alokai Console.

Navigate to your instance: In the Alokai Console, select the instance you want to configure.
Go to Domains: Within your instance settings, navigate to the "Domains" section.
Add Domain: Click the "Add Domain" button to initiate the process.
Find your Alokai IP address: The "Add Domain" dialog will display the IP address to which you need to point your DNS A record.
Update your DNS records: Log in to your domain registrar and update the DNS records for your domain. Create or modify the A record to point to the Alokai IP address.
Enter your domain name: Provide the full domain name you wish to add in Alokai Console and hit save (e.g., www.example.com or example.com).

Important: Adding a domain via the console will trigger automatic TLS Certificate generation using Let's Encrypt. Do not add domains via the console if you intend to use your own custom TLS certificate.

Key Requirements

DNS A Record: Ensure your DNS A record correctly points to your Alokai instance's IP address. You can find this IP address within the "Settings > Domains > Add Domain" dialog in the Alokai Console.
Certificate Generation: A Let's Encrypt TLS certificate will be automatically generated and issued for your domain. This process can take up to 2 hours.

⚠️ Note: If you wish to purchase and provide your own custom TLS certificate, or wish to use a wildcard certificate (unsupported by Let's Encrypt), you must contact the Alokai support team. Do not add custom domains via the console in this case.

Automatic Certificate Generation

Alokai Cloud automates the process of obtaining and renewing Let's Encrypt TLS certificates for your custom domains.

Process Overview

Domain Addition: When you add a new custom domain to your Alokai Cloud instance via the console, the system automatically initiates the Let's Encrypt certificate generation process.
ACME Challenge: Alokai's infrastructure handles the ACME challenge (explained below) to prove domain ownership to Let's Encrypt.
Certificate Issuance: Upon successful validation, Let's Encrypt issues an TLS certificate for your domain.
Installation and Renewal: Alokai installs the certificate on your instance and configures automatic renewal to ensure your certificates remain valid.

What triggers the certificate process?

Adding/removing a custom domain through the Alokai console.
DNS changes that require certificate re-issuance.
Scheduled certificate renewal processes. Let's Encrypt certificates are automatically renewed every 3 months.

Important Considerations

Verify DNS: Always verify that your DNS records are correctly configured before initiating certificate generation.
Browser Cache: Clear your browser cache and use private browsing mode to ensure you are seeing the latest certificate status.
External CDNs: When using an external CDN, ensure it is configured to forward /.well-known/ requests to the origin server (your Alokai instance). This is crucial for the ACME challenge to succeed.

ACME HTTP-01 Challenge Process

Alokai uses the HTTP-01 challenge, a key component of the ACME (Automated Certificate Management Environment) protocol, to prove domain control to Let's Encrypt.

Here's how it works:

Challenge Request: Alokai requests a certificate from Let's Encrypt for your domain.
Token Generation: Let's Encrypt provides a unique token to Alokai.
File Placement: Alokai places a file containing this token at a specific location on your domain's web server: /.well-known/acme-challenge/<token>.
Verification: Let's Encrypt attempts to retrieve this file from your domain via HTTP.
Validation: If Let's Encrypt can successfully retrieve the file and its content matches the expected token, the challenge is successful, proving that Alokai controls the domain.

Purpose: The primary goal of the ACME challenge is to prevent unauthorized certificate issuance by ensuring that the entity requesting a certificate genuinely controls the domain.

Visual Representation:

Certificate Generation

Common Errors and Troubleshooting:

404 Errors

Cause: Let's Encrypt cannot find the challenge file at the expected location (/.well-known/acme-challenge/<token>).
Troubleshooting:
- DNS: Verify that your DNS A records correctly point to your Alokai instance's IP addresses.
- Web Server Configuration: Check for any web server configurations that might be blocking access to the /.well-known/acme-challenge/ directory.
- External CDN/Proxy: If you are using an external CDN or proxy like Cloudflare, ensure that requests to /.well-known/acme-challenge/ are forwarded to your Alokai instance and that path is not blocked by the CDN.

Cloudflare Configuration Issues

Cause: Cloudflare's caching and security settings can sometimes interfere with the ACME challenge process.
Troubleshooting:
- Bypass Cache: Ensure that Cloudflare is not caching the /.well-known/acme-challenge/ directory. You can achieve this by creating a Page Rule to bypass caching for this path.
- HTTPS Redirection: Temporarily disable Cloudflare's "Always Use HTTPS" feature during certificate generation, as it might redirect Let's Encrypt's HTTP validation requests.
- Firewall Rules: Check your Cloudflare firewall rules to ensure they are not blocking access to the /.well-known/acme-challenge/ directory.

Cloudflare (or Similar) Rules

If you are using Cloudflare or a similar external CDN, configure the following Page Rule to ensure Let's Encrypt can access the ACME challenge files:

URL Matching: yourdomain.com/.well-known/acme-challenge/*
Setting: "Bypass Cache" or "Disable Cache"
Security Settings: Disable any security settings that could block access to this path.
Firewall Rules: Ensure that your Cloudflare firewall rules do not block access to this path.

DNS Propagation Delays

Cause: After updating your DNS records, it takes time for these changes to propagate across all DNS servers globally.
Troubleshooting:
- DNS Propagation Checkers: Use online DNS propagation checkers like whatsmydns or DNS Checker to verify if your DNS changes have propagated.
- Patience: If propagation is not yet complete, wait for some time before attempting certificate generation.

Firewall Restrictions

Cause: Firewalls on your network or server might be blocking Let's Encrypt's access to your domain for the HTTP-01 challenge.
Troubleshooting:
- Port 80: Ensure that port 80 (HTTP) is open on your server's firewall.
- Firewall Logs: Check your firewall logs for any blocked requests from Let's Encrypt.

Having many domains added

Cause: In case of many domains added make sure they are all valid and have the correct DNS records because Let's Encrypt will try to issue one certificate for all of the domains. It means that if one of the domains is not valid or has an incorrect DNS record, all domains will be affected.
Troubleshooting:
- Make revision of all domains and DNS records and make sure they are correct.

Limits

There is a limit in custom certificates and domains to be configured per instance which equals 15 for certificates and 100 for domains.

Supplying a Custom TLS Certificate

If you prefer to purchase and use your own TLS certificate instead of Let's Encrypt, Alokai supports this as well.

To use a custom certificate:

Open a Support Ticket: Open a support ticket and inform the Alokai support team that you wish to use a custom certificate.
Provide Certificate Files: You will need to provide the following files to the support team:
- The TLS certificate file (.pem or .crt)
- The intermediate certificate file (or bundled certificate) (.pem or .crt)
- The private key file (.pem)
Secure Transfer: Ensure you transfer these files through a secure channel to protect your private key.
Specify Environments: Indicate which environments (dev, stage, prod) require the custom certificate.

⚠️ Note: The Alokai Console does not currently support direct management of custom certificates.

Wildcard Certificates: You can also use wildcard certificates to cover multiple subdomains (e.g., *.example.com). This can be useful if you have development, staging, and production environments under the same base domain. Note that Let's Encrypt does not offer wildcard certificates.

Custom TLS Certificate Installation

The Alokai support team will handle the installation of your custom certificate. They will:

Receive Certificate Files: Receive the certificate files from you securely.
Create Secrets: Create Kubernetes secrets to store your certificate files securely within your Alokai instance.
Update Configuration: Update the configuration of your Alokai instance to use your custom certificate.
Verification: Verify that the certificate is installed correctly and that your domain is accessible via HTTPS.

Certificate Signing Requests (CSRs):

If you need to generate a CSR for your custom certificate, you can follow the instructions here. Make sure to put your own organization and country information in the CSR.

Important: Mixing custom TLS certificates and Let's Encrypt for the same instance is not supported. Choose one approach and configure all your domains accordingly.

Verifying Your Certificate

After a certificate is issued or updated, it's important to verify that it is installed correctly.

Browsers

While browsers can display certificate information, they often cache TLS information, making them unreliable for verifying recent changes. If you must use a browser, use a new private browsing or incognito session to check the certificate.

To view certificate details in your browser:

Chrome/Edge: Click the padlock icon in the address bar, then click "Certificate."
Firefox: Click the padlock icon, then click "More Information" -> "View Certificate."
Safari: Click the padlock icon, then click "Show Certificate."

Online Checkers

Several websites provide TLS certificate verification tools. These tools can provide a more comprehensive check of your certificate and its chain of trust. Some popular options include:

Command-Line Tools

You can also use command-line tools to inspect and verify TLS certificates.

OpenTLS

Retrieve certificate information:

openssl s_client -connect yourdomain.com:443 -showcerts

Verify certificate validity:

openssl s_client -connect yourdomain.com:443 -verify 1

curl

Retrieve certificate information:

curl -vI https://yourdomain.com

Check certificate expiration:

curl -vIs https://yourdomain.com | grep expire

Monitoring of Certificate Expirations

Alokai monitors the expiration dates of Let's Encrypt certificates for custom domains that are publicly accessible. You will receive notifications if a certificate is approaching its expiration date. Alokai will also attempt to automatically renew Let's Encrypt certificates before they expire.

External CDN Considerations

If you are using an external CDN with your own custom certificate, Alokai's monitoring capabilities might be limited. If your application relies on a different domain to communicate with Alokai internally, we currently cannot automatically check the expiration of the certificate on the external CDN. In such cases, you are responsible for monitoring and renewing your CDN's certificate.

Domain and Certificate Management via API

You can also manage custom domains and certificates programmatically using Alokai's Farmer API. This can be useful for automating domain and certificate management tasks.

⚠️ Note: If you are unfamiliar with using APIs, we recommend opening a support ticket for assistance.

Important: If you are transitioning from automatic (Let's Encrypt) certificates to a custom certificate, you must contact Alokai support. There are additional manual steps involved that require intervention from the support team.

Farmer API: Update Instance

You can use the PATCH method of the Farmer API to update your instance's domain and certificate configuration. This requires the x-user-id and x-api-key headers, which you can find in the Alokai Console settings (visible only to users with the Console Owner role).

⚠️ Note: When using the PATCH method with arrays (like the domains array), the existing values are overwritten. Therefore, if you already have domains configured, remember to include them along with any new domains in the request payload.

Examples:

Using Custom TLS Certificates:

curl -X PATCH \
-H 'X-User-Id: $CLOUD_USERNAME' \
-H 'X-Api-Key: $CLOUD_PASSWORD' \
-H 'Content-Type: application/json' \
-d'{
"ingress": {
    "custom_domain": {
        "domains": [
            {"name":"my-first-domain.com", "secret_name": "custom-my-first-domain-tls"},
            {"name":"my-second-domain.com", "secret_name": "custom-my-second-domain-tls"}
        ]
    }
}' https://farmer.storefrontcloud.io/instance/<your-namespace>

Replace <your-namespace> with your instance's namespace (e.g., my-instance-europe-west1-gcp-storefrontcloud-io).
The secret_name field refers to Kubernetes secrets that store your custom certificate files. These secrets need to be created by Alokai support beforehand.

Using Let's Encrypt:

{
    "ingress": {
        "custom_domain": {
            "domains": [
                "my-first-domain.com"
            ]
        }
    }
}

Important: Mixing custom TLS certificates and Let's Encrypt for the same instance is not supported. Choose one approach and configure all your domains accordingly.

Wildcard Example:

{
    "ingress": {
        "custom_domain": {
            "domains": [
                {"name":"*.my-wildcard-domain.com", "secret_name": "custom-my-wildcard-domain-tls"}
            ]
        }
    }
}