Controller add-on

Use a standalone kind: Controller file to add one new host to an existing remote control plane. You do not redeploy the full ControlPlane YAML. potctl reuses the stored global spec (auth, database, images, TLS policy, system microservices) from namespace config and runs the next-system-Edgelet-node path on the new host.

The first deploy is Remote. Database and ordering rules are Multi-controller HA.

Example

controller-add-on.yaml

apiVersion: datasance.com/v3
kind: Controller
metadata:
  name: ctrl-2
spec:
  host: 10.0.0.12
  ssh:
    user: ubuntu
    keyFile: ~/.ssh/id_rsa
    port: 22
  systemAgent:
    config:
      arch: arm64

A second host on an existing production namespace:

controller-west.yaml

apiVersion: datasance.com/v3
kind: Controller
metadata:
  name: edge-west-2
spec:
  host: 203.0.113.20
  ssh:
    user: ec2-user
    keyFile: ~/.ssh/prod.pem
  systemAgent:
    config:
      arch: amd64
      host: 203.0.113.20

Optional tls overrides the stored global spec.tls for this host only (cert and key, base64 PEM). Optional airgap stages images for this host. endpoint is written by potctl after deploy. See Securing a remote control plane.

A document labeled RemoteController is accepted as Controller.

What you need first

The potctl namespace must already contain a deploy-capable ControlPlane spec.

Requirement	Why
A prior deploy -f of the full ControlPlane, or connect -f with that full file	Stores auth, controller, database, and the rest of the global spec
The stored spec includes auth and controller	A thin connect stub is rejected
New metadata.name is not already in controllers[]	Names are unique
New host is not already used	Hosts are unique
An external database when this host makes the second controller	A SQLite-only control plane cannot grow

potctl deploy -f controller-add-on.yaml -n prod

deploy

What the add-on runs

On the new host only, the same pipeline as one row of the initial control plane:

1. SSH, then install Edgelet (and airgap or a private registry when the stored spec says so).
2. Translate the stored global spec plus this controller into an Edgelet ControlPlane manifest (apiVersion: edgelet.iofog.org/v1).
3. edgelet deploy -f on the new host.
4. Deploy the next system Edgelet node with upstreamRouters: [default-router] and upstreamNatsServers: [default-nats-hub]. If you omit those lists, the defaults are merged in.
5. Append the controller to stored spec.controllers[] and save config.

What the add-on skips

These ran during the initial ControlPlane deploy:

Step	On add-on
Wait for the Controller API	Skipped
Create iofogUser for embedded auth	Skipped
Register a private controller.package registry	Skipped
Upload global messaging CAs	Skipped. The CAs must already exist from the initial deploy or from a manual import.

To rotate global messaging CAs, update them on the Controller API or redeploy the full ControlPlane with new CA blocks before you add hosts that depend on the new trust material.

Several documents in one file

When one file contains both ControlPlane and Controller:

• Control plane actions run first.
• Controller add-on actions run after that block.
• Validation rejects a duplicate name or host shared by spec.controllers[] and a standalone Controller in the same file.

Role of the new host

Each added host runs its own Controller container on the same external database as the existing hosts. The new system Edgelet node is always a later node (index 1 or higher). It attaches to default-router and default-nats-hub on the first controller host from the original deploy order.

Adding a controller does not reorder the first host. Put the primary router and NATS host at index 0 in the original controllers[] list. See Multi-controller HA.

Errors

Message	Cause
Does not support adding controllers	Namespace control plane is missing a full deploy or connect file
External database is required	Second controller while the database provider is empty
Name or host already exists	Duplicate in the stored control plane
Collision in the same deploy file	controllers[] and Controller share a name or host

Day-2

The console does not install the new host. After deploy, Overview lists it under Cluster controllers (Active, Standby, or Stale). That block does not open a detail panel.

potctl describe controlplane -n prod
potctl describe controller ctrl-2 -n prod

• describe controlplane
• describe controller
• connect with the full remote file when this workstation does not yet have that stored spec

Platform image pins are Upgrade the platform train. Change them on the stored ControlPlane, deploy that file, then add hosts.

Fields

Global and per-host fields: Remote ControlPlane fields.

See anything wrong with the document? Help us improve it!

Edit this page on GitHub!