Private datacenters

What this is

Private datacenters (PDCs) are runner sites you operate inside your own network. Each site runs a MaxoPerf Outpost agent — a lightweight process that receives work from the platform and executes load on your behalf, from within your environment. Once a PDC is enrolled and its agent is running, the location appears alongside managed cloud regions when you configure a test.

Use private datacenters when your load target is:

• Internal and not reachable from the public internet.
• Subject to network or compliance constraints that require traffic to originate inside your environment.
• A system where you want to keep all load and result data on infrastructure you control.

BYOC feature flag required

The Private datacenters navigation entry and the /private-datacenters route are only visible when the Bring Your Own Cloud (BYOC) feature flag is enabled for your account. If you do not see this entry in the left nav, contact your MaxoPerf account team to discuss enablement.

Where to find it

Click Private datacenters in the left navigation sidebar. The route is /private-datacenters. The page is scoped to the workspace selected in the top-bar workspace scope switcher — a workspace must be selected to create or list PDCs.

---

Private datacenters list

The Workspace-owned sites section lists every PDC registered under the active workspace, one row per site.

Private datacenters list — Workspace-owned sites. Each row shows the PDC name, ID, workspace, and deployment mode. Click a row to open the PDC detail page.

Each row contains:

Element	What it shows
Site name	The human-readable label you gave the PDC at creation.
PDC ID	A truncated stable identifier — hover for the full value.
Workspace	The workspace that owns this PDC.
Deployment mode	docker (single-host Docker) or kubernetes (cluster-based).
Open	Click the row or the chevron to navigate to the PDC detail page.

Workspace scope required

If no workspace is selected in the scope switcher, the list shows a “No workspace” empty state. Select a workspace in the top-bar scope switcher before managing PDCs.

---

Connect an Outpost (create a PDC)

Connecting a new private datacenter is a two-step process: register the site in the console, then install the Outpost agent on your infrastructure using the generated install manifest.

Step 1 — Register the site

1. Ensure a workspace is selected in the top-bar scope switcher.
2. Click Create PDC in the page header. A dialog opens.
3. Enter a Name for the site (at least 2 characters). Use a descriptive label such as On-prem East or GCP VPC Internal.
4. Choose a Type:
   • Docker hosts — for a single Linux host running Docker.
   • Kubernetes — for a Kubernetes cluster where the agent runs as a workload.
5. Click Create PDC. The dialog closes and the new site appears in the list. Navigate to the PDC detail page to generate an install manifest.

Step 2 — Generate an install manifest and enrol the agent

Open the new PDC’s detail page and locate the Install manifest (with JWT) section.

1. In the Agent client ID field, enter a stable identifier for the host or Kubernetes pod — for example, a hostname (my-docker-host-01) or a durable pod name. This ID persists in the Outpost agents table so choose something descriptive.
2. Click Generate install manifest. The platform:
   • Issues a scoped, time-limited install JWT.
   • Fetches the install manifest for the PDC.
   • Merges the JWT into the snippet, replacing the placeholder token.
3. Copy the generated snippet and run it on your infrastructure:
   • Docker — copy the docker run command and run it on the target host.
   • Kubernetes — save the kubectl apply YAML to a file and apply it to your cluster.

Treat the install JWT like a password

The install JWT is displayed once after generation. Anyone with it can enrol an Outpost agent against your workspace until the token expires. Copy it immediately, use it, and do not paste it into shared chat channels, tickets, or commit it to a repository. If leaked, generate a new one (any existing enrolled agents retain their identity and are unaffected).

For a detailed walk-through of the full install path, see Connect a private datacenter.

---

PDC detail

The PDC detail page is opened by clicking any row in the private datacenters list, or by navigating to /private-datacenters/<pdc-id>.

PDC detail page. The Install manifest section generates the enrolment command. The Outpost agents section shows every enrolled agent with its lifecycle, heartbeat, and version.

The page is organised into four sections:

Identity and rename

The page heading shows the PDC name as an editable field (if you have edit rights). Click the name to rename the site inline. A meta pill row below the heading shows the deployment mode, PDC ID, and workspace ID.

Auto-update readiness

This read-only section summarises the scheduled upgrade posture for the PDC:

• Whether auto-update is enabled or disabled for the site.
• The current Outpost image reference and digest reported by the enrolled agents.
• The overall readiness state — whether the PDC is ready for a scheduled update or has blocking conditions.

Scheduled upgrades only run when agents are idle (no active workloads). If auto-update is disabled for an agent, that agent reports skipped upgrade outcomes instead of self-updating.

Install manifest (with JWT)

This section lets you generate a new install manifest at any time — useful for enrolling additional agents or re-installing on a replacement host.

