fixing linter errors in markdown

2025-11-24 10:30:46 +01:00
parent fe7d03ce9a
commit 8e9f0caf6c
4 changed files with 104 additions and 7 deletions
--- a/COMPUTE_BLADE_AGENT.md
+++ b/COMPUTE_BLADE_AGENT.md
@@ -5,16 +5,19 @@ Quick reference for deploying and managing the Compute Blade Agent in your k3s-a
 ## Quick Start

 ### Deploy Everything
+
 ```bash
 ansible-playbook site.yml
 ```

 ### Deploy Only Compute Blade Agent
+
 ```bash
 ansible-playbook site.yml --tags compute-blade-agent
 ```

 ### Skip Compute Blade Agent
+
 ```bash
 ansible-playbook site.yml --skip-tags compute-blade-agent
 ```
@@ -24,6 +27,7 @@ ansible-playbook site.yml --skip-tags compute-blade-agent
 ### Enable/Disable Globally

 Edit `inventory/hosts.ini`:
+
 ```ini
 [k3s_cluster:vars]
 enable_compute_blade_agent=true    # Set to false to disable
@@ -32,6 +36,7 @@ enable_compute_blade_agent=true    # Set to false to disable
 ### Enable/Disable Per-Node

 Edit `inventory/hosts.ini`:
+
 ```ini
 [worker]
 cb-02 ansible_host=192.168.30.102 ansible_user=pi enable_compute_blade_agent=true
@@ -42,18 +47,21 @@ cb-04 ansible_host=192.168.30.104 ansible_user=pi
 ## Verification

 ### Check Service Status
+
 ```bash
 ssh pi@<worker-ip>
 sudo systemctl status compute-blade-agent
 ```

 ### View Logs
+
 ```bash
 ssh pi@<worker-ip>
 sudo journalctl -u compute-blade-agent -f
 ```

 ### Check Installation
+
 ```bash
 ssh pi@<worker-ip>
 /usr/local/bin/compute-blade-agent --version
@@ -70,6 +78,7 @@ ls -la /etc/compute-blade-agent/
 ## Environment Variables

 Configure via `BLADE_` prefixed environment variables:
+
 ```bash
 export BLADE_CONFIG_PATH=/etc/compute-blade-agent/config.yaml
 /usr/local/bin/compute-blade-agent
@@ -80,11 +89,13 @@ export BLADE_CONFIG_PATH=/etc/compute-blade-agent/config.yaml
 ### Optional Kubernetes Resources

 Deploy monitoring components:
+
 ```bash
 kubectl apply -f manifests/compute-blade-agent-daemonset.yaml
 ```

 This creates:
+
 - Namespace: `compute-blade-agent`
 - ConfigMap: `compute-blade-agent-config`
 - DaemonSet: `compute-blade-agent-exporter`
@@ -93,6 +104,7 @@ This creates:
 ### Prometheus Integration

 To enable Prometheus scraping, uncomment the ServiceMonitor in the manifest:
+
 ```yaml
 apiVersion: monitoring.coreos.com/v1
 kind: ServiceMonitor
@@ -112,6 +124,7 @@ spec:
 ## Troubleshooting

 ### Service Not Running
+
 ```bash
 # Check service status
 sudo systemctl status compute-blade-agent
@@ -124,11 +137,13 @@ sudo systemctl restart compute-blade-agent
 ```

 ### Hardware Not Detected
+
 1. Verify hardware is connected
 2. Check logs for hardware errors
 3. Ensure systemd service started correctly

 ### Reinstall
+
 ```bash
 # SSH to node
 ssh pi@<worker-ip>
@@ -146,12 +161,14 @@ ansible-playbook site.yml --tags compute-blade-agent
 ## Uninstall

 ### From Single Node
+
 ```bash
 ssh pi@<worker-ip>
 sudo bash /usr/local/bin/k3s-uninstall-compute-blade-agent.sh
 ```

 ### From All Worker Nodes
+
 ```bash
 ansible worker -m shell -a "bash /usr/local/bin/k3s-uninstall-compute-blade-agent.sh" --become
 ```
