Install Nova with CLI

Overview

Purpose

This guide provides step-by-step instructions for installing Nova, a control plane and agent system designed to manage multiple Kubernetes clusters. By following this guide, you will set up the Nova Control Plane on a hosting Kubernetes cluster and deploy Nova Agents to workload clusters.

Scope

This guide covers:

• Prerequisites: Requirements before installing Nova.
• Installing novactl: How to download and set up the Nova CLI.
• Deploying Nova: Instructions for deploying the Nova Control Plane and Agents.
• Post-Installation Checks: Verifying the installation.
• Uninstalling Nova: Steps to remove Nova if needed.

Key Concepts

• Nova Control Plane: The central management unit running on a hosting Kubernetes cluster.
• Nova Agent: The component deployed to each workload cluster for management.
• novactl: The command-line interface (CLI) for installing, uninstalling and checking the status of a Nova deployment.
• Workload Cluster: A Kubernetes cluster managed by the Nova Control Plane.
• Hosting Cluster: A Kubernetes cluster where the Nova Control Plane runs.

Prerequisites

1. At least 2 Kubernetes clusters up and running. One cluster will be the hosting cluster where the Nova control plane runs. Other clusters will be workload clusters that are managed by the Nova control plane.
2. Installed and configured kubectl
3. Nova cannot be deployed to an Autopilot GKE cluster. Please validate that you are deploying to a non-Autopilot cluster.
4. Cluster hosting Nova Control Plane MUST have storage provisioner and default StorageClass configured. Nova Control Plane uses etcd as a backing store, which runs as a StatefulSet and requires a PersistentVolume to work.

Kubernetes compatibility

Nova Version	Kubernetes Versions Supported
v1.3	v1.31, v1.32, v1.33
v1.2	v1.30, v1.31, v1.32
v1.1	v1.29, v1.30, v1.31
v1.0	v1.29, v1.30, v1.31

Download novactl

novactl is our CLI that allows you to easily create new Nova Control Planes, register new Nova Workload Clusters, check the health of your Nova cluster, and more!

The novactl binary is included in the root directory of the Nova release tarball. If you don't have the release tarball, you can download the latest version of novactl for your operating system by running:

curl -s https://api.github.com/repos/elotl/novactl/releases/latest | \
jq -r '.assets[].browser_download_url' | \
grep "$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/i386/386/;s/aarch64/arm64/')" | \
xargs -I {} curl -L {} -o novactl

Install novactl

Make the binary executable

Once you have the binary, run:

chmod +x novactl*

Place the binary in your PATH

The following is an example to install the plugin in /usr/local/bin for Unix-like operating systems:

sudo mv novactl* /usr/local/bin/novactl

If you accidentally downloaded more than one novactl binary, please move only the binary that corresponds to the OS and ARCH of your machine to the /usr/local/bin location.

Install novactl as kubectl plugin

novactl is designed to work as a kubectl plugin, and our documentation assumes youare using it that way. To enable plugin functionality, simply run:”

sudo novactl kubectl-install

And check to see if the kubectl plugin has been installed successfully:

kubectl nova --help

Usage:
  kubectl nova [command]

Available Commands:
  get             get resources (clusters, schedule groups or deployments) with additional context
  help            Help about any command
  install         Install new Nova Control Plane or connect a new workload cluster to Nova Control Plane
  kubectl-install kubectl-install installs this binary as kubectl plugin
  status          Check status of Nova Control Plane installation
  uninstall       Uninstall Nova Control Plane or disconnect a workload cluster from Nova Control Plane

Flags:
  -h, --help      help for kubectl-nova
  -v, --version   version for kubectl-nova

Use "kubectl-nova [command] --help" for more information about a command.

Upgrading novactl

If you want to upgrade novactl to the latest version, please run all the previous steps starting from Download novactl up to this point again. This will automatically download the latest version and replace your local binary with it.

Check to see if the expected version of the novactl plugin is being invoked:

kubectl nova -v    

