Install Portainer Agent on your Kubernetes environment
Introduction
Portainer consists of two elements, the Portainer Server and the Portainer Agent. Both elements run as lightweight containers on Kubernetes. This document will outline how to install the Portainer Agent on your cluster and how to connect to it from your Portainer Server instance. If you do not have a working Portainer Server instance yet, please refer to the Portainer Server installation guide first.
To get started, you will need:
A working and up to date Kubernetes cluster.
Access to run
kubectl
commands on your cluster.Cluster Admin rights on your Kubernetes cluster. This is so Portainer can create the necessary
ServiceAccount
andClusterRoleBinding
for it to access the Kubernetes cluster.
The installation instructions also make the following assumption about your environment:
Your environment meets our requirements. While Portainer may work with other configurations, it may require configuration changes or have limited functionality.
You will be using the
portainer
namespace for Portainer.You have not set a custom
AGENT_SECRET
on your Portainer Server instance. If you have, you will need to provide that secret to your agent by adding it to the YAML file within the agent deployment definition:env:
- name: AGENT_SECRET
value: yoursecret
Deployment
To deploy Portainer Agent within a Kubernetes cluster you can use our provided YAML manifests.
Helm charts for agent-only deployments will be available soon.
Method 1: Deploying using NodePort
From the menu select Environments then click Add environment. Ensure Agent is selected in Environment type.
In the Information section select the correct operating system for the new environment then select the Kubernetes via node port tab. Copy the command, then run it on the control node of your Kubernetes cluster.
Make sure you run this command on your Kubernetes node before continuing.
The deployment command will return something similar to this:
To validate that the agent is running, use this command:
The result should look something like this:
Method 2: Deploying using Load Balancer
From the menu select Environments then click Add environment. Ensure Agent is selected in Environment type.
In the Information section select the correct operating system for the new environment then select the Kubernetes via load balancer tab. Copy the command, then run it on the control node of your Kubernetes cluster.
Make sure you run this command on your Kubernetes node before continuing.
The deployment command will return something similar to this:
To validate that the agent is running, use this command:
The result should look something like this:
Completing the configuration
Regardless of the method used, once the agent is running on the Kubernetes host, you must complete the appropriate environmental details.
Only do this once for your environment, regardless of how many nodes are in the cluster. You do not need to add each node as an individual environment in Portainer. Adding just one node will allow Portainer to manage the entire cluster.
Field/Option | Overview |
---|---|
Name | Give the environment a descriptive name. This is a required field. |
Endpoint URL | Define the IP address or name used to connect to the environment (the Kubernetes host) and specify the port if required ( |
Public IP | Enter the URL or IP address where exposed containers will be reachable. This field is optional and will default to the environment URL. |
In the Metadata section, as an optional step you can categorize the environment by adding it to a group or tagging it for better searchability.
When you're ready, click Add environment. You will then be taken to the Kubernetes features configuration where you can set the following options:
Field/Option | Overview |
---|---|
Allow users to use external load balancer | If enabled, users can expose an application deployed over an external IP address assigned by a cloud provider. |
Ingress controller | Adding ingress controllers lets users expose an application deployed over an HTTP route. |
This feature lets you restrict access to the default name space and is only available in Portainer Business Edition. |
Field/Option | Overview |
---|---|
This allows you to toggle the over-commit feature, letting you assign more resources to namespaces than are physically available within your cluster. This feature is only available in Portainer Business Edition. | |
Enable features using metrics server | If enabled, users can use specific features that leverage the metrics server component. The metrics server must be installed on your Kubernetes cluster to use this. |
Available storage options | Select which options will be available to users when they deploy applications. First, take a look at your storage driver documentation to figure out which access policy to configure, and if volume expansion capability is supported. Options are:
|
Find more information about access modes in Kubernetes' own documentation.
When the setup is complete, click Save configuration.
Last updated