☸️Kubernetes

This guide covers installing the Dstl8 agent on Kubernetes clusters using Helm.

Prerequisites

• Kubernetes cluster with kubectl access

• Helm 3.x installed

• Organization ID (provided by Dstl 8)

• Cluster name

• Deployment environment label (e.g., prod, dev, staging)

• Admission tokens (generated in the Dstl8 UI)

• Config and data endpoint URLs (provided in the Dstl8 UI)

Default Configuration

The installer uses these defaults unless otherwise specified:

• Kubeconfig: ~/.kube/config

• Namespace: controltheory

• Installation Type: both (DaemonSet + Cluster components)

• OTLP Port Exposure: Disabled (ports not exposed on nodes)

---

Installation

Quick Install

The Dstl8 UI generates a custom installation command for your cluster. Simply provide your cluster name and deployment environment, and the UI will generate the complete command with all required tokens and endpoints.

Generated Command Example:

curl -fsSL https://install.controltheory.com/scripts/install.sh -o install.sh && bash install.sh \
  -i <org-id> \
  --ds-token <daemonset-token> \
  --cluster-token <cluster-token> \
  --config-endpoint <config-url> \
  --data-endpoint <data-host:port> \
  --cluster-name <your-cluster-name> \
  -e <environment>

This installs both the DaemonSet and Cluster components by default.

Installation Types

You can choose which components to install:

Both Components (Default):

You'll typically want to install both components in each cluster per the default command above

bash install.sh -i <org-id> -t both \
  --ds-token <daemonset-token> \
  --cluster-token <cluster-token> \
  --config-endpoint <config-url> \
  --data-endpoint <data-host:port> \
  --cluster-name mycluster \
  -e prod

DaemonSet Only:

bash install.sh -i <org-id> -t ds \
  --ds-token <daemonset-token> \
  --config-endpoint <config-url> \
  --data-endpoint <data-host:port> \
  --cluster-name mycluster \
  -e prod

Cluster Component Only:

bash install.sh -i <org-id> -t cluster \
  --cluster-token <cluster-token> \
  --config-endpoint <config-url> \
  --data-endpoint <data-host:port> \
  --cluster-name mycluster \
  -e prod

Configuration Options

Namespace (Optional):

By default, the agent installs into the controltheory namespace. To use a different namespace:

bash install.sh ... -n my-namespace

Kubeconfig (Optional):

By default, the installer uses the kubeconfig at ~/.kube/config. To use a different kubeconfig file:

bash install.sh ... --kubeconfig ~/.kube/my-config

Expose OTLP Ports (Optional):

By default, OTLP ports are not exposed on the host. To expose OTLP ports (1757/1758) directly on nodes for the DaemonSet:

bash install.sh ... --host-port

Note: This is typically only needed if you have applications running outside the cluster that need to send telemetry data directly to the node ports.

---

Preflight Check (Dry Run)

Before installing, you can run a preflight check to verify your cluster is ready and identify any potential issues. The preflight check uses the default kubeconfig (~/.kube/config) unless you specify otherwise.

Basic Preflight Check:

bash install.sh -o preflight

With Custom Kubeconfig:

bash install.sh -o preflight --kubeconfig ~/.kube/my-config

What the Preflight Check Analyzes

The preflight check provides detailed analysis of:

• Node Resources: Available CPU, memory, and pod capacity on each node

• Scheduling Constraints: Whether the DaemonSet can be scheduled on each node

• Priority Classes: Available scheduling priorities in the cluster

• Node Taints: Taints that may require tolerations

• Over-provisioned Pods: Pods with excessive resource requests that may prevent scheduling

• Node Status: Ready/NotReady status of all nodes

Sample Output:

==============================================================================
DAEMONSET PLACEMENT ANALYSIS                                   v1.2.3
==============================================================================
Date:              2024-03-15 10:30:00
Kubeconfig:        /home/user/.kube/config
DaemonSet CPU:     100m
DaemonSet Memory:  128Mi
==============================================================================

