How to Install Portainer Bussiness Edition on Kubernetes (2025 Update)

This comprehensive guide walks you through a smooth, step-by-step deployment, addressing common challenges and offering practical solutions for a truly streamlined experience.

Before embarking on this journey, ensure your Kubernetes cluster is up-to-date and running smoothly. You'll also need the necessary administrative credentials to execute helm or kubectl commands, enabling Portainer to establish the essential ServiceAccount and ClusterRoleBinding for seamless cluster access. A default StorageClass is crucial for data persistence; we'll explore configuring this shortly. Finally, for Portainer Business Edition, you'll need a valid license key.

Data Persistence: The Foundation of Reliability

Portainer relies on persistent storage for its operational data. Therefore, at least one StorageClass must be available. Portainer defaults to using the system's default StorageClass. If none is explicitly defined, deployment will fail.

For optimal performance and reliability, block storage is strongly recommended over network storage. However, be mindful of the Input/Output Operations Per Second (IOPS) capabilities of your chosen block storage. Slower storage can significantly impact Portainer's responsiveness.

To verify the existence of a default StorageClass, execute the following command within your Kubernetes cluster:

      kubectl get sc
    

Look for a StorageClass with (default) appended to its name. An example output might look like this:

      NAME                            PROVISIONER                                   RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
managed-nfs-storage (default)   k8s-sigs.io/nfs-subdir-external-provisioner   Delete          Immediate           false                  11d
    

Should a default StorageClass be absent, you can designate one using this command, replacing <storage-class-name> with the appropriate name:

      kubectl patch storageclass <storage-class-name> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
    

Alternatively, if deploying via the Helm chart, specify the StorageClass directly using the --set persistence.storageClass=<storage-class-name> parameter during installation.

A common scenario arises with certain Kubernetes distributions (like microk8s) that utilize hostPath volumes. These volumes aren't inherently tied to a specific node, leading to potential data loss when pods are rescheduled. While this is a limitation of hostPath, a simple workaround is to use a nodeSelector to "pin" the Portainer pod to a particular node. Modify your values.yaml file to include:

nodeSelector:
  kubernetes.io/hostname: <YOUR_NODE_NAME>
    

We'll detail how to incorporate this into both Helm and YAML deployment methods below.

Deployment Strategies: Helm and YAML Manifests

Portainer offers two convenient deployment methods: Helm charts and YAML manifests. Each approach offers its own advantages.

Helm Deployment: A Chart for Smooth Sailing

For Helm deployment, ensure you're using Helm v3.2 or later to leverage the --create-namespace option. Begin by adding the Portainer Helm repository:

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

After updating, the installation process begins. The chosen method depends on your preferred service exposure:

To make Portainer accessible via HTTPS on port 30779, execute:

helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \
    --set enterpriseEdition.enabled=true \
    --set enterpriseEdition.image.tag=lts \
    --set tls.force=true
    

This command enables the enterprise edition, utilizes the Long Term Support (LTS) image, and forces the use of TLS, securing the connection. Portainer generates a self-signed SSL certificate by default. You can supply your own certificate during installation or later through the Portainer UI.

To access Portainer via HTTP on port 30777, omit the --set tls.force=true option.

To specify a target node during Helm deployment, append --set nodeSelector.kubernetes\.io/hostname=<YOUR_NODE_NAME> to the helm install command.

YAML Manifest Deployment: A Direct Approach

YAML manifests provide a direct, alternative path to deployment. They support both NodePort and LoadBalancer service types. For NodePort (HTTP on 30777, HTTPS on 30779), use:

      kubectl apply -n portainer -f https://downloads.portainer.io/ee-lts/portainer.yaml
    

Similar to Helm deployment, a self-signed certificate secures HTTPS traffic by default. You can provide your own certificate during installation or afterwards.

To explicitly set the target node when deploying with YAML manifests, utilize this one-liner to patch the deployment:

      kubectl patch deployments -n portainer portainer -p '{"spec": {"template": {"spec": {"nodeSelector": {"kubernetes.io/hostname": "'$(kubectl get pods -n portainer -o jsonpath='{ ..nodeName }')'"}}}}}' || (echo Failed to identify current node of portainer pod; exit 1)
    

This command dynamically patches the deployment, ensuring the pod remains on its current node.

Accessing Your Portainer Instance: The Final Step

Once deployment is complete, access your Portainer Server instance via a web browser. Depending on your chosen deployment method and port configuration, navigate to:

https://localhost:30779/ or http://localhost:30777/

Replace localhost with the appropriate IP address or fully qualified domain name (FQDN) as needed. You'll be greeted by the Portainer Server setup page, ready to begin managing your Kubernetes cluster with newfound ease. This comprehensive guide empowers you to seamlessly integrate Portainer into your Kubernetes workflow, significantly enhancing your management efficiency and control.

keywords: Portainer, Kubernetes, deployment, Helm, YAML, management, UI, container, orchestration, data persistence, StorageClass, nodeSelector, TLS, HTTPS, HTTP