Portainer: How to add a Kubernetes Environment

Let’s talk Portainer again, shall we?
One of the brilliant aspects of Portainer container management system is that it allows you to add multiple environments, which can then be assigned to different teams. With that setup, you might have one team given access to the local environment for development, one team might have access to an Azure environment for deployment, and yet another team might have access to an Edge agent.
One other type of Environment you can add is for Kubernetes. With this environment added, you can then manage your Kubernetes, which makes it possible to manage:
- Namespaces
- Helm
- Applications
- ConfigMaps & Secrets
- Cluster
When you create an application in a Portainer Kubernetes environment, you can do so from a manifest or using the Portainer form GUI (which is similar to adding a full stack or container deployment within a Docker environment).
For anyone who manages Kubernetes, and has been looking for a solid web-based GUI, adding a Kubernetes environment to Portainer is a great way to go.
The method I’m going to walk you through allows you to connect Portainer to a remote Kubernetes cluster, which will either need to be on the same LAN or accessible via an accessible FDQN.
Let me show you how this is done. I’m going to assume all you have up and running is a Linux server (I’ll demonstrate on Ubuntu Server 22.04, from start to finish).
How to Install Docker
The first thing we’re going to do is install Docker. Log into your Ubuntu Server instance and install the necessary dependencies with:
1 |
sudo apt-get install ca-certificates curl gnupg lsb-release wget apt-transport-https -y |
Next, add the official Docker GPG key with the command:
1 |
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg |
We can now add the Docker stable repository:
1 |
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null |
Finally, install Docker Engine with the following two commands:
1 2 |
sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io -y |
Start and enable the Docker service with:
1 |
sudo systemctl enable --now docker |
Next, you must add your user to the docker group with the command:
1 |
sudo usermod -aG docker $USER |
Make the system aware of the new group with:
1 |
newgrp docker |
How to Install kubectl and Minikube
We’re going to need both the kubectl command and Minikube installed. First, install kubectl with:
1 |
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" |
Install Kubectl with:
1 |
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl |
Next, we need to download the Minikube binary with:
1 |
wget https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 |
Copy the binary to /usr/local/bin with:
1 |
sudo cp minikube-linux-amd64 /usr/local/bin/minikube |
Give the binary executable permission with:
1 |
sudo chmod +x /usr/local/bin/minikube |
How to Deploy Portainer
Next, we’ll deploy Portainer. First, create a volume (for persistent data) with:
1 |
docker volume create portainer_data |
Deploy Portainer with Docker, using the command:
1 |
docker run -d -p 8000:8000 -p 9443:9443 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce |
Give the container a bit of time to spin up and then point your browser to http://SERVER:9443 (Where SERVER is the IP address of the hosting server). You will then need to create an account for Portainer and log in.
How to Add the Kubernetes Environment
We can now add our Kubernetes environment to Portainer. Click on Environments (in the left sidebar) and then (in the resulting page), click Add Environment (Figure 1).

Figure 1: I already have several environments configured in Portainer.
In the next window (Figure 2), click the Agent tab.

Figure 2: The Environments creation page in Portainer.
In the resulting window (Figure 3), click Kubernetes via node port to reveal the command you must run on your Kubernetes host. That command is:
1 |
curl -L https://downloads.portainer.io/portainer-agent-ce211-k8s-nodeport.yaml -o portainer-agent-k8s.yaml; kubectl apply -f portainer-agent-k8s.yaml |
Once the command completes, go back to Portainer and fill out the information for the Environment. You’ll need to give the new environment a name (such as kube, k8s, minikube, etc.). Next, type the address of the Kubernetes server, as in:
1 |
https://192.168.1.13:9001 |

Figure 3: Adding a new Kubernetes environment as an Agent.
If you want to assign the environment to a group, click the Group drop-down and select any group you’ve already created. Select any tags you’ve created and then click Add Environment. Click Add Environment and Portainer will connect to your Kubernetes cluster. Go back to the Portainer main window and you’ll see your new Kubernetes Environment listed (Figure 4).

Figure 4: Our new Kubernetes environment has been successfully added.
Congratulations, you’ve added Kubernetes into the Portainer mix. Enjoy that added power and flexibility.