Plan and Set Up a Managed Cluster

Use this guide to connect one pilot node, validate the complete path, and then roll the agent out to the remaining nodes.

Before You Begin

Choose a deployment profile and assign responsibilities before changing any hosts. 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 and an SSH server on nodes that users will access interactively.
• Slurm or PBS client commands on the scheduler controller if you want job information in ACTIVATE.
• A maintenance window and host backups appropriate for any NSS, PAM, sshd, or sudoers changes you plan to enable.

Access-management automation supports Debian- and RHEL-family distributions. User Population may install git, make, and a C compiler, then build libnss_cache from source if the library is absent. Permit access to the host's package repositories and GitHub during initial configuration, or preinstall the dependencies under your site's change process.

Check Network Paths

The metrics endpoint on TCP 9100 does not require credentials. The agent listens on all interfaces by default, so use host or network firewalls to prevent public or untrusted access. The platform connection itself is outbound; you do not need a public inbound route for the managed tunnel.

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

Choose the Pilot

Start with a non-critical node that represents the operating system and security configuration you will use in production. If possible, choose a node that can perform the intended login or scheduler-controller role so the pilot can validate more than heartbeats.

Do not enable cluster-wide access management until the pilot agent is online. When you are ready to test those settings, use a node-level override.

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. 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. The service runs as root.

A node is identified by its system hostname. Registering the same hostname again replaces that node's credential and registration. Before re-registering, confirm that no other active machine is using that hostname.

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 when available.
• 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 without duplicating it from every node. ACTIVATE displays Slurm partitions and jobs. For PBS, it displays jobs; do not expect a PBS partition view.

If you chose the ACTIVATE-managed identity and access profile, configure identity and access on the pilot now. Return here only after the applicable NSS, PAM, SSH-key, and sudo checks succeed.

Pilot Acceptance Checklist

Complete the basic connection checks and every identity check that applies to your deployment profile before registering more nodes:

• 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, a pilot user's UID, groups, home directory, SSH key, and sudo behavior match policy.
• Removing the pilot user's access or sudo permission produces the expected process-revocation behavior described in the identity guide.
• If sessions are enabled, a pilot desktop or VS Code session starts on the selected session node.
• TCP 9100 is unreachable from untrusted networks and reachable only from approved monitoring systems, if any.
• Agent logs show no repeated heartbeat, tunnel, scheduler, or access-management errors.
• Linux and ACTIVATE administrators have recorded the effective settings and rollback plan.

Roll Out the Remaining Nodes

After all applicable pilot checks pass, generate a fresh registration token for each node. Register only nodes that ACTIVATE needs to observe, use as a connection target, or configure. After each batch, verify node status, tunnel state where required, and effective access-management settings before continuing.

After rollout, share the user guide and the site's support path with everyone who receives access.