SC26AI agents lab + dinner on the river · Nov 17
Parallel Works
View as Markdown
Share:

Plan and Set Up a Managed Cluster

Register a pilot node, choose its connection and account settings, then register the remaining nodes.

Requiresorg:admin

Before You Begin

Choose a deployment profile. You need:

  • Organization administrator permission in ACTIVATE.
  • Root or sudo access to every node you plan to register.
  • A Linux distribution that uses systemd.
  • curl on each node where you will run the installer.
  • An SSH server on nodes used for terminal or CLI SSH connections.
  • Slurm or PBS client commands on the scheduler controller if you want job information in ACTIVATE.

Use a pilot node with the Linux distribution and configuration you intend to deploy. Install the host utilities, SSH/PAM modules, and session software needed for your chosen features. For account-management requirements, see How Linux Identities Are Stored.

Check Network Paths

DirectionSourceDestinationPort and protocolPurpose
OutboundEvery registered nodeACTIVATE platform hostTCP 443, HTTPS/WSSRegistration, heartbeats, API calls, and the managed tunnel
Inbound within trusted networksMonitoring systemsEvery registered nodeTCP 9100, HTTPPrometheus metrics served by the agent
Inbound to the selected login nodePlatform, workspace, or user networks, depending on login configurationSSH serverTCP 22Direct SSH path when configured
Local on the selected login nodeManaged agentSSH serverTCP 22Final SSH hop when ACTIVATE uses the managed tunnel; this does not require a public inbound rule

The Prometheus listener binds to all interfaces on TCP 9100 and serves metrics over HTTP without authentication. Limit access to trusted monitoring systems through the host or network firewall. The managed tunnel uses an outbound connection and needs no public inbound route.

See Compute Cluster Agent Connectivity for the broader control-plane network model.

Choose the Pilot

Choose a node that can perform the intended login, session, or scheduler-controller role. This lets you verify the features users will use as well as the agent connection.

Use node-level overrides to try account-management settings on the pilot before applying cluster defaults.

Create the Resource

  1. Open Compute > Clusters.
  2. Click Add Resource and select Managed Cluster.
  3. Enter a unique cluster name. Display name, description, tags, and favorite status are optional.
  4. Click Add Resource.

This creates an organization-level record in ACTIVATE. It does not create or modify any machines.

Register the Pilot Node

  1. Open the managed cluster and select Nodes.

  2. Click Add Node.

  3. Choose a single-use token for one node or a reusable token for a controlled rollout, select its expiry, and click Generate Registration Token.

  4. On the node, run the installation command shown in ACTIVATE. It follows this form:

    curl -fsSL https://<platform-host>/cli/install.sh | bash -s -- --to /usr/local/bin

  5. Run the registration command shown on the page:

    sudo /usr/local/bin/pw agent register --token '<registration-token>' --systemd

The command exchanges the token for a node-specific credential, installs and enables /etc/systemd/system/pw-agent.service, and starts the agent as root.

From registration token to running agent
  1. Cluster administratorCreate a registration tokenThe token identifies the ACTIVATE organization and cluster.
  2. Linux administratorRun the registration command on the nodeThe command sends the token to ACTIVATE.
  3. ACTIVATERegister the node and issue its credentialThe agent uses this credential for its ongoing connection.
  4. Agent on the Linux nodeConnect to ACTIVATE and apply enabled settingsThe agent reports node health and maintains its connection.

Registration enrolls a machine. Administrators configure user access separately in Manage Access.

Token modeUseDefault expiry
Single-useRegisters one node24 hours
ReusableRegisters multiple nodes until expiry or revocation1 hour

Expiry can be configured from 5 minutes to 24 hours. Keep tokens private, and use Add Node to review or revoke active tokens. Revoke a reusable token when its rollout is complete.

Token expiry or revocation stops further enrollment. Registered nodes continue using their issued credentials; to remove one, follow Offboard a Node or Cluster.

A node is identified by its system hostname. Use a unique hostname for each machine. Registering the same hostname again replaces that node's credential and registration.

Verify the Agent

On the node, inspect the service and follow its logs:

sudo systemctl status pw-agent
sudo journalctl -xefu pw-agent --output=cat

The agent sends a heartbeat every 30 seconds. ACTIVATE marks a node offline after it has missed heartbeats for about 90 seconds. Online and Tunnel Connected are separate states; verify both when the node will handle SSH or sessions.

Configure the Node Roles

Open the cluster and click Edit.

Login Address

Choose where terminal and CLI SSH connections land:

  • Registered node uses that node's live tunnel. If the tunnel is unavailable, ACTIVATE may attempt direct SSH to the node's hostname.
  • User workspace uses the user's workspace as the connection point when it can route to the cluster.
  • Custom address uses an administrator-supplied hostname or IP address.

If you use a custom address, enable Proxy SSH when the platform should proxy the connection rather than let the client connect directly.

Session Node

Select the registered node that should host browser desktop and VS Code sessions. It can differ from the login node, but its tunnel must show Connected when a session starts. Choose None to disable managed sessions for the cluster.

Scheduler Controller

Register the node running slurmctld or pbs_server to publish cluster scheduler data. ACTIVATE displays partitions and jobs for Slurm, and jobs for PBS.

Grant User Access

If ACTIVATE will create Linux accounts, first prepare usernames, UIDs, and groups.

Use Manage Access to grant cluster access to the groups or organization whose members will use the cluster. This step applies whether the agent or an existing system supplies Linux accounts.

For ACTIVATE-managed identities, enable the account settings on the pilot before continuing.

Pilot Acceptance Checklist

Verify the features in your deployment profile:

  • The pilot appears Online, and its hostname, operating system, architecture, filesystems, and metrics are correct.
  • If the node will carry SSH or sessions, its tunnel appears Connected.
  • The intended login address is configured, and a pilot user can open a terminal using the expected route.
  • If using Slurm, partitions and a test job appear. If using PBS, a test job appears.
  • If using ACTIVATE-managed identities, the pilot user's UID, groups, home directory, SSH key, and sudo access match the configured settings.
  • A user with Login access can connect through ACTIVATE; a user without cluster access is denied.
  • If No Root Access applies, Sudo Access is disabled and the managed sudoers rule is absent.
  • Removing the pilot user's access updates managed accounts, groups, and processes as described in Remove or Reduce Access.
  • If sessions are enabled, a pilot desktop or VS Code session starts on the selected session node.
  • Firewall rules limit TCP 9100 to the intended monitoring systems.
  • Agent logs show no repeated heartbeat, tunnel, scheduler, or access-management errors.

Roll Out the Remaining Nodes

After the pilot checks pass, register the remaining nodes with single-use tokens or a reusable token for the batch. Verify node status, required tunnels, and account settings after each batch.

Users can then follow Use a Managed Cluster to connect, start sessions, and run jobs.