# Clusters

A **cluster** is a set of hosts that run one service together instead of separately. They share one
configuration, they know about each other, and you publish them as a whole. If one member stops
answering, the service continues on another member.

Working on a cluster looks exactly like working on a single host: the same workspace, the same tabs,
the same Save and Publish buttons. The difference is what is behind it - one configuration for two
or more servers instead of one.

Use a cluster when a service must stay available through the loss of a single server - for example a
database or a cache behind a busy storefront. If you only want to share settings such as SSH keys
across servers that stay independent, use a [group](groups.md) instead.

![The Clusters overview page, listing a cluster with its Manage button|1000](../assets/screenshots/platform/clusters_list.png)

This page covers:

- [Clusters and groups](#clusters-and-groups) - which one you need
- [Viewing clusters](#viewing-clusters) - the overview
- [Creating a cluster](#creating-a-cluster) - members and their order
- [The cluster workspace](#the-cluster-workspace) - the tabs and what differs from a host
- [One configuration, every member](#one-configuration-every-member) - where the settings live
- [Publishing a cluster](#publishing-a-cluster) - always as a whole
- [How failover works](#how-failover-works) - what the platform does when a member is lost
- [Editing and deleting](#editing-and-deleting-a-cluster)

## Clusters and groups

Both apply configuration to several hosts, but they answer different questions.

| | Group | Cluster |
| --- | --- | --- |
| What it is for | Sharing settings across independent servers | Running one service across several servers |
| The hosts | Stay separate servers, each with its own configuration | Act as one unit with one shared configuration |
| If one host fails | The others are unaffected, and the service on that host is down | The service continues on another member |
| Membership | A host can be in several groups | A host belongs to at most one cluster |
| You publish | The group, which deploys each member host | The cluster, always as a whole |

## Viewing clusters

Select **Clusters** in the sidebar, or open `/clusters`. The overview lists every cluster in the
account, with a search box above it and a `Create` button. Use **Number of Items** at the bottom to
show more clusters per page.

Each cluster has its own page at `/clusters/{cluster}`.

> [!TIP]
> A read-only `Source (YAML)` view of a cluster is available at `/clusters/yaml/{cluster}`. The
> `GUI` button in the cluster header switches between the two.

## Creating a cluster

1. Go to `/clusters` and select `Create`.
2. Enter a name for the cluster.
3. Select `Add host`, choose the server under **Select a host**, and give it a position under
   **Select order**. Repeat for each member: you add the next row after filling the previous one.
4. Confirm to create the cluster and open it.

The order matters, and it decides more than the display: **the first member is the cluster's
primary**, and its configuration becomes the cluster's configuration. See
[One configuration, every member](#one-configuration-every-member).

`Edit` on the cluster reopens the same fields, so you can check the membership and the order at any
time:

![The cluster's members and their order, with test1.example.com first and test2.example.com second|1000](../assets/screenshots/platform/clusters_members.png)

> [!NOTE]
> A host can belong to only one cluster. Adding a host that is already a member of another cluster
> moves it.

## The cluster workspace

A cluster page is the host workspace. The same tab strip, the same header with `Save`,
`Save & Publish`, `Edit`, `Delete`, the Source view and the history. There is one difference: there
is **no Backups tab**, because backups are configured per host.

![A cluster opened in the same workspace a host uses, with the full tab strip|1000](../assets/screenshots/platform/clusters_detail.png)

Three tabs behave differently on a cluster:

| Tab | On a cluster |
| --- | --- |
| [Health](hosts/health.md) | The combined health of every member, rather than one server. |
| [Threat Center](hosts/threat-center.md) | The security findings of every member together. |
| [Credentials](hosts/credentials.md) | Grouped per member, so you can see which credential belongs to which server. |

The remaining tabs - [Applications](hosts/applications/index.md),
[Services](hosts/services.md), [Advanced](hosts/advanced/index.md), Groups,
[SSH](hosts/ssh.md) and [Security](hosts/security.md) - configure the cluster as one unit. What you
set there applies to every member.

## One configuration, every member

A cluster does not hold a copy of the configuration per server. **The configuration of the primary
member is the cluster's configuration**, and every member is deployed from it. That is what makes
the members behave as one machine rather than as two servers that happen to be similar.

You can read it in the `Source (YAML)` view, which shows one document for the whole cluster:

![The Source view of a cluster, showing the single YAML configuration every member is deployed from|1000](../assets/screenshots/platform/clusters_source.png)

This has three practical consequences.

- **Edit on the cluster, not on a member.** A change made on one member alone is not what the
  cluster deploys, and the next publish of the cluster replaces it.
- **Changing the order changes which configuration is authoritative**, because the primary changes
  with it. Set the order when you create the cluster and leave it alone afterwards.
- **The members are aware of each other.** The platform knows the full membership, which is what
  lets a service address move between them.

> [!IMPORTANT]
> A setting made on a single member is temporary. Publish the cluster and the shared configuration
> wins.

## Publishing a cluster

Saving stores the configuration; **publishing** applies it to the member servers. The buttons sit in
the cluster header, and work as they do on a host.

| Action | What it does |
| --- | --- |
| `Save` | Stores the cluster configuration. Nothing is applied to the members yet. |
| `Save & Publish` | Saves and starts a deployment across the cluster. |
| `Save & Full Publish` | In the menu next to `Save & Publish`. Re-applies the whole configuration on every member. |

> [!WARNING]
> Always publish the complete cluster. Deploying a single member as though it were an independent
> server leaves the members disagreeing about who runs the service, which is exactly the situation a
> cluster exists to prevent.

## How failover works

You do not configure any of this - the platform sets it up when the cluster is deployed. It helps to
know what it does.

- **One member holds the service at a time.** The address that applications connect to is not tied
  to one server. It moves to whichever member is currently running the service, so applications keep
  using the same address.
- **The members check each other continuously.** When the member holding a service stops responding,
  another member takes it over.
- **A member that loses contact with the rest stops itself.** Rather than risk two members serving
  different data, a member that can no longer reach the others restarts instead of continuing alone.
- **A failed service is retried, not abandoned.** After a failure, the service becomes eligible to
  run on that member again a few minutes later, so a member recovers on its own once the underlying
  problem is fixed.

> [!NOTE]
> A cluster decides by majority, so an odd number of members can settle it among themselves. A
> cluster with an even number of members needs one extra vote from outside the cluster, which
> Hosted Power provides. This is arranged when the cluster is set up.

## Editing and deleting a cluster

`Edit` in the cluster header changes the cluster name and its membership. `Delete` removes the
cluster.

> [!WARNING]
> Deleting a cluster cannot be undone. Its member hosts stay, but they are no longer configured or
> published together, and the service no longer moves between them. Take a
> [backup](hosts/backups.md) of the members first.

## Related

- [Groups](groups.md) - shared settings across independent hosts
- [Managing hosts](hosts/index.md)
- [Publishing changes](hosts/publishing.md)
- [Health](hosts/health.md) and [Threat Center](hosts/threat-center.md)
- [Credentials](hosts/credentials.md)