This guide covers the steps you need to take your site live on Layer0 with a secure, custom domain.

Layer0 enterprise customers can choose the region in which their serverless functions will run, as well as backup region to which traffic will be diverted in the event of an outage. Choose the regions which are closest to the datacenter which hosts your origin site or APIs.

Before going live, you must create a production environment and configure your domains. For more information on environments, see Environments

To configure your custom domains:

  1. Create an environment by navigating to your site and selecting Environments => New Environment
  2. Click Edit to create a draft. Enter your domains here, save the changes, and activate:

domains

If you're migrating to Layer0 from Fastly, you will need to do the following before adding your domains to your Layer0 environment:

  • Contact Fastly support and request that control of your domains be transferred to Layer0. Be sure to explicitly list each domain that needs to transferred and ask Fastly to contact support(at)layer0.co if they need Layer0 to confirm the transfer.
  • Before going live with Layer0, you will need to ensure that you've removed your domains from all active Fastly services. To remove domains from a service, clone the service, remove the domains, then activate the new version of the service. Once the new service version is activated you can add the domains to your Layer0 environment and activate it.

You can find the DNS and whitelisting IP configurations in the "Networking" tab for your environment.

networking

In order to configure your DNS provider to direct traffic for a particular set of domains to Layer0, you must create DNS records with values depending on the type of domain you are using for your website. If you are launching a new site then you can set this up whenever you feel ready. For sites that are already live, the DNS update is the last step. Once you have updated your DNS you are committed to launching.

To host your site on a subdomain, add a CNAME record with the value shown under DNS Configuration (see above).

# To verify your DNS entry, run the following command
dig <your-sub-domain>

# Example
dig www.mywebsite.xyz

# Result
www.mywebsite.xyz.   599    IN    CNAME    d12ea738-71b3-25e8-c771-6fdd3f6bd8ba.layer0.link.

To host your site on the apex domain, create multiple A records on your apex domain, with the following Anycast IP Addresses values: 151.101.1.79, 151.101.65.79, 151.101.129.79, 151.101.193.79.

# To verify your DNS entry, run the following command
dig <your-apex-domain>

# Example
dig mywebsite.xyz

# Result
mywebsite.xyz.        599    IN    A        151.101.1.79
mywebsite.xyz.        599    IN    A        151.101.65.79
mywebsite.xyz.        599    IN    A        151.101.129.79
mywebsite.xyz.        599    IN    A        151.101.193.79

  • Create the multiple A records with the IPs, on your apex domain (see above).
  • Create a CNAME record for your sub-domain, with the value of your apex domain.

    # To verify your DNS entries, run the following command
    dig <your-sub-domain>
    
    # Example
    dig www.mywebsite.xyz
    
    # Result
    www.mywebsite.xyz.    599    IN    CNAME.   mywebsite.xyz.
    mywebsite.xyz.        599    IN    A        151.101.1.79
    mywebsite.xyz.        599    IN    A        151.101.65.79
    mywebsite.xyz.        599    IN    A        151.101.129.79
    mywebsite.xyz.        599    IN    A        151.101.193.79

Before going live, ensure that all Layer0 IP addresses are whitelisted in the security layer in front of your origin and/or API servers. The IP addresses you need to whitelist can be found on the "IP Whitelist" section of the "Networking" tab. Note that your IP addresses may differ from the ones show above.

All data transmitted to and from your Layer0 site must be secured with TLS (Transport Layer Security). TLS, also known as SSL (Secure Sockets Layer), is a cryptographic protocol to communicate securely over the Internet. TLS provides end-to-end data encryption and data integrity for all web requests.

Layer0 provides a wildcard TLS certificate that covers the auto-generated domains that it assigns to your site (e.g {team}-{site}-{branch}-{version}.layer0.link). You need to provide your own certificate for your site's custom domains.

Note: If you already have an existing certificate, you can use it by skipping ahead to Uploading your certificate. Many customers who have existing certificates still choose to obtain a new one when adopting Layer0 so as not to reuse the same private key with more than one vendor/system.

