Managed Object Storage custom domains and static websites

A custom domain lets you reach a Managed Object Storage service through your own domain name, such as assets.example.com, instead of the service's upcloudobjects.com name. A static website serves the files in a bucket as a website, on a domain that the service provides or on a custom domain. You manage both on the service's Custom domains and Static websites tabs in the Control Panel, or with the UpCloud API. For step-by-step instructions, see How to configure a custom domain for Managed Object Storage and How to host a static website on UpCloud Object Storage.

Custom domain purposes

Each custom domain has a purpose, which you choose when you add it. The purpose can't be changed later, so to use a domain for the other purpose, delete it and add it again.

Through an S3 API domain, each file in a bucket has two URLs, https://<domain>/<bucket-name>/<file-path> and https://<bucket-name>.<domain>/<file-path>. Anyone can open them for files that are publicly readable. Other files need signed requests, so S3 tools such as the AWS CLI can use the domain as their endpoint.

DNS records

UpCloud doesn't host DNS for your domain, so you add the records at your DNS provider. For how DNS records work, see Domain Name System and how to manage DNS records.

Every custom domain needs three CNAME records. The Control Panel lists them with their exact values when you add the domain, and again under the domain's DNS button. For the domain assets.example.com on a service whose S3 endpoint is abcd1.upcloudobjects.com, they are:

The _acme-challenge record points to your account's challenge domain, which is the same for all your custom domains. With the API, GET /1.3/load-balancer/certificate-bundles/dns-challenge-domain returns it.

Add all three records before you add the domain, or straight after. The certificate can't be issued until all of them are in place.

Apex domains

Apex domains, such as example.com, work too. A CNAME record isn't allowed at the apex of a domain, so the Control Panel lists an ALIAS record for the domain itself instead. Use an ALIAS record if your DNS provider has them, or a CNAME record if your provider flattens CNAME records at the apex, as Cloudflare does. If your provider supports neither, use a subdomain such as www.example.com.

Cloudflare

If your DNS provider is Cloudflare, set all three records to DNS only. UpCloud can't get the certificate through proxied records.

Certificates

UpCloud gets a TLS certificate for each custom domain automatically. It covers the domain and the names under it, such as *.assets.example.com. The certificates are issued by ZeroSSL, whose certificates are signed by Sectigo. If your domain has CAA records, they must allow sectigo.com, as described in CAA records for automatically issued certificates.

While the certificate is being issued, the domain's status is Pending and the service goes through setup steps. The domain is ready to use once its status is Active and the service is Running again. In the API, the custom domain's details show "status": "active".

If a record is missing or wrong, or a CAA record doesn't allow sectigo.com, the certificate can't be issued. The domain's status in the API is then failed-challenge, and the service keeps going back to setup steps. Once the records are fixed, UpCloud tries again by itself.

Custom domains and static websites also answer requests over plain HTTP. They don't redirect them to HTTPS.

Domains you can use

• A service can have up to 5 custom domains.
• An S3 API domain can't be the parent or a subdomain of another custom domain, on the same service or on another one. For example, if assets.example.com is an S3 API domain, neither example.com nor cdn.assets.example.com can be added as a custom domain.
• Static website domains can be parents and subdomains of each other, such as example.com and blog.example.com, on the same service or on different ones.
• Domains that only share a parent, such as assets.example.com and www.example.com, can have either purpose, on the same service or on different ones.

Public access

Custom domains and static websites are reached over the service's public access. If you turn public access off, they stop working until you turn it back on. For details, see Connecting to Managed Object Storage.

Static websites

A static website serves the files in one bucket over HTTPS. Each service has its own static website domain, <service-id>-static.upcloudobjects.com, for example abcd1-static.upcloudobjects.com. A website can use it or a custom domain with the Static website purpose.

• Each domain has one website, so a service can have a website on its static website domain and one on each of its static website custom domains.
• A bucket can serve more than one website, for example on the service's domain and on your own.
• Names under a custom domain also show its website, through the domain's wildcard record. For example, a website on example.com is also served at www.example.com.
• A website's domain can't be changed. To move a website to another domain, create a new website on that domain and delete the old one.
• Deleting a website doesn't delete the files in the bucket.

Public read access

Visitors open the website without credentials, so the files must be publicly readable. You can make the whole bucket publicly readable, or only some of its files, as described in How to set up a public read bucket. Files that aren't publicly readable don't load on the website.

Routing

The index document, index.html by default, is served for the website's root and for any path that ends in /. For example, /docs/ serves docs/index.html. To serve the website from a folder in the bucket instead of the bucket's root, set a bucket prefix such as public/.

A website uses one of two routing modes:

• File-based routing serves the file that matches the path. A path without an extension also finds the matching .html file, so /about serves about.html. Paths that don't match a file return a 404 error.
• SPA mode is for single-page applications. Paths with a file extension, such as /app.js, serve that file. Every other path serves the index document, so the application's own router can handle it.

Error pages

By default, visitors who request a missing file get a standard error page. You can set your own error pages instead, each for a single status code such as 404 or for a range such as 400–499. A website can have up to 25 error pages. Each one names an HTML file in the bucket.

Caching

Files are served without a Cache-Control header unless they have one. To let browsers cache your files, set the header on the files when you upload them.

Turning a website off

A website can be turned off without deleting it. While it's off, its domain returns 503 Service Unavailable.