Documentation

Portainer integration

Manage fleets of KubeSolo nodes from one Portainer server through the outbound Edge Agent.

How KubeSolo and Portainer fit together

KubeSolo is a Portainer product, and it runs standalone without Portainer. Portainer adds fleet management through the Portainer Edge Agent, which runs as a pod on each node and opens an outbound connection to your Portainer server. Nodes behind NAT or strict firewalls can be managed centrally without any inbound rules.

Portainer adds centralised fleet visibility, GitOps deployments, RBAC across nodes, an application template library, and a UI for the container lifecycle. See the Portainer documentation for creating Edge environments.

Connecting a node

Create a Kubernetes Edge environment in Portainer to get an Edge ID and Edge key, then pass both at install time. The key contains special characters, so pass it as an environment variable rather than a flag:

bash
1$ curl -sfL https://get.kubesolo.io | \
2 KUBESOLO_PORTAINER_EDGE_ID=your-edge-id \
3 KUBESOLO_PORTAINER_EDGE_KEY=your-edge-key \
4 sudo -E sh -

KubeSolo deploys the agent only when both the ID and the key are set. On an existing node, add them to the configuration file and restart:

/etc/kubesolo/config.yaml
1portainer:
2 edgeID: "your-edge-id"
3 edgeKey: "your-edge-key"
4 async: false
5 image: docker.io/portainer/agent:lts

With kubesoloctl, use --portainer-edge-id and --portainer-edge-key on install, or the same environment variables.

SettingInstallerDefaultMeaning
portainer.edgeIDKUBESOLO_PORTAINER_EDGE_ID""Edge ID from Portainer.
portainer.edgeKeyKUBESOLO_PORTAINER_EDGE_KEY""Edge key. Stored in the 0600 configuration file and redacted by the config API.
portainer.async--portainer-edge-async=truefalseEdge async mode: the agent polls the server instead of keeping a tunnel open.
portainer.image--portainer-edge-image=IMAGEdocker.io/portainer/agent:ltsAgent image, including the tag.

The agent on the node

KubeSolo creates the agent's resources in the portainer namespace: a portainer-agent Deployment, its ServiceAccount and RBAC, a ConfigMap and a Secret holding the key.

bash
1$ kubectl -n portainer get pods
  • Image: the offline build embeds the default docker.io/portainer/agent:lts and loads it locally. The online build, and any non-default image, pulls from the registry, so the node needs access to it. No agent image is bundled for riscv64. Short references are expanded the way Docker expands them: portainerci/agent:develop becomes docker.io/portainerci/agent:develop.
  • Created once: KubeSolo creates the agent resources only if they do not already exist. After the first deployment, Portainer manages the agent, including its upgrades. Changing portainer.image or the other settings on an existing node does not update an agent that is already deployed.

Remote configuration

KubeSolo's configuration API listens on a root-only unix socket, so it can only be reached through a channel that already has access to the node. The Edge Agent cannot reach it today, because its deployment mounts no host paths. Configure nodes over SSH, or with your own tooling, until that changes.