1. Enter a Agent client ID (stable per host or pod).
2. Click Generate install manifest.
3. Copy the rendered snippet and run it on the target host or cluster.

The manifest variant shown depends on the PDC’s deployment mode: docker run for Docker hosts; kubectl apply YAML for Kubernetes.

One manifest per agent

Generate a separate manifest for each distinct host or Kubernetes node you want to enrol. Reusing the same clientAgentId on two hosts can cause conflicts in the agents table.

Outpost agents

The Outpost agents section shows a table of every agent enrolled against this PDC, followed by expanded operation details for each agent.

Agent table columns:

Column	What it shows
Agent	The clientAgentId you provided at install time. A leader badge marks the elected leader in multi-agent PDCs.
Lifecycle	Current lifecycle state — see the lifecycle reference below.
Runtime	Deployment mode (docker or kubernetes) and count of active workloads.
Version	Agent binary version and Outpost image version.
Heartbeat	Timestamp of the last heartbeat received from the agent.
Actions	Revoke button — removes the agent’s enrolled identity.

Lifecycle states:

State	Meaning
running	Agent is healthy and accepting workloads.
updating	Agent is in the process of a self-upgrade.
idle	Agent is connected but has no active workloads.
dead	No heartbeat received within the expected window — agent is unreachable.
revoked	The agent’s credentials were manually revoked. It must be re-enrolled to resume.
pending	Agent has not yet sent its first heartbeat after enrolment.

Expanded agent details (below the table):

Each agent card shows:

• Last heartbeat and Active workloads counters.
• Current Outpost image and Current image digest — the exact image the agent is running.
• Catalog preload — per-image preload status (pending, pulling, ready, failed) for each workload image cached on the agent.
• Agent upgrade — the current upgrade stage, candidate image, target digest, and any error or skipped reason.
• Kubernetes registry overrides (Kubernetes PDCs only) — any private registry pull-secret overrides configured for workload images.

Revoke an agent

1. In the Outpost agents table, find the agent row.
2. Click Revoke. The agent’s identity is invalidated immediately.
3. The agent moves to the revoked lifecycle state. The Outpost process on the host will stop receiving work. To restore the agent, generate a new install manifest and re-run it on the same host.

---

Lifecycle and health monitoring

Use the PDC detail page to monitor the health of your private runner site on an ongoing basis:

• Heartbeat staleness — if the last heartbeat timestamp is more than a few minutes old, the agent may be unreachable or crashed. Check the host’s Docker or Kubernetes logs.
• Dead agents — a dead lifecycle badge means the agent missed its heartbeat window. Investigate the host before a scheduled run that targets this location.
• Preload failures — a failed preload entry means the agent could not pull a workload image. Check the host’s network access to your image registry.
• Auto-update disabled — if an agent has autoUpdateEnabled: false, it will not self-upgrade. Schedule manual upgrades or re-enable the flag if you want automatic patch rollouts.

---

Select a private datacenter as a run location

Once an agent is in running lifecycle state, the PDC appears as a selectable location in the test configuration. To use it:

1. Open Tests in the left nav and open the test you want to run from the private location.
2. In the Configuration tab, find the Locations section.
3. Select the PDC from the locations list — it appears alongside managed cloud regions.
4. Optionally adjust the runner split across locations (e.g. 100% from the PDC, or a mix with a managed region).
5. Save and run the test.

Mixing locations

A single test can spread load across managed cloud regions and private datacenters simultaneously. This is useful when part of your system is public and another part is internal — run the public portion from a managed region and the internal portion from your PDC.

---

Tips & gotchas

• BYOC flag required. The Private datacenters nav entry is only visible when the BYOC feature is enabled for your account. Contact your account team if you need to enable it.
• Workspace scope matters. PDCs are workspace-owned. Switch to the correct workspace in the scope switcher before creating or managing sites.
• Install JWT is one-shot. Each click of Generate install manifest issues a new JWT. The previous JWT remains valid until it expires but is not shown again. Copy and use it immediately.
• Agent client IDs must be unique per PDC. Using the same clientAgentId on two different hosts in the same PDC causes agent conflicts. Use hostnames or pod names.
• Dead agents block scheduled runs. If a PDC’s agents are dead, tests targeting that location will fail to allocate runners. Restore the agents before scheduling runs.
• Revoking an agent does not delete run history. Historical run data for completed runs remains accessible even after an agent is revoked.

---

Related docs

• Managed and private load locations — when to use private locations versus managed cloud regions, and how to mix both in a single test.
• Connect a private datacenter — full step-by-step install guide including prerequisites and operating tips.
• Tests — create and configure — how to select a private location when creating or editing a test.
• Runs — read results — interpreting run results from private-location tests.
• Navigating the console — the shell, sidebar, and workspace scope switcher.