Adopt Existing Cluster | PodWarden Hub

Import a K3s cluster that is already running on a host into PodWarden without reinstalling or modifying any software

What this does

Adopt existing cluster lets you bring a K3s cluster that is already running on a host under PodWarden management without reinstalling K3s, running Ansible, or interrupting running workloads.

PodWarden connects to the host over SSH, reads the existing kubeconfig, validates that the cluster API is reachable, and registers the cluster in its database. No software is installed or modified on the host.

Use this when:

A host was provisioned outside PodWarden (e.g. via manual setup or another tool)
PodWarden detected an existing K3s installation on a host you probed
You migrated a cluster between PodWarden instances and want to re-register it

Prerequisites

Before adopting a cluster the following must be true:

Requirement	How to verify
The host exists in PodWarden	It appears on the Hosts page
K3s is running on the host	The host shows "Kubernetes detected" on its detail page, or you have verified this manually
PodWarden can reach the host via SSH	The host was successfully probed, or SSH connectivity is confirmed
An SSH key is configured	Either `PW_SSH_KEY_PATH` is set in PodWarden's environment, or a named SSH key pair is stored in Settings → Secrets
The K3s kubeconfig is at `/etc/rancher/k3s/k3s.yaml`	Standard K3s default location

Starting adoption

From the host detail page (normal path)

Navigate to Hosts and click the host you want to adopt.
If K3s was detected during probing, you will see an amber alert: "Kubernetes detected on this host". This alert also appears when you click Provision and K3s is already running.
Click Adopt cluster in the host toolbar, or choose Adopt existing cluster (recommended) from the K8s-detected confirmation dialog.
The Adopt existing cluster modal opens.

From the K8s-detected confirmation dialog

When you click Provision on a host that already has K3s running, PodWarden intercepts the action and shows a choice:

Adopt existing cluster (recommended) — fetch kubeconfig and register with no reinstall, no downtime
Overwrite and re-provision — full Ansible reinstall, destroys existing workloads on this host

Select the first option to open the adopt modal.

Adopt cluster modal

Field	Required	Description
Cluster name	Yes	The name PodWarden will use for this cluster internally (e.g. `k3s-dev`, `home-cluster`). Does not need to match the K3s node name.
SSH key pair	No	Select a named key pair from Settings → Secrets. Leave empty to use the default `PW_SSH_KEY_PATH`. Only shown if named key pairs are configured.

Click Adopt cluster to begin.

What happens during adoption

The modal shows a progress indicator with four steps:

SSH to the host and fetch /etc/rancher/k3s/k3s.yaml
Replace 127.0.0.1 / localhost in the kubeconfig with the host's connect address so PodWarden can reach the API from outside the host
Validate the cluster is reachable by calling the Kubernetes API (kubectl get nodes equivalent)
Create a cluster record in PodWarden's database and link the host as control-plane

When adoption completes, the host status changes to ready and the cluster appears on the Clusters page. The host is automatically marked as protected so it cannot be accidentally re-provisioned or wiped without first removing it from the cluster.

After adoption

Once adopted, the cluster behaves identically to a cluster PodWarden provisioned itself:

It appears on the Clusters page with node status and Kubernetes API health
The Infrastructure Canvas shows the cluster, its host, and any deployments
You can deploy workloads to the cluster via the normal deployment flow
Health checks run against it on each 15-minute cycle

Worker nodes that are already part of the cluster will appear in Kubernetes API responses. To add them to PodWarden as managed hosts, probe each worker node and join it to the cluster via the normal host management flow.

Troubleshooting

"adopt_existing requires K8s to be running on the host"

PodWarden checks the k8s_running_detected flag, which is set during a host probe. If the flag is not set, run a probe on the host first: open the host detail page and click Probe.

Adoption fails with SSH error

Verify the SSH key has access to the host: ssh -i <key_path> <host_address>
Check that the host's connect_address in PodWarden is correct (the IP or hostname PodWarden uses to reach it over SSH)
If using Tailscale connectivity, ensure PodWarden's Tailscale node is authenticated and the host is online in Tailscale

Adoption fails with kubeconfig error

Confirm K3s is running on the host: systemctl status k3s
Confirm the kubeconfig exists: ls -la /etc/rancher/k3s/k3s.yaml
The SSH user must have read access to /etc/rancher/k3s/k3s.yaml (typically requires root or sudo)

Host shows error status after adoption

The host detail page will display the adoption error message. Common causes:

Error	Fix
Could not detect public IP	The gateway IP detection failed. Check network connectivity from PodWarden.
Failed to fetch kubeconfig	SSH succeeded but the file was not readable. Check file permissions.
Cluster API not reachable	The kubeconfig was fetched but the Kubernetes API did not respond. Verify K3s is healthy on the host.

After fixing the underlying issue, you can retry adoption by clicking Adopt cluster again. The host status will reset to the provisioning flow.

Related docs

Hosts — Probe hosts and manage host status
Clusters — View and manage clusters after adoption
Provisioning — Full Ansible-based provisioning for new hosts
System Messages — Health check alerts for adopted clusters