Learn About Enhancing User Experience with Custom Error Pages in OCI Load Balancer

Generic HTTP error responses such as “502 Bad Gateway” are unhelpful and unbranded, degrading the user experience during outages. This playbook describes how to implement informative, branded custom error pages on Oracle Cloud Infrastructure (OCI) using Load Balancer and API Gateway. This approach preserves brand consistency (such as logo, colors, and messaging), provides actionable guidance (next steps or support contacts), and sustains user trust by presenting professional, user-friendly responses when downtime occurs.

Architecture

This architecture shows a simple example deployment of OCI components to implement an automated failover mechanism for displaying custom error messages.


Description of custom-error-lb-arch.png follows
Description of the illustration custom-error-lb-arch.png

custom-error-lb-arch-oracle.zip

This architecture functions as follows:

Normal Operation

  1. User Access: End-users access the application through an Internet Gateway via the OCI Load Balancer's public IP address.
  2. Traffic Distribution: The load balancer's application listener (Listener 1) receives this traffic and distributes it across the available healthy backend servers, which are OCI Compute virtual machine (VM) instances deployed in a private subnet.

Failure State: Activating the Maintenance Page

  1. Trigger: If all backend servers become unhealthy, a OCI Monitoring alarm is triggered.
  2. Action: This alarm triggers a notification, which activates an automated function (deployed with the serverless OCI Functions).
  3. Logic: The function parses the data from the alarm notification. If the notification contains the keyword OK_TO_FIRING (indicating a new failure), the function makes an API call to the load balancer.
  4. Result: The function's API call invokes an operation that attaches a "Maintenance-Page" ruleset to the application listener (Listener 1) of the load balancer. This new rule forces all incoming traffic to be redirected to a separate listener (Listener 2) that serves a user-friendly maintenance page.

Recovery State: Restoring Normal Service

  1. Trigger: When the backend servers recover and are healthy again, the OCI Monitoring service sends a new notification.
  2. Action: The same automated function in OCI Functions is triggered by this recovery notification.
  3. Logic: The function parses the new notification. If it finds the keyword FIRING_TO_OK, the function makes a different API call to the load balancer.
  4. Result: This API call removes the "Maintenance-Page" ruleset from the application listener. The normal traffic flow is immediately restored, allowing users to access the application.

This architecture supports the following components:

  • OCI region

    An OCI region is a localized geographic area that contains one or more data centers, hosting availability domains. Regions are independent of other regions, and vast distances can separate them (across countries or even continents).

  • OCI virtual cloud network and subnet

    A virtual cloud network (VCN) is a customizable, software-defined network that you set up in an OCI region. Like traditional data center networks, VCNs give you control over your network environment. A VCN can have multiple non-overlapping classless inter-domain routing (CIDR) blocks that you can change after you create the VCN. You can segment a VCN into subnets, which can be scoped to a region or to an availability domain. Each subnet consists of a contiguous range of addresses that don't overlap with the other subnets in the VCN. You can change the size of a subnet after creation. A subnet can be public or private.

  • Internet gateway

    An internet gateway allows traffic between the public subnets in a VCN and the public internet.

  • Load balancer

    Oracle Cloud Infrastructure Load Balancer provides automated traffic distribution from a single entry point to multiple servers.

  • OCI Compute

    With Oracle Cloud Infrastructure Compute, you can provision and manage compute hosts in the cloud. You can launch compute instances with shapes that meet your resource requirements for CPU, memory, network bandwidth, and storage. After creating a compute instance, you can access it securely, restart it, attach and detach volumes, and terminate it when you no longer need it.

  • OCI API Gateway

    Oracle Cloud Infrastructure API Gateway enables you to publish APIs with private endpoints that are accessible from within your network, and which you can expose to the public internet if required. The endpoints support API validation, request and response transformation, CORS, authentication and authorization, and request limiting.

  • OCI Functions

    Oracle Cloud Infrastructure Functions is a fully-managed, multitenant, highly scalable, on-demand, Functions-as-a-Service (FaaS) platform. It is powered by the Fn Project open source engine. OCI Functions enables you to deploy your code, and either call it directly or trigger it in response to events. OCI Functions uses Docker containers hosted in Oracle Cloud Infrastructure Registry.

  • OCI Monitoring

    Oracle Cloud Infrastructure Monitoring actively and passively monitors your cloud resources, and uses alarms to notify you when metrics meet specified triggers.

  • OCI Notifications

    OCI Notifications broadcasts messages to distributed components by using a low latency publish-subscribe pattern, delivering secure, highly reliable, durable messages for applications hosted on OCI.

  • Service gateway

    A service gateway provides access from a VCN to other services, such as Oracle Cloud Infrastructure Object Storage. The traffic from the VCN to the Oracle service travels over the Oracle network fabric and does not traverse the internet.

About Required Services and Roles

This solution requires the following services and roles:

  • Oracle Cloud Infrastructure

These are the roles needed for each service.

Service Name: Role Required to...
Oracle Cloud Infrastructure: Administrator Configure the OCI Load Balancer, OCI Monitoring, and OCI API Gateway, and create functions in OCI Functions.

See Oracle Products, Solutions, and Services to get what you need.