K3s Migrate Control Plane

Published
Length
3 min read

Luis Felipe Dias

All posts

To run a k3s migrate control plane task, back up your cluster data and tokens first. Then, restore that state onto your new server nodes and point your worker agents to them. Platform teams often use full admin keys to run this move across hosts. Still, broad admin roles create big risks if a token leaks or someone runs a bad command. How the k3s migrate control plane workflow operates A K3s cluster stores all its state in a local file or an external database. When you do a k3s migrate contro

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

To run a k3s migrate control plane task, back up your cluster data and tokens first. Then, restore that state onto your new server nodes and point your worker agents to them. Platform teams often use full admin keys to run this move across hosts. Still, broad admin roles create big risks if a token leaks or someone runs a bad command.

How the k3s migrate control plane workflow operates

A K3s cluster stores all its state in a local file or an external database. When you do a k3s migrate control plane workflow, you move this datastore first. You must also copy the server token from the old host to the new host. This token lets worker nodes trust the new server and decrypt cluster secrets.

If your cluster uses an embedded database, you take an on-demand snapshot first. You stop the service on the old node so no new data writes occur. Next, you install the server binary on the new host and restore the snapshot file. The new server reads the state file and starts the cluster processes.

If your cluster uses an external SQL database, the process is much simpler. You start the new server node and point it to the same database address. You also pass the original server token during startup so it can read encrypted data. Once the new server is healthy, you update your load balancer or DNS record. Worker agents then talk to the new server address without losing running apps.

Preparing node networks and storage paths

Before you switch traffic, check the network rules between all your hosts. Worker agents need open network ports to reach the new server address. If a firewall blocks these ports, nodes will drop offline during the move. You should test port reachability from each worker before stopping the old server.

You must also check local storage paths if apps run on the server node. Moving the control plane only moves cluster state, not local volume files. If pods store files on the old server disk, move those workloads to worker nodes first. Draining the old node moves stateless pods over to healthy workers right away.

Security Control Plane: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

What native cluster roles solve and where they fall short

Native cluster roles and host keys control who can log into the servers. They let you grant admin rights to the engineer who runs the migration. Once the move finishes, you can revoke those temporary user roles from the cluster. This setup handles basic login rules for both the host and the cluster API.

Still, static admin keys and broad roles leave a large operational gap open. Native setup decides who logs in, not what individual commands or requests do in flight. An engineer with the master cluster file can delete namespaces or read secret keys. Shared host keys also make it hard to see which person ran a specific command. If a script targets the wrong server during the cutover, native roles will not stop it. Teams also struggle to rotate the master cluster file after the migration ends. Anyone who copied that file during the move keeps full access until certs expire. And if secrets contain emails or card numbers, native roles do not rewrite matched fields in results.

Check Kubernetes API requests and responses on the wire

Kubernetes RBAC decides who may call the API server. RBAC does not check response payloads or split listing Secret names from reading Secret values when a role grants get access. With hoop.dev, you run an open-source HTTP proxy, a sidecar for your Kubernetes API. The kubectl client changes only the server address it talks to while RBAC stays in place.

On each call, hoop.dev guardrails read the method, normalized path, and headers to refuse bad deletes or full Secret reads with a 403 error. On the way back, hoop.dev data masking walks JSON responses by key and masks matched values in Secrets, ConfigMaps, and pod logs. Every request and verdict is logged without storing bearer tokens. View the project on GitHub.

Frequently asked questions

Do worker pods restart when I move the K3s server?

No, running pods on worker nodes keep running while the server moves. Workers cache their local state and wait to talk to the new server address.

What happens if I lose the original server token during migration?

Without the original token, the new server cannot read encrypted data in your snapshot. You must keep a safe copy of the token file before stopping the old node.

Can I change the cluster IP address during a control plane move?

Yes, you can move the server to a host with a new IP address. You will need to update your DNS record or agent config files to match.

The query runs. The emails stay hidden.