For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Portainer embeds the Edge Compute addresses in each Edge key when it creates the environment. It doesn't read them again afterwards. If you change the addresses later, existing Edge environments keep the old values, and you must recreate them for the change to take effect.

In the add-on, you must provide:

In Portainer, you must have:

  1. 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, localhost refers to the agent itself, not the Portainer server.

  2. An Edge environment on Kubernetes with an associated agent. A local Kubernetes environment is not a valid deployment target for Portainer-IDP.

  3. 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 set portainerTlsSkipVerify.

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:/export mapping, 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": true for each catalog entry. If an entry omits tlsVerify, Portainer treats it as false and 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?