coulomb/rail-kubernetes
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rail-kubernetes/docs/create-overlay-command.md
codex 004f1c4dc1 Enforce private-by-default rail exposure 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a02669-87ee-7a31-b111-edc95a16e0fa
2026-08-22 12:34:25 +02:00

1.6 KiB
Raw Blame History

Create Overlay Command

bin/railiance create-overlay scaffolds a local Railiance overlay repo for a third-party upstream application.

The command is intentionally local and conservative:

  • records the upstream source in railiance/upstream.toml;
  • generates a stage-aware railiance/app.toml;
  • creates a starter Helm chart, stage values, tests, and runbooks;
  • initializes only local files and directories;
  • does not clone upstream code, create remotes, fetch secrets, or push anything.

Usage

bin/railiance create-overlay \
  --app-id forgejo \
  --upstream-url https://codeberg.org/forgejo/forgejo \
  --name Forgejo \
  --owner platform \
  --criticality high \
  --init-git

The generated Service is explicitly ClusterIP, a default-deny ingress NetworkPolicy is included, and Stage 2 does not emit an Ingress. Enabling an Ingress later requires matching rapp and reef declaration files at the Stage 2 deploy gate; an Ingress object is not itself an ADR-0008 grant.

Required arguments:

  • --app-id
  • --upstream-url

Useful optional arguments:

  • --name
  • --owner
  • --criticality
  • --upstream-revision
  • --upstream-tracking
  • --out-dir
  • --init-git

Generated Structure

The scaffold creates:

  • README.md
  • railiance/upstream.toml
  • railiance/app.toml
  • charts/<app-id>/templates/
  • values/
  • patches/upstream/
  • tests/
  • runbooks/
  • docs/

The output is a compatibility-era overlay starting point on the path toward future rapp-* packaging. It keeps the current migration window usable without moving workload ownership into rail-kubernetes.