Agent Commands

The pipeops agent commands install and manage PipeOps agents on your infrastructure. Agents enable you to run workloads on your own servers while leveraging PipeOps orchestration capabilities.

Overview

PipeOps agents provide:

Self-hosted infrastructure: Run on your own servers
Kubernetes cluster management: Automated cluster setup
Secure communication: Encrypted agent-to-platform communication
Multi-node support: Join worker nodes to clusters
Cross-platform: Linux, Windows, FreeBSD support

`pipeops agent install`

Install the PipeOps agent and set up a Kubernetes cluster on your server.

Usage

pipeops agent install [flags]

Description

Installs the PipeOps agent on the current machine and initializes a Kubernetes cluster. This command transforms your server into a PipeOps-managed infrastructure node.

Flags

Flag	Type	Description
`--cluster-name`	string	Name for the cluster (default: auto-generated)
`--server-id`	string	PipeOps server ID to associate with
`--token`	string	Agent registration token
`--advertise-address`	string	IP address to advertise (default: auto-detect)
`--node-labels`	string	Comma-separated node labels (key=value)
`--skip-kubernetes`	boolean	Install agent only, skip Kubernetes setup

Prerequisites

Root or sudo access
Supported OS: Linux, FreeBSD
Minimum 2GB RAM, 2 CPU cores
20GB disk space
Open ports: 6443 (API), 10250 (kubelet)

Examples

Basic installation:

sudo pipeops agent install

Install with custom cluster name:

sudo pipeops agent install --cluster-name production-cluster

Install with server association:

sudo pipeops agent install \
  --server-id srv_1234567890 \
  --token "agent-token-here"

Install with custom advertise address:

sudo pipeops agent install \
  --advertise-address 192.168.1.100 \
  --cluster-name my-cluster

Install with node labels:

sudo pipeops agent install \
  --node-labels "environment=production,region=us-east"

Install agent only (no Kubernetes):

sudo pipeops agent install --skip-kubernetes

What Gets Installed

The installation process:

System checks: Validates prerequisites
Agent binary: Installs PipeOps agent service
Kubernetes cluster: Sets up control plane (unless --skip-kubernetes)
Container runtime: Installs containerd if needed
Network plugin: Configures CNI networking
Agent registration: Registers with PipeOps platform
Health checks: Verifies installation

Installation Output

$ sudo pipeops agent install --cluster-name my-cluster

[1/7] Checking system requirements...
✓ Operating system: Linux
✓ Architecture: x86_64
✓ Memory: 4GB (minimum 2GB)
✓ Disk space: 50GB (minimum 20GB)

[2/7] Installing dependencies...
✓ Installing containerd
✓ Installing CNI plugins

[3/7] Installing PipeOps agent...
✓ Downloaded agent binary
✓ Created systemd service
✓ Agent version: 1.0.0

[4/7] Initializing Kubernetes cluster...
✓ Generating certificates
✓ Starting control plane
✓ Configuring network plugin

[5/7] Registering with PipeOps platform...
✓ Agent registered successfully
✓ Server ID: srv_1234567890

[6/7] Running post-installation checks...
✓ Agent service: running
✓ Kubernetes API: healthy
✓ Node status: ready

[7/7] Installation complete!

Cluster Information:
  Name: my-cluster
  Node: ip-192-168-1-100
  Status: Ready
  Kubernetes Version: v1.28.0
  
Join token for worker nodes:
  pipeops agent join --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Next steps:
  - View cluster info: pipeops agent info
  - Join worker nodes: pipeops agent join --token <token>
  - Deploy workloads from PipeOps console

Platform Support

Linux

Ubuntu 20.04, 22.04, 24.04
Debian 11, 12
CentOS 8, 9
RHEL 8, 9
Amazon Linux 2, 2023
Rocky Linux 8, 9

FreeBSD

FreeBSD 12.x, 13.x, 14.x

Troubleshooting Installation

Insufficient permissions:

# Run with sudo
sudo pipeops agent install

Port already in use:

# Check what's using port 6443
sudo lsof -i :6443

# Stop conflicting service or use different port

Network issues:

# Check connectivity to PipeOps platform
curl -v https://api.pipeops.io/health

