# 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**: 1. **Given** a clean repository state, **When** I build the vps image, **Then** the build completes and produces a Linode-compatible image artifact. 2. **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**: 1. **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. 2. **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**: 1. **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.