5.6 KiB
Feature Specification: VPS Image Migration
Feature Branch: 003-vps-image-migration
Created: February 3, 2026
Status: Draft
Input: User description: "Remove deprecated image generator usage, add a new vps host that builds a Linode image, ensure first-boot secrets are available, and support remote rebuilds for ongoing changes."
Clarifications
Session 2026-02-03
- Q: Who is allowed to trigger remote rebuilds? → A: Only explicitly authorized operator machines.
User Scenarios & Testing (mandatory)
User Story 1 - Provision a VPS Image (Priority: P1)
As an operator, I want to build a Linode-compatible image for the new vps host so I can provision a replacement VPS that boots with network connectivity and remote access.
Why this priority: This is the core migration outcome; without a working image, the VPS replacement cannot proceed.
Independent Test: Can be fully tested by building the image, launching a Linode instance from it, and confirming network and remote access.
Acceptance Scenarios:
- Given a clean repository state, When I build the vps image, Then the build completes and produces a Linode-compatible image artifact.
- Given a Linode instance created from the vps image, When it boots, Then it has working network connectivity and remote access is available.
User Story 2 - Secrets Available After Enrollment (Priority: P2)
As an operator, I want the vps to generate its own secrets key on first boot and then make required secrets available after enrollment so core services can start securely.
Why this priority: The VPS must remain secure; services should start only after the host is enrolled and secrets are re-encrypted for it.
Independent Test: Can be fully tested by provisioning from the image, enrolling the host key, and verifying required secrets become available after the follow-up deployment.
Acceptance Scenarios:
- Given a freshly provisioned vps instance, When the system completes its first boot, Then it generates host-specific bootstrap key material and remains reachable for enrollment.
- Given the host key is enrolled and secrets are re-encrypted, When a follow-up deployment runs, Then required secrets become available to services.
User Story 3 - Remote Rebuild Workflow (Priority: P3)
As an operator, I want to trigger rebuilds of the vps host from any authorized system so updates (such as firewall changes) can be applied consistently.
Why this priority: Ongoing updates are essential for operations and security, and should not depend on a single workstation.
Independent Test: Can be fully tested by triggering a rebuild from a separate authorized system and verifying the changes apply on the VPS.
Acceptance Scenarios:
- Given an explicitly authorized operator machine, When a rebuild is triggered, Then the vps host updates successfully and reflects the new configuration.
Edge Cases
- What happens when the vps image build completes but the artifact is not compatible with the target environment?
- How does the system handle first-boot secret access when bootstrap material is missing or corrupted?
- What happens when a remote rebuild is triggered but the VPS is unreachable?
Requirements (mandatory)
Functional Requirements
- FR-001: The system MUST stop using any deprecated image-generation dependency currently used for host images.
- FR-002: The system MUST define a new vps host configuration that produces a Linode-compatible image artifact.
- FR-003: A VPS provisioned from the image MUST boot with working network connectivity and remote access enabled.
- FR-004: The system MUST support a secure, two-phase bootstrap where the host generates key material on first boot and secrets become available after enrollment and re-deploy.
- FR-005: The system MUST provide a documented, repeatable way for explicitly authorized operator machines to trigger remote rebuilds of the vps host.
- FR-006: Existing hosts and images MUST continue to build and operate without regression after the migration.
Key Entities (include if feature involves data)
- Host Profile: A named system configuration (e.g., vps) that defines the target environment behavior.
- Image Artifact: A deployable disk image produced from the host profile.
- Bootstrap Secret Material: Data required to unlock or access secrets on first boot.
- Deployment Target: The infrastructure environment where the image is launched.
- Rebuild Trigger: An authorized action that initiates a configuration update on the VPS.
Assumptions
- The vps host can generate bootstrap key material on first boot and is reachable for enrollment.
- Operators already have a secure, authorized path for remote access to the VPS.
- The Linode environment can accept and boot the produced image artifact.
Dependencies
- Access to the target environment needed to validate image compatibility and boot behavior.
- Existing secrets management process and data required for the vps host.
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: A Linode instance provisioned from the vps image is reachable via remote access within 10 minutes of first boot in at least 95% of test provisions.
- SC-002: Required secrets for core services are available after enrollment and follow-up deployment in 100% of test provisions.
- SC-003: Existing host builds complete without new failures after the deprecated dependency is removed.
- SC-004: Remote rebuilds apply a configuration change to the vps host within 15 minutes in at least 90% of test runs.