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

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:

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:

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:

kubectl-ate create atespace demo

Actors are lightweight processes that run within atespaces. The implementation in cmd/kubectl-ate/internal/cmd/create_actor.go supports launching actors with specific parent atespaces:

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)
• kubectl-ate get actors – Displays actor details including state, assigned worker, and pod name (source: 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)

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): Suspends an actor and persists its state for later restoration.
• Resume (source: cmd/kubectl-ate/internal/cmd/resume_actor.go): Restores a paused actor to any available worker in the cluster.

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:

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—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:

# 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, create_actor.go, get_actors.go, pause_actor.go, resume_actor.go, and 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}