Running Kubernetes in a homelab is fun until everything starts living in the terminal.

The CLI is powerful. Tools like `kubectl` give you full control over your cluster. But after a while, constantly running commands just to inspect workloads or check logs can slow things down.

I wanted something closer to what many teams use in production. A visual interface where I could see workloads, inspect containers, and manage resources quickly.

That led me to [Portainer](https://www.portainer.io/).

In this article, I walk through how I installed Portainer on my Kubernetes homelab running on **Proxmox Server Solutions**, the issues I ran into along the way, and how I fixed them.

## My Homelab Setup

My infrastructure currently looks like this:

```bash
Proxmox host
    └── Virtual machines
        └── Kubernetes cluster (k3s)
                └── Container workloads
```

The Kubernetes cluster runs inside VMs managed by Proxmox, and most of my applications run as containers inside the cluster.

Portainer runs inside [Kubernetes](https://fullstackwriter.dev/post/how-i-installed-kubernetes-on-my-homelab-using-k3s-on-proxmox-ubuntu?category=kubernetes) as well, which allows it to interact directly with the Kubernetes API and manage cluster resources.

## Why I Wanted Portainer

Even though the CLI works perfectly, I wanted a management layer that offers:

- A visual view of workloads
- Faster troubleshooting
- Easier inspection of pods and logs
- Cluster-wide visibility
- A user interface similar to production environments

The goal was not to replace the CLI. It was to complement it.

In real infrastructure environments, engineers rarely rely on commands alone. Tools that visualize cluster state make day-to-day operations much easier.

## Step 1. Install Helm (If Not Already Installed)

[Helm](https://helm.sh/) is a package manager for Kubernetes (similar to NPM for Node.js and Cargo for Rust). Portainer provides an official Helm chart, so Helm is required for installation.

To check if Helm is installed:

```bash
helm version
```

If not installed, [install Helm](https://helm.sh/docs/intro/install) based on your operating system.

## Step 2. Add the Portainer Helm Repository

To do this, I ran the command below:

```bash
helm repo add portainer https://portainer.github.io/k8s/
helm repo update
```

This makes the Portainer chart available locally.

## Step 3. First Installation Attempt (And the Error I Hit)

When I first tried installing Portainer, I got this error:

```bash
cluster reachability check failed:
kubernetes cluster unreachable:
Get "http://localhost:8080/version":
connect: connection refused
```

It means Helm could not find my Kubernetes cluster configuration. It defaulted to trying `localhost:8080`, which does not exist.

This happened because my cluster runs [k3s](https://k3s.io/), which stores its kubeconfig in:

```bash
/etc/rancher/k3s/k3s.yaml
```

`kubectl` was automatically using this file, but Helm was not. So Helm had no cluster credentials.

## Step 4. Fixing the Cluster Reachability Error

I explicitly exported the kubeconfig:

```bash
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
```

After that, Helm could communicate with Kubernetes. I verified by running the command below

```bash
helm list
```

To make this changes permanent, I ran:

```bash
echo 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> ~/.bashrc
source ~/.bashrc
```

## Step 5. Install Portainer in Kubernetes

Once Helm could talk to the cluster, installation was straightforward. I did so by running the command below:

```bash
helm install portainer portainer/portainer \
  --namespace portainer \
  --create-namespace \
  --set service.type=NodePort
```

This deploys:

- Portainer server
- Kubernetes integration components
- A service for web access

## Step 6. Verify Deployment

Check pods:

```bash
kubectl get pods -n portainer
```

I waited until the status showed `Running`:

![Portainer running on Kubernetes](https://paper-attachments.dropboxusercontent.com/s_05AD378A82578B8F940350A334CC24A83B9D9779BBD50D7F99799A62C18025AC_1772907054520_Screenshot+2026-03-07+at+19.10.10.png)

## Step 7. Access the Portainer UI

To access the UI, first, I need to find the service on which Portainer is exposed:

```bash
kubectl get svc -n portainer
```

Then looked for the NodePort value.

![Portainer NodePort value](https://paper-attachments.dropboxusercontent.com/s_05AD378A82578B8F940350A334CC24A83B9D9779BBD50D7F99799A62C18025AC_1772907432360_Screenshot+2026-03-07+at+19.13.20.png)


Access in browser:

```bash
https://<node-ip>:<nodeport>
```

## Step 8. Second Issue I Encountered (Security Timeout)

When I opened the UI, I saw:

![Timeout error](https://paper-attachments.dropboxusercontent.com/s_05AD378A82578B8F940350A334CC24A83B9D9779BBD50D7F99799A62C18025AC_1772907578117_screencapture-10-90-1-30-30777-timeout-html-2026-02-25-03_41_32.png)


This happens if you do not create the admin account quickly after the first launch, which I didn’t in my case. It’s a security measure with Portainer. It locks itself after some time.

## Step 9. Fixing the Timeout

To fix it, I restarted the  Portainer deployment:

```bash
kubectl rollout restart deployment portainer -n portainer
```

Then waited for the pod to become `Running`, then refreshed the browser.

This time, I created the admin account immediately.

![Portainer Admin Account](https://paper-attachments.dropboxusercontent.com/s_05AD378A82578B8F940350A334CC24A83B9D9779BBD50D7F99799A62C18025AC_1772907813899_screencapture-10-90-1-30-30777-2026-02-25-03_44_25.png)

## Final Result

After logging in, Portainer automatically detected my Kubernetes environment. From there, I could:

- View nodes and namespaces
- Inspect pods and logs
- Deploy applications
- Scale workloads
- Manage cluster resources visually

Everything worked out of the box.

![Portainer Admin](https://paper-attachments.dropboxusercontent.com/s_05AD378A82578B8F940350A334CC24A83B9D9779BBD50D7F99799A62C18025AC_1772907944407_screencapture-10-90-1-30-30777-2026-02-25-03_46_30.png)

## Final Thoughts

Running Kubernetes in a homelab is a great way to learn infrastructure, but tools like Portainer add an important layer of usability.

It provides a clear view of what is happening inside the cluster and makes management easier without removing the flexibility of the command line.

For anyone running Kubernetes at home, especially on virtualized infrastructure, adding a management interface is a worthwhile improvement.



A step-by-step guide to installing Portainer on a Kubernetes (k3s) homelab running on Proxmox. Covers Helm setup, fixing cluster reachability errors, resolving the security timeout, and accessing the Portainer UI.

#portainer

How I Installed Portainer on My Kubernetes Homelab (Running on Proxmox)