kubectl-nova version v1.3.6 (git: 7d3cc79) built: 20250803185128

This should match the version from the most recent novactl binary that was downloaded:

/usr/local/bin/novactl -v 

kubectl-nova version v1.3.6 (git: 7d3cc79) built: 20250803185128

Deploy Nova

To deploy the Nova Control Plane to one cluster and use another as a workload cluster, make sure you have at least two contexts in your kubeconfig.

kubectl config get-contexts

CURRENT   NAME                     CLUSTER                AUTHINFO               NAMESPACE
          k8s-cluster-1            wlc-1                  wlc-1
          k8s-cluster-2            wlc-2                  wlc-2
          k8s-cluster-hosting-cp   hosting-cluster        hosting-cluster

Install the Nova Control Plane

For installing Nova Control Plane use kubectl nova install control-plane command

kubectl nova install control-plane --help

Install new Nova Control Plane.

Installs Nova Control Plane components in current cluster, outputs configuration to Nova home directory at ~/.nova

Usage:
  kubectl-nova install control-plane --context=[hosting cluster context]  [CLUSTER NAME] [flags]

Aliases:
  control-plane, cp

Examples:

  Start Nova Control Plane with default configuration:

      kubectl nova install control-plane nova-cp


Flags:
      --gcp-access-key string     GCP access key JSON file path. Set for Nova Control Plane running in GKE.
      --gcp-project-id string     GCP Project ID. Set for Nova Control Plane running in GKE.
  -h, --help                      help for control-plane
      --image-repository string    (default "elotl/nova-scheduler-trial")
      --image-tag string           (default "v1.3.6")
      --version string             (default "v1.3.6")
      --webhook-api-key string    Webhook api key. When not passed a default value will be used.

Global Flags:
      --context string     
      --namespace string    (default "elotl")
      --rollback           Rollback changes made during installation in case it fails.

The Nova Control Plane will be deployed by default to the elotl namespace, which will be created if it does not already exist.

To deploy the Nova Control Plane run:

export NOVA_NAMESPACE=elotl
export K8S_HOSTING_CLUSTER_CONTEXT=k8s-cluster-hosting-cp
export NOVA_CONTROLPLANE_CONTEXT=nova

kubectl nova install control-plane --context=${K8S_HOSTING_CLUSTER_CONTEXT} --namespace=${NOVA_NAMESPACE} ${NOVA_CONTROLPLANE_CONTEXT}

Here, nova is the name of your Nova Control Plane as well as the context name to interact with the Nova Control Plane. If you choose a different name, remember to replace all uses of --context=${NOVA_CONTROLPLANE_CONTEXT} in other commands in the documentation to the custom name chosen.

Installing Nova Control Plane... 🪄
Cluster name - nova
Creating namespace elotl in control plane
Creating certificates
Generating certificates
Certificates successfully generated.
Installing Kube API Server...
Kube API Server installed.
Creating kubeconfig...
kubeconfig created.
Applying Nova CRDs...
Nova CRDs applied.
Installing Nova Scheduler...
Nova Scheduler installed.

Nova Control Plane components installed! 🚀

Nova kubeconfig is stored at /Users/example-user/.nova/nova/nova-kubeconfig

To interact with Nova, run:
    export KUBECONFIG=~/.kube/config:/Users/example-user/.nova/nova/nova-kubeconfig

Thank you for deploying and using Nova! Your participation is invaluable to us.
If you have any feedback, questions, or simply want to engage further:
Please join our Slack channel: http://tinyurl.com/slack-elotl
Or email us at info@elotl.co
Your input helps us improve our product for you. Thank you!

Troubleshooting Tips

You can find troubleshooting tips in the Troubleshooting section.

Install the Nova agent

Each workload cluster needs a Nova agent. The Nova agent will be deployed by default to the elotl namespace. Before deploying the Nova agent, you need to ensure that Nova's init-kubeconfig is present in the elotl namespace. Nova's init-kubeconfig provides a kube config to the Nova Control Plane. This kube config is used by the Nova agent in the workload cluster to connect and register itself as a workload cluster to the Nova Control Plane.

