What are the requirements for installing add-ons?
Add-ons can only be installed when Portainer runs on Kubernetes, with cluster-admin access, outside FIPS mode, and under its default Helm release name and namespace. Some add-ons also need additional configuration in Portainer before they will work. This page lists the requirements that apply to all add-ons.
Requirements for all add-ons
Before you can install any add-on, your Portainer server must meet the following requirements. Only Portainer administrators can install, uninstall, or repair add-ons.
Portainer must run on Kubernetes
Add-ons are installed into the Kubernetes cluster that Portainer itself runs on. If Portainer runs on Docker or Docker Swarm, the add-on list still displays, but installation is unavailable.
Portainer must have cluster-admin access
Portainer installs add-ons using Helm, running as Portainer's in-cluster ServiceAccount. That ServiceAccount must be bound to the cluster-admin role. Without it, the add-on pages load but every installation fails.
If you installed Portainer using the official Helm chart, set localMgmt=true to create this binding.
Portainer must not run in FIPS mode
Add-ons are not available when Portainer runs in FIPS mode, and there is no option to enable them.
Portainer must use the default release name, namespace, and ports
Install Portainer as the Helm release portainer in the namespace portainer, using the chart's default ports. Add-ons connect to Portainer at the following in-cluster address:
If Portainer is installed under a different release name, namespace, or port, the add-on still installs and its interface still loads. However, the add-on cannot read its own settings, and displays the following error:
To fix it, reinstall Portainer using the default release name, namespace, and ports.
Only one Portainer server per cluster can install add-ons
Each add-on is installed into a namespace named portainer-addon-<id>, based on the add-on rather than on the Portainer server that installed it. If two Portainer servers on the same cluster install add-ons, they compete for the same namespaces and Helm release names.
A common symptom is a running portainer-addon-* namespace for an add-on that Portainer shows as not installed. This happens because each Portainer server tracks installation status in its own database.
Additional requirements for specific add-ons
Each add-on has its own setup step in its interface. The requirements below are the Portainer-side prerequisites that apply in addition to the requirements for all add-ons.
Portainer-Command
Portainer-Command needs a credential configured on its settings page before it can create sessions. See the Portainer-Command documentation for details.
Portainer-Command also runs its own Postgres database in its add-on namespace. Include this database in your resource planning and backup strategy.
Portainer-IDP
In the add-on, you must provide:
A Git credential encryption key.
In Portainer, you must have:
Valid Edge Compute server addresses. Set the Portainer API server URL and Tunnel server address to addresses that the Edge agent can resolve from its own network location. Do not use
localhost. Inside an agent container,localhostrefers to the agent itself, not the Portainer server.An Edge environment on Kubernetes with an associated agent. A local Kubernetes environment is not a valid deployment target for Portainer-IDP.
An Edge group that contains that environment. If no Edge groups exist, the deployment target list is empty.
Each user must also add a Git personal access token, which Portainer-IDP uses for their commit identity.
Portainer-Migrate
To install
The Kubernetes cluster that hosts the add-on must run Kubernetes 1.21 or later. The add-on image is
portainer/portainer-migrate. For air-gapped installs, you can point the chart at a mirror of this image.The add-on's backend must be able to reach the Portainer API. In most setups it discovers the address by itself, and the Pre-flight check reports the result. If discovery fails, set the chart value
portainerUrl. If Portainer uses a self-signed certificate, also setportainerTlsSkipVerify.
To migrate
Source: a Docker standalone or Docker Swarm environment in Portainer.
Target: a Kubernetes environment in Portainer. This can be the same cluster that hosts the add-on. The target needs a StorageClass that can provision PersistentVolumeClaims (PVCs) for named volumes.
A Git repository and an access token. Portainer-Migrate is GitOps-only. It commits the generated manifests to your repository, then creates a Portainer Kubernetes Git stack for each application. The token needs read/write access to repository contents. For a GitHub fine-grained token, this means Contents: Read and write and Metadata: Read.
Requirements for some workloads
The following apply only if your applications use these features:
Copying volume data (cold copy): the target cluster must be able to pull
python:3.13-alpine, which Portainer-Migrate uses for a short-lived restore init container. Clusters with restricted admission policies may need to allow this image. The source container is stopped briefly while its data is copied.NFS-backed volumes or bind mounts: the target nodes must be able to reach the same NFS server, which lets the data stay in place. Bind mounts also need a host path to
server:/exportmapping, which you set in the migration wizard.Ingress: the target needs an Ingress controller. Without one, Portainer-Migrate falls back to NodePort Services.
Permissions
A non-administrator user needs access to the target namespace and, for Docker sources, permission to stop and start containers.
Do I need to change the add-on catalog URL?
In most cases, no. When the Add-on Catalog URL field is empty, Portainer uses its own published catalog, which is the correct choice for almost all deployments. You can find this setting under Administration > Settings > General > Add-on settings.
You might set a custom catalog URL if you need to:
Pin a specific catalog that your organization has reviewed.
Serve the catalog from an internal mirror, for example in an air-gapped environment.
If you use a custom catalog, keep the following in mind:
Changes may not appear immediately. Portainer caches the catalog. If the add-on list does not update after you change the URL, restart the Portainer server. The setting itself will show the new URL even while the list is out of date.
Set
"tlsVerify": truefor each catalog entry. If an entry omitstlsVerify, Portainer treats it asfalseand pulls the add-on's chart without verifying the registry's TLS certificate. For a registry with a publicly signed certificate, always set"tlsVerify": true.
Last updated
Was this helpful?