# Verify DNS resolution
nslookup api.pipeops.io

`pipeops agent join`

Join a worker node to an existing PipeOps Kubernetes cluster.

Usage

pipeops agent join [flags]

Description

Joins the current machine as a worker node to an existing Kubernetes cluster managed by PipeOps. Use this to add capacity to your cluster.

Flags

Flag	Type	Description
`--token`	string	Join token from control plane (required)
`--server`	string	Control plane server address
`--node-labels`	string	Comma-separated node labels
`--kubelet-extra-args`	string	Additional kubelet arguments

Prerequisites

Root or sudo access
Same requirements as agent install
Network connectivity to control plane
Join token from control plane node

Examples

Join worker node:

sudo pipeops agent join --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Join with explicit server address:

sudo pipeops agent join \
  --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
  --server https://192.168.1.100:6443

Join with node labels:

sudo pipeops agent join \
  --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
  --node-labels "role=worker,zone=us-east-1a"

Join Process

$ sudo pipeops agent join --token eyJ...

[1/5] Validating join token...
✓ Token is valid
✓ Control plane: https://192.168.1.100:6443

[2/5] Installing dependencies...
✓ Installing containerd
✓ Installing CNI plugins

[3/5] Configuring kubelet...
✓ Downloaded cluster CA certificate
✓ Generated kubelet config

[4/5] Joining cluster...
✓ Connected to control plane
✓ Node registered

[5/5] Post-join verification...
✓ Node status: Ready
✓ Agent service: running

Successfully joined cluster!

Node Information:
  Name: worker-01
  Status: Ready
  Role: worker
  Labels: role=worker

Getting Join Token

The join token is displayed when you run pipeops agent install on the control plane. If you need to retrieve it again:

From control plane node:

sudo pipeops agent info --show-join-token

From PipeOps console: Navigate to Servers > [Your Server] > Agent > Join Token

Troubleshooting Join

Invalid token:

Error: invalid join token

# Get a new token from control plane
sudo pipeops agent info --show-join-token

Cannot reach control plane:

Error: failed to connect to control plane

# Verify network connectivity
ping <control-plane-ip>
telnet <control-plane-ip> 6443

Node not ready:

# Check node status
kubectl get nodes

# View node events
kubectl describe node <node-name>

# Check kubelet logs
journalctl -u kubelet -f

`pipeops agent info`

Display information about the PipeOps agent and cluster.

Usage

pipeops agent info [flags]

Description

Shows detailed information about the installed agent, Kubernetes cluster, and node status.

Flags

Flag	Type	Description
`--show-join-token`	boolean	Display join token for adding workers
`--show-config`	boolean	Display agent configuration

Examples

View cluster info:

pipeops agent info

Output:

Agent Information:
  Version: 1.0.0
  Status: Running
  Uptime: 5 days, 3 hours
  Server ID: srv_1234567890

Cluster Information:
  Name: production-cluster
  Type: Control Plane
  Kubernetes Version: v1.28.0
  API Server: https://192.168.1.100:6443

Node Information:
  Name: control-plane-01
  Status: Ready
  Role: control-plane
  CPU: 4 cores
  Memory: 8GB
  Pods: 15/110
  
Network:
  Pod CIDR: 10.244.0.0/16
  Service CIDR: 10.96.0.0/12
  CNI Plugin: flannel

Get join token:

pipeops agent info --show-join-token

Output:

Join token for worker nodes:
  pipeops agent join --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

This token is valid for 24 hours.

View configuration:

pipeops agent info --show-config

JSON output:

pipeops agent info --json

{
  "agent": {
    "version": "1.0.0",
    "status": "running",
    "uptime_seconds": 432000
  },
  "cluster": {
    "name": "production-cluster",
    "type": "control-plane",
    "kubernetes_version": "v1.28.0",
    "api_server": "https://192.168.1.100:6443"
  },
  "node": {
    "name": "control-plane-01",
    "status": "Ready",
    "roles": ["control-plane"],
    "cpu_cores": 4,
    "memory_gb": 8,
    "pods": 15,
    "max_pods": 110
  }
}

Common Agent Workflows

Setting Up a Multi-Node Cluster

