k3s-ansible/GETTING_STARTED.md

Getting Started with Compute Blade Agent Deployment

This document provides a quick guide to deploy your k3s-ansible cluster with Compute Blade Agent support.

Prerequisites

• Ansible installed on your control machine
• SSH access to all nodes configured
• Raspberry Pi CM4/CM5 modules with Raspberry Pi OS installed

Quick Start (5 minutes)

Step 1: Review Configuration

cat inventory/hosts.ini

Verify:

• Master nodes are correct (cm4-01, cm4-02, cm4-03)
• Worker node IP is correct (cm4-04)
• enable_compute_blade_agent=true is set (optional for masters)

Step 2: Test Connectivity

ansible all -m ping

All nodes should respond with pong.

Step 3: Deploy

ansible-playbook site.yml

This will:

1. Prepare all nodes (10-15 minutes)
2. Install K3s server on master (5 minutes)
3. Install K3s agents on workers (5 minutes)
4. Install compute-blade-agent on all nodes (2-3 minutes per node)
5. Deploy test application (1 minute)

Total time: ~30-45 minutes

Step 4: Verify Cluster

export KUBECONFIG=$(pwd)/kubeconfig
kubectl get nodes

You should see all 4 nodes ready (3 masters + 1 worker):

NAME     STATUS   ROLES                       AGE   VERSION
cm4-01   Ready    control-plane,etcd,master   5m    v1.35.0+k3s1
cm4-02   Ready    control-plane,etcd          3m    v1.35.0+k3s1
cm4-03   Ready    control-plane,etcd          3m    v1.35.0+k3s1
cm4-04   Ready    <none>                      3m    v1.35.0+k3s1

Configuration

Enable/Disable Agent

To enable agent on all nodes (default):

[k3s_cluster:vars]
enable_compute_blade_agent=true

To disable agent:

enable_compute_blade_agent=false

To enable/disable on specific nodes:

[master]
cm4-01 ansible_host=192.168.30.101 ansible_user=pi k3s_server_init=true enable_compute_blade_agent=true
cm4-02 ansible_host=192.168.30.102 ansible_user=pi k3s_server_init=false enable_compute_blade_agent=false
cm4-03 ansible_host=192.168.30.103 ansible_user=pi k3s_server_init=false enable_compute_blade_agent=false

[worker]
cm4-04 ansible_host=192.168.30.104 ansible_user=pi enable_compute_blade_agent=true

Deployment Options

Option 1: Full Deployment (Recommended for new clusters)

ansible-playbook site.yml

Deploys K3s + compute-blade-agent on all nodes + test application

Option 2: Skip Test Application (Faster)

ansible-playbook site.yml --skip-tags test

Useful if cluster already has applications

Option 3: Agent Only (Existing K3s cluster)

ansible-playbook site.yml --tags compute-blade-agent

Deploy agent to existing K3s cluster (all nodes)

Option 4: Skip Agent

ansible-playbook site.yml --skip-tags compute-blade-agent

Deploy K3s without agent

Verification

Check Agent Status

# From control machine
bash scripts/verify-compute-blade-agent.sh

# On any node
ssh pi@192.168.30.101
sudo systemctl status compute-blade-agent

View Logs

ssh pi@192.168.30.101
sudo journalctl -u compute-blade-agent -f

Press Ctrl+C to exit logs.

Check Binary

ssh pi@192.168.30.101
/usr/bin/compute-blade-agent --version

What Was Installed

On Each Node (Control-plane and Workers)

• Binary: /usr/bin/compute-blade-agent
• CLI Tool: /usr/local/bin/bladectl
• Config: /etc/compute-blade-agent/config.yaml
• Service: compute-blade-agent.service (auto-start)

Features Enabled

• Hardware monitoring (temperature, fan speed, buttons)
• Critical mode protection (overheat response)
• LED identification (blade location)
• Prometheus metrics export
• Auto-restart on node reboot

Troubleshooting

Service Not Running

Check Service

ssh pi@192.168.30.101
sudo systemctl status compute-blade-agent
sudo journalctl -u compute-blade-agent -n 50

Re-run Deployment

ansible-playbook site.yml --tags compute-blade-agent

Check Installation on Node

ssh pi@192.168.30.102
ls -la /usr/bin/compute-blade-agent
ls -la /etc/compute-blade-agent/
sudo systemctl status compute-blade-agent

Next Steps

1. Review Documentation

   • COMPUTE_BLADE_AGENT.md - Quick reference
   • DEPLOYMENT_CHECKLIST.md - Detailed steps
   • README.md - Full guide

2. Configure Monitoring (Optional)

   kubectl apply -f manifests/compute-blade-agent-daemonset.yaml
   

3. Access Cluster (If deployed K3s)

   export KUBECONFIG=$(pwd)/kubeconfig
   kubectl get nodes
   

4. Customize Configuration (If needed)

   • Edit inventory/hosts.ini for deployment options
   • Edit /etc/compute-blade-agent/config.yaml on nodes

Common Tasks

Check Cluster Status

export KUBECONFIG=$(pwd)/kubeconfig
kubectl get nodes
kubectl get pods --all-namespaces

Access Any Master Node

# Access cm4-01
ssh pi@192.168.30.101

# Or access cm4-02 (backup master)
ssh pi@192.168.30.102

# Or access cm4-03 (backup master)
ssh pi@192.168.30.103

Deploy Only to Specific Nodes

ansible-playbook site.yml --tags compute-blade-agent --limit cm4-01

Disable Agent for Next Deployment

# Edit inventory/hosts.ini
enable_compute_blade_agent=false

# Then run playbook again
ansible-playbook site.yml --tags compute-blade-agent

Uninstall

Uninstall Agent (All Workers)

ansible k3s_cluster -m shell -a "bash /usr/local/bin/k3s-uninstall-compute-blade-agent.sh" --become

Uninstall K3s (All Nodes)

ansible all -m shell -a "bash /usr/local/bin/k3s-uninstall.sh" --become

Documentation

• README.md - Full guide with all configuration options
• DEPLOYMENT_CHECKLIST.md - Step-by-step checklist
• COMPUTE_BLADE_AGENT.md - Quick reference for agent deployment
• MIKROTIK-VIP-SETUP-CUSTOM.md - Virtual IP failover configuration

File Locations

k3s-ansible/
├── inventory/hosts.ini                    ← Configuration
├── site.yml                               ← Main playbook
├── roles/compute-blade-agent/
│   └── tasks/main.yml                    ← Installation logic
├── manifests/
│   └── compute-blade-agent-daemonset.yaml ← K8s resources
├── scripts/
│   └── verify-compute-blade-agent.sh     ← Verification
├── GETTING_STARTED.md                     ← This file
├── COMPUTE_BLADE_AGENT.md                 ← Quick reference
├── DEPLOYMENT_CHECKLIST.md                ← Step-by-step
└── README.md                              ← Full documentation

---

Ready to deploy? Run this command:

ansible-playbook site.yml

Then verify with:

bash scripts/verify-compute-blade-agent.sh

Good luck! 🚀