NODE DETAILS
------------

Node: worker-node-1
  Ready:           True
  Taints:          <none>
  Allocatable:     CPU=3920m  Mem=15024Mi  Pods=110
  Requested:       CPU=2100m  Mem=8192Mi  Pods=45
  Available:       CPU=1820m  Mem=6832Mi  Pods=65
  Can Schedule:    YES

Node: worker-node-2
  Ready:           True
  Taints:          dedicated=gpu:NoSchedule
  Allocatable:     CPU=3920m  Mem=15024Mi  Pods=110
  Requested:       CPU=3850m  Mem=12000Mi  Pods=80
  Available:       CPU=70m  Mem=3024Mi  Pods=30
  Can Schedule:    NO (InsufficientCPU, HasTaints)

==============================================================================
SUMMARY TABLE
==============================================================================
NODE                                          CPU(m)     MEM(Mi)    PODS SCHEDULABLE
----                                          ------     -------    ---- -----------
worker-node-1                                   1820        6832      65 YES
worker-node-2                                     70        3024      30 NO (InsufficientCPU, HasTaints)

* = Requires tolerations (see below)

Use the preflight check to:

• Identify nodes with insufficient resources

• Plan toleration requirements for tainted nodes

• Detect over-provisioned workloads blocking the DaemonSet

• Validate cluster capacity before installation

---

Verify Installation

After installation, check the status of your deployed components. This uses the default kubeconfig and namespace unless specified otherwise:

bash install.sh -o status

With Custom Options:

bash install.sh -o status -n my-namespace --kubeconfig ~/.kube/my-config

This command displays:

• Deployment health status

• Running pods and their status

• Version information

• Configuration details

---

Uninstall

To completely remove the Dstl 8 agent from your Kubernetes cluster:

Basic Uninstall:

bash install.sh -o uninstall

With Custom Options:

# Uninstall from specific namespace
bash install.sh -o uninstall -n my-namespace

# Use custom kubeconfig
bash install.sh -o uninstall --kubeconfig ~/.kube/my-config

The uninstall process removes:

• DaemonSet and Cluster Helm releases

• Associated ConfigMaps and Secrets

• ServiceAccounts and RBAC resources

• The namespace (if no other resources exist in it)

---

Troubleshooting

Common Issues

Insufficient Resources: Run the preflight check to identify nodes with resource constraints:

bash install.sh -o preflight

DaemonSet Not Scheduling:

1. Check node taints with preflight analysis

2. Verify nodes have sufficient CPU/memory available

3. Review pod capacity limits on nodes

Permission Errors: Ensure your kubeconfig has the necessary permissions:

• Create namespaces

• Deploy Helm charts

• Create RBAC resources (ServiceAccounts, Roles, RoleBindings)

• Create ConfigMaps and Secrets

Pods Not Starting: Check pod logs:

kubectl logs -n controltheory -l app=aigent-ds
kubectl logs -n controltheory -l app=aigent-cluster

Network Connectivity Issues: Verify the cluster can reach the config and data endpoints:

kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
  curl -v <config-endpoint>

Getting Help

For installation issues:

1. Run the status check to gather diagnostic information

2. Run the preflight check to identify resource or scheduling constraints

3. Review pod logs for error messages

4. Collect the output and contact Dstl 8 support

---

Advanced Configuration

Using Environment Variables

You can set the namespace via environment variable:

bash

export NAMESPACE=my-custom-namespace
bash install.sh ...

Multiple Kubeconfigs

To install on multiple clusters, use the --kubeconfig flag with different config files:

bash

bash install.sh --kubeconfig ~/.kube/prod-cluster ...
bash install.sh --kubeconfig ~/.kube/staging-cluster ...

---

Version Information

Current installer version: v1.2.3

To check the installer version:

bash install.sh --version

To view all available options:

bash install.sh --help