--- a/DEPLOYMENT_CHECKLIST.md
+++ b/DEPLOYMENT_CHECKLIST.md
@@ -10,10 +10,13 @@
 ## Deployment

 ### Option 1: Full Stack Deployment (Recommended for new clusters)
+
 ```bash
 ansible-playbook site.yml
 ```
+
 This will:
+
 1. Prepare all nodes (prerequisites)
 2. Install K3s server on master
 3. Install K3s agents on workers
@@ -25,6 +28,7 @@ This will:
 - [ ] Check for any errors in output

 ### Option 2: Skip Test Application
+
 ```bash
 ansible-playbook site.yml --skip-tags test
 ```
@@ -33,6 +37,7 @@ ansible-playbook site.yml --skip-tags test
 - [ ] Faster deployment, suitable if cluster already has applications

 ### Option 3: Deploy Only Compute Blade Agent
+
 ```bash
 ansible-playbook site.yml --tags compute-blade-agent
 ```
@@ -44,49 +49,60 @@ ansible-playbook site.yml --tags compute-blade-agent
 ## Post-Deployment Verification

 ### 1. Check Cluster Status
+
 ```bash
 export KUBECONFIG=$(pwd)/kubeconfig
 kubectl get nodes
 ```
+
 - [ ] All master and worker nodes should show "Ready"

 ### 2. Run Verification Script
+
 ```bash
 bash scripts/verify-compute-blade-agent.sh
 ```
+
 - [ ] All worker nodes pass connectivity check
 - [ ] Binary is installed at `/usr/local/bin/compute-blade-agent`
 - [ ] Service status shows "Running"
 - [ ] Config file exists at `/etc/compute-blade-agent/config.yaml`

 ### 3. Manual Verification on a Worker
+
 ```bash
 ssh pi@192.168.30.102
 sudo systemctl status compute-blade-agent
 ```
+
 - [ ] Service is active (running)
 - [ ] Service is enabled (will start on boot)

 ### 4. Check Logs
+
 ```bash
 ssh pi@192.168.30.102
 sudo journalctl -u compute-blade-agent -n 50
 ```
+
 - [ ] No error messages
 - [ ] Service started successfully
 - [ ] Hardware detection messages present (if applicable)

 ### 5. Verify Installation
+
 ```bash
 ssh pi@192.168.30.102
 /usr/local/bin/compute-blade-agent --version
 ```
+
 - [ ] Binary responds with version information
 - [ ] bladectl CLI tool is available

 ## Optional: Kubernetes Monitoring Setup

 ### Deploy Monitoring Resources
+
 ```bash
 kubectl apply -f manifests/compute-blade-agent-daemonset.yaml
 ```
@@ -96,6 +112,7 @@ kubectl apply -f manifests/compute-blade-agent-daemonset.yaml
 - [ ] Check service: `kubectl get service -n compute-blade-agent`

 ### Enable Prometheus Monitoring
+
 1. Edit `manifests/compute-blade-agent-daemonset.yaml`
 2. Uncomment the ServiceMonitor section
 3. Apply: `kubectl apply -f manifests/compute-blade-agent-daemonset.yaml`
@@ -106,18 +123,21 @@ kubectl apply -f manifests/compute-blade-agent-daemonset.yaml
 ## Troubleshooting

 ### Service Not Running
+
 - [ ] Check status: `sudo systemctl status compute-blade-agent`
 - [ ] Check logs: `sudo journalctl -u compute-blade-agent -f`
 - [ ] Check if binary exists: `ls -la /usr/local/bin/compute-blade-agent`
 - [ ] Check systemd unit: `cat /etc/systemd/system/compute-blade-agent.service`

 ### Installation Failed
+
 - [ ] Re-run Ansible playbook: `ansible-playbook site.yml --tags compute-blade-agent`
 - [ ] Check for network connectivity during installation
 - [ ] Verify sufficient disk space on nodes
 - [ ] Check /tmp directory permissions

 ### Hardware Not Detected
+
 - [ ] Verify physical hardware connection
 - [ ] Check dmesg: `sudo dmesg | grep -i compute`
 - [ ] Check hardware info: `lspci` or `lsusb`
