@bryanjbelanger/talos-skills 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# Talos Linux Skills Suite for Pi
+
+A complete **Pi Skills** suite for managing immutable [Talos Linux](https://www.talos.dev) Kubernetes clusters and machine nodes directly via `talosctl`.
+
+---
+
+## Included Skills
+
+| Skill | Description | Usage Command |
+| :--- | :--- | :--- |
+| **`talos-cluster`** | Generating configs, applying node configurations, bootstrapping etcd, fetching `kubeconfig`, and validating cluster health. | `/skill:talos-cluster` |
+| **`talos-node`** | Inspecting machine services, viewing logs (`kubelet`, `dmesg`), rebooting, OS upgrades, and node resets. | `/skill:talos-node` |
+
+---
+
+## Prerequisites
+
+* **Node.js v20.6+**
+* `talosctl` CLI (automatically downloaded and configured on first use if absent).
+
+---
+
+## Installation & Usage
+
+### Option A: Install via npm package
+In any project:
+```bash
+npm install --save-dev @bryanjbelanger/talos-skills
+```
+And add to `.pi/settings.json`:
+```json
+{
+  "skills": ["node_modules/@bryanjbelanger/talos-skills"]
+}
+```
+
+---
+
+## License
+
+MIT License

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bryanjbelanger/talos-skills",
+  "version": "1.0.0",
+  "description": "Talos Linux Kubernetes cluster management skills suite for Pi agent using talosctl CLI.",
+  "type": "module",
+  "main": "scripts/talosctl-helper.js",
+  "bin": {
+    "talosctl-helper": "scripts/talosctl-helper.js"
+  },
+  "files": [
+    "skills/",
+    "scripts/",
+    "README.md"
+  ],
+  "pi": {
+    "skills": [
+      "skills"
+    ]
+  },
+  "keywords": [
+    "pi",
+    "pi-skill",
+    "talos",
+    "talosctl",
+    "kubernetes",
+    "k8s",
+    "siderolabs",
+    "devops"
+  ],
+  "author": "Bryan Belanger <bryanbelanger@hotmail.com>",
+  "license": "MIT"
+}

package/scripts/talosctl-helper.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execSync } from "child_process";
+
+const TALOS_VERSION = "v1.9.4";
+
+function getPlatform() {
+  const platform = os.platform();
+  const arch = os.arch();
+  let osName = platform;
+  if (platform === "darwin") osName = "darwin";
+  else if (platform === "linux") osName = "linux";
+  else if (platform === "win32") osName = "windows";
+
+  let archName = arch;
+  if (arch === "x64") archName = "amd64";
+  else if (arch === "arm64") archName = "arm64";
+
+  return { osName, archName };
+}
+
+async function ensureTalosctl() {
+  try {
+    execSync("talosctl version --client --short", { stdio: "ignore" });
+    return "talosctl";
+  } catch {
+    // Check local bin fallback
+    const binDir = path.join(process.env.HOME || "", ".local", "bin");
+    const localBinary = path.join(binDir, process.platform === "win32" ? "talosctl.exe" : "talosctl");
+    if (fs.existsSync(localBinary)) {
+      return localBinary;
+    }
+
+    fs.mkdirSync(binDir, { recursive: true });
+    const { osName, archName } = getPlatform();
+    const downloadUrl = `https://github.com/siderolabs/talos/releases/download/${TALOS_VERSION}/talosctl-${osName}-${archName}`;
+
+    console.log(`Downloading talosctl ${TALOS_VERSION} for ${osName}/${archName}...`);
+    const res = await fetch(downloadUrl);
+    if (!res.ok) throw new Error(`Failed to download talosctl from ${downloadUrl}: ${res.statusText}`);
+
+    const fileStream = fs.createWriteStream(localBinary);
+    const reader = res.body.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      fileStream.write(value);
+    }
+    fileStream.end();
+
+    if (process.platform !== "win32") {
+      fs.chmodSync(localBinary, 0o755);
+    }
+
+    console.log(`talosctl installed to ${localBinary}`);
+    return localBinary;
+  }
+}
+
+async function main() {
+  const binary = await ensureTalosctl();
+  const args = process.argv.slice(2);
+  if (args.length > 0) {
+    try {
+      const output = execSync(`"${binary}" ${args.join(" ")}`, { encoding: "utf-8" });
+      console.log(output);
+    } catch (err) {
+      console.error(err.stdout || err.stderr || err.message);
+      process.exit(err.status || 1);
+    }
+  } else {
+    console.log(`talosctl binary ready: ${binary}`);
+  }
+}
+
+main().catch(err => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});

