Skip to main content

Portainer

The Portainer integration reads every environment a Portainer server manages, through the Portainer API and its Docker and Kubernetes proxies. One integration covers all of them. It runs on an Integrator inside your network.

It is read-only. The integration never starts, stops, deploys or reconfigures anything.

What it collects​

SyncCollects
Environment discoveryEvery environment: a Docker host with its Docker version, OS, kernel, CPU and memory; a Swarm with every node, its role, state and address; a Kubernetes cluster with every node, its kubelet version, OS, CPU, memory and addresses
Container discoveryIn Docker and Swarm environments, every container with its image, addresses, MACs, state and stack; Swarm services with their running task count; the image store with registries, repositories and tags. In Kubernetes environments, namespaces, pods and their containers with the image each one pulled
Service discoveryEvery port a container or Swarm service publishes on its host, tied to the container or service behind it

Containers appear under Compute > Containers next to those from every other platform, Kubernetes clusters under Compute > Kubernetes, and images under Compute > Registries.

Stacks and Compose projects are groupings, not things that run, so they are not listed on their own: each container and Swarm service carries its stack's name as a stack label. A published port is recorded with the host address it answers on: a Swarm ingress port answers on every node of the swarm, and a port bound to the host's loopback address is not published to the network and is left out. Services of Kubernetes environments are collected by the Kubernetes integration, not through Portainer.

An environment that is down, or whose agent does not answer, is reported from what Portainer last saw of it, and the sync reports that its detail could not be collected. The other environments are unaffected.

Create a read-only access token​

Portainer authenticates API clients by access token. A token acts as the user it belongs to, so create a user that can only view.

  1. Under Users > Add user, add a user (for example inventory) with the Standard user role.
  2. Under Environment-related > Environments, open each environment's Access management and grant the user the Read-only user role. For Business Edition, grant Read-only user on the environment group instead to cover every environment in it.
  3. Log in as the user, open My account (the user menu, top right), and under Access tokens > Add access token create a token (for example inventory). Copy it: it is shown once and starts with ptr_.

A Portainer administrator's token sees every environment but can also change anything. Prefer the read-only user.

Connect it​

  1. Under Integrations, add Portainer with the server's URL (for example https://portainer.example.com:9443) and the access token.
  2. In the integration's settings, assign the Integrator that can reach the server on that port.
  3. Enable the syncs you want.

Portainer serves its own self-signed certificate on port 9443 unless you install one. The first connection records the certificate's fingerprint and later connections must present the same certificate. After replacing it, clear the pinned fingerprint in the integration's settings.

A token Portainer does not accept fails the sync with an error. It does not report an empty server. An environment the token's user cannot see is not listed and not reported.