How to Deploy the RealTheory Agent Using the Bulk Deployment Tool

  • Updated on Jan 26, 2026
  • Published on Jan 26, 2026
  • 3 minute(s) read
Prev Next

The RealTheory bulk deployment tool enables customers to generate or generate and deploy Kubernetes deployment manifests for the RealTheory Agent (also referred to as the collector) across one or many Kubernetes clusters. This tool is designed for Linux environments and supports both manual and automated deployment workflows.

The bulk deployment tool is available upon request. Existing customers can obtain access by contacting RealTheory Support, who will provide the binary and any required onboarding details.

The tool uses two configuration files:

  • A client configuration file stored in the user’s home directory
  • A cluster configuration file defining the clusters to target

Once configured, the tool can:

  • Generate deployment manifests in bulk, or
  • Generate and deploy the RealTheory Agent manifests directly to multiple Kubernetes clusters using their kubeconfig contexts.

1. Installation

Copy the rt-deploy binary into a directory included in your PATH. The recommended location is:

/usr/local/bin

Ensure the binary is executable:

chmod a+x /usr/local/bin/rt-deploy

2. Client Configuration File

This file contains the credentials and endpoint information required for the tool to communicate with the RealTheory SaaS platform. It must be placed in the user’s home directory.

Template : ~/.rt-deploy.yaml

# client configuration file
logging:
  path: '/Users/<username>/rt-deploy/app.log'
  production: true
  disable_stacktrace: true

client:
  base_url: '<rt-endpoint>'
  output_path: '/Users/<username>/rt-deploy'
  end_points:
    K8sArtifacts: '/theory/api/v1/k8sartifacts/collector'
  auth:
    type: 'basic'
    domain: '<rt-domain>'
    secret: '<rt-secret>'
    username: '<rt-username>'

Field Definitions:

Key Description
logging.path Full path to the log file written by the tool (e.g., /Users/joebloggs/rt-deploy/app.log).
logging.production Enables production‑mode logging.
logging.disable_stacktrace Disables stack traces unless needed for debugging.
client.base_url RealTheory SaaS API endpoint for your region (e.g., https://api-us1.realtheory.io).
client.output_path Directory where generated deployment manifests will be written.
client.end_points.K8sArtifacts API path used to retrieve RealTheory Agent artifacts.
client.auth.type Authentication type (always basic).
client.auth.domain Your RealTheory account name (or domain).
client.auth.username Your RealTheory API username (typically APIKey1 or APIKey2).
client.auth.secret Your RealTheory API key or security token.

Sample: ~/.rt-deploy.yaml

# client configuration file
logging:
  path: '/Users/joebloggs/rt-deploy/app.log'
  production: true
  disable_stacktrace: true

client:
  base_url: 'https://api-us1.realtheory.io'
  output_path: '/Users/joebloggs/rt-deploy'
  end_points:
    K8sArtifacts: '/theory/api/v1/k8sartifacts/collector'
  auth:
    type: 'basic'
    domain: 'acme'
    secret: 'APIKey1'
    username: '41698726-5B09-4F24-BDE2-FF0A91CA426F'

3. Cluster Configuration File

This file defines the clusters you want to generate or deploy manifests to. It also controls whether the tool performs manifest generation only or generation + deployment.

Template: cluster-config.json

{
  "configuration": {
    "output-path": "/users/<username>/rt-deploy",
    "deploy-clusters": true,
    "kubectl-path": ""
  },
  "clusters": [
    {
      "name": "<cluster-name>",
      "k8s-use-context": "<cluster-context>",
      "description": "<cluster-description>",
      "os": "linux",
      "architecture": "<cluster-architecture>",
      "cloud-account-id": "<cloud-identifier>",
      "account-owner": "<cluster-contact>",
      "vcpu-count": 100,
      "labels": {
        "rt-management-team": "<cluster-team>",
        "rt-billing-model": "<billing-model>",
        "rt-optimization-strategy": "<optimization-strategy>"
      },
      "http-proxy-list": "<http-proxy>",
      "https-proxy-list": "<https-proxy>",
      "no-proxylist": "<no-proxy-list>"
    }
  ]
}

Field Definitions

Parameter Covered Description
os Specifies the operating system of the target cluster. Must be linux.
architecture CPU architecture of the cluster nodes (amd64 or arm64).
vcpu-count Total number of vCPUs available in the cluster.
name Sets the name of the cluster as it will appear in the RealTheory platform.
description Provides a human‑readable description of the cluster.
labels Adds metadata labels to the cluster inside the RealTheory platform for filtering and targeting. Does not modify Kubernetes labels.
http-proxy-list Defines the HTTP proxy used by the RealTheory Agent.
https-proxy-list Defines the HTTPS proxy used by the RealTheory Agent.
no-proxylist Comma‑separated list of hosts or CIDRs that should bypass proxy settings.
cloud-account-id Identifies the cloud account or business unit associated with the cluster.
account-owner Email or name of the person responsible for the cluster.
deploy-clusters When true, the tool generates and deploys manifests. When false, it only generates manifests.
k8s-use-context The kubeconfig context used to deploy the RealTheory Agent to the target cluster.

Sample: cluster-config.json

{
  "configuration": {
    "output-path": "/users/joebloggs/rt-deploy",
    "deploy-clusters": true,
    "kubectl-path": ""
  },
  "clusters": [
    {
      "name": "k8s-acme-dev",
      "k8s-use-context": "k8s-acme-dev",
      "description": "Acme dev cluster",
      "os": "linux",
      "architecture": "amd64",
      "cloud-account-id": "Acme, Inc.",
      "account-owner": "joebloggs@acme.com",
      "vcpu-count": 250,
      "labels": {
        "rt-management-team": "dev",
        "rt-billing-model": "aws-sku-discount",
        "rt-optimization-strategy": "cost-optimized"
      },
      "http-proxy-list": "http://proxy.acme.com:8080",
      "https-proxy-list": "https://proxy.acme.com:8443",
      "no-proxylist": "localhost,127.0.0.1"
    }
  ]
}

4. Running the Tool

Once both configuration files are in place, run the tool using:

rt-deploy k8sartifacts --file config.json

Example:

rt-deploy k8sartifacts --file cluster-config.json

Behavior based on the deploy-clusters value:

Value Behavior
true Generates deployment manifests and deploys them to each cluster using the specified kubeconfig context.
false Generates deployment manifests only (no deployment performed).

5. Output

Generated manifests are written to the directory specified in:

configuration.output-path

If deployment is enabled, the tool applies the manifests using:

  • The kubeconfig available to the user
  • The context specified in k8s-use-context