Homelab Wave Migration (Compose → k3s)

Migrate homelab services from Docker Compose to k3s with Helm charts and network policies.

Updated Sep 29, 2025
One-click install
npx skills add https://github.com/LucasSantana-Dev/homelab --skill homelab-wave-migration-compose-k3s
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: Homelab Wave Migration (Compose → k3s)
Source: https://github.com/LucasSantana-Dev/homelab/tree/main/.claude/skills/homelab-wave-migration
Command: npx skills add https://github.com/LucasSantana-Dev/homelab --skill homelab-wave-migration-compose-k3s

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill automates the complex process of migrating services from Docker Compose to a Kubernetes (k3s) environment, ensuring a smooth transition with minimal downtime.

Core Features & Use Cases

  • Phased Migration: Execute services in waves (A, B, C, D) based on risk and statefulness.
  • Preflight Checks & Validation: Ensures k3s, Terraform, SOPS, and service health are ready before migration.
  • Automated Deployment: Builds and deploys Helm charts for services in k3s.
  • Network Policy Management: Automatically configures essential Network Policies for Traefik ingress.
  • Stateful Data Migration: Provides a workflow for migrating data from Docker volumes to k3s Persistent Volume Claims.
  • Cutover & Rollback: Facilitates seamless switching from Docker Compose to k3s and includes rollback procedures.
  • Use Case: Migrating your self-hosted password manager (Vaultwarden) from a Docker Compose setup to k3s, ensuring data integrity and secure access.

Quick Start

Initiate the pre-flight checks for migrating services to k3s by running the migration preflight command.

Frequently Asked Questions about Homelab Wave Migration (Compose → k3s)

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate Docker Compose services to k3s?

Migrate Docker Compose services to k3s by executing a phased wave migration that includes preflight checks, automated Helm chart deployment, Traefik network policy configuration, and stateful data migration.

How do I move Docker volumes to k3s Persistent Volume Claims?

Move Docker volumes to k3s Persistent Volume Claims using a dedicated stateful data migration workflow, ensuring data integrity for stateful applications like Vaultwarden during the transition.

Do I need Terraform and SOPS to deploy homelab services on k3s?

Yes, you need Terraform and SOPS to deploy homelab services on k3s, as validated preflight checks require these tools to ensure environment readiness and secure secret management before migration.

What is the best way to execute a wave migration for stateful homelab services?

The best way to execute a wave migration for stateful homelab services is grouping them into risk-based waves (A, B, C, D), running health checks, and utilizing the provided cutover and rollback procedures.

How do I configure Traefik ingress network policies when moving to k3s?

Configure Traefik ingress network policies when moving to k3s through automated network policy management, which sets up essential routing rules as part of the Helm chart deployment process.

Can I rollback a homelab service after switching from Docker Compose to k3s?

Yes, you can rollback a homelab service after switching from Docker Compose to k3s, because the migration process includes specific cutover and rollback procedures to ensure minimal downtime.