Nodes

A node is a machine that up builds on and deploys to. You declare nodes under the top-level nodes key in up.yaml. Each node has one or more roles that decide what it is allowed to do, and connection details for reaching it over SSH.

nodes:
  - name: builder-1
    roles: [build]
    host: 10.0.0.1
    user: root
    port: 22
    key_path: ~/.ssh/id_ed25519

name

The node’s unique name. Other parts of the configuration reference nodes by this name, for example build.node. Required.

name: builder-1

host

The node’s IP address or hostname. This is where up connects over SSH. Required.

host: 10.0.0.1

user

The SSH user to connect as. Empty means the operating system default.

user: root

port

The SSH port. Defaults to 22.

port: 22

key_path

The path to the SSH private key used to reach the host.

key_path: ~/.ssh/id_ed25519

roles

The capabilities of the node, drawn from control, build, and deploy. A node may hold several roles. When roles is empty, the node is given build and deploy when it is provisioned.

• control makes this node the control node.
• build executes image builds, so git-source services need at least one build node for their build.node.
• deploy runs the deployed service containers.

roles: [build]

Roles are resolved live from the node, not stored on the control node. When you change roles in up.yaml and run up apply, up pushes the new set to the node through the node config API, the node applies it without a restart, and up confirms the result by reading the node back. You can also read or change the roles of one node directly:

up node config --node edge-1
up node config set roles build,deploy --node edge-1

A node that cannot be reached is reported as offline and is skipped by build and deploy placement. Removing the deploy role from a node that still hosts an environment is refused with an error naming the environments: move or remove them first.

Changing host or user after the node is registered requires re-provisioning the node; see the Setting up nodes guide.