> For the complete documentation index, see [llms.txt](https://docs.portainer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.portainer.io/portainer-documentation/sts/faqs/getting-started/add-on-requirements.md).

# What are the requirements for installing add-ons?

[Add-ons](https://docs.portainer.io/portainer-documentation/sts/admin/add-ons.md) 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.

{% hint style="warning" %}
Add-ons marked as **Pre-release** may change in future releases and should not be used in production environments.

Add-ons marked as **Alpha** are in early development. They may change significantly or be removed in future releases, and should not be used in production environments.
{% endhint %}

## Requirements for all add-ons <a href="#requirements-for-all-add-ons" id="requirements-for-all-add-ons"></a>

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 <a href="#portainer-must-run-on-kubernetes" id="portainer-must-run-on-kubernetes"></a>

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.&#x20;

***

#### The add-on secret key must be available (Portainer 3.0 and later)

The `--addons-secret-key-name` flag must point to a file that exists. This flag is separate from `--secret-key-name`, and Portainer does not fall back to the main secret key if the add-on key is missing.

The simplest way to meet this requirement is to reuse your existing database encryption key. Point `--addons-secret-key-name` at the same key file that `--secret-key-name` uses, so no new secret or volume mount is needed.

If you installed Portainer using the Helm chart, add the flag to the `feature.flags` value. If you already set other flags in `feature.flags`, include them as well, or they will be removed:

```
helm upgrade portainer portainer/portainer -n portainer --reuse-values \
  --set feature.flags="--addons-secret-key-name=<path-to-key-file>"
```

***

#### Portainer must have cluster-admin access <a href="#portainer-must-have-cluster-admin-access" id="portainer-must-have-cluster-admin-access"></a>

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 <a href="#portainer-must-not-run-in-fips-mode" id="portainer-must-not-run-in-fips-mode"></a>

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 <a href="#the-add-on-secret-key-must-be-available-portainer-30-and-later" id="the-add-on-secret-key-must-be-available-portainer-30-and-later"></a>

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:

```
https://portainer.portainer.svc.cluster.local:9443
```

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:

```
Could not check setup status — Unauthorized
```

To fix it, reinstall Portainer using the default release name, namespace, and ports.

***

#### Only one Portainer server per cluster can install add-ons <a href="#only-one-portainer-server-per-cluster-can-install-add-ons" id="only-one-portainer-server-per-cluster-can-install-add-ons"></a>

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](https://docs.portainer.ai/portainer-command/initial-configuration) for details.&#x20;

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

{% hint style="info" %}
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.
{% endhint %}

In the add-on, you must provide:

* An [Edge Admin API key](https://docs.portainer.io/portainer-documentation/sts/user/account-settings.md#access-tokens).
* A Git credential encryption key.

In Portainer, you must have:

1. [Edge Compute features enabled](https://docs.portainer.io/portainer-documentation/sts/admin/settings/edge.md).
2. 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.&#x20;
3. An [Edge environment on Kubernetes](https://docs.portainer.io/portainer-documentation/sts/admin/environments/add/kubernetes/edge.md) with an associated agent. A local Kubernetes environment is not a valid deployment target for Portainer-IDP.
4. An [Edge group](https://docs.portainer.io/portainer-documentation/sts/user/edge/groups.md) 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.

***

## Some add-on versions need a newer version of Portainer

A chart version can declare that it needs capabilities a given Portainer may not have - for example, a newer way of authenticating the add-on's own calls back to Portainer. Portainer only offers versions it can actually run: an incompatible version never appears in the install wizard's or the Configuration tab's version list, and if every published version is incompatible, the add-on's card in the catalog shows a disabled **Needs a newer Portainer** button instead of **Install**. Upgrading Portainer to a newer release resolves this.

***

## Do I need to change the add-on catalog URL? <a href="#do-i-need-to-change-the-add-on-catalog-url" id="do-i-need-to-change-the-add-on-catalog-url"></a>

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**](https://docs.portainer.io/portainer-documentation/sts/admin/settings/general.md#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`.