1. Install control plane:

# On first node
sudo pipeops agent install --cluster-name production

# Save the join token from output

2. Join worker nodes:

# On additional nodes
sudo pipeops agent join --token <join-token>

3. Verify cluster:

# On control plane
pipeops agent info
kubectl get nodes

Managing Agent Service

Check agent status:

sudo systemctl status pipeops-agent

Restart agent:

sudo systemctl restart pipeops-agent

View agent logs:

sudo journalctl -u pipeops-agent -f

Stop agent:

sudo systemctl stop pipeops-agent

Upgrading Agent

Check current version:

pipeops agent info | grep Version

Upgrade to latest:

sudo pipeops agent upgrade

Upgrade to specific version:

sudo pipeops agent upgrade --version 1.2.0

Removing Agent

Uninstall agent and cluster:

sudo pipeops agent uninstall

This will:

Stop agent service
Remove Kubernetes cluster
Clean up resources
Unregister from platform

Uninstall with data cleanup:

sudo pipeops agent uninstall --purge

Security Considerations

Agent Authentication

Agents use mutual TLS for platform communication
Join tokens expire after 24 hours
Tokens are single-use (join once)
All communication is encrypted

Network Security

Required ports:

6443: Kubernetes API server
10250: Kubelet API
10251: kube-scheduler (localhost only)
10252: kube-controller-manager (localhost only)
2379-2380: etcd (control plane only)

Firewall rules:

# Control plane
sudo ufw allow 6443/tcp
sudo ufw allow 10250/tcp
sudo ufw allow 2379:2380/tcp

# Worker nodes
sudo ufw allow 10250/tcp

Best Practices

Use dedicated infrastructure: Don't install agent on shared machines
Keep agent updated: Regular upgrades for security patches
Monitor agent health: Set up alerts for agent failures
Secure join tokens: Don't commit tokens to version control
Use node labels: Organize workload placement
Regular backups: Backup etcd on control plane

Troubleshooting

Agent Won't Start

Check logs:

sudo journalctl -u pipeops-agent -n 50

Verify configuration:

pipeops agent info --show-config

Check permissions:

ls -l /etc/pipeops-agent/

Cluster Issues

Node not ready:

kubectl get nodes
kubectl describe node <node-name>

Pod networking issues:

kubectl get pods -n kube-system
kubectl logs <cni-pod> -n kube-system

API server unreachable:

# Check if API server is running
sudo systemctl status kube-apiserver

# Check API server logs
sudo journalctl -u kube-apiserver

Server Management: Managing servers via web UI
Server Provisioning: Provisioning PipeOps servers
Quick Start: CLI getting started guide
Troubleshooting: General troubleshooting

Agent Commands

Overview​

pipeops agent install​

Usage​

Description​

Flags​

Prerequisites​

Examples​

What Gets Installed​

Installation Output​

Platform Support​

Linux​

FreeBSD​

Troubleshooting Installation​

pipeops agent join​

Usage​

Description​

Flags​

Prerequisites​

Examples​

Join Process​

Getting Join Token​

Troubleshooting Join​

pipeops agent info​

Usage​

Description​

Flags​

Examples​

Common Agent Workflows​

Setting Up a Multi-Node Cluster​

Managing Agent Service​

Upgrading Agent​

Removing Agent​

Security Considerations​

Agent Authentication​

Network Security​

Best Practices​

Troubleshooting​

Agent Won't Start​

Cluster Issues​

Related Documentation​

See Also​

Overview

`pipeops agent install`

Usage

Description

Flags

Prerequisites

Examples

What Gets Installed

Installation Output

Platform Support

Linux

FreeBSD

Troubleshooting Installation

`pipeops agent join`

Usage

Description

Flags

Prerequisites

Examples

Join Process

Getting Join Token

Troubleshooting Join

`pipeops agent info`

Usage

Description

Flags

Examples

Common Agent Workflows

Setting Up a Multi-Node Cluster

Managing Agent Service

Upgrading Agent

Removing Agent

Security Considerations

Agent Authentication

Network Security

Best Practices

Troubleshooting

Agent Won't Start

Cluster Issues

Related Documentation

See Also