---
title: How to add a custom domain to a function
description: Guide to adding a custom domain name to your Scaleway serverless function.
tags: functions custom-domain
dates:
  validation: 2025-09-01
  posted: 2022-02-21
---
import Requirements from '@macros/iam/requirements.mdx'

import image from './assets/cloudflare-root-domain-configuration.webp'

Each function comes with an automatically generated domain, on which it is available. However, it is possible to use your own domain name to address your function to facilitate their use.

<Requirements />

- A Scaleway account logged into the [console](https://console.scaleway.com)
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
- A [Serverless Function](/serverless-functions/how-to/create-a-function/) that is running
- Registered a domain name with the provider of your choice and have access to the domain name's DNS zone file

    If you are using **Cloudflare DNS**, see the note below regarding proxying.

1. On your domain provider's platform (for example, [Scaleway's domains](/domains-and-dns/how-to/manage-dns-records/)), add a CNAME record pointing to your function default URL in the domain's DNS zone file.

    <Message type="note">
      - All domains are supported.
      - When using a root domain:
          - If available, CNAME flattening is **mandatory**. [CNAME flattening](https://blog.cloudflare.com/introducing-cname-flattening-rfc-compliant-cnames-at-a-domains-root/) speeds up CNAME resolution and allows you to use a CNAME record at your root/apex domain. For example, for Cloudflare, this will look like the following:

          <Lightbox image={image} size="medium" alt="" />

          - If your DNS provider does not support CNAME flattening, you need to create an ALIAS on your root domain (named `@` or with an empty name) instead of a CNAME.
    </Message>
2. Before continuing, make sure the DNS entry is available. If not, the custom domain will likely end up in `error` on step 6. You can check this by:
    - running `dig`, `drill` or `nslookup` commands on your domain using common DNS resolvers `1.1.1.1` and `8.8.8.8`: `dig <your_custom_domain> @1.1.1.1`, `dig <your_custom_domain> @8.8.8.8`
    - or using a DNS check tool of your choice (some are available online)
3. Click the **Endpoints** tab on your functions' page.
4. Click **+ Add endpoint**.
5. Enter your custom domain name and validate the form.
    <Message type="note">
      Before being `ready`, some checks are performed. Refer to the [technical details](#technical-details) below to know more about these checks.
    </Message>
6.  Connect to your function through that custom domain once the custom domain status is `ready`.

## Technical details

Read this section if you want more details about how custom domains are handled.

When adding a custom domain, the following tasks are be performed on Scaleway's side:

1. We configure the custom domain on our gateways, so that they can handle traffic for that custom domain.
2. We ensure that the custom domain points to one of the Serverless Function existing endpoints: either the default one `....functions.fnc.<region>.scw.cloud`, or an existing custom domain.
3. If step 2 is OK, we generate a dedicated TLS certificate for that custom domain so it can respond to HTTPS requests.

    <Message type="note">
      During that step, the custom domain might be available in plain HTTP. But, it will be accessible in HTTPS only once this step is over.
    </Message>

During the configuration of a custom domain (`pending` status), callers will likely receive HTTP 404 errors, while our gateways are reconfiguring themselves.

The last 2 steps above are done simultaneously with a HTTP-01 challenge. If that challenge does not succeed after 3 minutes:

- The custom domain will be put in `error` status.
- The custom domain will not be reachable (in HTTP or HTTPS).
- No TLS certificate will be generated.

If the HTTP-01 challenge fails and the custom domain is in `error` status, see the dedicated [troubleshooting page](/serverless-functions/troubleshooting/custom-domain-in-error-status/).

## Migrating an active domain

Read this section if you are trying to migrate a domain that is already serving a live web application -- but not yet hosted on a Serverless Function -- and you are trying to migrate.

To clarify, let's take a concrete example:

- your web application is hosted on a Scaleway Instance, with the IP `51.15.x.x`
- you own a domain `mydomain.com`
- an `A` record is configured on `webapp.mydomain.com` and points to `51.15.x.x`
- when a client accesses `http://webapp.mydomain.com`, the request hits your Instance IP `51.15.x.x:80`
- you also have a running version of your web application hosted as a Serverless Function (only accessible using `example-webapp.functions.fnc.fr-par.scw.cloud`), and now you want your users to access this version from `http://webapp.mydomain.com`

Before adding the custom domain on your Serverless Function, you must change the DNS record to point to the Serverless Function endpoint:

- before: `webapp.mydomain.com` is an A record to `51.15.x.x`
- after: `webapp.mydomain.com` is a CNAME record to `example-webapp.functions.fnc.fr-par.scw.cloud`

By doing this, clients that already have the `webapp.mydomain.com` DNS record cached locally will continue to hit `51.15.x.x`, until the TTL expires. New clients (or those whose cache has expired) will start to hit `example-webapp.functions.fnc.fr-par.scw.cloud`. **However**, as long as the custom domain is not configured on the Serverless Function, these requests will end up in 404, because `webapp.mydomain.com` is not (yet) known in our infrastructure. Depending on your downtime tolerance (clients receiving 404) for a few minutes, there are 2 cases:

- downtime is acceptable or can be planned (e.g. during the night or when there is less traffic on your web application). In that case, after creating the CNAME record, and once you are sure DNS is available everywhere, create the custom domain on the Serverless Function. Once ready, requests to `http://webapp.mydomain.com` will hit your Serverless Function (no more 404).
- downtime is not acceptable. Unfortunately, this is not possible right now out-of-the-box. To serve requests from `webapp.mydomain.com`, our infrastructure must know it, so a custom domain has to be configured. However, for the custom domain to be configured, the DNS record must point to the Serverless Function endpoint, resulting in a chicken-and-egg problem. To handle such scenarios, a CDN can be configured to serve a cached version of your web application while the domain is being reconfigured (for example with [`stale-if-error`](https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Cache-Control#stale-if-error) option). If you choose this solution, be sure to disable caching on routes starting with `/.well-known/acme-challenge` to avoid issues described in the "Technical details" section.