Layer0 can generate SSL Certificates on your behalf using Let's Encrypt. Certificates are free, valid for 3 months, and automatically renewed as long as the technical requirements, shown below, remain met:

  1. Make sure each environment is configured with the custom domains on which it will receive traffic. For more information on configuring custom domains, see Domains above.

  2. Using your DNS provider, verify and possibly add a CAA record to allow Let's Encrypt to generate certificates for your domains.

    The CAA DNS entries of a domain behave like a whitelist to indicate wheither any or only certain Certificate Autorities are allowed to generate certificates for that domain.

    If there are no CAA records, it means that any Certificate Authority is allowed to generate certificates for that domain.

    If there are CAA records, it means that only certain Certificate Authorities are allowed to generate certificates for that domain.

    So in order for Let's Encrypt to be able to generate a certificate for your domains, you must either not have defined any CAA records, or Let's Encrypt's CAA entry must be among those defined in the list of CAA records.

    You can verify the value of the CAA records for your domain from the command line using the command below.

    # Run the following command
    dig caa +short <your-apex-domain>
    
    # Example
    dig caa +short mywebsite.xyz

    Example of a CAA query showing that only certain Certificate Authorities are allowed to generate certificates for that domain:

    0 issue "amazon.com"
    0 issue "digicert.com"
    0 issue "globalsign.com"
    0 issue "letsencrypt.org"

    If the result of the CAA DNS query is empty, it means that any Certificate Authority is allowed to generate certificates on that domain. If so, you can directly go to the next step.

    If there are already some CAA DNS entries defined on your domain, and if Let's Encrypt's CAA entry is not among those, you will have to add an additionnal CCA entry for Let's Encrypt.

    To do so, log into your DNS provider, and add a CAA type DNS record with the following values:

    • Type : CAA
    • Name : empty (or @, depending on the DNS provider)
    • Flags: 0
    • Tag: issue
    • Value: letsencrypt.org (or "letsencrypt.org")

    Example with GoDaddy:

    CAA Record on GoDaddy

    Example with Gandi:

    CAA Record on Gandi

    You can use the following links to see how to configure the CAA record on commonly used DNS providers:

    Once the DNS entry has been added, you can verify the CAA record using one of the following:

    Notes:

    • Many DNS providers have already added this CAA DNS record by default
    • Some DNS providers does not allow the creation of CAA DNS records and therefore allow any Certificate Authority to generate certificates
    • You can learn more about CAA DNS records on Let's Encrypt website, on Wikipedia, on Gandi and on eff.org
  3. Add an _acme-challenge. CNAME DNS entry to allow Layer0 to issue a certificate request on your behalf.

    Log into your DNS provider and add one CNAME type DNS entry with the value _acme-challenge.<your-domain-here> for each domains you use on your Layer0 website. For example, if your domain is mywebsite.xyz, the DNS entry should have a value of _acme-challenge.mywebsite.xyz. This record should point to _acme-challenge.xdn-validation.com. Repeat the operation of each domain associated with your Layer0 website.

    Example with Godaddy:

    ACME Challenge Record on GoDady

    Example with Gandi:

    ACME Challenge Record on Gandi

    Once the DNS entries have been added, you can use one of the following to verify that they are correctly configured:

    You can also verify the CNAME records using the command line:

    # Run the following 'dig' command to verify the presence of the '_acme-challenge.' CNAME :
    dig +short cname _acme-challenge.<your-domain>
    
    # For example:
    dig +short cname _acme-challenge.mywebsite.xyz

    Expected result for the DNS query:

    _acme-challenge.xdn-validation.com.

    If you use multiple domains for your website, like mywebsite.xyz and www.mywebsite.xyz, you will have to make sure that the _acme-challenge DNS record has been added for both domains:

    _acme-challenge.mywebsite.xyz -> _acme-challenge.xdn-validation.com.
    _acme-challenge.www.mywebsite.xyz -> _acme-challenge.xdn-validation.com.

    If you have been previously using Let's Encrypt to generate certificates for this domain, please verify that there are no remaining TXT records named _acme-challenge.mywebsite.xyz.

    Notes:

  4. Once the requirements above are met, you can generate the certificate using the Layer0 Developer Console:

    1. Select your site and navigate to Settings => SSL Certificate

    2. Verify the state of your certificate (you should see that there's no certificate provided yet for your website):

    ssl-generation-01

    1. Click on the Generate SSL Certificate button:

    ssl-generation-02

    1. After a couple of minutes, you should see that your website has received a valid certificate:

    ssl-generation-03

TLS certificates are issued by Certificate Authorities (CA) based on Certificate Signing Request (CSR) that they receive from you. Alongside the CSR the same process creates certificate's private key. You only need to share your CSR with CA, not the private key which you should store securely.

The following steps describe the creation of the CSR and private key with OpenSSL. OpenSSL is an open-source toolkit for the TLS protocol. We recommend using OpenSSL because it ensures that your private key will only be stored locally on your infrastructure. Your CA may to have more customized guides or entirely customized certification process.

To create CSR and private key do the following:

  1. Open your terminal window and make sure that you have OpenSSL installed:
  • On MacOS you can install it by using brew package manager (e.g. brew install openssl)
  • On Windows you can install it by using Chocolatey package manager (e.g. choco install openssl)
  • On Linux/Unix you can install it by running the built-in OS package manager (e.g. apt-get install openssl, apk add openssl and so on)
  1. Go to the directory of your choice and create a configuration file layer0.conf based on this template:
[req]
default_bits=2048
distinguished_name = req_distinguished_name
req_extensions = v3_req

[req_distinguished_name]
countryName=Country Name (2 letter code)
countryName_default=US
stateOrProvinceName=State or Province Name (full name)
stateOrProvinceName_default=California
localityName=Locality Name (e.g. city)
localityName_default=San Francisco
organizationName=Organization Name (e.g. company)
organizationName_default=YourCompanyName
commonName=Fully Qualified Domain Name (FQDN) e.g. www.your-company-name.com
commonName_default=www.your-company-domain.com

[ v3_req ]
subjectAltName=@alt_names

[alt_names] # Other domains: apex domain, wildcard domain for staging and dev, and so on
DNS.1=*.your-main-domain.com
DNS.2=*.your-dev-domain.com
DNS.3=your-apex-domain.com
# And so on

Replace the country, state/province, locality, organization name and, most importantly Common Name (CN), for the cert which must be the fully qualified domain name for your domain (e.g. for Layer0 that is www.layer0.co)

You will want to add all the additional domains into the alt_names section. There you should add your development, staging and other domains although Layer0 strongly encourages the use of wildcard certs.

  1. Run openssl req -out layer0.csr -newkey rsa:2048 -nodes -keyout layer0.key -config layer0.conf -batch. This should generate your CSR in layer0.csr and private key in layer0.key. If you want OpenSSL to ask you for each different input, remove -batch option and re-run the command.
  2. Verify your CSR contains the expected domains by running openssl req -in layer0.csr -noout -text | grep DNS
  3. Read the CSR (e.g. cat layer0.csr) or copy to your clipboard (on OSX cat layer0.csr | pbcopy) and send it to your CA for certification.

To upload your SSL certificate, navigate to the Settings tab on your site and

ssl

Then, scroll down to SSL Certificate. Note that you need to be in the Admin role on your team and your team needs to be upgraded to Layer0 Enterprise to see this section:

empty-certificate

Layer0 needs three things to correctly host your certificate:

  • Certificate issued by CA
  • Intermediate certificates (IC) used by CA including CA's signing certificate
  • Private key that was generated at the same time with CSR

The private key part is non-public data and must not be shared with parties other than Layer0. Layer0 stores your private key securely at rest. It is never shown in the developer console and only used to provision parts of the infrastructure that are used to terminate TLS connections.

You need to copy the certificate, intermediate certificates and the private key into the corresponding edit boxes and, once done, click on "Save Changes" button. This will change the status of your certificate to "Activation in Progress".

in-progress-certificate

Note that the certificate activation should take a few minutes. If you don't see the following within the hour, please contact support. Once activated, you should see the following:

activated-certificate