Service Topologies

Last Updated October 2014

A service’s topology describes the service’s architecture and defines how the service scales. There are three different topologies available: Single, Redundant, & Cluster. This doc explains each and provides information about what topologies are available to each service type. After reading it, you should be familiar with:

  • Single, Redundant, & Cluster Topologies
  • Defining a Service’s topology
  • What topologies are available for each service type

Available Service Topologies

There are three service topologies available on Pagoda Box: Single, Redundant, & Cluster. Each topology provides certain benefits and scaling options.


Services with the “Single” topology consist of a single instance and can be scaled vertically.


The "Redundant" topology, as the same suggests, provides a redundant architecture for services through multiple instances and Master-Master or Master-Slave replication (depends on the service type). Redundant services consist of two "data-housing" instances along with a third "monitor" instance. The monitor manages the replication/sync process between the primary instances, ensuring data stays in sync.

This mutli-instance architecture provides both hardware failover and "hot-failover." If the primary instance becomes unresponsive, it will immediately failover to the 2nd instance. Instances in any multi-instance service, are purposely placed on separate physical machines. If there is ever a hardware issue, the unaffected instance will automatically begin handling requests.

Instances within a redundant service can be scaled vertically.


Services with the "Cluster" topology consist of multiple instances all working together as one. These are ideal for web services, allowing you to increase your service’s ability to handle concurrent traffic through horizontal scaling as well as supply instances with more power through vertical scaling. Some data services also support the cluster topology, providing the same kind of scaling functionality.

Defining Your Topology

Topologies can be defined when creating a service either in your dashboard or in your Boxfile. They can also be changed in your Dashboard.

In the Dashboard

Data services can be created in your dashboard. Selecting your service’s topology is part of the service creation process.

Simply add a new data service, select your service type, name your service (optional), then select your topology.

In the Boxfile

Each service config in the Boxfile has a topology option. When creating a service from your Boxfile, the service will be created with the specified topology (if available for the service type).

Defining Topologies in the Boxfile YAML

    type: php
    topology: cluster
    type: mysql
    topology: redundant
    type: redis
    topology: single

Boxfile Topologies Only Apply on Service Create

When defining a service's topology in your Boxfile, it only gets applied when the service is created. For existing services, changes to the topology Boxfile config are ignored.

Changing a Data Service's Topology

To make a manage the topology of a data service, click on the service in your dashboard to expand its options. Under the "Configure" tab, you'll see the current topology in the lower left. Click to expand the scaling options. Select the "Redundant" topology from the dropdown and click "Save Changes".

Updating a Data Service's Topology

Topology Availability Chart

Code Service Type Single Redundant Cluster
Database Type Single Redundant Cluster
Cache Type Single Redundant Cluster
Network Storage Type Single Redundant Cluster

If you have any questions, suggestions, or corrections, let us know.