export NOVA_NAMESPACE=elotl
export NOVA_CONTROLPLANE_CONTEXT=nova
export K8S_CLUSTER_CONTEXT_1=k8s-cluster-1
export K8S_CLUSTER_CONTEXT_2=k8s-cluster-2
export K8S_HOSTING_CLUSTER_CONTEXT=k8s-cluster-hosting-cp
export NOVA_WORKLOAD_CLUSTER_1=wlc-1
export NOVA_WORKLOAD_CLUSTER_2=wlc-2

Let's create the namespace first:

kubectl --context=${K8S_CLUSTER_CONTEXT_1} create namespace ${NOVA_NAMESPACE}

We then copy the init-kubeconfig secret from the Nova Control Plane to the workload cluster:

kubectl --context=${NOVA_CONTROLPLANE_CONTEXT} get secret -n ${NOVA_NAMESPACE} nova-cluster-init-kubeconfig -o yaml | kubectl --context=${K8S_CLUSTER_CONTEXT_1} apply -f -

To connect a workload cluster to Nova, we will use kubectl nova install agent command.

kubectl nova install agent --help

Install new Nova Agent.

Installs Nova Agent components in current cluster making it part of Nova Workload Fleet in current Nova Control Plane.

Usage:
  kubectl-nova install agent [CLUSTER NAME] [flags]

Examples:

  Start Nova Agent in current cluster with default configuration:

      kubectl nova install agent nova-agent-1

  Start Nova Agent in some other context using specific version:

      kubectl nova --context some-other-context install agent --image-tag v0.5.0 nova-agent-2


Flags:
  -h, --help                      help for agent
      --image-repository string   --image-repository elotl/nova-agent (default "elotl/nova-agent")
      --image-tag string          --image-tag v0.0.0 (default "v1.3.7")

Global Flags:
      --context string
      --namespace string    (default "elotl")
      --rollback           Rollback changes made during installation in case it fails.

Deploy the Nova agent to the workload cluster:

kubectl nova install agent --context=${K8S_CLUSTER_CONTEXT_1} --namespace=${NOVA_NAMESPACE} ${NOVA_WORKLOAD_CLUSTER_1}

Installing Nova Agent... 🪄

Nova Agent components installed! 🚀

To ensure that the workload cluster has successfully registered to the Nova control plane, please run:
  kubectl get clusters --context=[Nova Control Plane context]

And verify that wlc-1 cluster is listed

If you don’t see your newly added workload cluster listed, please visit https://docs.elotl.co/nova/troubleshooting/
 for tips on troubleshooting what might have gone wrong.

Thank you for deploying and using Nova! Your participation is invaluable to us.
If you have any feedback, questions, or simply want to engage further:
Please join our Slack channel: http://tinyurl.com/slack-elotl
Or email us at info@elotl.co
Your input helps us improve our product for you. Thank you!

Now let's check if that worked. Simply run:

kubectl get --context=${NOVA_CONTROLPLANE_CONTEXT} clusters

Remember to update path to your Nova Control Plane kubeconfig

NAME    K8S-VERSION   K8S-CLUSTER   REGION        ZONE            READY   IDLE   STANDBY
wlc-1   1.32          nova-wlc-1    us-central1   us-central1-f   True    True   False
wlc-2   1.32          nova-wlc-2    us-central1   us-central1-c   True    True   False

What if I don't see my workload cluster listed?

Visit the Troubleshooting section.

Install other workload clusters

If you have a second cluster, run the same commands with a different cluster and cluster name, e.g.,

kubectl --context=${K8S_CLUSTER_CONTEXT_2} create namespace ${NOVA_NAMESPACE}

  kubectl --context=${NOVA_CONTROLPLANE_CONTEXT} get secret --namespace=${NOVA_NAMESPACE} nova-cluster-init-kubeconfig -o yaml | kubectl --context=${K8S_CLUSTER_CONTEXT_2} apply -f -

  kubectl nova install agent --context=${K8S_CLUSTER_CONTEXT_2} --namespace=${NOVA_NAMESPACE} ${NOVA_WORKLOAD_CLUSTER_2}

