Skip to content


The term "Cluster" refers to any Kubernetes cluster you register with Statehub. Once a cluster is registered with your Statehub organization, it will be able to access your Statehub states and volumes.

Statehub allows you to register multiple clusters in various geographic locations and cloud vendors, and to easily move your stateful applications between them.

Cloud Permissions

Statehub requires that pods on your cluster could perform a mininal set of operations on your cloud account, to enable your clusters to access the states and volumes. These operations revolve around provisioning Private Link endpoints, and allowing outbound connections through them to the Statehub service.

On AWS, these permissions are:

On Azure, the Network Contributor role at the cluster's resource group scope is required.

During cluster registration, the Statehub CLI will verify the sufficient permissions are granted to the nodes by default. If they are not, you will be requested to create a service principal, by either creating a CloudFormation stack (on AWS) or running a CloudShell script (on Azure).

Registering a Cluster

Registering clusters is done with the Statehub CLI. The CLI is aware of your Kubernetes configuration contexts, and which context is being currently being used. Most CLI commands operate on the current context.

To register the cluster associated with the current context with the default settings, run:

statehub register-cluster

When you register a cluster, the following things happen:

  1. Statehub will verify it has sufficient permissions to create and configure the necessary network components to access the Statehub service in the cluster's locations. If not, you will be prompted with instructions to create a service principal, depending on the cloud vendor the cluster is running on. You will be requested to paste the output of the cloud-specific operation, that will contain the service principal credentials that will be stored as a secret on the cluster.

    You can skip the permission verification by running, if you are certain the nodes have the necessary permissions to perform the needed network operations:

    statehub register-cluster --skip-permissions

    You can also provide credentials for a service principal with the necessary permissions. This will skip the permission verification, and will store the service principal as a secret on the cluster:

    statehub register-cluster --service-principal {principalId}:{password}
  2. Statehub is made aware of the cluster and its locations.

    Statehub needs a name to refer to your cluster. The CLI will attempt to use the name of the current context as the name of the cluster. In order to override the cluster name and specify your own, add a name when running the command:

    statehub register-cluster my-cluster

    This for example, will register the cluster associated with the current context under the name my-cluster.

  3. A cluster token is generated for the cluster and save it in your cluster's secrets, so that your cluster can access the Statehub REST API.

  4. Several lightweight Statehub pods are started on the cluster using helm. They facilitate the communication between the cluster and the states in its locations.

    By default, all pods used by the Statehub system are created in the statehub-system namespace. This can be overridden by specifying the namespace explicitly:

    statehub register-cluster --namespace my-namespace

    This will create the namespace my-namespace and run all the Statehub system pods in it.

    In certain cases, such as advanced environment preparation, or troubleshooting, you might want to skip the installation of the Statehub Helm charts. In that case, you can run:

    statehub register-cluster --skip-helm

    You can later fetch the necessary the helm commands that would have run by getting the cluster information:

    statehub show-cluster
  5. The cluster's locations are added to the default state, if default state doesn't span thess locations yet. You can however, specify a list of states which either include or don't include default, to which the locations of this cluster should be added:

    statehub register-cluster --states state1 --states state2

    In this case, new locations, corresponding with the locations of the clusters, would be added to the states called state1 and state2, but not to the default state.

    You can also choose to not extend any of the states to the locations of the cluster you're registering by running:

    statehub register-cluster --no-state

    This will result in the cluster being able to access only the states that already span its location.

  6. Configure the default state's corresponding storage class ( as the default storage class.

    This is a convenience feature that allows you to deploy stateful applications without configuring the storage class for their persistent volume claims. You can choose a to set the storage class for a different state as the default by specifying:

    statehub register-cluster --default-storage-class state1

    This will set as the default storage class. If you want to leave the default storage class the same it was before you registered the cluster, run:

    statehub register-cluster --no-default-storage-class

Getting Registered Cluster Information

To get a list of all clusters:

  • Using the Statehub CLI:

    statehub list-clusters

    Output example:

    ☸            azure-us-east [azure/eastus2]
    ☸              aws-us-west [aws/us-west-2]
    ☸           aws-eu-central [aws/eu-central-1]

    In this example, we see three clusters, azure-us-east, aws-us-west, and aws-eu-central, located in Azure region EastUS2, AWS region us-west-2, and AWS region eu-central-1 respectively.

  • Using the Statehub Management Console:

    1. Go to

    Generating a Token

To show detailed cluster information:

  • Using the Statehub CLI:

    To show the details of the cluster associated with the current context (assuming the name of the cluster is the same as the name of the context), run:

    statehub show-cluster

    To show the details of a cluster by specifying its name, run:

    statehub show-cluster my-cluster

    Output example:

    Cluster:     aws-us-west
    Id:          7e74b235-3358-4afd-8786-ac44fde47ed5
    Locations:   aws/us-west-2
    Created:     3 days ago
    Modified:    now
    Helm install:
                  helm install statehub-csi-driver --namespace statehub-system --repo --version 1.0.25 statehub-csi-driver --set provider=eks
                  helm install state-controller --namespace statehub-system --repo --version 0.0.27 state-controller
                  helm install statehub-controller --namespace statehub-system --repo --version 0.1.7 statehub-controller
    Visible states:

    The output gives out the following information about the cluster:

    • Name
    • Unique ID in the Statehub system
    • A list of locations where the cluster has nodes
    • When was the cluster registered and modified
    • What helm commands and arguments were run or are necessary to install the Statehub components on the cluster
    • A list of states visible to the cluster (states available in the cluster's locations)


  • Using the Statehub Management Console:

    1. Go to{cluster-name}

Unregistering a Cluster

When you no longer want a cluster to have access to your Statehub organization and resources, you can unregister it. This operation will result in:

  1. Invalidation of the cluster's API token, so that the cluster is no longer able to communicate with Statehub
  2. Disconnection of the state from the cluster, by removing any networking components provisioned in your cloud account
  3. Removal of the states' CRDs and the associated storage classes the from the cluster
  4. Removal of the Helm charts with the Statehub components from the cluster

To unregister a cluster:

  • Using the Statehub CLI:

    Specify the name of the cluster you want to unregister, by running:

    statehub unregister-cluster my-cluster

    If running in a script or an automated process, you can skip confirmation with the -f flag:

    statehub unregister-cluster -f my-cluster
  • Using the Statehub Management Console:

    1. Go to
    2. Click on the cluster you want to unregister
    3. Click the "Unregister" button on the bottom of the page and confirm when prompted

Cluster Locations

Statehub supports clusters that are located in the public cloud (currently, AWS and Azure). In most cases, a cluster will be located in a single location – a specific region of a specific cloud (e.g., aws/us-west-1, azure/eastus2, etc.) In specific cases, a cluster can be installed in multiple locations, for example when a cluster spans multiple cloud vendors in the same geographical region.

Once a cluster is registred and the Statehub components on the cluster are running, it will report its location(s) to Statehub, so that it could be given access to the states and volumes available there.