# How to Use the kubectl-ate Plugin to Manage Agent Substrate Resources

> Learn to use the kubectl-ate plugin for Agent Substrate to manage atespaces, actors, and workers via CLI. Simplify your cluster resource management today.

- Repository: [Agent Substrate/substrate](https://github.com/agent-substrate/substrate)
- Tags: how-to-guide
- Published: 2026-08-22

---

**The `kubectl-ate` plugin is a kubectl extension that enables CLI management of Agent Substrate resources—including atespaces, actors, and workers—through automatic port-forwarding to the cluster's ate-api-server.**

The `kubectl-ate` plugin provides a native Kubernetes experience for interacting with the **agent-substrate/substrate** control plane. By adhering to the kubectl plugin naming convention (`kubectl-<name>`), it integrates seamlessly with your existing kubeconfig and command-line workflow, eliminating the need for manual API server discovery or port-forwarding.

## Installing the kubectl-ate Plugin

To install the plugin, compile the binary directly from the repository source.

Run the following command from the root of the `agent-substrate/substrate` repository:

```bash
go install ./cmd/kubectl-ate

```

This command builds the plugin and places the executable in your Go binary directory (typically `$HOME/go/bin`). Ensure this directory is included in your `$PATH` environment variable so Kubernetes can discover the plugin.

Verify the installation by listing available plugins:

```bash
kubectl plugin list

```

You should see `kubectl-ate` listed among the available kubectl plugins. The binary name conforms to the `kubectl-<name>` pattern, which allows Kubernetes to automatically register it as a plugin.

## Core Commands for Resource Management

The plugin implements its command tree in `cmd/kubectl-ate/internal/cmd/`, with each subcommand residing in its own source file. Below are the essential operations for managing Agent Substrate clusters.

### Creating Atespaces and Actors

**Atespaces** are logical namespaces that isolate groups of actors. Create one using the command defined in [`cmd/kubectl-ate/internal/cmd/create_atespace.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/create_atespace.go):

```bash
kubectl-ate create atespace demo

```

**Actors** are lightweight processes that run within atespaces. The implementation in [`cmd/kubectl-ate/internal/cmd/create_actor.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/create_actor.go) supports launching actors with specific parent atespaces:

```bash
kubectl-ate create actor myapp --atespace demo

```

### Inspecting Cluster State

Retrieve resource information using the family of `get` commands implemented across several source files:

- **`kubectl-ate get atespaces`** – Lists all atespaces (source: [`cmd/kubectl-ate/internal/cmd/get_atespaces.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/get_atespaces.go))
- **`kubectl-ate get actors`** – Displays actor details including state, assigned worker, and pod name (source: [`cmd/kubectl-ate/internal/cmd/get_actors.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/get_actors.go))
- **`kubectl-ate get workers`** – Shows the underlying worker pods that host actors (source: [`cmd/kubectl-ate/internal/cmd/get_workers.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/get_workers.go))

```bash
kubectl-ate get actors
kubectl-ate get workers

```

### Managing Actor Lifecycle

Suspend and restore actors without losing state using the pause and resume commands:

- **Pause** (source: [`cmd/kubectl-ate/internal/cmd/pause_actor.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/pause_actor.go)): Suspends an actor and persists its state for later restoration.
- **Resume** (source: [`cmd/kubectl-ate/internal/cmd/resume_actor.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/resume_actor.go)): Restores a paused actor to any available worker in the cluster.

```bash
kubectl-ate pause actor myapp
kubectl-ate resume actor myapp

```

### Monitoring Worker Performance

Analyze resource utilization using the `top` command implemented in [`cmd/kubectl-ate/internal/cmd/top_workers.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/top_workers.go):

```bash
kubectl-ate top workers

```

This displays live statistics for each worker, including CPU usage, memory consumption, and the count of active actors.

## How the Plugin Works

When you invoke any `kubectl-ate` command, the plugin—coordinated by the root command definition in [`cmd/kubectl-ate/internal/cmd/root.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/internal/cmd/root.go)—automatically performs the following steps:

1. **Loads `~/.kube/config`** to identify the current Kubernetes cluster and authentication context.
2. **Discovers `ate-api-server` pods** running within the target cluster.
3. **Establishes a temporary port-forward tunnel** to the API server, enabling secure local communication without manual network configuration.
4. **Executes the requested operation** via gRPC calls to the Substrate control plane through the established tunnel.

This automatic port-forwarding behavior eliminates the need to manually expose the ate-api-service or configure ingress rules for CLI access.

## Complete Workflow Example

The following sequence demonstrates a typical development workflow using the kubectl-ate plugin:

```bash

# Install the plugin

go install ./cmd/kubectl-ate

# Create a new atespace for isolation

kubectl-ate create atespace hello-world

# Deploy an actor into the atespace

kubectl-ate create actor hello-app --atespace hello-world

# Verify the actor is running and assigned to a worker

kubectl-ate get actors

# Pause the actor for maintenance or resource conservation

kubectl-ate pause actor hello-app

# Resume the actor on any available worker

kubectl-ate resume actor hello-app

# Check worker resource utilization

kubectl-ate top workers

```

All commands handle authentication, port-forwarding lifecycle management, and gRPC communication transparently.

## Summary

- The **kubectl-ate plugin** follows the standard `kubectl-<name>` binary naming convention for automatic discovery by Kubernetes.
- Install the plugin using `go install ./cmd/kubectl-ate` and verify with `kubectl plugin list`.
- Core commands reside in `cmd/kubectl-ate/internal/cmd/` with specific files for each operation: [`create_atespace.go`](https://github.com/agent-substrate/substrate/blob/main/create_atespace.go), [`create_actor.go`](https://github.com/agent-substrate/substrate/blob/main/create_actor.go), [`get_actors.go`](https://github.com/agent-substrate/substrate/blob/main/get_actors.go), [`pause_actor.go`](https://github.com/agent-substrate/substrate/blob/main/pause_actor.go), [`resume_actor.go`](https://github.com/agent-substrate/substrate/blob/main/resume_actor.go), and [`top_workers.go`](https://github.com/agent-substrate/substrate/blob/main/top_workers.go).
- The plugin automatically manages port-forwarding to the `ate-api-server` and communicates via gRPC, requiring no manual network configuration.
- You can manage the full resource lifecycle—creating atespaces, deploying actors, pausing/resuming execution, and monitoring workers—directly from your terminal.

## Frequently Asked Questions

### How does kubectl-ate discover the cluster API server?

The plugin automatically loads your `~/.kube/config` file to determine the current context and cluster location. It then discovers running `ate-api-server` pods within that cluster and creates a temporary port-forward tunnel for secure gRPC communication. This process occurs transparently with every command execution.

### What is the difference between an atespace and a Kubernetes namespace?

An **atespace** is a logical isolation boundary specific to the Agent Substrate platform, managed by the control plane, while a Kubernetes namespace is the underlying orchestration primitive. Atespaces group actors together for management purposes, but they exist as a layer above standard Kubernetes namespaces. The plugin creates these resources via the ate-api-server rather than directly through the Kubernetes API.

### Can I use kubectl-ate without installing it via go install?

The primary installation method documented in the `agent-substrate/substrate` repository uses `go install ./cmd/kubectl-ate`. While you could theoretically build the binary manually from [`cmd/kubectl-ate/main.go`](https://github.com/agent-substrate/substrate/blob/main/cmd/kubectl-ate/main.go) and place it anywhere in your `$PATH` under the name `kubectl-ate`, the Go toolchain installation is the supported method for ensuring compatibility with the source code in the repository.

### Why does the plugin require port-forwarding instead of using a service?

The plugin uses automatic port-forwarding to the `ate-api-server` pods to ensure secure, authenticated access without requiring the API server to be exposed via external load balancers or ingress controllers. This approach leverages existing Kubernetes RBAC and kubeconfig authentication while keeping the control plane inaccessible from outside the cluster network.