Managers

Overview

The Kasm Manager coordinates the Kasm API and the Agent fleet, so taking one offline for maintenance must not disrupt active sessions. This guide shows administrators how to disable a Kasm Manager for patching, debugging, or rolling updates without stopping the container, then re-enable it cleanly. The Manager drains out of rotation, the remaining Managers in the Deployment Zone hold capacity, and Primary Manager failover keeps the zone operational throughout. The result is confident, low-risk maintenance on a running deployment.

Prerequisites

Before you begin, confirm the following:

• Administrator access to the Kasm admin UI with permission to manage Infrastructure.
• A multi-server deployment with at least two Kasm Managers in the target Deployment Zone. At least one Manager per zone must stay enabled at all times.
• Shell access to the host running the target Kasm Manager container, for verification commands.

Solution approach

This guide progresses through the following phases:

1. Review the Managers in the deployment.
2. Disable the target Manager.
3. Verify draining and Primary Manager failover.
4. Re-enable the Manager.

Detailed steps

Review the Managers in the deployment

Identify which Manager to take out of rotation and confirm the zone has spare capacity.

1. In the Kasm admin UI, navigate to Infrastructure -> Managers.

2. Review the list of registered Managers and their current state. Each entry reports the following:

   Column	Description
   Instance ID	Unique identifier for the Manager container instance.
   Enabled	Whether the Manager is currently active and accepting Agent connections.
   First Reported Time	Timestamp when the Manager first registered with the deployment.
   Last Reported Time	Time elapsed since the Manager last sent a heartbeat.
   Zone	The Deployment Zone this Manager belongs to.
   Status	Current operational status, either running or unknown.
   Primary Manager	Indicates which Manager holds the primary role in its zone.

3. Confirm the target Manager's zone contains at least one other enabled Manager. Note whether the target currently holds the Primary Manager role, because disabling it triggers a failover.

Disable the target Manager

A Manager can be disabled without stopping or restarting its container. This takes the Manager out of rotation for maintenance while the Agent fleet keeps running.

1. In Infrastructure -> Managers, locate the target Manager.
2. Set its Enabled flag to false.

Zone constraint

At least one Manager per zone must remain enabled at all times. The UI displays an error and blocks the action when disabling a Manager would leave a zone with no enabled Managers.

When the enabled flag is set to false in the database, the Manager drains in a defined sequence:

1. A sentinel file is created. The Manager process writes a sentinel file at /tmp/kasm_manager_draining inside the container, mapped to /opt/kasm/current/tmp/manager/ on the host.
2. Nginx stops serving the Manager. The kasm_proxy nginx container checks for the sentinel file on every incoming request. When the file is present, nginx returns 503 Service Unavailable with a Retry-After: 30 header on /health and stops proxying /manager_api/ requests. The same sentinel check triggers both behaviors independently.
3. Work is suspended. The Manager's internal guardian loop skips all work while enabled=false. A disabled Manager cannot promote itself to Primary or modify shared resources.
4. The container stays healthy. Docker's container health reporting distinguishes "disabled" from "unhealthy", so a disabled Manager continues to report healthy to Docker and does not trigger an automatic restart.

Verify draining and Primary Manager failover

Confirm the disabled Manager has drained and the zone still has a Primary Manager. Run the following commands on the host where the Manager container runs.

When you disable the current Primary Manager, another enabled Manager in the same zone promotes itself to Primary. All Agents in the zone re-register with the new Primary Manager. The guardian loop runs on a fixed interval, so this promotion completes within a few minutes.

The Manager exposes two health endpoints that serve different purposes:

Endpoint	Used by	Disabled response
/__healthcheck	Docker internal healthcheck	503, remapped to healthy by the healthcheck script to prevent a container restart
/health	kasm_proxy nginx	503, nginx stops proxying requests to the Manager

To inspect the Manager process directly and bypass nginx, query the internal healthcheck endpoint:

docker exec -it kasm_manager curl -i http://localhost:8181/__healthcheck

Interpret the response as follows:

• 200 OK indicates the Manager is enabled and healthy.
• 503 with a {"ok": false, "status": "disabled", "enabled": false} body indicates the Manager is intentionally disabled. Docker's healthcheck script maps this to healthy, so the container is not restarted.
• 500 indicates the Manager process is unhealthy, such as a missed heartbeat or a timeout.

Confirm Docker still considers the container healthy:

docker inspect --format='{{.State.Health.Status}}' kasm_manager

This reports healthy even when the Manager is disabled. An unhealthy result would indicate the container is at risk of a restart.

To verify Agent routing, open the Diagnostics section in the admin UI and review the Manager request logs for 503 responses. Agents stop routing to the disabled Manager within one check-in interval.

Re-enable the Manager

Return the Manager to rotation after maintenance completes.

1. In Infrastructure -> Managers, locate the disabled Manager.
2. Set its Enabled flag to true.

When the Manager is re-enabled, the sentinel file is removed, nginx resumes proxying requests and returns 200 OK, and the guardian loop resumes. The Manager can re-acquire the Primary role when appropriate.

Re-enabling takes a moment

After re-enabling a Manager, allow up to a minute for it to return to running status. The guardian loop processes state on a fixed interval, so the transition is not instantaneous.

Common troubleshooting steps

• The UI blocks disabling the Manager. The target zone would be left with no enabled Manager. Enable or add another Manager in the same zone, then retry.
• Docker reports the container as unhealthy. A 503 on /__healthcheck should map to healthy when the Manager is disabled. An unhealthy result points to a missed heartbeat or a process timeout rather than an intentional disable. Inspect the Manager logs.
• Agents keep routing to the disabled Manager. Allow one Agent check-in interval to pass. If routing persists, confirm the sentinel file exists at /opt/kasm/current/tmp/manager/ on the host and that kasm_proxy is running.
• No Primary Manager appears after a failover. Allow a few minutes for the guardian loop cycle to complete. Confirm at least one other Manager in the zone is enabled and reporting a recent Last Reported Time.