Data planes¶
A data plane is a small DV Forge service that you run inside your own network, on-prem or in your own cloud account. CI uploads go to it instead of to DV Forge. It keeps the raw simulation logs in your storage, analyzes failures locally, and sends DV Forge only structured, redacted results. This page is for the administrators who decide whether to use one, install it, and keep it healthy.
Why use a data plane¶
Without a data plane, a project uploads straight to DV Forge, and DV Forge stores the logs. That's the quickest way to start. With a data plane:
- Raw logs stay in your network. They're stored only in the data plane's storage: a local disk or an S3-compatible bucket you own.
- Failures are analyzed where the logs are. The data plane parses each failing job's log, applies your redaction rules, and forwards only the result.
- Connections are outbound only. The data plane connects out to DV Forge over HTTPS. You don't open any inbound firewall ports to the internet. It sends heartbeats and asks DV Forge for work, such as "send the log for job X, because a user opened it".
- Uploads survive outages. If DV Forge is unreachable, the data plane queues results on disk and forwards them later.
flowchart LR
subgraph net["Your network"]
CI["CI: dvforge upload"] -->|"results + logs"| DP["Data plane<br/>logs · parsing · redaction"]
DP --- ST[("Log storage")]
end
DP -->|"outbound HTTPS only:<br/>results, redacted analyses"| DV["DV Forge"]
What leaves your network¶
| Sent to DV Forge | Never sent |
|---|---|
| Job metadata: test name, status, seed, component, simulator, build target, configuration, plusargs, host, runtime, cycles, exit code, and the log's SHA-256 hash | Raw logs. They stay in the data plane's storage. |
| For each failing job, the failure analysis after redaction: headline, error line, signature title, parsed messages, and an excerpt capped at 16 KiB by default | RTL, repositories, and design files |
| A job's one-line failure message, after redaction | Anything in bulk: there is no export path |
| A full log, only when a user opens it in the log viewer. It passes through DV Forge to the user's browser and isn't stored. | Queued uploads at rest. They stay on the data plane's disk until delivered. |
| Heartbeats: the data plane's version and queue health (counts and the last error) |
Redaction covers the analysis, not the metadata
Your redaction patterns apply to the failure analysis and the job's failure message. Job metadata such as test names, plusargs, configuration, and host names is forwarded as your JUnit reports it. See Redaction on a data plane.
Before you begin¶
- Roles. Registering and revoking data planes needs the org_admin role. Binding a project needs project_admin or higher (roles apply to every project in the organization). See Projects, roles and tokens.
- The data plane software. Your DV Forge contact provides it as a container image or as a Python package (Python 3.11 or later).
- A host in your network that your CI machines can reach on port 8100 (or
a port you choose), and that can make outbound HTTPS connections to
https://api.daruur.cloud. - Persistent storage for logs and the outage queue. Logs can go to an S3-compatible bucket instead, but the queue always needs a local disk.
Set up a data plane¶
1. Register it¶
- In the app, select Data planes in the sidebar.
- Under Manage, type a name in Register a data plane, for example
austin-farmorcloud-west. - Select Register.
- Copy the key that appears. It starts with
dvp_, and it is shown only once: "copy it now, it won’t be shown again". Store it in your secret manager, then select I've stored it.
The data plane appears in the Registered table as offline until it sends its first heartbeat. Only signed-in people manage data planes; project tokens can't create, list, or revoke them.
2. Install and start it¶
The data plane is configured entirely through environment variables. Two are required:
| Variable | Value |
|---|---|
DVFORGE_DP_CONTROL_PLANE_URL |
https://api.daruur.cloud |
DVFORGE_DP_KEY |
The dvp_ key from step 1 |
docker run -d --name dvforge-dataplane --restart unless-stopped \
-p 8100:8100 \
-v dvforge-data:/data \
-e DVFORGE_DP_CONTROL_PLANE_URL=https://api.daruur.cloud \
-e DVFORGE_DP_KEY=dvp_... \
<the data plane image from your DV Forge contact>
The image runs as a non-root user, listens on port 8100, and keeps logs
in /data/blobs and the outage queue in /data/spool. Mount /data on
persistent storage. The image includes a health check against
/healthz.
python3.11 -m venv /opt/dvforge-dataplane
/opt/dvforge-dataplane/bin/pip install /path/to/the-data-plane-package
export DVFORGE_DP_CONTROL_PLANE_URL=https://api.daruur.cloud
export DVFORGE_DP_KEY=dvp_...
export DVFORGE_DP_BLOB_DIR=/srv/dvforge/blobs
/opt/dvforge-dataplane/bin/dvforge-dataplane
The package installs the dvforge-dataplane command. It also reads a
.env file in its working directory. Run it under your service manager
so it restarts after a reboot.
If a setting is missing or invalid, the data plane prints
dvforge-dataplane: invalid configuration: followed by each offending
variable, and exits with code 2. dvforge-dataplane --version prints its
version.
Plain HTTP on the CI side
The data plane serves HTTP. If your CI machines reach it across a network you don't trust, put a TLS-terminating proxy or load balancer in front of it. Its own connection to DV Forge always uses the HTTPS URL you configure.
Within one heartbeat (30 seconds by default), the data plane shows as online on the Data planes page.
3. Bind projects to it¶
A project uses a data plane only once it's bound to it.
- Select the project in the project switcher.
- Open Data planes in the sidebar.
- Under Manage, in Where project keeps its raw logs, choose Data plane: name. The change takes effect immediately.
Repeat for each project. One data plane can serve several projects in the same organization.
Switch the upload URL at the same time
From the moment a project is bound, DV Forge refuses direct uploads for
it ("this project ingests through its data plane; point the uploader at
it") and refuses the paste form. A data plane, in turn, refuses projects
that aren't bound to it. Bind the project and update DVFORGE_URL in CI
together, between two nightly runs.
4. Point the CLI at it¶
In your CI, set DVFORGE_URL to the data plane's address. Keep the same
project token; the data plane passes it on to DV Forge, which checks it.
export DVFORGE_URL=http://dvforge-dp.example.internal:8100
export DVFORGE_TOKEN=dvf_... # the project's usual token
dvforge upload --name "nightly $BUILD_ID" --external-id "$BUILD_ID" \
--junit out/results.xml --logs 'out/logs/**/*.log' --only-failing-logs
Nothing else in the command changes. See CI integration.
Configuration reference¶
Every setting is an environment variable starting with DVFORGE_DP_.
| Variable | Default | Meaning |
|---|---|---|
DVFORGE_DP_CONTROL_PLANE_URL |
required | DV Forge's API URL: https://api.daruur.cloud. |
DVFORGE_DP_KEY |
required | This data plane's dvp_ key. Never logged. |
DVFORGE_DP_BLOB_BACKEND |
local |
Where logs are stored: local (disk) or s3 (AWS S3 or any S3-compatible store). |
DVFORGE_DP_BLOB_DIR |
./data/blobs |
Log directory for local (/data/blobs in the container). |
DVFORGE_DP_S3_BUCKET |
none | Bucket for s3. Required with s3; created if it doesn't exist. |
DVFORGE_DP_S3_ENDPOINT_URL |
none | Endpoint of an S3-compatible store. Leave empty for AWS S3. |
DVFORGE_DP_S3_REGION |
none | S3 region. |
DVFORGE_DP_REDACT_PATTERNS |
[] |
JSON array of regular expressions. Every match in a failure analysis or a job's failure message becomes [redacted] before forwarding. Example: '["tb_top(\\.\\w+)+", "0x[0-9a-fA-F]{8,}"]'. |
DVFORGE_DP_MAX_EXCERPT_CHARS |
16384 |
Maximum excerpt size forwarded per failure, up to 65536. 0 forwards no log lines. |
DVFORGE_DP_EXCERPT_CONTEXT_LINES |
25 |
Lines kept before and after the failure in the excerpt. |
DVFORGE_DP_HEARTBEAT_SEC |
30 |
Seconds between heartbeats. Keep it well under 90, or the data plane will show as offline. |
DVFORGE_DP_CLAIM_WAIT_SEC |
20 |
How long each request for work waits for a task, in seconds (at most 25). |
DVFORGE_DP_TOKEN_CACHE_SEC |
60 |
How long the data plane remembers that a CI token is valid. 0 checks every request. |
DVFORGE_DP_TOKEN_GRACE_SEC |
21600 (6 hours) |
While DV Forge is unreachable, how long a token checked successfully before keeps working. 0 disables. |
DVFORGE_DP_SPOOL_DIR |
spool next to the blob directory |
The outage queue (/data/spool in the container). Keep it on persistent storage, even with s3 logs. |
DVFORGE_DP_SPOOL_MAX_BYTES |
1073741824 (1 GiB) |
Size cap for queued uploads. 0 disables queuing. |
DVFORGE_DP_SPOOL_MAX_FILES |
10000 |
Entry cap for queued uploads. 0 disables queuing. |
DVFORGE_DP_SPOOL_DEAD_MAX_BYTES |
268435456 (256 MiB) |
Size cap for dead letters; the oldest are removed first. |
DVFORGE_DP_SPOOL_DEAD_MAX_FILES |
1000 |
Count cap for dead letters. |
DVFORGE_DP_SPOOL_DEAD_MAX_AGE_DAYS |
30 |
Dead letters older than this are deleted. |
DVFORGE_DP_MAX_UPLOAD_BYTES |
67108864 (64 MiB) |
Largest log upload or job batch request accepted. |
DVFORGE_DP_MAX_LOG_BYTES |
268435456 (256 MiB) |
Largest log accepted, uncompressed. |
DVFORGE_DP_HOST, DVFORGE_DP_PORT |
0.0.0.0, 8100 |
Listen address and port. |
DVFORGE_DP_LOG_LEVEL |
info |
debug, info, warning, or error. |
Monitoring¶
In the app¶
The Data planes page lists every data plane in your organizations under Registered:
| Column | What it shows |
|---|---|
| Name | The name you registered. |
| Status | online (a heartbeat in the last 90 seconds), offline, or revoked. |
| Version | The data plane software version it last reported. |
| Spool | The health of its outage queue (see below). |
| Projects | Projects bound to it. |
| Last seen | Its last heartbeat or request for work, or "never". |
| Key | The start of its key, dvp_<prefix>_…, so you can tell keys apart. |
On the data plane¶
GET /healthz on the data plane returns its own view as JSON: status,
version, org, bound projects, last_heartbeat_at,
control_plane_reachable, last_error, counts of log requests served and
refused, and spool health. Use it for your own monitoring or load-balancer
checks.
The outage queue (spool)¶
If the data plane can't reach DV Forge while CI is uploading (a network failure, a timeout, or HTTP 502, 503, or 504), it doesn't fail the upload:
- Logs are stored locally as usual. They never needed DV Forge.
- Job batches and the completion of a regression are written to the spool and acknowledged to the CLI as queued. The CLI exits 0 and says the upload was "spooled on the data plane".
- Opening a regression can't be queued, because the CLI needs the regression id DV Forge returns. The data plane answers "try again later", the CLI retries, and if DV Forge stays unreachable the CLI exits 4.
A background loop forwards the queue oldest first, as soon as DV Forge answers again. Batches for one regression are never reordered, and the completion always goes last. Each entry is written to disk safely, so the queue survives crashes and restarts, and an entry sent twice is recognized by DV Forge and not counted twice.
The queue holds exactly what would have been forwarded: the analyzed, redacted batch, never a raw log. It also holds the uploader's token, because DV Forge checks it again on delivery. Files are readable only by the data plane's user and are deleted once delivered.
Spool health in the app¶
| Indicator | Meaning |
|---|---|
| empty | Nothing waiting. |
| N waiting | Uploads queued for DV Forge. Hover to see the last error. They drain by themselves once the data plane can reach DV Forge. |
| N dead letter(s) | Uploads DV Forge refused for good. Hover to see the last reason. |
| — | The data plane hasn't reported queue health. |
Dead letters are queued uploads that DV Forge rejected permanently: for
example, the token was revoked, the regression was deleted, or the request was
invalid. They're not retried. The data plane moves them to the dead
directory inside the spool, removes the token from them, and deletes them
after 30 days by default. To recover the results, fix the cause (such as the
token) and rerun the CI upload. It's safe to repeat.
When the queue reaches DVFORGE_DP_SPOOL_MAX_BYTES or
DVFORGE_DP_SPOOL_MAX_FILES, the data plane stops accepting batches until it
drains; the CLI retries and then exits 4.
When something is offline¶
| Situation | Uploads | Log viewer |
|---|---|---|
| DV Forge is unreachable from the data plane | Logs are stored; batches and completions are queued and forwarded later. New regressions can't be opened until DV Forge is back (CLI exit 4). CI tokens checked in the last 6 hours keep working. | Unavailable for this data plane's logs. |
| The data plane is down or unreachable from CI | Fail after the CLI's retries (exit 4). Rerun once it's back. | Shows "This log lives in your data plane, which didn't answer." |
Analyses, signatures, and triage in DV Forge keep working in every case: they don't need the raw logs.
Unbinding a project¶
To move a project back to direct uploads, choose Embedded (DV Forge control
plane — dev and demos) in Where project keeps its raw logs, then set
DVFORGE_URL back to https://api.daruur.cloud in CI. Logs uploaded while the
project was bound stay in the data plane, and the log viewer keeps fetching
them from there.
Revoking a data plane¶
- On the Data planes page, under Manage, select Revoke name.
- Read the warning: "Its key stops working immediately", and any bound projects "will stop ingesting until you bind them to another data plane".
- Select Revoke.
After revoking:
- The data plane can no longer send heartbeats, forward uploads, or answer log requests. It shows as revoked.
- Projects still bound to it can't upload anywhere until you bind them to another data plane or back to embedded. The binding list shows the revoked data plane as "revoked — ingest blocked; choose another".
- Logs stored in the revoked data plane can't be opened from DV Forge anymore, even if the service keeps running. Analyses and signatures are unaffected.
There is no key rotation
A data plane's key can't be replaced. Replacing it means registering a new data plane, binding the projects to it, and revoking the old one. The log viewer finds each log through the data plane that stored it, so logs stored under the old registration become unviewable after the revoke. Plan replacements accordingly, and treat the key like any other long-lived secret.
Security notes¶
- The data plane never checks CI tokens itself. It asks DV Forge, caches the answer for 60 seconds by default, and refuses tokens that can't write to the project, and projects that aren't bound to it.
- DV Forge can ask the data plane for one thing only: the beginning of a stored log (up to 4 Mi characters), when a user opens it. The data plane refuses any other kind of request, so DV Forge can't make it do anything else inside your network.
- The data plane contains the log parsing library and nothing else from DV Forge.