@@ -126,7 +146,9 @@ kubectl apply -f manifests/compute-blade-agent-daemonset.yaml
 ## Configuration

 ### Global Configuration
+
 To enable/disable on all workers, edit `inventory/hosts.ini`:
+
 ```ini
 [k3s_cluster:vars]
 enable_compute_blade_agent=true  # or false
@@ -136,7 +158,9 @@ enable_compute_blade_agent=true  # or false
 - [ ] Saved inventory file

 ### Per-Node Configuration
+
 To enable/disable specific nodes, edit `inventory/hosts.ini`:
+
 ```ini
 [worker]
 cb-02 ansible_host=... enable_compute_blade_agent=false
@@ -148,7 +172,9 @@ cb-03 ansible_host=... enable_compute_blade_agent=true
 - [ ] Re-run playbook if changes made

 ### Agent Configuration
+
 Edit configuration on the node:
+
 ```bash
 ssh pi@<worker-ip>
 sudo vi /etc/compute-blade-agent/config.yaml
@@ -161,49 +187,62 @@ sudo systemctl restart compute-blade-agent
 ## Maintenance

 ### Restart Service
+
 ```bash
 ssh pi@<worker-ip>
 sudo systemctl restart compute-blade-agent
 ```
+
 - [ ] Service restarted
 - [ ] Service is still running

 ### View Real-time Logs
+
 ```bash
 ssh pi@<worker-ip>
 sudo journalctl -u compute-blade-agent -f
 ```
+
 - [ ] Monitor for any issues
 - [ ] Press Ctrl+C to exit

 ### Check Service on All Workers
+
 ```bash
 ansible worker -m shell -a "systemctl status compute-blade-agent" --become
 ```
+
 - [ ] All workers show active status

 ## Uninstall (if needed)

 ### Uninstall from Single Node
+
 ```bash
 ssh pi@<worker-ip>
 sudo bash /usr/local/bin/k3s-uninstall-compute-blade-agent.sh
 ```
+
 - [ ] Uninstall script executed
 - [ ] Service removed
 - [ ] Configuration cleaned up

 ### Uninstall from All Workers
+
 ```bash
 ansible worker -m shell -a "bash /usr/local/bin/k3s-uninstall-compute-blade-agent.sh" --become
 ```
+
 - [ ] All workers uninstalled

 ### Disable in Future Deployments
+
 Edit `inventory/hosts.ini`:
+
 ```ini
 enable_compute_blade_agent=false
 ```
+
 - [ ] Setting disabled
 - [ ] Won't be deployed on next playbook run

@@ -211,7 +250,7 @@ enable_compute_blade_agent=false

 - [ ] Read README.md compute-blade-agent section
 - [ ] Read COMPUTE_BLADE_AGENT.md quick reference
- [ ] Check GitHub repo: https://github.com/compute-blade-community/compute-blade-agent
+- [ ] Check GitHub repo: [compute-blade-agent](https://github.com/compute-blade-community/compute-blade-agent)
 - [ ] Review Ansible role: `cat roles/compute-blade-agent/tasks/main.yml`

 ## Completion
@@ -227,7 +266,7 @@ enable_compute_blade_agent=false

 Document any issues, customizations, or special configurations here:

-```
+```text
 [Add notes here]
 ```

--- a/GETTING_STARTED.md
+++ b/GETTING_STARTED.md
@@ -11,16 +11,19 @@ This document provides a quick guide to deploy your k3s-ansible cluster with Com
 ## Quick Start (5 minutes)

 ### Step 1: Review Configuration
+
 ```bash
 cat inventory/hosts.ini
 ```

 Verify:
+
 - Master node IP is correct (cb-01)
 - Worker node IPs are correct (cb-02, cb-03, cb-04)
 - `enable_compute_blade_agent=true` is set

 ### Step 2: Test Connectivity
+
 ```bash
 ansible all -m ping
 ```
@@ -28,11 +31,13 @@ ansible all -m ping
 All nodes should respond with `pong`.

 ### Step 3: Deploy
