Deploying a static website in a fault-tolerant configuration in Yandex Cloud

This guide provides multiple solutions for deploying a fault-tolerant static website with dynamic elements (such as a registration or application form, etc.) in the Yandex Cloud infrastructure.

These solutions optimize costs and ensure high loading speeds for the website’s end users.

Solution architecture overviewSolution architecture overview

The core infrastructure components in all solutions are Yandex Object Storage and Yandex Virtual Private Cloud. Yandex Cloud CDN ensures fast content delivery to end users. Also, different solutions rely on various combinations of other services within the Yandex Cloud ecosystem, such as Yandex Cloud DNS, Yandex Certificate Manager, Yandex API Gateway, Yandex Application Load Balancer, Yandex Cloud Postbox, and Yandex Cloud Functions.

Fault tolerance is achieved through automatic replication of data stored in Object Storage buckets, as well as optional bucket versioning.

The proposed solutions offer the following benefits:

• You do not need to plan simultaneous fault-tolerant website deployments across multiple availability zones. All services natively provide high availability and fault tolerance.
• Streamlined architecture.
• Lower costs compared to other hosting solution with an option to use free tier which allows you to host low-traffic and low-data projects almost entirely for free.

Automatic infrastructure deploymentAutomatic infrastructure deployment

This tutorial includes supplemental Terraform configuration examples that allow you to accelerate your cloud infrastructure deployment. These examples provide ready-to-use solutions for common tasks, such as:

• Uploading and updating static website files in Object Storage.
• Creating a Let's Encrypt certificate for the website in Certificate Manager.
• Setting up Yandex Cloud Postbox to send transactional emails.
• Integrating a function from Cloud Functions to send emails and an example of such a function for Node.js.

You can find the supplemental materials in the yc-object-storage-cdn-static-site GitHub repository.

Solution overviewSolution overview

Depending on your website’s requirements, the system architecture of the solutions can vary significantly. However, all hosting options require a custom domain name for the website, a correctly configured DNS for the domain, and an SSL certificate.

This overview describes the following static website hosting solutions in the Yandex Cloud infrastructure:

• Yandex Object Storage bucket with public access
• Public Yandex Object Storage bucket with Yandex Cloud CDN content delivery
• Yandex Object Storage bucket without public access with Yandex API Gateway and content delivery via Yandex Cloud CDN
• Yandex Object Storage bucket without public access with Yandex Application Load Balancer

Yandex Object Storage bucket with public accessYandex Object Storage bucket with public access

Yandex Object Storage buckets feature a dedicated Hosting mode, which is one of the simplest and most affordable ways to host a static website in Yandex Cloud. Smaller projects may also be eligible for a free tier, as an additional benefit. For more information about the Object Storage free tier, see this Yandex Cloud Billing article.

Here is a diagram that illustrates the solution:

Required resourcesRequired resources

To host a static website using this solution, you need:

• Object Storage bucket with enabled Hosting mode.
• Domain name and its associated SSL certificate.
• Public DNS zone configured for your domain and a resource record mapping the bucket to your domain name.

For a step-by-step guide on setting up a static website using a public Object Storage bucket with enabled Hosting, see Static website in Yandex Object Storage.

Pros and consPros and cons

Other deployment options can help overcome the above constraints.

Implementation considerationsImplementation considerations

When deploying a website, consider the following:

• The type of the DNS resource record mapping a domain name to a bucket depends on the domain level:

  • For second-level domains, e.g., example.com, create an ANAME resource record.
  • For third-level domains and higher, e.g., my.example.com, my.other.example.com, etc., create a CNAME resource record.

  Note

  The resource record must always point to the bucket's service domain.

  For example, for the my.example.com domain in the example.com public DNS zone, create a my CNAME record pointing to my.example.com.website.yandexcloud.net..

  You must include the trailing dot; omitting it will take your website down.

  For more information on how to create a resource record, see Creating a resource record.

• Object Storage is integrated with Certificate Manager, which supports both custom and Let's Encrypt certificates.

  When creating a Let's Encrypt certificate, verify your domain ownership. The most reliable and convenient way is DNS verification via a CNAME record. This is a one-time check that requires no further user actions for certificate renewal.

  For more on how to pass domain ownership verification, see Verifying domain ownership.

• The Hosting mode requires public access to the bucket and unlocks several additional features.

  Additional bucket features in Hosting mode

  • Requests to the / path return the file contents specified in the Home page parameter.

  • Requests to non-existent objects return the file contents specified in the Error page parameter.

  • Support for request redirection.

  • Service domain natively supports https to handle requests to the main domain.

  • Service domain of a bucket in Hosting mode: website.yandexcloud.net.

    Note

    When the Hosting mode is disabled, the bucket uses the storage.yandexcloud.net service domain.

