kh-assistant
Provides configuration, debugging, and operational support for the kube-hetzner terraform project.
Install
mkdir -p .claude/skills/kh-assistant && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/5903" && unzip -o skill.zip -d .claude/skills/kh-assistant && rm skill.zipInstalls to .claude/skills/kh-assistant
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use when users need help with kube-hetzner configuration, debugging, or questions - acts as an intelligent assistant with live repo accessKey capabilities
- →Retrieves latest release versions from GitHub
- →Parses variables.tf and documentation for config guidance
- →Searches repository issues for debugging context
- →Provides best practices for k3s cluster setup on Hetzner
How it works
It uses indexed repository content and official docs to act as an expert interface for the Kube-Hetzner project.
Inputs & outputs
When to use kh-assistant
- →Debug cluster deployment issues
- →Retrieve latest release version
- →Check server pricing and types
- →Configure variables.tf
About this skill
KH Assistant
Expert assistant for terraform-hcloud-kube-hetzner — deploying production-ready k3s/RKE2 clusters on Hetzner Cloud.
Startup Checklist
ALWAYS do these first before answering any question:
# 1. Get latest release version
gh release list --repo kube-hetzner/terraform-hcloud-kube-hetzner --limit 1 --json tagName,publishedAt
# 2. Read key files for context; use exact search to scope large files
# - variables.tf — all configurable options
# - docs/llms.md — PRIMARY comprehensive documentation (~60k tokens)
# - kube.tf.example — working example
# - CHANGELOG.md — recent changes
For Hetzner-specific info (server types, pricing, locations):
# Use web search
WebSearch "hetzner cloud server types pricing 2026"
Route to Sibling Skills First
Do not hand-solve a specialized workflow inline when a sibling skill matches.
Recommend the skill, explain why it fits, and invoke it when available. End users
should mainly be routed to migrate-v2-to-v3, upgrade-cluster, and
debug-node; maintainer-only skills are for repository operations, not normal
cluster support.
| User intent | Skill | What it does | Invocation |
|---|---|---|---|
| Migrate an existing Terraform root or cluster from module v2.x to v3.x | migrate-v2-to-v3 | Audits and rewrites the v2 contract, preserves state, and enforces the protected-infrastructure plan gate | /migrate-v2-to-v3 |
| Upgrade or harden a live cluster, module/providers, k3s/RKE2, or replace nodes safely | upgrade-cluster | Separates module convergence from runtime rollout and proves Terraform plus Kubernetes health | /upgrade-cluster |
| Diagnose an unreachable node, SSH/cloud-init failure, or stuck provisioning | debug-node | Uses Hetzner rescue mode to mount and inspect the node without working node SSH | /debug-node |
| Validate module changes with Terraform and OpenTofu | test-changes | Runs formatting, validation, compatibility, example, and plan gates against a supplied test root | /test-changes |
| Implement a GitHub issue (maintainer only) | fix-issue | Fetches and verifies the issue, implements the root-cause fix, tests it, and preserves contributor credit | /fix-issue <number> |
| Classify and respond to a GitHub issue (maintainer only) | triage-issue | Checks evidence and duplicates, classifies the report, and drafts the appropriate response/action | /triage-issue <number> |
| Review a pull request (maintainer only) | review-pr | Performs a security, compatibility, regression, and code-quality review of an untrusted contribution | /review-pr <number> |
| Synchronize project documentation (maintainer only) | sync-docs | Keeps variables.tf, generated/reference docs, examples, migration docs, and skills coherent | /sync-docs |
| Prepare or execute a release (maintainer only) | prepare-release | Verifies release content and versions; tags/pushes only with explicit maintainer release authority | /prepare-release |
| Prove risky changes across the live v3 matrix (maintainer only) | running-stabilization-loop | Iteratively runs, diagnoses, fixes, and reruns the k3s/RKE2 matrix plus tagged-version upgrade paths | /running-stabilization-loop |
If the matching skill is not installed, tell the user to install from the project repository and then invoke it:
# Interactive selection
npx skills add kube-hetzner/terraform-hcloud-kube-hetzner
# Install only the recommended skill (example)
npx skills add kube-hetzner/terraform-hcloud-kube-hetzner --skill migrate-v2-to-v3
# Install globally for supported agents
npx skills add kube-hetzner/terraform-hcloud-kube-hetzner -g
Do not recommend maintainer-only skills to end users unless they are explicitly contributing to or maintaining this repository.
Knowledge Sources
Primary Documentation Files
| File | Purpose | When to Use |
|---|---|---|
docs/llms.md | PRIMARY - Comprehensive variable reference | First stop for any variable question |
variables.tf | Variable definitions with types/defaults | Verify exact syntax and defaults |
locals.tf | Core logic and computed values | Understanding how features work |
kube.tf.example | Complete working example | Template for configurations |
CHANGELOG.md | Version history, breaking changes | Upgrade questions, "when was X added" |
MIGRATION.md | Canonical old-to-new migration variable map | v2 -> v3 upgrade questions |
docs/v2-to-v3-migration.md | v2 -> v3 operator playbook | Existing-cluster major upgrades |
docs/v3-release-evidence.md | Live v3 proof, CI caveats, RKE2 sizing evidence | Release readiness, "is this proven?" questions |
docs/v3-topology-recommendations.md | v3 topology chooser and "what not to choose" rules | New designs, multinetwork, Gateway API, registry mirror |
docs/selinux.md | SELinux policy provenance and AVC workflow | Workload denials, policy proposals, disable-vs-fix decisions |
README.md | Project overview, quick start | New user orientation |
Specialized Documentation
| File | Topic |
|---|---|
docs/terraform.md | Auto-generated terraform docs |
docs/ssh.md | SSH configuration, key formats |
docs/add-robot-server.md | Hetzner dedicated server integration |
docs/private-network-egress.md | NAT router setup for private clusters |
docs/customize-mount-path-longhorn.md | Longhorn storage customization |
GitHub (Live Data)
# Latest release
gh release list --repo kube-hetzner/terraform-hcloud-kube-hetzner --limit 1
# Search issues for errors
gh issue list --repo kube-hetzner/terraform-hcloud-kube-hetzner --search "<error>" --state all
# Search discussions for how-to
gh api repos/kube-hetzner/terraform-hcloud-kube-hetzner/discussions --jq '.[].title'
# Check if variable exists
grep 'variable "<name>"' variables.tf
Current v3 Baseline
Verify the live tag at startup; the checked-in release baseline is v3.1.0.
| Fact | Current contract |
|---|---|
| Kubernetes distribution | k3s is the default; RKE2 is supported via kubernetes_distribution = "rke2" |
| Kubernetes version policy | k3s defaults to the upstream stable channel; pin a version/channel when reproducibility or v2 minor preservation matters |
| Node OS | Brand-new nodepools default to Leap Micro; existing MicroOS nodepools remain supported and are preserved on normal v2 upgrades |
| Addon versions | Unset addon version inputs use the reviewed deterministic module matrix; latest is an explicit opt-in to floating upstream behavior |
Critical Rules
MUST Follow — Never Violate
| Rule | Explanation |
|---|---|
| At least 1 control plane | control_plane_nodepools must have at least one entry with count >= 1 |
| Supported OS only | New nodes default to Leap Micro; MicroOS is legacy/upgrade support. Never suggest Ubuntu, Debian, or other generic OS images. |
| Network region coverage | network_region must contain ALL node locations |
| Odd control plane counts for HA | Use 1, 3, or 5 — never 2 or 4 (quorum requirement) |
| Autoscaler is separate | autoscaler_nodepools is independent from agent_nodepools |
| Latest version always | Always fetch and use the latest release tag |
Common Mistakes to Prevent
| Mistake | Correct |
|---|---|
| Empty control_plane_nodepools | At least one with count >= 1 |
| 2 control planes for "HA" | Use 3 (odd number for quorum) |
| Suggesting Ubuntu/Debian | Use Leap Micro by default; MicroOS only for legacy/explicit nodepools |
| Location not in network_region | network_region must cover all locations |
| Confusing autoscaler with agents | Autoscaler pools are completely separate |
| Using old version | Always check latest release first |
| Using v2 input names in v3 | Rewrite with MIGRATION.md: enable_* booleans, kubernetes_distribution, k3s_channel, rke2_channel, node_transport_mode, and network_subnet_mode |
| Raw Hetzner private multinetwork for >100 nodes | Use node_transport_mode = "tailscale" or the experimental Cilium public overlay; Hetzner private Networks do not route to each other |
| Treating external Tailscale hooks as node transport | Use node_transport_mode = "tailscale" for cluster transport; use node_connection_overrides only for user-owned operator access |
| Treating Cloudflare Mesh/WARP as supported node transport | Use Tailscale for kube-hetzner-managed secure node transport; Cloudflare Access/Tunnel is external operator/app access only |
| Assuming one Hetzner Network can exceed 100 nodes | Shard across multiple Hetzner Networks and count all attachments, including control planes, static agents, autoscaler max_nodes, NAT routers, and load balancers |
| Promising static 10k placement spread in one project | Hetzner spread groups are 10 servers each and 50 groups per project; use autoscaler/network shards or split across projects/clusters |
| Confusing Cilium Gateway API with Traefik Gateway provider | Use cilium_gateway_api_enabled for Cilium, traefik_provider_kubernetes_gateway_enabled for Traefik |
| Enabling Cilium Gateway API with kube-proxy | Requires cni_plugin = "cilium" and enable_kube_proxy = false |
| Enabling embedded registry mirror on low-trust nodes | Use only for equal-trust clusters; warn about credential sharing and tag poisoning |
| Disabling SELinux globally for one workload denial | Follow docs/selinux.md: collect AVCs, try udica, use per-pool selinux = false only as the last resort |
| Assuming RKE2 needs 8GB control planes | v3 size-aware kubelet reservations make 4GB cx23 control planes viable; still size production for workload headroom |
| Manual cloud deletes during teardown | Use scripts/destroy.sh first; scripts/cleanup.sh is the forceful fallback |
v3 Topology Shortcuts
| Need | Recomme
Content truncated.
When not to use it
- →When working with non-Hetzner cloud providers
- →When the user is not deploying k3s infrastructure
Prerequisites
Limitations
- →Limited to the Kube-Hetzner terraform implementation
- →Depends on documentation freshness
How it compares
It is context-aware of the specific Kube-Hetzner project architecture and variables rather than generic k8s advice.
Compared to similar skills
kh-assistant side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| kh-assistant (this skill) | 1 | 6mo | Review | Intermediate |
| senior-devops | 7 | 7mo | Review | Advanced |
| devops-engineer | 1 | 3mo | Review | Advanced |
| terraform-specialist | 1 | 4mo | No flags | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by mysticaltech
View all by mysticaltech →You might also like
senior-devops
davila7
Comprehensive DevOps skill for CI/CD, infrastructure automation, containerization, and cloud platforms (AWS, GCP, Azure). Includes pipeline setup, infrastructure as code, deployment automation, and monitoring. Use when setting up pipelines, deploying applications, managing infrastructure, implementing monitoring, or optimizing deployment processes.
devops-engineer
Jeffallan
Use when setting up CI/CD pipelines, containerizing applications, or managing infrastructure as code. Invoke for pipelines, Docker, Kubernetes, cloud platforms, GitOps.
terraform-specialist
sickn33
Expert Terraform/OpenTofu specialist mastering advanced IaC automation, state management, and enterprise infrastructure patterns. Handles complex module design, multi-cloud deployments, GitOps workflows, policy as code, and CI/CD integration. Covers migration strategies, security best practices, and modern IaC ecosystems. Use PROACTIVELY for advanced IaC, state management, or infrastructure automation.
devops-engineer
I-Synergy
DevOps and CI/CD specialist. Use for building pipelines, containerization, infrastructure as code, or deployment automation. User-invocable only for production deployments.
bazel-build-optimization
wshobson
Optimize Bazel builds for large-scale monorepos. Use when configuring Bazel, implementing remote execution, or optimizing build performance for enterprise codebases.
deployment-engineer
sickn33
Expert deployment engineer specializing in modern CI/CD pipelines, GitOps workflows, and advanced deployment automation. Masters GitHub Actions, ArgoCD/Flux, progressive delivery, container security, and platform engineering. Handles zero-downtime deployments, security scanning, and developer experience optimization. Use PROACTIVELY for CI/CD design, GitOps implementation, or deployment automation.