GDC Companion Dashboard

gcp-project: ...
Select an installation session from the left sidebar to view logs.

Select a build

Build Outcome
-
Duration
-
Git Branch / Commit
-
Local ISO Size
-
Build Stages Binaries Audit Packages & Seed GCS Details
Select a build report from the left sidebar to view pipeline status.

No machine selected

🔗 Share / Download JSON
Select a machine from the left sidebar to view and edit its key-value configurations.

🌐 Network & IP Matrix

Loading 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.

Machine Config Schema

Defines required machine properties (hostname, bmctl_version, network [management & cluster], gcp_info, cluster, peers).

/v1/schema/machine
Diagnostic Report Schema

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>
⚠️ Security Notice: The current environment operates in a fail-open state when 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 cert CN matches the registered hostname before 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 cert CN when 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.

⚠️ Fleet Governance Advisory: Avoid assigning one-off custom bundles to individual machines. Use standardized fleet bundles across profiles to prevent snowflake cluster drift.
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