+
 ```bash
 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)
@@ -42,11 +47,13 @@ This will:
 **Total time**: ~30-45 minutes

 ### Step 4: Verify
+
 ```bash
 bash scripts/verify-compute-blade-agent.sh
 ```

 All workers should show:
+
 - ✓ Network: Reachable
 - ✓ Service Status: Running
 - ✓ Binary: Installed
@@ -56,17 +63,20 @@ All workers should show:
 ### Enable/Disable Agent

 To enable agent on all workers (default):
+
 ```ini
 [k3s_cluster:vars]
 enable_compute_blade_agent=true
 ```

 To disable agent:
+
 ```ini
 enable_compute_blade_agent=false
 ```

 To enable/disable on specific nodes:
+
 ```ini
 [worker]
 cb-02 ansible_host=192.168.30.102 ansible_user=pi enable_compute_blade_agent=true
@@ -77,32 +87,41 @@ cb-04 ansible_host=192.168.30.104 ansible_user=pi
 ## Deployment Options

 ### Option 1: Full Deployment (Recommended for new clusters)
+
 ```bash
 ansible-playbook site.yml
 ```
+
 Deploys K3s + compute-blade-agent + test application

 ### Option 2: Skip Test Application (Faster)
+
 ```bash
 ansible-playbook site.yml --skip-tags test
 ```
+
 Useful if cluster already has applications

 ### Option 3: Agent Only (Existing K3s cluster)
+
 ```bash
 ansible-playbook site.yml --tags compute-blade-agent
 ```
+
 Deploy agent to existing K3s cluster

 ### Option 4: Skip Agent
+
 ```bash
 ansible-playbook site.yml --skip-tags compute-blade-agent
 ```
+
 Deploy K3s without agent

 ## Verification

 ### Check Agent Status
+
 ```bash
 # From control machine
 bash scripts/verify-compute-blade-agent.sh
@@ -113,6 +132,7 @@ sudo systemctl status compute-blade-agent
 ```

 ### View Logs
+
 ```bash
 ssh pi@192.168.30.102
 sudo journalctl -u compute-blade-agent -f
@@ -121,6 +141,7 @@ sudo journalctl -u compute-blade-agent -f
 Press `Ctrl+C` to exit logs.

 ### Check Binary
+
 ```bash
 ssh pi@192.168.30.102
 /usr/local/bin/compute-blade-agent --version
@@ -129,12 +150,14 @@ ssh pi@192.168.30.102
 ## What Was Installed

 ### On Each Worker Node
+
 - **Binary**: `/usr/local/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)
@@ -144,6 +167,7 @@ ssh pi@192.168.30.102
 ## Troubleshooting

 ### Service Not Running
+
 ```bash
 ssh pi@192.168.30.102
 sudo systemctl status compute-blade-agent
@@ -151,11 +175,13 @@ sudo journalctl -u compute-blade-agent -n 50
 ```

 ### Re-run Deployment
+
 ```bash
 ansible-playbook site.yml --tags compute-blade-agent
 ```

 ### Check Installation on Node
+
 ```bash
 ssh pi@192.168.30.102
 ls -la /usr/local/bin/compute-blade-agent
@@ -171,11 +197,13 @@ sudo systemctl status compute-blade-agent
   - `README.md` - Full guide

 2. **Configure Monitoring** (Optional)
+
   ```bash
   kubectl apply -f manifests/compute-blade-agent-daemonset.yaml
   ```

 3. **Access Cluster** (If deployed K3s)
+
   ```bash
   export KUBECONFIG=$(pwd)/kubeconfig
   kubectl get nodes
@@ -188,21 +216,25 @@ sudo systemctl status compute-blade-agent
 ## Common Tasks

 ### Restart Agent on All Workers
+
 ```bash
 ansible worker -m shell -a "sudo systemctl restart compute-blade-agent" --become
 ```

 ### View Agent Logs on All Workers
+
 ```bash
 ansible worker -m shell -a "sudo journalctl -u compute-blade-agent -n 20" --become
 ```

 ### Deploy Only to Specific Nodes
+
 ```bash
 ansible-playbook site.yml --tags compute-blade-agent --limit cb-02,cb-03
 ```

 ### Disable Agent for Next Deployment
+
 ```bash
 # Edit inventory/hosts.ini
 enable_compute_blade_agent=false