package/skills/talos-cluster/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: talos-cluster
+description: Create, configure, bootstrap, and validate Talos Linux Kubernetes clusters using talosctl. Use when generating machine configs, applying node configs, bootstrapping etcd, fetching kubeconfig, or checking cluster health.
+---
+
+# Talos Linux Cluster Management
+
+## Preflight
+
+Verify `talosctl` is installed (auto-installed if missing via helper):
+```bash
+node ./scripts/talosctl-helper.js version --client
+```
+
+---
+
+## 1. Generate Machine Configs
+
+Generate Talos machine configurations for control plane and worker nodes along with `talosconfig`:
+```bash
+# Syntax: talosctl gen config <cluster-name> <cluster-endpoint-url> --output-dir <dir>
+node ./scripts/talosctl-helper.js gen config "vbox-dc" "https://10.0.10.10:6443" --output-dir ./talos-config
+```
+*Produces `controlplane.yaml`, `worker.yaml`, and `talosconfig`.*
+
+---
+
+## 2. Apply Machine Config to Nodes
+
+Apply the generated machine configs to fresh Talos nodes in maintenance mode:
+
+```bash
+# Apply to Control Plane Node (insecure initial apply before TLS PKI is active)
+node ./scripts/talosctl-helper.js apply-config --insecure --nodes 10.0.10.10 --file ./talos-config/controlplane.yaml
+
+# Apply to Worker Node
+node ./scripts/talosctl-helper.js apply-config --insecure --nodes 10.0.20.20 --file ./talos-config/worker.yaml
+```
+
+---
+
+## 3. Configure Local talosctl Client
+
+Merge the generated `talosconfig` context and target the control plane endpoint:
+```bash
+# Merge context
+node ./scripts/talosctl-helper.js config merge ./talos-config/talosconfig
+node ./scripts/talosctl-helper.js config endpoint 10.0.10.10
+node ./scripts/talosctl-helper.js config node 10.0.10.10
+```
+
+---
+
+## 4. Bootstrap etcd Cluster
+
+Bootstrap the primary control plane node (run **once** per cluster):
+```bash
+node ./scripts/talosctl-helper.js bootstrap --nodes 10.0.10.10
+```
+
+---
+
+## 5. Retrieve Kubeconfig & Verify Health
+
+Fetch cluster kubeconfig and verify Kubernetes API accessibility:
+```bash
+# Retrieve kubeconfig
+node ./scripts/talosctl-helper.js kubeconfig . --nodes 10.0.10.10
+
+# Validate cluster health
+node ./scripts/talosctl-helper.js health --nodes 10.0.10.10
+```
+
+Verify with `kubectl`:
+```bash
+kubectl --kubeconfig ./kubeconfig get nodes -o wide
+```
+
+---
+
+## Advanced Topics & Reference Guides
+* For machine config patches, inline JSON/YAML overlays, and HA VIP setup, see `references/config-patches.md`.
+

package/skills/talos-cluster/references/config-patches.md

@@ -0,0 +1,36 @@
+# Talos Machine Config Patches & HA Clusters
+
+## Machine Config Patches
+
+Talos uses JSON/YAML Strategic Merge Patches (`--config-patch`) or inline JSON patches (`--config-patch-control-plane`) when generating machine configurations.
+
+### 1. Define Patch (`patch.yaml`)
+Example: Enable VIP (Virtual IP) for HA Control Plane and enable extra kernel arguments:
+
+```yaml
+machine:
+  network:
+    interfaces:
+      - interface: eth0
+        dhcp: true
+        vip:
+          ip: 10.0.10.100
+  sysctls:
+    net.ipv4.ip_forward: "1"
+cluster:
+  extraManifests:
+    - https://raw.githubusercontent.com/alex1989hu/kubelet-serving-cert-approver/main/deploy/ha-control-plane-k8s-1.27.yaml
+```
+
+### 2. Apply Patch During Config Generation
+```bash
+talosctl gen config "vbox-dc" "https://10.0.10.100:6443" \
+  --config-patch @patch.yaml \
+  --output-dir ./talos-config
+```
+
+### 3. Patching Live Nodes
+Apply patches to live running nodes without full reconfiguration:
+```bash
+talosctl patch machineconfig --nodes 10.0.10.10 --patch '[{"op": "replace", "path": "/machine/time/servers/0", "value": "pool.ntp.org"}]'
+```

