kagent
Get started
Back to Blog

Install Agent Substrate on Any Kubernetes Cluster#

Anyone adopting software or a product, whether it's paid, free, or OSS, wants one question answered:

"Is it vendor-agnostic?"

That's why everything about a platform, from where you can install it to what you can connect it to, needs to be as universal as possible. In AI this matters even more, because the systems, data, and workflows you design should never be tied to a single LLM provider or cloud platform.

In this blog post, you'll learn how to install and configure Agent Substrate on any cluster.

Prerequisites#

To follow along with this blog post in a hands-on fashion, you need:

  1. A Kubernetes cluster running v1.37 or above. It can be any cluster, from a Kind or Minikube cluster to an AKS, EKS, or GKE cluster.

You need v1.37 or above because Agent Substrate uses the PodCertificate API to issue certs to Substrate Workers.

Why Is a Universal Installer Needed?#

"Where can this run?"

That's one of the most important questions for anyone implementing any software or platform.

It comes in a few forms:

  • Can this only run on X cloud?
  • Can I export my data?
  • Can I migrate from X environment to Y environment?

If a tool, platform, or piece of software only runs in one cloud, you're stuck between a rock and a hard place the moment you need to move, whether that's because of billing, a better deal, or more experience with another cloud.

A universal installer is the difference between a team that reuses the same systems everywhere and a team that has to build "snowflakes" in every environment.

What Does the Installer Entail?#

When you run the installer, you get everything that comes with a standard Agent Substrate installation, the same as if you'd installed it on GKE or Kind.

The installer:

  1. Checks that the cluster has what it needs to run as expected (for example, the PodCertificate API).
  2. Installs all of the necessary components: CRDs, the cert controller, Postgres, and all of the Substrate components.
  3. Verifies that everything installed successfully and is working as expected.

The key difference is that it doesn't make assumptions about where it's running. For example, if you install Agent Substrate today, it expects you to set the PROJECT_ID environment variable. A project ID only exists in Google Cloud, so if you're installing on something like AKS or EKS, the "hacky" workaround is to set the variable to a placeholder value, because if you don't, the installation fails.

How to Use the Installer#

To get past those "hacky" workarounds, use the universal installer in the kagent Agent Substrate fork.

  1. Download the kubectl-ate binary, which is how you interact with Agent Substrate on the CLI. This example pulls the macOS (Apple silicon) build; pick the pattern that matches your OS and architecture.
gh release download v1.0.1 \
  --repo kagent-dev/substrate \
  --pattern 'kubectl-ate-darwin-arm64*'
  1. Put the binary on your PATH so you can use it against your Kubernetes cluster.
mkdir -p "$HOME/.local/bin"
install -m 0755 kubectl-ate-darwin-arm64 "$HOME/.local/bin/kubectl-ate"
export PATH="$HOME/.local/bin:$PATH"
  1. Set an environment variable with the context name of the cluster you're installing Agent Substrate on.
export CTX="your-cluster"
  1. Run the install.
kubectl-ate --context "$CTX" install

The installer asks you a few things:

  • Which Postgres to use: a bundled single replica for evaluation, or an external database you've already created the connection Secrets for.
  • Where to store snapshots: RustFS in the cluster, Amazon S3 (or a compatible store), or Google Cloud Storage.
  • Whether you want hardware-level isolation with the microVM sandbox class. If you choose No, it defaults to gVisor (software-level isolation).

Then confirm the install.

Once the installation completes, you can see all of the Agent Substrate resources running in your Kubernetes environment.

kubectl get pods -n ate-system

Wrapping Up#

When we install and configure agentic infrastructure, we want it to run everywhere: on-prem, in the cloud, on managed Kubernetes services like AKS and EKS, and everything in between. Without an installer that works anywhere, each team across an organization ends up with its own way of running the same system instead of one universal approach.