104 lines
5.6 KiB
Markdown
104 lines
5.6 KiB
Markdown
# 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.
|