@@ -214,11 +246,13 @@ ansible-playbook site.yml --tags compute-blade-agent
 ## Uninstall

 ### Uninstall Agent (All Workers)
+
 ```bash
 ansible worker -m shell -a "bash /usr/local/bin/k3s-uninstall-compute-blade-agent.sh" --become
 ```

 ### Uninstall K3s (All Nodes)
+
 ```bash
 ansible all -m shell -a "bash /usr/local/bin/k3s-uninstall.sh" --become
 ```
@@ -228,11 +262,11 @@ ansible all -m shell -a "bash /usr/local/bin/k3s-uninstall.sh" --become
 - **Quick Reference**: `cat COMPUTE_BLADE_AGENT.md`
 - **Checklist**: `cat DEPLOYMENT_CHECKLIST.md`
 - **Full Guide**: `cat README.md`
- **GitHub**: https://github.com/compute-blade-community/compute-blade-agent
+- **GitHub**: [compute-blade-agent](https://github.com/compute-blade-community/compute-blade-agent)

 ## File Locations

-```
+```bash
 k3s-ansible/
 ├── inventory/hosts.ini                    ← Configuration
 ├── site.yml                               ← Main playbook
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ Ansible playbook to deploy a k3s Kubernetes cluster on Raspberry Pi Compute Modu

 ## Project Structure

-```
+```bash
 k3s-ansible/
 ├── ansible.cfg                  # Ansible configuration
 ├── site.yml                     # Main playbook
@@ -123,6 +123,7 @@ ansible-playbook site.yml --tags prereq
 ## What the Playbook Does

 ### Prerequisites Role (`prereq`)
+
 - Sets hostname on each node
 - Updates and upgrades system packages
 - Installs required packages (curl, wget, git, iptables, etc.)
@@ -132,6 +133,7 @@ ansible-playbook site.yml --tags prereq
 - Reboots if necessary

 ### K3s Server Role (`k3s-server`)
+
 - Installs k3s in server mode on master node(s)
 - Configures k3s with Flannel VXLAN backend (optimized for ARM)
 - Retrieves and stores the node token for workers
@@ -139,11 +141,13 @@ ansible-playbook site.yml --tags prereq
 - Fetches kubeconfig to local machine for kubectl access

 ### K3s Agent Role (`k3s-agent`)
+
 - Installs k3s in agent mode on worker nodes
 - Joins workers to the cluster using the master's token
 - Configures agents to connect to the master

 ### K3s Deploy Test Role (`k3s-deploy-test`)
+
 - Waits for all cluster nodes to be ready
 - Deploys the nginx test application with 5 replicas
 - Verifies deployment is successful
@@ -163,7 +167,7 @@ kubectl get nodes

 You should see all your nodes in Ready state:

-```
+```bash
 NAME          STATUS   ROLES                  AGE   VERSION
 pi-master     Ready    control-plane,master   5m    v1.28.3+k3s1
 pi-worker-1   Ready    <none>                 3m    v1.28.3+k3s1
@@ -271,6 +275,7 @@ ansible-playbook site.yml --tags deploy-test
 ```

 The Ansible role will:
+
 - Wait for all nodes to be ready
 - Deploy the nginx application with ingress
 - Wait for all pods to be running
@@ -303,7 +308,7 @@ kubectl --kubeconfig=./kubeconfig get ingress

 You should see output similar to:

-```
+```bash
 NAME         READY   UP-TO-DATE   AVAILABLE   AGE
 nginx-test   5/5     5            5           1m

@@ -402,12 +407,14 @@ ansible-playbook reboot.yml --limit pi-worker-1
 ### Check k3s service status

 On master:
+
 ```bash
 sudo systemctl status k3s
 sudo journalctl -u k3s -f
 ```

 On workers:
+
 ```bash
 sudo systemctl status k3s-agent
 sudo journalctl -u k3s-agent -f