Boot Service

UEFI HTTP boot endpoints and boot profile management

The Boot Service is a custom Go microservice that provides UEFI HTTP boot endpoints for bare metal servers and manages boot profiles. It serves boot scripts, streams kernel/initrd assets, and handles boot profile administration (kernel/initrd upload, storage, and lifecycle management).

Architecture Overview

The Boot Service is deployed on GCP Cloud Run and accessed through a WireGuard VPN tunnel from bare metal servers. It integrates with:

Machine Service: Retrieves machine hardware profiles by MAC address
Cloud Storage: Stores and retrieves kernel/initrd blobs
Firestore: Stores boot profile metadata
Cloud Monitoring: OpenTelemetry observability with distributed tracing

Machine Service - Machine hardware profile management
ADR-0005: Network Boot Infrastructure Implementation on Google Cloud - Architecture decision and design rationale
ADR-0002: Network Boot Architecture - Overall network boot strategy

API Endpoints

UEFI HTTP Boot Endpoints

Accessed by bare metal servers during boot process (via WireGuard VPN):

GET /boot.ipxe - Serves iPXE boot scripts customized for the requesting machine
GET /asset/{boot_profile_id}/kernel - Streams kernel images from Cloud Storage
GET /asset/{boot_profile_id}/initrd - Streams initrd images from Cloud Storage

Admin API

Boot profile management endpoints for administrators:

POST /api/v1/profiles - Create a new boot profile for a machine
GET /api/v1/boot/{machine_id}/profile - Retrieve the active boot profile for a machine
PUT /api/v1/boot/{machine_id}/profile - Update the boot profile for a machine
DELETE /api/v1/boot/{machine_id}/profile - Delete a machine’s boot profile

Health Check Endpoints

Standard Cloud Run health endpoints:

GET /health/startup - Startup probe endpoint
GET /health/liveness - Liveness probe endpoint

Security Model

VPN-Based Access Control

Since HP DL360 Gen 9 servers do not support client-side TLS certificates for UEFI HTTP boot, all boot traffic is secured via WireGuard VPN:

Boot Endpoints: Only accessible through WireGuard tunnel (source IP validation)
Transport Security: WireGuard provides mutual authentication and encryption

Authentication Methods

UEFI Boot Endpoints: VPN source IP validation (bare metal servers)
Health Checks: Unauthenticated (used by Cloud Run for liveness/startup probes)

Common Patterns

Error Responses

All API endpoints follow the RFC 7807 Problem Details standard (see ADR-0007):

{
  "type": "https://api.example.com/errors/resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Machine with MAC address aa:bb:cc:dd:ee:ff not found",
  "instance": "/api/v1/boot/aa:bb:cc:dd:ee:ff/profile",
  "mac_address": "aa:bb:cc:dd:ee:ff"
}

Error responses use Content-Type: application/problem+json.

Standard HTTP Status Codes

200 OK - Successful request
201 Created - Resource created successfully
204 No Content - Successful deletion
400 Bad Request - Invalid request parameters
401 Unauthorized - Missing or invalid authentication
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
409 Conflict - Resource already exists
422 Unprocessable Entity - Validation error
500 Internal Server Error - Server error

Content Types

application/json - JSON responses (admin API)
application/problem+json - RFC 7807 error responses
text/plain - iPXE boot scripts
application/octet-stream - Binary boot assets (kernel, initrd)
text/cloud-config - Cloud-init configuration files