Reorganized for new stable/waypoint versioning design.
This commit is contained in:
692
admin/docs/design.md
Normal file
692
admin/docs/design.md
Normal file
@@ -0,0 +1,692 @@
|
||||
# Wild Directory Versioning and Upgrade System
|
||||
|
||||
Design specification for how Wild Cloud packages its third-party applications,
|
||||
tracks versions, and manages upgrades between versions.
|
||||
|
||||
## Problem
|
||||
|
||||
Wild Cloud packages third-party applications as Kustomize templates. Each
|
||||
application needs:
|
||||
|
||||
1. **Identity** that doesn't change between versions (name, description, icon)
|
||||
2. **Version-specific files** (k8s manifests, config schema, secrets schema)
|
||||
3. **Upgrade routing** when breaking changes prevent direct version jumps
|
||||
4. A clear, low-friction workflow for maintainers bumping versions
|
||||
|
||||
The system must handle both simple apps (any version replaces any other) and
|
||||
complex apps (database migrations, mandatory stepping stones between major
|
||||
versions).
|
||||
|
||||
## Design
|
||||
|
||||
### Two-level structure: `app.yaml` + `versions/`
|
||||
|
||||
Each app in the Wild Directory has a root-level `app.yaml` for identity and a
|
||||
`versions/` directory containing one or more version slots:
|
||||
|
||||
```
|
||||
ghost/
|
||||
+-- app.yaml
|
||||
+-- versions/
|
||||
+-- 5/
|
||||
+-- manifest.yaml
|
||||
+-- kustomization.yaml
|
||||
+-- deployment.yaml
|
||||
+-- ...
|
||||
```
|
||||
|
||||
**`app.yaml`** holds version-independent fields: name, description, icon,
|
||||
category, the `latest` pointer, and upgrade routing rules. These are facts
|
||||
about the app itself, not about any particular release.
|
||||
|
||||
**`versions/{slot}/manifest.yaml`** holds version-specific fields: the precise
|
||||
version string, dependency declarations, default config, default secrets,
|
||||
deploy configuration, and per-version migration jobs. These are facts about a
|
||||
particular release.
|
||||
|
||||
When the API installs an app, it reads both files and merges them. The
|
||||
installed manifest in the instance data directory contains the complete picture
|
||||
(name, description, icon, version, config, etc.).
|
||||
|
||||
### Version slots vs version strings
|
||||
|
||||
A version directory is a **slot**, not a precise version identifier.
|
||||
|
||||
The directory name is a stable label chosen by the maintainer. The actual
|
||||
version string lives in `manifest.yaml` inside the directory. These are
|
||||
intentionally decoupled:
|
||||
|
||||
| Concept | Where it lives | Example |
|
||||
|---------|---------------|---------|
|
||||
| Slot name | Directory name under `versions/` | `5` |
|
||||
| Actual version | `version` field in `manifest.yaml` | `5.118.1-2` |
|
||||
| Latest pointer | `latest` field in `app.yaml` | `5` |
|
||||
| Waypoint pointer | `via` field in upgrade rules | `2` |
|
||||
|
||||
The slot name should be the simplest stable identifier that distinguishes it
|
||||
from other slots. For semver apps, use the major version (`1`, `2`, `3`). For
|
||||
apps with non-semver schemes, use whatever upstream version boundary makes
|
||||
sense (`5`, `v4`, etc.).
|
||||
|
||||
**Packaging revisions** (`-1`, `-2`, etc.) never appear in directory names.
|
||||
They only appear in `manifest.yaml`'s `version` field. A packaging revision
|
||||
is a Wild Cloud-side fix (template improvement, security context change, config
|
||||
restructure) that doesn't change the upstream software.
|
||||
|
||||
**Minor and patch versions** also don't require new directories unless they
|
||||
introduce a breaking change that requires a waypoint. Updating Ghost from
|
||||
5.118.1 to 5.119.0 means editing files inside `versions/5/` and bumping the
|
||||
`version` field. The directory stays the same.
|
||||
|
||||
This follows how established package systems work:
|
||||
|
||||
| System | Directory/file identity | Where version lives |
|
||||
|--------|------------------------|-------------------|
|
||||
| Debian source packages | Package name (stable) | `debian/changelog` |
|
||||
| Helm charts | Chart name directory | `Chart.yaml` |
|
||||
| Homebrew | Formula file per package | Version attribute in file |
|
||||
| Nix packages | Package name directory | Derivation attribute |
|
||||
| FreeBSD ports | Port name directory | `Makefile` variable |
|
||||
| **Wild Cloud** | **Slot directory** | **`manifest.yaml`** |
|
||||
|
||||
Wild Directory is a source package collection (templates compiled at install
|
||||
time), not an artifact repository (pre-built binaries stored per version). The
|
||||
source package pattern is the right fit.
|
||||
|
||||
### When directories are created and destroyed
|
||||
|
||||
**Most apps have exactly one version directory.** This is the common case for
|
||||
apps where any version can replace any other (Ghost, Redis, most stateless
|
||||
services).
|
||||
|
||||
**A second directory appears only when a waypoint is needed** -- when a
|
||||
breaking change means some installed versions can't jump directly to the
|
||||
latest and must pass through an intermediate version first.
|
||||
|
||||
**A directory is removed when it's no longer needed as a waypoint.** If
|
||||
version `2/` was a waypoint for upgrading from 1.x to 3.x, but you later
|
||||
decide to drop support for 1.x entirely, you can remove `2/` and update the
|
||||
routing rules to block `<2.0.0`.
|
||||
|
||||
### `app.yaml` specification
|
||||
|
||||
```yaml
|
||||
# Required
|
||||
name: ghost # Must match directory name
|
||||
is: ghost # Unique type id, used for `requires` matching
|
||||
description: "Ghost is a..." # Shown in app listings
|
||||
latest: "5" # Slot name pointing to a directory in versions/
|
||||
|
||||
# Optional
|
||||
icon: "https://..." # URL to app icon
|
||||
category: infrastructure # Category for filtering
|
||||
|
||||
# Optional -- only needed for apps with breaking upgrade paths
|
||||
upgrade:
|
||||
from:
|
||||
- version: ">=3.0.0" # Constraint against installed version
|
||||
- version: ">=2.0.0"
|
||||
via: "2" # Slot name of waypoint directory
|
||||
- version: "<2.0.0"
|
||||
blocked: true
|
||||
notes: "Upgrade to 2.x first"
|
||||
preUpgrade:
|
||||
backup: recommended # "none", "recommended", or "required"
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | yes | App identifier, must match directory name |
|
||||
| `is` | string | yes | Type id for dependency matching |
|
||||
| `description` | string | yes | Human-readable description |
|
||||
| `latest` | string | yes | Slot name -- directory name under `versions/` |
|
||||
| `icon` | string | no | URL to icon image |
|
||||
| `category` | string | no | Grouping category (e.g. `infrastructure`) |
|
||||
| `upgrade` | object | no | Routing rules for version upgrades |
|
||||
| `upgrade.from` | list | no | Ordered list of version constraint rules |
|
||||
| `upgrade.from[].version` | string | yes | Version constraint: `>=`, `>`, `<=`, `<`, `=`, or `>0` |
|
||||
| `upgrade.from[].via` | string | no | Slot name of waypoint to pass through |
|
||||
| `upgrade.from[].blocked` | bool | no | If true, upgrade is blocked |
|
||||
| `upgrade.from[].notes` | string | no | Human-readable message |
|
||||
| `upgrade.preUpgrade` | object | no | Pre-upgrade requirements |
|
||||
| `upgrade.preUpgrade.backup` | string | no | `"none"`, `"recommended"`, or `"required"` |
|
||||
|
||||
**`latest` is a slot name, not a version string.** It tells the API which
|
||||
directory to look in. The actual version is read from the manifest inside that
|
||||
directory.
|
||||
|
||||
**`via` is also a slot name.** It tells the upgrade planner which waypoint
|
||||
directory to route through.
|
||||
|
||||
### Version `manifest.yaml` specification
|
||||
|
||||
```yaml
|
||||
# Required
|
||||
version: 5.118.1-2
|
||||
|
||||
# Optional
|
||||
requires:
|
||||
- name: pg
|
||||
alias: db
|
||||
- name: redis
|
||||
defaultConfig:
|
||||
namespace: ghost
|
||||
domain: ghost.{{ .cloud.domain }}
|
||||
# ...
|
||||
defaultSecrets:
|
||||
- key: password
|
||||
- key: dbUrl
|
||||
default: "postgresql://..."
|
||||
requiredSecrets:
|
||||
- db.password
|
||||
deploy:
|
||||
# ...
|
||||
scripts:
|
||||
# ...
|
||||
|
||||
# Optional -- only when this version has step-specific upgrade behavior
|
||||
upgrade:
|
||||
migrations:
|
||||
pre:
|
||||
- migrations/pre-deploy.yaml
|
||||
post:
|
||||
- migrations/post-deploy.yaml
|
||||
configMigrations:
|
||||
oldKey: new.key
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `version` | string | yes | Precise version string (e.g. `5.118.1-2`) |
|
||||
| `requires` | list | no | Dependencies with optional aliases |
|
||||
| `defaultConfig` | map | yes | Configuration schema merged into instance config |
|
||||
| `defaultSecrets` | list | no | App's own secrets |
|
||||
| `requiredSecrets` | list | no | Secrets needed from dependencies |
|
||||
| `deploy` | object | no | Deployment behavior (CRDs, phases, etc.) |
|
||||
| `scripts` | list | no | Operational scripts |
|
||||
| `upgrade.migrations.pre` | list | no | K8s Job YAMLs to run before deploying this version |
|
||||
| `upgrade.migrations.post` | list | no | K8s Job YAMLs to run after deploying this version |
|
||||
| `upgrade.configMigrations` | map | no | Old config key -> new config key renames |
|
||||
|
||||
**Note the field split:** Identity and routing live in `app.yaml`. Installation
|
||||
details live here. The version manifest never contains `name`, `is`,
|
||||
`description`, `icon`, `category`, or `upgrade.from` routing rules.
|
||||
|
||||
### Versioning convention
|
||||
|
||||
Wild Cloud uses a two-part version scheme: `<upstream>-<revision>`.
|
||||
|
||||
- **Upstream** tracks the third-party software version: `5.118.1`, `v4.0.18`,
|
||||
`1.135.3`
|
||||
- **Revision** tracks Wild Cloud packaging changes: `-1`, `-2`, etc.
|
||||
|
||||
A version without a revision suffix (e.g., `5.118.1`) is the initial
|
||||
packaging. Revision `-1` is the first packaging fix that doesn't change
|
||||
upstream software.
|
||||
|
||||
This is the same convention Debian uses for its source packages.
|
||||
|
||||
## Upgrade system
|
||||
|
||||
### The 90% case: no routing rules needed
|
||||
|
||||
Most apps can upgrade from any version to any other directly. The app has no
|
||||
`upgrade` block in `app.yaml`. When the API detects a version mismatch between
|
||||
installed and latest, it produces a single-step plan: install the latest
|
||||
version over the current one.
|
||||
|
||||
### The 10% case: routing rules in `app.yaml`
|
||||
|
||||
Apps with breaking changes between versions need routing rules. These live in
|
||||
`app.yaml`, centralized for all versions. The rules are evaluated iteratively:
|
||||
|
||||
1. Compare installed version against `upgrade.from` rules (first match wins)
|
||||
2. If the matching rule has `via`, step to that waypoint
|
||||
3. Re-evaluate the same rules with the waypoint's version as the new
|
||||
"installed" version
|
||||
4. Repeat until reaching latest or hitting a block
|
||||
|
||||
This is iterative re-evaluation, not recursive descent into waypoint
|
||||
manifests. The routing logic lives in one place (`app.yaml`), not scattered
|
||||
across version manifests.
|
||||
|
||||
### Rule evaluation
|
||||
|
||||
Rules are evaluated in order. First match wins. This means more-specific
|
||||
rules must come before less-specific ones:
|
||||
|
||||
```yaml
|
||||
upgrade:
|
||||
from:
|
||||
- version: ">=3.0.0" # Already past the breaking change, direct
|
||||
- version: ">=2.0.0"
|
||||
via: "2" # Must step through 2.x waypoint first
|
||||
- version: "<2.0.0"
|
||||
blocked: true # Too old, no supported path
|
||||
```
|
||||
|
||||
An installed version of `2.5.0` matches `>=2.0.0`, steps to waypoint `2/`
|
||||
(which contains, say, version `2.8.0`). Re-evaluation with `2.8.0` matches
|
||||
`>=2.0.0` again... but this time the waypoint IS the current version, so the
|
||||
visited-set check catches the cycle.
|
||||
|
||||
To avoid this, ensure a rule exists that matches post-waypoint versions
|
||||
and routes them directly:
|
||||
|
||||
```yaml
|
||||
upgrade:
|
||||
from:
|
||||
- version: ">=2.5.0" # Post-waypoint versions go direct
|
||||
- version: ">=2.0.0"
|
||||
via: "2" # Pre-waypoint versions step through
|
||||
- version: "<2.0.0"
|
||||
blocked: true
|
||||
```
|
||||
|
||||
After stepping to waypoint `2/` (version `2.8.0`), re-evaluation matches
|
||||
`>=2.5.0` (no `via`), which means direct upgrade to latest.
|
||||
|
||||
### Version constraints
|
||||
|
||||
Supported operators: `>=`, `>`, `<=`, `<`, `=`, and the special `>0` (matches
|
||||
any version). Constraints compare major.minor.patch numerically. The packaging
|
||||
revision is ignored in constraint matching so `>=5.118.0` matches `5.118.1-2`.
|
||||
|
||||
### Waypoints
|
||||
|
||||
A waypoint is a version slot that exists solely as a stepping stone in an
|
||||
upgrade path. It contains a complete app package (manifest, kustomize, k8s
|
||||
resources) that can be installed and run.
|
||||
|
||||
Waypoints are created when an upstream app has breaking changes that require
|
||||
sequential upgrades. For example, Discourse requires stepping through each
|
||||
major version. A database schema migration might require running version N
|
||||
before jumping to version N+2.
|
||||
|
||||
Waypoint directories are referenced by slot name in `via` fields:
|
||||
|
||||
```yaml
|
||||
# app.yaml
|
||||
latest: "3"
|
||||
upgrade:
|
||||
from:
|
||||
- version: ">=2.5.0"
|
||||
- version: ">=2.0.0"
|
||||
via: "2"
|
||||
```
|
||||
|
||||
```
|
||||
myapp/
|
||||
+-- app.yaml
|
||||
+-- versions/
|
||||
+-- 3/ # Latest (version: 3.0.0)
|
||||
+-- 2/ # Waypoint (version: 2.8.0)
|
||||
```
|
||||
|
||||
### Per-version migrations
|
||||
|
||||
Migration jobs (database schema changes, data transformations) are version-
|
||||
specific, not app-level. They live in the version's directory and are
|
||||
referenced from that version's `manifest.yaml`:
|
||||
|
||||
```yaml
|
||||
# versions/3/manifest.yaml
|
||||
version: 3.0.0
|
||||
upgrade:
|
||||
migrations:
|
||||
pre:
|
||||
- migrations/pre-deploy.yaml
|
||||
post:
|
||||
- migrations/post-deploy.yaml
|
||||
```
|
||||
|
||||
```
|
||||
versions/3/
|
||||
+-- manifest.yaml
|
||||
+-- migrations/
|
||||
| +-- pre-deploy.yaml # K8s Job: runs before deploying 3.0.0
|
||||
| +-- post-deploy.yaml # K8s Job: runs after deploying 3.0.0
|
||||
+-- kustomization.yaml
|
||||
+-- deployment.yaml
|
||||
+-- ...
|
||||
```
|
||||
|
||||
Migration jobs must be idempotent (safe to re-run on retry). Use
|
||||
`CREATE IF NOT EXISTS`, `ALTER TABLE IF NOT EXISTS`, etc.
|
||||
|
||||
**Pre-migrations** run before deploying the new version's manifests. Use for
|
||||
schema changes the new code depends on.
|
||||
|
||||
**Post-migrations** run after deploying. Use for data backfills or cleanup
|
||||
the old code didn't need.
|
||||
|
||||
### Config migrations
|
||||
|
||||
When a version renames config keys, `configMigrations` in the version manifest
|
||||
tells the system to rename them automatically in the instance's `config.yaml`
|
||||
before recompiling templates:
|
||||
|
||||
```yaml
|
||||
# versions/2/manifest.yaml
|
||||
version: 2.0.0
|
||||
upgrade:
|
||||
configMigrations:
|
||||
dbHost: db.host
|
||||
dbPort: db.port
|
||||
```
|
||||
|
||||
## API path resolution
|
||||
|
||||
The API resolves app paths through `resolveAppDir()`:
|
||||
|
||||
1. Read `app.yaml` from the app root
|
||||
2. Use `latest` (or a specific requested slot) to find `versions/{slot}/`
|
||||
3. Verify `manifest.yaml` exists in that directory
|
||||
4. Return the directory path and parsed `AppMeta`
|
||||
|
||||
For old-style apps (no `app.yaml`, `manifest.yaml` at root), the function
|
||||
falls back to the legacy path. This provides backward compatibility during
|
||||
migration.
|
||||
|
||||
When installing, `applyMeta()` merges identity fields from `app.yaml` onto
|
||||
the version manifest:
|
||||
|
||||
```
|
||||
app.yaml + versions/5/manifest.yaml = installed manifest.yaml
|
||||
(name, is, desc, (version, requires, (complete picture)
|
||||
icon, category) defaultConfig, ...)
|
||||
```
|
||||
|
||||
The installed manifest in the instance data directory always contains all
|
||||
fields because the instance needs the complete picture -- it doesn't have
|
||||
access to the Wild Directory's `app.yaml` at runtime.
|
||||
|
||||
## Drift detection
|
||||
|
||||
The API detects when an installed app's version differs from the Wild
|
||||
Directory's latest. For new-style apps:
|
||||
|
||||
1. Read `app.yaml` to get the `latest` slot name
|
||||
2. Read `versions/{latest}/manifest.yaml` to get the actual version string
|
||||
3. Compare against the installed manifest's version
|
||||
|
||||
If they differ, the app is marked as having source drift with the available
|
||||
version noted. The upgrade planner then computes whether an upgrade path
|
||||
exists and how many steps it requires.
|
||||
|
||||
## Maintainer workflows
|
||||
|
||||
### Simple version bump
|
||||
|
||||
The app upstream releases a new version with no breaking changes. Edit files
|
||||
in-place:
|
||||
|
||||
```bash
|
||||
# 1. Update files inside the existing slot
|
||||
vi wild-directory/ghost/versions/5/manifest.yaml # bump version: 5.119.0
|
||||
vi wild-directory/ghost/versions/5/deployment.yaml # update image tag
|
||||
|
||||
# 2. app.yaml doesn't change -- latest still points to "5"
|
||||
|
||||
# 3. Test
|
||||
wild app add ghost && wild app deploy ghost
|
||||
```
|
||||
|
||||
No directory created, renamed, or deleted. No `app.yaml` change.
|
||||
|
||||
### Packaging fix
|
||||
|
||||
A Wild Cloud template fix, no upstream change:
|
||||
|
||||
```bash
|
||||
# 1. Bump packaging revision in manifest
|
||||
vi wild-directory/ghost/versions/5/manifest.yaml # version: 5.118.1-3
|
||||
|
||||
# 2. Fix whatever needs fixing
|
||||
vi wild-directory/ghost/versions/5/deployment.yaml
|
||||
|
||||
# 3. app.yaml doesn't change
|
||||
```
|
||||
|
||||
### Breaking upstream version (new waypoint)
|
||||
|
||||
The app upstream releases a major version with schema changes:
|
||||
|
||||
```bash
|
||||
# 1. Current slot becomes a waypoint -- leave it in place
|
||||
# versions/2/ stays, containing version 2.8.0
|
||||
|
||||
# 2. Create the new slot
|
||||
mkdir -p wild-directory/myapp/versions/3
|
||||
# ... add manifest.yaml, kustomization.yaml, *.yaml for 3.0.0 ...
|
||||
|
||||
# 3. Update app.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# app.yaml
|
||||
name: myapp
|
||||
latest: "3"
|
||||
upgrade:
|
||||
from:
|
||||
- version: ">=2.5.0" # Post-waypoint, direct
|
||||
- version: ">=2.0.0"
|
||||
via: "2" # Step through waypoint
|
||||
- version: "<2.0.0"
|
||||
blocked: true
|
||||
```
|
||||
|
||||
### Adding a new app
|
||||
|
||||
```bash
|
||||
mkdir -p wild-directory/newapp/versions/1
|
||||
|
||||
# Create app.yaml
|
||||
cat > wild-directory/newapp/app.yaml <<EOF
|
||||
name: newapp
|
||||
is: newapp
|
||||
description: My new application
|
||||
latest: "1"
|
||||
EOF
|
||||
|
||||
# Create version manifest + k8s resources in versions/1/
|
||||
# ... manifest.yaml, kustomization.yaml, deployment.yaml, etc.
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Ghost (simple app, one slot)
|
||||
|
||||
```
|
||||
ghost/
|
||||
+-- app.yaml
|
||||
| name: ghost
|
||||
| is: ghost
|
||||
| description: Ghost is a powerful app for...
|
||||
| icon: https://...
|
||||
| latest: "5"
|
||||
+-- versions/
|
||||
+-- 5/
|
||||
+-- manifest.yaml # version: 5.118.1-2
|
||||
+-- kustomization.yaml
|
||||
+-- deployment.yaml
|
||||
+-- service.yaml
|
||||
+-- ingress.yaml
|
||||
+-- namespace.yaml
|
||||
+-- pvc.yaml
|
||||
+-- db-init-job.yaml
|
||||
```
|
||||
|
||||
Upgrading from 5.100.0 to 5.118.1-2: single step, no routing rules needed.
|
||||
|
||||
### e2e-test-app (two slots, waypoint)
|
||||
|
||||
```
|
||||
e2e-test-app/
|
||||
+-- app.yaml
|
||||
| name: e2e-test-app
|
||||
| is: e2e-test-app
|
||||
| description: End-to-end test application...
|
||||
| latest: "2"
|
||||
| upgrade:
|
||||
| from:
|
||||
| - version: ">=1.0.0"
|
||||
| via: "1"
|
||||
| - version: "<1.0.0"
|
||||
| blocked: true
|
||||
| notes: "Versions before 1.0.0 are not supported"
|
||||
| preUpgrade:
|
||||
| backup: recommended
|
||||
+-- versions/
|
||||
+-- 2/
|
||||
| +-- manifest.yaml # version: 2.0.0
|
||||
| +-- kustomization.yaml
|
||||
| +-- ...
|
||||
+-- 1/
|
||||
+-- manifest.yaml # version: 1.0.0-1
|
||||
+-- kustomization.yaml
|
||||
+-- ...
|
||||
```
|
||||
|
||||
Upgrading from 0.5.0: blocked ("Versions before 1.0.0 are not supported").
|
||||
Upgrading from 1.2.0: two steps -- 1.2.0 -> 1.0.0-1 (waypoint) -> 2.0.0.
|
||||
|
||||
### SMTP (infrastructure service, one slot)
|
||||
|
||||
```
|
||||
smtp/
|
||||
+-- app.yaml
|
||||
| name: smtp
|
||||
| is: smtp
|
||||
| description: SMTP relay service...
|
||||
| category: infrastructure
|
||||
| latest: "1"
|
||||
+-- versions/
|
||||
+-- 1/
|
||||
+-- manifest.yaml # version: 1.0.0
|
||||
```
|
||||
|
||||
### Complex app with migrations
|
||||
|
||||
```
|
||||
discourse/
|
||||
+-- app.yaml
|
||||
| name: discourse
|
||||
| is: discourse
|
||||
| description: Discourse forum...
|
||||
| latest: "3"
|
||||
| upgrade:
|
||||
| from:
|
||||
| - version: ">=2.5.0"
|
||||
| - version: ">=2.0.0"
|
||||
| via: "2"
|
||||
| - version: "<2.0.0"
|
||||
| blocked: true
|
||||
| notes: "See upstream migration guide"
|
||||
| preUpgrade:
|
||||
| backup: required
|
||||
+-- versions/
|
||||
+-- 3/
|
||||
| +-- manifest.yaml # version: 3.6.0
|
||||
| +-- migrations/
|
||||
| | +-- pre-deploy.yaml
|
||||
| +-- kustomization.yaml
|
||||
| +-- ...
|
||||
+-- 2/
|
||||
+-- manifest.yaml # version: 2.8.0
|
||||
+-- kustomization.yaml
|
||||
+-- ...
|
||||
```
|
||||
|
||||
## Implementation notes
|
||||
|
||||
### Go types
|
||||
|
||||
```go
|
||||
// app.yaml
|
||||
type AppMeta struct {
|
||||
Name string `yaml:"name"`
|
||||
Is string `yaml:"is,omitempty"`
|
||||
Description string `yaml:"description"`
|
||||
Icon string `yaml:"icon,omitempty"`
|
||||
Category string `yaml:"category,omitempty"`
|
||||
Latest string `yaml:"latest"` // slot name
|
||||
Upgrade *UpgradeConfig `yaml:"upgrade,omitempty"`
|
||||
}
|
||||
|
||||
// version manifest.yaml (version-specific fields only)
|
||||
type AppManifest struct {
|
||||
Version string `yaml:"version"` // precise version string
|
||||
Requires []AppDependency `yaml:"requires,omitempty"`
|
||||
DefaultConfig map[string]interface{} `yaml:"defaultConfig,omitempty"`
|
||||
DefaultSecrets []SecretDefinition `yaml:"defaultSecrets,omitempty"`
|
||||
RequiredSecrets []string `yaml:"requiredSecrets,omitempty"`
|
||||
Deploy *DeployConfig `yaml:"deploy,omitempty"`
|
||||
Scripts []Script `yaml:"scripts,omitempty"`
|
||||
Upgrade *UpgradeConfig `yaml:"upgrade,omitempty"` // migrations only
|
||||
// Identity fields (Name, Is, Description, etc.) populated by applyMeta()
|
||||
}
|
||||
```
|
||||
|
||||
### Backward compatibility
|
||||
|
||||
The API supports both new-style (`app.yaml` + `versions/`) and old-style
|
||||
(`manifest.yaml` at root, `.versions/` for waypoints). `resolveAppDir()`
|
||||
checks for `app.yaml` first and falls back to the old layout.
|
||||
`ComputeUpgradePlan()` similarly checks for `app.yaml` before falling back
|
||||
to recursive manifest-based routing.
|
||||
|
||||
Old-style support exists for migration purposes. New apps should always use
|
||||
the new-style layout.
|
||||
|
||||
### Source URI in installed manifests
|
||||
|
||||
The `source` field in installed manifests points to the app root
|
||||
(`file:///wild-directory/ghost`), not the version directory. `Fetch()` and
|
||||
`Update()` resolve through `resolveAppDir()` from the root, which reads
|
||||
`app.yaml` to find the current latest slot.
|
||||
|
||||
## Design rationale
|
||||
|
||||
### Why decouple directory name from version string?
|
||||
|
||||
Coupling them creates unnecessary churn. Every packaging fix requires creating
|
||||
a new directory and deleting the old one (`5.118.1/` -> `5.118.1-1/`). Every
|
||||
minor upstream release does the same. This churn has no benefit -- the files
|
||||
inside are what matter, not the directory name.
|
||||
|
||||
Decoupling follows the source package pattern used by every major package
|
||||
system. The directory is a stable container. The version is metadata inside it.
|
||||
|
||||
### Why centralize routing rules in `app.yaml`?
|
||||
|
||||
Scattering `upgrade.from` rules across version manifests means each waypoint
|
||||
must know how to route TO itself. Adding a new waypoint requires editing
|
||||
multiple manifests. Reading the upgrade path requires opening every version
|
||||
manifest in the chain.
|
||||
|
||||
Centralizing in `app.yaml` means one file describes the complete routing
|
||||
topology. The upgrade planner reads one file and iteratively applies rules.
|
||||
Adding a new waypoint means editing one file.
|
||||
|
||||
### Why iterative re-evaluation instead of recursive descent?
|
||||
|
||||
Recursive descent reads the target manifest, finds a `via`, recurses into the
|
||||
waypoint, which has its own `via`, and so on. This scatters routing logic
|
||||
across files and makes the path hard to reason about.
|
||||
|
||||
Iterative re-evaluation reads `app.yaml` once, applies rules, steps to a
|
||||
waypoint, then applies the SAME rules again with the new version. The routing
|
||||
table is evaluated like firewall rules -- same table, different input. This
|
||||
is simpler to implement, debug, and maintain.
|
||||
|
||||
### Why not use a flat file for all versions?
|
||||
|
||||
A single YAML file listing all versions and their configs would centralize
|
||||
everything but would grow unwieldy for apps with many k8s resource files.
|
||||
Each version slot needs its own `kustomization.yaml`, deployment specs,
|
||||
service definitions, etc. Directories are the natural unit.
|
||||
Reference in New Issue
Block a user