# Embedded Cluster overview (Beta)

This topic provides an introduction to Replicated Embedded Cluster.

## Overview

Replicated Embedded Cluster allows you to distribute a Kubernetes cluster and your application together as a single appliance, making it easy for enterprise users to install, update, and manage the application and the cluster in tandem. Embedded Cluster is based on the open source Kubernetes distribution k0s. For more information, see the [k0s documentation](https://docs.k0sproject.io/stable/).

Software vendors can configure the Embedded Cluster Config manifest to define characteristics of the cluster and the installation. For example, you can add optional Helm extensions to deploy components in the cluster before Embedded Cluster installs your application.

Embedded Cluster delivers the entire installation through a single binary. Running the binary launches a guided UI that walks end users through the full process: cluster configuration, preflight checks, node setup, and application deployment. Unlike previous Replicated installers where cluster infrastructure was set up on the command line before a separate UI handled the application, Embedded Cluster v3 brings everything into one guided experience. Upgrades work the same way, and Embedded Cluster automatically updates the cluster infrastructure alongside application updates so users can keep both current without needing to use kubectl.

## Limitations {#ec-limitations}

* Embedded Cluster v3 is Beta. The limitations and features are subject to change. For Replicated's definition of Beta, see [Support lifecycle policy](/vendor/policies-support-lifecycle).

* Embedded Cluster v3 (Beta) does not support disaster recovery.

* The following Replicated template functions are not supported in Embedded Cluster v3: `HasLocalRegistry`, `LocalRegistryAddress`, `LocalRegistryHost`, `LocalRegistryNamespace`, and `LocalImageName`. Use `ReplicatedImageName` and `ReplicatedImageRegistry` instead. See [Template Functions for Embedded Cluster](template-functions).

## Built-in extensions {#built-in-extensions}

The built-in extensions installed by Embedded Cluster include:

* **OpenEBS:** Embedded Cluster uses OpenEBS to provide local PersistentVolume (PV) storage. For more information, see the [OpenEBS](https://openebs.io/docs/) documentation.

* **Image registry:** Embedded Cluster installs an image registry where it pushes the images required to install and run the application.

Embedded Cluster installs each built-in extension in its own namespace.

## About installing with Embedded Cluster

Embedded Cluster supports installations in online (internet-connected) environments and air gap environments with no outbound internet access.

To install, users first download and extract the Embedded Cluster installation assets. Then, users can choose to follow a guided installation with the UI or a headless install with the CLI.

During installation, Embedded Cluster automatically runs preflight checks to verify that the installation environment meets the requirements. Users then configure the application and can optionally add nodes to the cluster before deploying.

For more information about how to install with Embedded Cluster, see:
* [Online Installation with Embedded Cluster](installing-embedded)
* [Air Gap Installation with Embedded Cluster](installing-embedded-air-gap)
* [Install with a customer-managed registry](installing-embedded-byo-registry)

## Deployment pipeline {#deployment-pipeline}

During both installation and upgrade, Embedded Cluster deploys components in a fixed, sequential pipeline. Each stage must complete before the next begins:

1. **Host preflight checks:** Verifies that the host meets requirements (disk space, memory, CPU, ports, hostname length).
1. **Kubernetes bootstrap:** Embedded Cluster installs and starts the k0s Kubernetes distribution.
1. **Built-in addons:** Installs infrastructure addons in a fixed order:
   1. **OpenEBS** (local PersistentVolume storage)
   1. **SeaweedFS** (S3-compatible object store, HA airgap clusters only)
   1. **Image registry** (internal image registry, airgap only unless using a customer-managed registry)
1. **Helm chart extensions:** Installs vendor-provided extension charts, sorted by `weight` (ascending). Charts with equal weights install in alphabetical order. See [extensions](embedded-config#extensions).
1. **Application preflight checks:** Runs vendor-defined preflight checks against the cluster.
1. **Application charts:** Installs the application's HelmChart custom resources, sorted by `weight` (ascending).

Each Helm chart (addons, extensions, and application charts) is installed with `--wait` and `--wait-for-jobs`, which means Helm hooks (`pre-install`, `post-install`, `pre-upgrade`, `post-upgrade`) run and must succeed before the next chart begins. This enables patterns like running database migrations in a Helm pre-upgrade hook Job.

Extensions install after built-in addons and before application charts. This provides a platform-then-infrastructure-then-application deployment order when combined with `weight`-based sorting within each tier.

## About upgrading with Embedded Cluster

Upgrades can be performed from the CLI on a controller. Alternatively, an opt-in [persistent admin console](embedded-persistent-console) can be installed on a controller to give end users a browser-driven upgrade experience without SSH access. The persistent admin console is not enabled by default.

For more information, see [Perform updates in embedded clusters](updating-embedded).

## Instance telemetry

Embedded Cluster installations automatically send telemetry data to the Vendor Portal. The Replicated SDK reports periodic instance data (application version, status, cluster info, and Embedded Cluster-specific data like the cluster ID, version, and node count), while the Embedded Cluster daemon sends lifecycle events in real time as installations, upgrades, and node joins occur. For air gap installations, the SDK stores telemetry locally for collection via support bundles.

For more information, see [About Instance and Event Data](/vendor/instance-insights-event-data).

## Embedded Cluster host preflight checks {#about-host-preflight-checks}

During installation, Embedded Cluster automatically runs a default set of _host preflight checks_. The default host preflight checks verify that the installation environment meets the requirements for Embedded Cluster, such as:
* The system has sufficient disk space, memory, and CPU cores
* Required kernel modules and network parameters are configured
* The ports that Embedded Cluster uses are available
* The system clock syncs

If any of the Embedded Cluster host preflight checks fail, Embedded Cluster stops and displays a message describing the failure. In the installer UI, the user can choose to continue past the failure. In a headless installation, the command exits unless `--ignore-host-preflights` is passed. For more information, see [Whether users can bypass a failed check](embedded-using#preflight-bypass).

The host preflight checks verify the requirements described in [Embedded Cluster installation requirements](installing-embedded-requirements). Ensure that the installation environment meets those requirements before you install.

### Add custom host preflight checks {#custom-host-preflight-checks}

To add your own host preflight checks, include a HostPreflight custom resource (`kind: HostPreflight`, `apiVersion: troubleshoot.sh/v1beta2`) in the release. Your checks run in addition to the default checks, during installation, during upgrades, and when a node joins the cluster.

Custom host preflight checks behave the same as the default checks. A failure stops the installation and displays a message describing the failure, and the user can bypass it the same way they bypass a default check.

To make a check that users cannot bypass, set `strict: true` on the analyzer, alongside `checkName`. Users cannot continue past a failed strict check from the UI or with `--ignore-host-preflights`, and the installation cannot proceed until the host meets the requirement.

Embedded Cluster honors strict checks in version 3.13.0 and later. In earlier versions, users can bypass a failed strict check.

Use custom host preflight checks to enforce requirements that are more restrictive than the defaults. You can also use them to verify application-specific host requirements, such as a required kernel module or connectivity to an external endpoint.

The following example adds a check for a host with at least six CPU cores:

```yaml
apiVersion: troubleshoot.sh/v1beta2
kind: HostPreflight
metadata:
  name: ec-host-preflights
spec:
  collectors:
    - cpu: {}
  analyzers:
    - cpu:
        checkName: Number of CPU cores
        outcomes:
          - fail:
              when: "count < 6"
              message: This server has less than 6 CPU cores
          - pass:
              message: This server has at least 6 CPU cores
```

Put all of your custom checks in a single HostPreflight resource. If a release contains more than one, Embedded Cluster uses the first and ignores the rest without reporting an error.

If your spec fails to parse, Embedded Cluster does not stop the installation. It runs the default checks, warns that it skipped your checks, and continues.

For more information about writing collectors and analyzers, see [Host Collectors](https://troubleshoot.sh/docs/collect/host-collectors/) and [Host Analyzers](https://troubleshoot.sh/docs/analyze/host-analyzers/) in the Troubleshoot documentation.

### Limitations

Embedded Cluster host preflight checks have the following limitations:

* The default host preflight checks for Embedded Cluster cannot be modified or removed. Custom host preflight checks run in addition to the defaults.
* Host preflight checks do not verify that the application meets any application-specific requirements. For more information about defining preflight checks for your application, see [Define Preflight Checks](/vendor/preflight-defining).

## Multi-node installations

Embedded Cluster supports installations in multi-node clusters. Your end customers can add nodes to a cluster during or after installation from the UI, the CLI, or the [external API](embedded-cluster-external-api).

Embedded Cluster automatically enables high availability (HA) when at least three controller nodes are present in the cluster.

For more information, see [Manage Multi-Node Clusters with Embedded Cluster](embedded-manage-nodes).