Single Node Clusters

A Single Node Cluster — sometimes called a SingleNode cluster — is an individual server that ModStack treats as a self-contained Cluster. It is the simplest possible compute target: one machine, running your workloads, managed by ModStack.

Under the hood, ModStack implements Single Node Clusters using a single-box Kubernetes distribution — specifically minikube. This gives Single Node Clusters strong runtime compatibility with the production Kubernetes Clusters you would deploy to at scale: the same Service definitions, the same Module behavior, the same observability surface.

When to use a Single Node Cluster

Single Node Clusters are designed for situations where a full Kubernetes cluster would be more overhead than it is worth:

  • Small or low-traffic workloads where one server has plenty of capacity.
  • Edge deployments — a single appliance in a retail location, factory floor, or remote site.
  • Cost-sensitive environments where avoiding the control-plane footprint of Kubernetes matters.
  • Existing servers that you already own and want to put to work without provisioning a managed Kubernetes service.

BYOC only

Single Node Clusters are only available in BYOC (Bring Your Own Cloud) Projects. ModStack does not host single-server compute on your behalf — the server is yours, and you connect it to ModStack so we can orchestrate deployments and operations on it. The compute, network, and disk all live on infrastructure you own.

Hobby plan

Single Node Clusters are supported on the ModStack Hobby plan. Hobby users can deploy up to two servers for free, at no cost — making Single Node Clusters the natural starting point for side projects, personal tools, and small production workloads that do not yet justify a paid plan.

What runs on it

Functionally, a Single Node Cluster hosts the same things any other Cluster does:

  • Long-running Services defined by your application.
  • Scheduled jobs and background workers.
  • Ephemeral storage for workloads that need scratch space.
  • The supporting infrastructure ModStack installs to manage workloads — health probes, log and metric collection, rolling upgrades.

Service definitions and Modules are portable: a Service that runs on a Kubernetes Cluster runs the same way on a Single Node Cluster. The difference is the available capacity and the fact that there is no horizontal scheduler underneath — everything is constrained to the single host.

System requirements

ModStack assumes full ownership of any server you connect as a Single Node Cluster. The agent allocates and uses all cores and all RAM on the box, so the server should be dedicated to ModStack — nothing else should be running on it.

Supported operating systems

The only supported operating system at this time is Ubuntu Server LTS 26.04 or later. Other distributions are not supported.

Minimum resources

The minimum supported RAM is 4 GB. Of that, roughly 2 GB is reserved for the infrastructure ModStack runs on the box — the operating system, Docker, minikube, and the networking stack. The remainder is what is available to your Services and jobs. Provision more RAM than the minimum if your workloads are non-trivial.

Upgrading RAM and CPU

Because ModStack uses all of the cores and RAM on the box, growing a Single Node Cluster's capacity simply means giving the underlying machine more resources. This is a two-step process:

  1. Stop the server and resize it. Increase the CPU and RAM as you see fit. When the machine restarts, ModStack automatically detects and uses all of the RAM and CPU available on the box — no further configuration is needed for it to start using the extra capacity.
  2. Update the values in the Cluster UI. Once the machine is back up and running, navigate to the Cluster UI and update the RAM and CPU figures to reflect the new values, so that ModStack's view of the Cluster matches the resized machine.

OS patching

The Cluster UI exposes a Patch OS action that installs the latest security patches on the server. Once the patches have been applied, the server is automatically rebooted to complete the update.

Patching is deliberately conservative: only security updates are installed. No new packages are added, and the distribution is not upgraded to a new release — patching an Ubuntu Server LTS 26.04 box keeps it on 26.04. This keeps the action low-risk and predictable.

Because a Single Node Cluster is a single machine, the reboot takes your workloads offline for its duration. Schedule the Patch OS action inside a maintenance window for your application.

Infrastructure upgrades

From time to time, ModStack needs to upgrade the infrastructure components installed on the server — the Kubernetes distribution, the agent, and the surrounding system pieces. On Single Node Clusters this is a drop-and-replace upgrade rather than an in-place one: the existing infrastructure is removed and a fresh version is installed on top.

The practical consequence is that the server is down for the duration of the upgrade. The typical upgrade takes about 10 minutes.

Each infrastructure release is supported for 12 months. Within that window you can choose when to upgrade to the next release. If you have not upgraded by the end of the support period, the infrastructure will be automatically upgraded — so it is best to plan the upgrade for a maintenance window of your choosing rather than letting it happen on the support deadline.

Trade-offs

Because a Single Node Cluster is a single machine, it does not provide the high-availability or horizontal-scaling characteristics of a multi-node Kubernetes Cluster. Even if you deploy multiple instances of your Service, they are all ultimately running on this one machine — and therefore in the same availability zone. If the host fails, the workloads on it are unavailable until the host is recovered. For true multi-AZ high availability on production workloads, Kubernetes Clusters are the right choice.

That said, Hobby-plan users do not have to give up high availability entirely. ModStack's Disaster Recovery (DR) features can be used to pair two Single Node Clusters across different availability zones in an active-active configuration — giving you cross-AZ resilience without moving to Kubernetes.

When running in this HA configuration, OS patching and infrastructure upgrades on the two servers must be coordinated manually — operate on one server at a time and wait for it to come back healthy before touching the other. Otherwise both nodes can be down at the same time and the HA benefit is lost.