Install the Kubernetes agent

This guide installs the Helm chart in agent mode (mode: kubernetes-agent). In this mode the chart does not install the Supervisely platform. Instead, it installs a lightweight agent that connects your cluster to an existing Supervisely instance and lets that instance run apps and tasks (including GPU workloads) on your cluster's nodes.

Use this when you already have a Supervisely instance and want to add a Kubernetes cluster as extra compute — for example, a dedicated GPU cluster.

Not sure which mode you need? Read the Overview. If you want to run Supervisely itself on Kubernetes, use Install full Supervisely instead.

How it works

The agent chart installs only the pieces needed to run tasks:

• A task namespace (a separate namespace where app/task pods run) with a network policy

• RBAC and a service account so Supervisely can create and manage task pods

• A one-time registration job that adds your cluster to the connected Supervisely instance as a compute node

• A logs agent that streams task logs back to the instance

Once installed, the cluster shows up as an available compute backend in your Supervisely instance, and you can launch apps on it.

Before you start

• An existing, reachable Supervisely instance

• A Kubernetes cluster (version 1.21 or later) with kubectl + helm (v3)

• Network connectivity both ways: the cluster must reach the Supervisely instance, and the instance must be able to reach the cluster to schedule work

• NVIDIA device plugin on GPU nodes, if you want GPU tasks

Step 1: Download the chart

The chart is the same one used for the full install — you just select agent mode in the values. Fetch it with the Supervisely CLI (the same supervisely command from the standard installation; set your license first with supervisely set-license <YOUR_LICENSE> if needed):

# latest version
supervisely k8s fetch-chart

# or a specific Supervisely version
supervisely k8s fetch-chart --version 6.12.3

The CLI downloads and unpacks the chart into ~/.supervisely/k8s/chart/ and prints the paths.

Agent mode needs to be pointed at your existing instance, and the exact connection values depend on your setup. The easiest path is to ask Supervisely support to generate a ready-to-use agent values.yaml for your instance — then you only adjust storage and GPU settings below.

Step 2: Configure your values

Set agent mode and point the agent at your instance:

# Install the agent only, not the full platform.
mode: kubernetes-agent

options:
  # The address of your existing Supervisely instance,
  # reachable from this cluster.
  serverAddress: https://supervisely.mycompany.com

services:
  logsAggregator:
    taskExecution:
      # Where task logs are sent (your instance's public API URL).
      apiUrl: https://supervisely.mycompany.com
      token:
        # Shared token that authorizes this agent. Prefer an existing
        # secret in production; a plain value is shown here for clarity.
        value: "<TASK_EXECUTION_TOKEN>"

Agent mode requires the instance connection details (serverAddress, the logs apiUrl and token, and — depending on your deployment — access to the instance's database so the cluster can register itself). These are environment-specific. If in doubt, use the values file generated by Supervisely for your instance rather than filling them in by hand.

Storage and GPU

• Storage — task pods may need scratch/persistent storage. Set a storageClassName as in the full install guide.

• GPU — to run GPU tasks, install the NVIDIA device plugin on GPU nodes and enable GPU pod presets under nodeManager.node.options.podsPresets (a preset with supportsGpu: true and runtimeClassName: nvidia). The generated values.yaml includes commented examples.

Step 3: Install the chart

supervisely k8s install

This fetches the chart if needed and runs helm upgrade -i using your values.yaml, into the supervisely namespace. (You can also run helm upgrade -i directly against ~/.supervisely/k8s/chart if you prefer.)

Step 4: Verify

Check that the agent resources are up and the registration job completed:

kubectl -n supervisely get pods
kubectl -n supervisely get jobs

The registration job should show Completed, and the logs agent pod should be Running. Then open your Supervisely instance — the cluster should now appear as an available compute backend, ready to run apps and tasks.

No cluster yet?

If you need to create a cluster first, there's a from-scratch tutorial for building one on AWS (cluster, storage, ingress, optional GPU nodes):

• Build a cluster on AWS EKS