• If a bucket domain name contains dots, https access to the bucket's service domain in <domain_name>.website.yandexcloud.net format is not possible. The service domain in this format uses a wildcard SSL certificate that only supports fourth-level domains (*.website.yandexcloud.net).

  To access the bucket's service domain over https in this scenario, use a URL in https://website.yandexcloud.net/<domain_name> format.

  Here is an example: https://website.yandexcloud.net/my.example.com.

• You can restrict access to the bucket contents using bucket policies. However, these policies may have practical limitations. For example, you can restrict access to bucket contents for specific IP ranges but not for domain names.

  For more on how to configure a bucket policy, see Managing a bucket policy.

• When uploading objects to a bucket, you can set headers to control how your content is processed. For example, the Content-Type header allows you to explicitly define the content’s MIME type.

  There are more headers you can set for Object Storage bucket objects to customize how browsers process your content.

  Common headers

  • Content-Type: Defines the MIME content type of the bucket object.

  • Cache-Control: Manages client-side caching and on intermediary caching servers. Customizing client-side caching settings may considerably improve page load speed and reduce traffic consumption.

    Warning

    Use caution when defining caching settings via the Cache-Control header, especially for HTML pages. If a client caches a corrupted page for a long period, the browser will display incorrect information until the cache expires or the user clears it manually.

  • Content-Disposition: Instructs the browser to save the object as a local file and sets the default file name.

  • Content-Encoding: Indicates the file’s encoding method, e.g., gzip compression.

  For more on how to set headers for bucket objects, see Troubleshooting.

TroubleshootingTroubleshooting

yc storage s3api put-object \
  --bucket my.example.com \
  --key index.html \
  --body /path/to/my/index.html \
  --content-type 'text/html'

variable "site_source_dir" {
  type        = string
  description = "Site source directory" # Local directory with website files
  default     = "~/path/to/my/site"     # Use the pathexpand() function to handle ~ and other special characters 
}

locals {
  site_mime_types = jsondecode(file("mime.json")) # File with a table mapping file extensions to Mime types
}

resource "yandex_storage_object" "files" {
  for_each     = var.site_source_dir == null ? toset([]) : fileset(pathexpand(var.site_source_dir), "**") # Going through all folder files recursively
  bucket       = "my.example.com"
  key          = each.key
  source       = pathexpand("${var.site_source_dir}/${each.key}")
  source_hash  = filemd5(pathexpand("${var.site_source_dir}/${each.key}")) # Storing file digest in state to trigger file updates when content changes
  content_type = lookup(local.site_mime_types, regex("\\.[^.]+$", each.key), null) # Assigning Content-Type dynamically based on the file extension
}

{
  ".html": "text/html",
  ".htm": "text/html",
  ".shtml": "text/html",
  ".css": "text/css",
  ".xml": "text/xml",
  ".gif": "image/gif",
  ...
}

Public Yandex Object Storage bucket with Yandex Cloud CDN content deliveryPublic Yandex Object Storage bucket with Yandex Cloud CDN content delivery

In this solution, a bucket in hosting mode serves as an origin for a Cloud CDN resource. A CNAME resource record maps your website domain name to a special CDN provider domain name assigned to the user cloud folder in Yandex Cloud.

The CDN resource caches end-user requests on its servers and queries the origin bucket only when the requested file is missing from the cache.

The main advantage of CDN is geographical distribution. CDN points of presence are located in major cities in close proximity to your primary content consumers. Content caching and reducing the distance between the client and the CDN server accelerates website loading speed in the end user's browser.

Here is a diagram for a fully static website:

Required resourcesRequired resources

To host a static website using this solution, you need:

• Object Storage bucket with enabled Hosting mode.
• Cloud CDN resource.
• Domain name and its associated SSL certificate.
• Configured public DNS zone for the domain and a resource record mapping the CDN resource to your domain name.

For more information on how to create a CDN resource, see Creating a resource.

Pros and consPros and cons

Therefore, if your website's content is cache-friendly, which static websites usually are, and you configure hosting with SEO in mind, you can achieve significant savings in traffic delivery costs, maximize your website's availability to end users, and, as a result, considerably improve the overall customer experience.

TroubleshootingTroubleshooting

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Mailer API
servers:
- url: https://d5dglu90r7y0********.wm******.apigw.yandexcloud.net
paths:
  /register:
    x-yc-apigateway-cors:
      origin:
        - https://my.example.com
      methods:
        - POST
    post:
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: d4edj6bo1uy0********
        service_account_id: ajekjkm28y0********

