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:
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:
With kubesoloctl, use --portainer-edge-id and --portainer-edge-key on install, or the same environment variables.
| Setting | Installer | Default | Meaning |
|---|---|---|---|
| portainer.edgeID | KUBESOLO_PORTAINER_EDGE_ID | "" | Edge ID from Portainer. |
| portainer.edgeKey | KUBESOLO_PORTAINER_EDGE_KEY | "" | Edge key. Stored in the 0600 configuration file and redacted by the config API. |
| portainer.async | --portainer-edge-async=true | false | Edge async mode: the agent polls the server instead of keeping a tunnel open. |
| portainer.image | --portainer-edge-image=IMAGE | docker.io/portainer/agent:lts | Agent 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.
- Image: the offline build embeds the default
docker.io/portainer/agent:ltsand 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:developbecomesdocker.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.imageor 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.