package/skills/talos-node/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: talos-node
+description: Manage Talos Linux nodes — inspect machine status, view service logs, reboot, upgrade, or reset nodes via talosctl. Use when checking Talos node health, viewing dmesg/logs, rebooting nodes, or upgrading Talos OS.
+---
+
+# Talos Node Operations
+
+## Preflight
+
+Verify `talosctl` client configuration:
+```bash
+node ./scripts/talosctl-helper.js version --nodes 10.0.10.10
+```
+
+---
+
+## 1. Inspect Node Status & Services
+
+### View Machine Services & Resources
+```bash
+# List running Talos machine services (etcd, kubelet, containerd, etc.)
+node ./scripts/talosctl-helper.js service --nodes 10.0.10.10
+
+# Get machine members and cluster state
+node ./scripts/talosctl-helper.js get members --nodes 10.0.10.10
+```
+
+### View Logs & Kernel Messages
+```bash
+# View kubelet or containerd logs
+node ./scripts/talosctl-helper.js logs kubelet --nodes 10.0.10.10
+node ./scripts/talosctl-helper.js logs containerd --nodes 10.0.10.10
+
+# View kernel dmesg
+node ./scripts/talosctl-helper.js dmesg --nodes 10.0.10.10
+```
+
+---
+
+## 2. Node Lifecycle Operations
+
+### Reboot Node
+```bash
+node ./scripts/talosctl-helper.js reboot --nodes 10.0.10.10
+```
+
+### Upgrade Talos OS Image
+Upgrade a node to a newer Talos Linux installer image:
+```bash
+node ./scripts/talosctl-helper.js upgrade --nodes 10.0.10.10 --image factory.talos.dev/installer/v1.9.4
+```
+
+### Reset Node (Wipe & Return to Maintenance Mode)
+Wipe node data disk and reset to clean installer state:
+```bash
+node ./scripts/talosctl-helper.js reset --nodes 10.0.10.10 --system-labels-to-wipe STATE,EPHEMERAL --reboot
+```
+
+---
+
+## Advanced Topics & Reference Guides
+* For etcd snapshots, restores, process/memory stats, container inspection, and disk layouts, see `references/etcd-and-troubleshooting.md`.
+

package/skills/talos-node/references/etcd-and-troubleshooting.md

@@ -0,0 +1,52 @@
+# Talos Etcd Operations, Containers & Troubleshooting
+
+## Etcd Maintenance & Backup
+
+### 1. Etcd Status & Health
+```bash
+# Check etcd members and health
+talosctl etcd members --nodes 10.0.10.10
+talosctl etcd status --nodes 10.0.10.10
+talosctl etcd alarm list --nodes 10.0.10.10
+```
+
+### 2. Etcd Snapshot Backup & Restore
+```bash
+# Take etcd snapshot
+talosctl etcd snapshot ./etcd-backup.snapshot --nodes 10.0.10.10
+
+# Defrag etcd database
+talosctl etcd defrag --nodes 10.0.10.10
+```
+
+---
+
+## Machine Inspection & Diagnostics
+
+### 1. Running Containers & Processes
+```bash
+# List all running CRI containers on node
+talosctl containers --nodes 10.0.10.10
+talosctl containers --nodes 10.0.10.10 --kubernetes
+
+# Inspect processes and resource usage
+talosctl processes --nodes 10.0.10.10
+talosctl stats --nodes 10.0.10.10
+talosctl memory --nodes 10.0.10.10
+```
+
+### 2. Disks & Mounts
+```bash
+# List disks and partition layout
+talosctl disks --nodes 10.0.10.10
+talosctl mounts --nodes 10.0.10.10
+```
+
+### 3. Read Machine Configuration & Files
+```bash
+# Retrieve live running machine configuration
+talosctl get machineconfig --nodes 10.0.10.10
+
+# Read file from node filesystem
+talosctl read /etc/hosts --nodes 10.0.10.10
+```