Yandex Object Storage bucket without public access with Yandex API Gateway and content delivery via Yandex Cloud CDNYandex Object Storage bucket without public access with Yandex API Gateway and content delivery via Yandex Cloud CDN

In some scenarios, you may need to restrict access to the entire bucket or its part. For example, if your website must contain both a public section, accessible to all visitors, and a private section, accessible only to authorized users.

One way to implement this scenario is to use API Gateway and its extensions.

Here is a diagram that illustrates the solution:

Required resourcesRequired resources

To host a static website using this solution, you need:

• Object Storage bucket with Hosting mode disabled.
• API Gateway.
• Cloud CDN resource.
• Domain name and its associated SSL certificate.
• Configured public DNS zone for the domain and a resource record mapping the API gateway service domain to your domain name.

In this solution, you do not need to assign a name to the bucket that matches the domain name. End users will not access the bucket directly, but through an API gateway associated with your domain name.

For more information on how to create an API gateway, see Creating an API gateway.

Pros and consPros and cons

This static website hosting option is not suitable for private corporate portals with access via VPN or Yandex Cloud Interconnect. The API gateway always uses a public IP address and does not have native tools to restrict access by IP address.

Implementation considerationsImplementation considerations

Since you cannot enable the Hosting mode for a non-public bucket, configure request forwarding instead. Make sure to properly configure root page / request processing so that such requests return the contents of your website's main page (typically the index.html file). Additionally, set up an error page to return together with 4xx code responses.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Mailer API
servers:
- url: https://d5dglu90r7y0********.wm******.apigw.yandexcloud.net
- url: https://my.example.com
paths:
  /:
    get:
      summary: Serve root page
      parameters:
        - name: file
          in: path
          required: true
          schema:
            type: string
      x-yc-apigateway-integration:
        type: object_storage
        bucket: mysecretbucket0x7adfbu
        object: index.html
        error_object: 
          object: 404.html
          statusCode: 404
        service_account_id: ajebg5lgngy0********
  /{file+}:
    get:
      summary: Serve static site content
      parameters:
        - name: file
          in: path
          required: true
          schema:
            type: string
      x-yc-apigateway-integration:
        type: object_storage
        bucket: mysecretbucket0x7adfbu
        object: '{file}'
        error_object: 
          object: 404.html
          statusCode: 404
        service_account_id: ajebg5lgngy0********

For more information on how to update API gateway settings, see Updating an API gateway.

TroubleshootingTroubleshooting

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Mailer API
servers:
- url: https://d5dglu90r7y0********.wm******.apigw.yandexcloud.net
paths:
  /register:
    x-yc-apigateway-cors:
      origin:
        - https://my.example.com
      methods:
        - POST
    post:
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: d4edj6bo1uy0********
        service_account_id: ajekjkm28y0********

Yandex Object Storage bucket without public access with Yandex Application Load BalancerYandex Object Storage bucket without public access with Yandex Application Load Balancer

To create a static website based on a non-public Object Storage bucket, you can use an L7 load balancer.

L7 load balancers automatically scale as load increases by creating new resource units, which ensures significantly higher performance compared to API Gateway.

Required resourcesRequired resources

To host a static website using this solution, you need:

• Object Storage bucket with Hosting mode disabled.
• Application Load Balancer (L7).
• Domain name and its associated SSL certificate.
• Configured public DNS zone for the domain and a resource record mapping the IP address of the L7 load balancer listener to your domain name.

In this solution, you do not need to assign a name to the bucket that matches the domain name. End users will not access the bucket directly, but through an API gateway associated with your domain name.

For more information on how to create an L7 load balancer, see Creating an L7 load balancer.

Pros and consPros and cons

Implementation considerationsImplementation considerations

When implementing this solution, consider the following Application Load Balancer features:

• There are fees for load balancer resource units. As the load on your website grows, the number of resource units may increase as per scaling rules, which increases your costs.

  Tip

  To cut costs for a public website, connect a CDN resource that allows caching of incoming website requests. Implement shielding of CDN resource origins to further improve the solution's performance by adding an extra caching layer.

  Note that internal load balancers do not support Yandex Cloud CDN caching.

  For more information on how to create a CDN resource, see Creating a resource.

• Since you cannot enable Hosting on a non-public bucket or a bucket with access via a service connection, make sure to properly configure root page / request processing on the load balancer side: such requests must return the contents of your website's main page (typicallyindex.html file).

  For more information on how to configure request processing in a load balancer, see Updating HTTP router settings.

• L7 load balancer does not create additional (service) domains.

TroubleshootingTroubleshooting