Installing Nova Agent... 🪄
Nova Agent components installed! 🚀

...
<abbreviated for readability>
...

Post installation check

We should now see the newly added workload cluster registered in Nova Control Plane:

kubectl --context=${NOVA_CONTROLPLANE_CONTEXT} get clusters

NAME    K8S-VERSION   K8S-CLUSTER   REGION        ZONE            READY   IDLE   STANDBY
wlc-1   1.32          nova-wlc-1    us-central1   us-central1-f   True    True   False
wlc-2   1.32          nova-wlc-2    us-central1   us-central1-c   True    True   False

To get further insight into the clusters' available resources, use the following command. Please note that this command runs get clusters along with the Nova plugin.

kubectl nova --context=${NOVA_CONTROLPLANE_CONTEXT} get clusters

  | CLUSTER NAME                  | K8S VERSION | CLOUD PROVIDER | REGION        | STATUS        | 
  |----------------------------------------------------------------------------------------------|  
  | wlc-1                         | 1.32        | gce            | us-central1   | ClusterReady  | 
  |----------------------------------------------------------------------------------------------|  
  |                                              NODES                                           |  
  |----------------------------------------------------------------------------------------------|  
  | NAME                                                 | AVAILABLE   | AVAILABLE   | AVAILABLE | 
  |                                                      | CPU         | MEMORY      | GPU       | 
  |                                                                                              | 
  | gke-nova-wlc-1-default-pool-6d89fc13-n5p8            | 328m        | 2137252992  | 0         | 
  | gke-nova-wlc-1-default-pool-b3163bd9-q21c            | 419m        | 2315296512  | 0         | 
  | gke-nova-wlc-1-default-pool-b7f3238d-mwzb            | 586m        | 2278604544  | 0         | 
  |                                                                                              | 
  |                      NODES' TAINTS                                                           |
  |                                                                                              |                                                                     
  |----------------------------------------------------------------------------------------------|  



  | CLUSTER NAME                  | K8S VERSION | CLOUD PROVIDER | REGION        | STATUS        | 
  |----------------------------------------------------------------------------------------------|  
  | wlc-2                         | 1.32        | gce            | us-central1   | ClusterReady  | 
  |----------------------------------------------------------------------------------------------|  
  |                                              NODES                                           |  
  |----------------------------------------------------------------------------------------------|  
  | NAME                                                 | AVAILABLE   | AVAILABLE   | AVAILABLE | 
  |                                                      | CPU         | MEMORY      | GPU       | 
  |                                                                                              | 
  | gke-nova-wlc-2-default-pool-51b8e1fa-pbp7            | 404m        | 2252381952  | 0         | 
  | gke-nova-wlc-2-default-pool-7d936330-jvsl            | 555m        | 2242110592  | 0         | 
  | gke-nova-wlc-2-default-pool-cc368a7e-f5xq            | 374m        | 2236653312  | 0         | 
  |                                                                                              | 
  |                      NODES' TAINTS                                                           |
  |                                                                                              |                                                                     
  |----------------------------------------------------------------------------------------------|  

Run Workloads

You can now run workloads on your workload clusters by following the various tutorials available here:

Nova Tutorials

Uninstall Nova

Uninstall Nova Agent from Workload cluster

 kubectl nova uninstall agent --context=${K8S_CLUSTER_CONTEXT_1} ${NOVA_WORKLOAD_CLUSTER_1}

Uninstall Nova Control Plane

To uninstall Nova Control Plane components, run:

kubectl nova uninstall control-plane --context=${K8S_HOSTING_CLUSTER_CONTEXT} ${NOVA_CONTROLPLANE_CONTEXT}

Here, nova specified as the last argument is the name of your Nova control plane (chosen at the install step). Default namespace is elotl.