Select a session
No report selected
Select a build
No machine selected
🌐 Network & IP Matrix
❓ GDC Companion Help & Documentation
Quick reference guide for JSON Schema validation, API endpoints, and authentication settings.
📐 JSON Schema Adherence
All machine configurations and diagnostic report artifacts ingested by the GDC Companion App must adhere strictly to defined JSON Schemas. Schemas are hosted as zero-dependency embedded assets directly on the companion instance.
Defines required machine properties (hostname, bmctl_version,
network [management
& cluster],
gcp_info,
cluster,
peers).
Defines system health, hardware inventory, network connectivity, and bootstrap stage progress.
/v1/schema/report⚡ API Endpoints Reference
| Method | Endpoint | Auth & Security | Description & Purpose |
|---|---|---|---|
| GET | /v1/machine-info/list | 🔑 API Key | Lists all registered bare-metal nodes and hostnames. |
| GET | /v1/machine-info/{mac-address} |
🔑 API Key
🔒 mTLS planned (future)
|
Returns resolved Machine Config JSON object for target MAC address. (mTLS-bound client certificate validation planned in a future release). |
| POST | /v1/machine-info/{mac-address} | 🔑 API Key | Seeds or updates Machine Config JSON properties in PostgreSQL. |
| GET | /v1/machine-credentials/gcp-token/{mac-address} |
🔒 mTLS Required
+ API Key if enabled
|
Returns short-lived GCP JWT Access Token for specific
machine. Requires client certificate
CN matching registered
machine hostname.
|
| POST | /v1/machine-reports/ingest | 🔑 API Key |
Ingests compressed diagnostic report tarball (*.tar.gz). Aliases:
/upload,
/v1/machine-report/ingest, and
/v1/machine-reports/upload.
|
| GET | /v1/machine-reports | 🔑 API Key | Retrieves list of uploaded diagnostic reports. |
| POST | /v1/install-logs |
⚡ Auth Bypass
Optional mTLS tagging
|
Captures Cloud-Init & Subiquity provisioning logs without authentication during node turnup. Supports optional mTLS cert tagging. |
| GET | /v1/downloads/{filename} | 🔑 API Key |
Downloads verified diagnostic scripts (e.g.
collect-diagnostics.sh).
|
| GET | /v1/build-reports | 🔑 API Key | Retrieves CI/CD build history and system build reports. |
| GET | /v1/schema/machine | 🔑 API Key | Returns Machine Config JSON Schema. |
| GET | /v1/schema/report | 🔑 API Key | Returns Diagnostic Report JSON Schema. |
| GET | /health & /version | 🌐 Public | System health check and active build version info. |
🔑 API Key Authentication
When the environment variable
GDC_API_KEY
is configured on the server, all
/v1/* endpoints require
authentication. Clients can supply the key using any of the
following formats:
-
Header:
X-API-Key: <your-api-key> -
Header:
Authorization: Bearer <your-api-key> -
Query Param (Debug Mode):
?api_key=<your-api-key>
GDC_API_KEY is omitted to allow
unauthenticated initial bootstrapping.
Future production releases will transition to a strict
fail-closed model, where any cluster deployment lacking a valid API key will fail
closed and reject unauthenticated requests.
🔒 Mutual TLS (mTLS) & Node Identity
Mutual TLS authenticates bare-metal nodes during bootstrapping and
cluster turnup. The edge proxy terminates TLS and forwards the
validated client certificate Common Name (CN) via the
X-Client-Cert-CN
or
ssl-client-subject-dn
header.
-
Token Broker (
/v1/machine-credentials/gcp-token/*): Strictly validates that the client certCNmatches the registeredhostnamebefore minting short-lived Google OAuth tokens. -
Machine Config (
/v1/machine-info/*): Currently secured via API Key. Future releases will mandate mTLS certificate binding matching the target node. -
Log Streaming (
/v1/install-logs): Uses client certCNwhen present to automatically correlate and tag live-boot install sessions.
Custom Playbook Bundles
Manage and distribute custom Ansible lifecycle extension archives (.tar.gz) for GDC edge nodes.
| Bundle Name | Bundle ID | SHA-256 Checksum | Size | Uploaded At | Actions |
|---|---|---|---|---|---|
| Loading bundles... | |||||
Upload Custom Playbook Bundle
Drag and drop your .tar.gz bundle here, or click to browse
🏷 Assign Network Segment