mariano/soleprint
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

big update based on real wokr

Browse Source
This commit is contained in:
buenosairesam
2026-09-23 18:52:57 -03:00
parent 45018e4743
commit 8fad2223f3
23 changed files with 652 additions and 670 deletions
Download Patch File Download Diff File Expand all files Collapse all files

352
rig/docs/index.html
View File

@@ -2,6 +2,7 @@
<html lang="en">
<head>
<meta charset="utf-8">
<link rel="icon" href="data:,">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>rig — local environment installer</title>
<style>
@@ -237,13 +238,9 @@
<div class="nav-backdrop"></div>
<nav>
<a href="#start">Start here</a>
<a href="#steps">The steps</a>
<a href="#install">Installation</a>
<a href="#environments">Environments</a>
<a href="#overlays">Overlays</a>
<a href="#profiles">Profiles</a>
<a href="#registry">Registry</a>
<a href="#architecture">Architecture</a>
<a href="#troubleshooting">Troubleshooting</a>
</nav>
@@ -251,114 +248,68 @@
<section class="section" id="start">
<h2>Start here</h2>
<p class="lede">A runnable local model of a large, regulated estate — legacy and new side by side.</p>
<div class="prose">
<p>rig builds a disposable Kubernetes environment on your machine so you can
explore how a system fits together without needing access to any of it. Its
job is <b>onboarding and exploration</b>, not a production replica.</p>
<p>rig builds a disposable Kubernetes environment on your machine, so you can
see how a system fits together without access to any of it. It is for
<b>onboarding and exploration</b>, not a production replica.</p>
<p>Most services in it are deliberately <b>not real</b>. What has to be faithful
is the topology — the names, the ports, the dependency order, who can reach whom,
and how it fails. The workloads themselves are noise. This is what makes the
whole estate fit on a laptop: a real 20-service platform will not fit even once
on 14&nbsp;GB, but mocks are about 30&nbsp;MB each, so three faithful copies do.</p>
<p>Most services in it are <b>not real</b>. What has to be faithful is the
topology: names, ports, dependency order, who can reach whom, and how it fails.
That is what makes a whole estate fit on a laptop. A real 20-service platform
does not fit once in 14&nbsp;GB; stubs of about 30&nbsp;MB each fit three times.</p>
<h3>The only prerequisite</h3>
<p><b>Docker.</b> No curl, no jq, no python, no apt repositories to configure.</p>
<pre><code><span class="c"># then, in the environment directory:</span>
make check <span class="c"># is this machine ready? reports, never fixes</span>
make deps <span class="c"># install the pinned toolchain</span>
<pre><code><span class="c"># in the environment directory:</span>
make check <span class="c"># is this machine ready? reports, never changes anything</span>
make deps <span class="c"># install the pinned toolchain; safe to re-run</span>
make cluster up <span class="c"># cluster + registry + addons; ports derive by themselves</span>
</code></pre>
<p>Read <code>make check</code> before <code>make deps</code>. It never changes
anything — it prints what it found and, at the end, the steps it cannot perform
for you.</p>
</div>
</section>
<section class="section" id="steps">
<h2>The steps</h2>
<p class="lede">Start to finish, in order, with what each one actually does.</p>
<div class="prose">
<h3>1 &middot; make check</h3>
<p>Asks whether this machine is ready. It <b>changes nothing</b> — it
reports what it found and, at the end, the things only a human can do
(anything needing <code>sudo</code>, or a Windows-side restart). Read it
before installing anything; it is faster than discovering the same problems
one failure at a time.</p>
<pre><code>make check</code></pre>
<h3>2 &middot; make deps</h3>
<p>Installs the pinned toolchain — only what is missing — and tells you
if its directory is not on PATH yet. Running it twice is safe.</p>
<pre><code>make deps</code></pre>
<h3>3 &middot; make cluster up</h3>
<p>Builds the cluster, starts its registry and installs the profile's
addons — there is nothing else to run first. It prints what the profile
locks in <i>before</i> spending the time, because the kind config is
fixed at creation and cannot be changed afterwards.</p>
<p>Re-running is safe and, more importantly, <b>convergent</b>: if a first
attempt was interrupted before the CNI was installed, running it again
finishes the job rather than reporting "already exists" and leaving every
node permanently NotReady.</p>
<pre><code>make cluster up <span class="c"># built-in defaults — no profile needed</span>
make cluster up PROFILE=mirror <span class="c"># after copying env.d/mirror.env.example: cached registry</span>
<p>Read <code>make check</code> before <code>make deps</code>: it lists what is
missing, including the steps only you can do, such as anything needing
<code>sudo</code> or a Windows-side restart.</p>
<h3>make cluster up</h3>
<p>It prints what the kind config locks in before spending the time, because
that config is fixed when the cluster is created. Re-running is safe and
continues where an interrupted run stopped, rather than reporting that the
cluster already exists and leaving every node <code>NotReady</code>.</p>
<pre><code>make cluster up <span class="c"># built-in defaults — no profile needed</span>
make cluster up PROFILE=mirror <span class="c"># images through an internal registry</span>
make cluster up OVERLAY=examples/data <span class="c"># an overlay: what runs, kept outside rig</span>
make cluster reset <span class="c"># destroy and rebuild — how an edited kind config takes effect</span>
make cluster reset <span class="c"># destroy and rebuild: how an edited kind config takes effect</span>
</code></pre>
<h3>4 &middot; make docs</h3>
<p>Serves this page from a throwaway container. Works with no cluster and
no toolchain, which is deliberate: these pages are the instructions for
building everything else, so they cannot depend on it.</p>
<pre><code>make docs</code></pre>
<h3>Checking on things</h3>
<dl>
<dt>make cluster list</dt><dd>Every cluster on the machine, its memory cost and its port block. The usual reason a new one will not start is an old one you forgot about; <code>make cluster free</code> frees them without deleting.</dd>
<dt>make check</dt><dd>Short: host, toolchain, and whether this cluster fits, its ports, registry and addons. Details only appear when something needs attention; <code>make check all</code> prints every one.</dd>
<dt>make check mem</dt><dd>Memory in depth: what caps it, how far it really climbs, and on WSL the <code>.wslconfig</code> backup and restore.</dd>
<dt>make cluster list</dt><dd>Every cluster on the machine, its memory cost and its port block. A new cluster usually fails to start because of an old one; <code>make cluster free</code> stops them without deleting.</dd>
<dt>make check</dt><dd>Host, toolchain, and whether this cluster fits, its ports, registry and addons. Only problems print; <code>make check all</code> prints everything.</dd>
<dt>make check mem</dt><dd>Memory in depth: what caps it, how far it climbs, and on WSL the <code>.wslconfig</code> backup and restore.</dd>
<dt>make docs</dt><dd>Serves these pages from a throwaway container. It needs no cluster and no toolchain, because these are the instructions for building both.</dd>
</dl>
<h3>Running more than one</h3>
<p>Name another overlay, or copy the directory and rename it. Cluster name,
context, image tags and the port block all follow the folder name — the
overlay's, or rig's — so the second environment collides with nothing and
neither one's teardown can reach the other.</p>
<pre><code>OVERLAY=local/platform-v2 make cluster up
cp -r rig ../platform-v3 &amp;&amp; cd ../platform-v3 &amp;&amp; make cluster up
</code></pre>
</div>
</section>
<section class="section" id="install">
<h2>Installation</h2>
<p class="lede">A container installs onto the host and then gets out of the way.</p>
<div class="graph-container">
<a href="viewer.html?src=graphs/01-install.svg"><img src="graphs/01-install.svg" alt="Installation flow"></a>
<a href="viewer.html?src=graphs/01-install.svg"><img src="graphs/01-install.svg" alt="How the installer works"></a>
</div>
<div class="prose">
<p>The installer is a container, not a shell script, for a specific reason: a
stock slim Debian has no <code>curl</code>, no <code>wget</code>, no
<code>jq</code>, no <code>python3</code> and <b>no CA bundle</b>. A shell
installer could not make a verified HTTPS request, let alone check one. The
container carries its own toolchain, so the host needs nothing but Docker.</p>
<p>The cluster never runs inside that container. Everything it installs —
kind, kubectl, tilt, jq — runs natively afterwards, so nothing pays a
container tax during daily work.</p>
<h3>Pinned and verified</h3>
<p>Every tool is a single binary fetched at a pinned version and checked
against a published SHA256. Node images are pinned <b>by digest</b>, so
upgrading kind cannot silently move your Kubernetes version.</p>
<h3>Not every machine should get cluster tooling</h3>
<p>A managed or corporate-issued machine — the kind that holds the access
you cannot get anywhere else — is not somewhere to install development
tools by default. So the toolchain comes in two tiers:</p>
<p>The installer is a container, not a shell script, because a stock slim Debian
has no curl, wget, jq, python3 or CA bundle: a shell installer could not make a
verified HTTPS request, let alone check one. The container carries its own
toolchain, so the host needs only Docker. Nothing runs inside it afterwards —
kind, kubectl, tilt and jq run natively.</p>
<p>Every tool is a single binary at a pinned version, checked against a published
SHA256. Node images are pinned <b>by digest</b>, so upgrading kind cannot move
your Kubernetes version.</p>
<h3>Two tiers</h3>
<p>A managed or corporate-issued machine is not somewhere to install development
tools by default, so installing cluster tooling is a decision rather than a side
effect:</p>
<table>
<tr><th>tier</th><th>installs</th><th>for</th></tr>
<tr><td><code>core</code></td><td>kubectl, jq</td><td>talk to a cluster someone else runs</td></tr>
@@ -367,11 +318,6 @@ cp -r rig ../platform-v3 &amp;&amp; cd ../platform-v3 &amp;&amp; make cluster up
<pre><code>make deps core <span class="c"># kubectl and jq only — nothing that creates a cluster</span>
make deps <span class="c"># dev, the default</span>
</code></pre>
<p>Testing <i>in situ</i> on a managed machine is still possible — install
the <code>dev</code> tier deliberately when you need it. The point is that
it should be a decision rather than a side effect of installing.</p>
<p>The documentation itself needs neither tier: <code>make docs</code>
wants only Docker.</p>
<h3>Air-gapped</h3>
<pre><code>make deps image full <span class="c"># bakes every binary into the image</span>
@@ -384,185 +330,129 @@ docker load &lt; rig.tgz &amp;&amp; make cluster up PROFILE=offline <span clas
<section class="section" id="environments">
<h2>Environments</h2>
<p class="lede">One folder is one environment — an overlay's, or rig's own. Copy it, rename it, run it.</p>
<div class="graph-container">
<a href="viewer.html?src=graphs/02-environment.svg"><img src="graphs/02-environment.svg" alt="Environment derivation"></a>
</div>
<div class="prose">
<p>Running several versions of a system at once means several clusters on one
machine, not several machines. Everything that could collide is derived from
the folder name (the overlay's when one is named):</p>
<p>One folder is one environment. Running several versions of a system at once
means several clusters on one machine, and everything that could collide is
derived from the folder name (the overlay's, when one is named):</p>
<dl>
<dt>cluster + context</dt><dd><code>platform-v2/</code> builds <code>platform-v2</code> on <code>kind-platform-v2</code>.</dd>
<dt>port block</dt><dd>Ten ports from a hash of the name, in the 20000+ range — clear of 80, 443, 3000, 5432, 8000 and 8080.</dd>
<dt>port block</dt><dd>Ten ports from a hash of the name, above 20000 — clear of 80, 443, 3000, 5432, 8000 and 8080.</dd>
<dt>registry + images</dt><dd>Named after the environment, so two copies never share one.</dd>
</dl>
<p>Two copies therefore never collide, and neither one's
<code>make cluster down</code> can touch the other. <code>make check</code>
shows the block; <code>bash ctrl/ports.sh persist</code> freezes it into
<code>ctrl/.env</code> if you want it fixed rather than derived.</p>
<p>So two copies never collide, and neither one's <code>make cluster down</code>
can touch the other. <code>make check</code> shows the block;
<code>bash ctrl/ports.sh persist</code> freezes it into <code>ctrl/.env</code>.</p>
<h3>Configuration layers</h3>
<p>Weakest first, later wins: built-in defaults → pinned versions → a
profile, if you name one → the overlay's <code>rig.env</code> →
<code>ctrl/.env</code> → the environment. So
<code>make cluster up PROFILE=&lt;name&gt;</code> always beats every file.</p>
<p>Weakest first, later wins: built-in defaults → pinned versions → a profile, if
you name one → the overlay's <code>rig.env</code> → <code>ctrl/.env</code> → the
caller's environment. So a value on the command line always beats every file.</p>
<h3>Profiles</h3>
<p>A profile says how this machine reaches the world. rig needs none.</p>
<table>
<tr><th>example</th><th>registry</th><th>for</th></tr>
<tr><td>none</td><td><code>local</code></td><td>the built-in defaults</td></tr>
<tr><td><code>mirror.env.example</code></td><td><code>mirror</code></td><td>images through an internal registry</td></tr>
<tr><td><code>offline.env.example</code></td><td><code>local</code></td><td>air-gapped</td></tr>
</table>
<h3>Registry modes</h3>
<table>
<tr><th>mode</th><th>what it does</th></tr>
<tr><td><code>none</code></td><td>images are built straight into the node</td></tr>
<tr><td><code>local</code></td><td>a registry container wired into the cluster</td></tr>
<tr><td><code>mirror</code></td><td>that container as a pull-through cache of the corporate registry</td></tr>
<tr><td><code>remote</code></td><td>no local container; pull direct with an <code>imagePullSecret</code></td></tr>
</table>
<p><code>mirror</code> is what a locked-down network looks like: images come from
the corporate registry, you do not hammer it, and you keep working when the
connection drops. It is also only reachable from where that registry is routable —
from a laptop, use <code>local</code> or <code>offline</code>.</p>
<p><b>Corporate CA trust is the usual failure.</b> It has to reach three places:
the host Docker daemon, every node's containerd (nodes do not inherit host trust),
and any in-cluster client. Set <code>REGISTRY_CA_FILE</code>;
<code>make check</code> reports which is still missing. Without it the error is
<code>x509: certificate signed by unknown authority</code>.</p>
<h3>LoadBalancer services</h3>
<p>Real manifests use <code>type: LoadBalancer</code>. On a bare local cluster
those Services sit at <code>EXTERNAL-IP &lt;pending&gt;</code> forever, with no
error: the deployment looks healthy and is unreachable. The <code>metallb</code>
addon fixes that, so upstream manifests work unchanged. Its address pool is
derived from the cluster's Docker network at install time, because Docker picks
that subnet and it differs between machines.</p>
<p>Those addresses are reachable from the Linux side, including inside WSL. A
browser on Windows has no route to them: use the ingress host ports instead.</p>
<h3>Networking and memory</h3>
<p>The cluster uses kind's built-in networking, which does enforce standard
NetworkPolicy — verified against a no-policy control. A pluggable CNI was tried
and removed: it added policy features nothing here needs, in exchange for a
slower boot and one more thing to get right at creation time.</p>
<p>Every cluster is a running container tree whether you use it or not.
<code>make cluster list</code> shows what each costs, and
<code>make cluster free</code> stops the others without deleting them.</p>
</div>
</section>
<section class="section" id="overlays">
<h2>Overlays</h2>
<p class="lede">What runs lives outside rig — rig reads it and never writes into it.</p>
<div class="prose">
<p>An overlay is one folder, kept outside rig's version control, holding a
use case. Every piece is optional:</p>
<p>An overlay is one folder, kept outside rig's version control, holding a use
case. rig reads it and never writes into it. Every piece is optional:</p>
<table>
<tr><th>in the overlay</th><th>what rig does with it</th></tr>
<tr><td><code>rig.env</code></td><td>a config layer: addons, namespaces, images — anything a profile could set</td></tr>
<tr><td><code>k8s/overlays/dev/</code></td><td>the manifests the dev loop applies</td></tr>
<tr><td><code>kind-config.yaml.tpl</code></td><td>the cluster's shape, when it needs its own (mounts, ports)</td></tr>
<tr><td><code>addons/&lt;name&gt;.sh</code></td><td>addons, found before rig's own</td></tr>
<tr><td><code>addons/&lt;name&gt;.sh</code></td><td>addons, found before rig's own; each applies its own <code>&lt;name&gt;.yaml</code></td></tr>
<tr><td><code>Tiltfile</code></td><td>the workload's half of the dev loop, included by rig's</td></tr>
</table>
<pre><code>cp -r examples/starter local/myenv <span class="c"># local/ is gitignored</span>
OVERLAY=local/myenv make cluster up
</code></pre>
<p>With none named, rig runs its own <code>examples/starter</code>.
<code>examples/data</code> carries postgres, redis and airflow as an
overlay's own addons. A project can also carry rig at
<code>&lt;project&gt;/rig/</code> and be the overlay itself, with a
three-line forwarding Makefile — see <code>docs/notes/overlay.md</code>.</p>
</div>
</section>
<section class="section" id="profiles">
<h2>Profiles</h2>
<p class="lede">How this machine reaches the world — optional; rig needs none.</p>
<div class="prose">
<table>
<tr><th>example</th><th>registry</th><th>for</th></tr>
<tr><td><i>none</i></td><td>local</td><td>the built-in defaults; no profile needed</td></tr>
<tr><td><code>mirror.env.example</code></td><td>mirror</td><td>images through an internal registry</td></tr>
<tr><td><code>offline.env.example</code></td><td>local</td><td>air-gapped</td></tr>
</table>
<div class="note"><p><b>The kind config cannot be re-applied.</b> Edit
<code>ctrl/k8s/kind-config.yaml.tpl</code> (or the overlay's own); it takes effect when the cluster is created. <code>cluster up</code> prints what it
locks in before spending the time, and <code>make cluster reset</code> is
the way out.</p></div>
<h3>LoadBalancer services</h3>
<p>Real manifests use <code>type: LoadBalancer</code>, because a real
cluster has one. On a bare local cluster those Services sit at
<code>EXTERNAL-IP &lt;pending&gt;</code> forever, with no error anywhere —
the deployment looks healthy and simply is not reachable.</p>
<p>The <code>metallb</code> addon fixes that, so the same manifests work
here as upstream and nothing has to be rewritten to NodePort. Its address
pool is derived from the cluster's Docker network at install time rather
than hardcoded, because Docker picks that subnet and it differs between
machines.</p>
<div class="note"><p><b>Where those addresses are reachable from.</b> The
pool lives on the Docker bridge, so LoadBalancer IPs work from the Linux
side — including from inside WSL. A browser on Windows has no route to
them. Use the ingress host ports for anything you need to open in a
browser.</p></div>
<h3>Networking</h3>
<p>The cluster uses kind's built-in networking, which <b>does</b> enforce
standard NetworkPolicy — verified against a no-policy control, not assumed.
The widely repeated claim that it accepts policies and silently ignores
them is out of date.</p>
<p>A pluggable CNI was tried and removed: it only added
GlobalNetworkPolicy, policy tiers and egress-CIDR rules, none of which are
needed yet, in exchange for a slower boot and one more thing that has to be
right at creation time. Worth revisiting only when a policy the built-in
cannot express actually comes up.</p>
<h3>Memory</h3>
<p>Every cluster is a running container tree whether you are using it or not.
<code>make cluster list</code> shows what exists and what it costs;
<code>make cluster free</code> stops the others without deleting them.</p>
</div>
</section>
<section class="section" id="registry">
<h2>Registry</h2>
<p class="lede">Local, cached, or straight to the corporate registry.</p>
<div class="prose">
<table>
<tr><th>mode</th><th>what it does</th></tr>
<tr><td><code>none</code></td><td>images are built straight into the node</td></tr>
<tr><td><code>local</code></td><td>a registry container wired into the cluster</td></tr>
<tr><td><code>mirror</code></td><td>that container as a <b>pull-through cache</b> of the corporate registry</td></tr>
<tr><td><code>remote</code></td><td>no local container; pull direct with an imagePullSecret</td></tr>
</table>
<p><code>mirror</code> is what a locked-down network actually looks like:
images originate from the corporate registry, you do not hammer it, and you
keep working when the connection drops.</p>
<div class="note"><p><b>The corporate CA will bite you.</b> A corporate
registry is usually behind an internal CA, and trust has to reach
<b>three</b> places: the host Docker daemon, every cluster node's containerd
(nodes do <i>not</i> inherit host trust), and any in-cluster client. Set
<code>REGISTRY_CA_FILE</code> and <code>make check</code> reports which is
still missing. The symptom otherwise is an opaque
<code>x509: certificate signed by unknown authority</code>.</p></div>
<p>Reachability also depends on where you are: if the registry is only
routable from a managed workspace, <code>mirror</code> and <code>remote</code>
will not resolve from a laptop at all. That is what <code>local</code> and
<code>offline</code> are for.</p>
</div>
</section>
<section class="section" id="architecture">
<h2>Architecture</h2>
<p class="lede">The estate being modelled.</p>
<div class="note"><p><b>TODO — placeholder.</b> The diagram below is
illustrative only: it shows how a mocked dependency, a service under active
work, and an unreachable remote system sit together. It is not the real
topology. Replace <code>docs/graphs/03-architecture.dot</code> with the
extracted platform diagrams, then run <code>make docs graphs</code>.</p></div>
<div class="graph-container">
<a href="viewer.html?src=graphs/03-architecture.svg"><img src="graphs/03-architecture.svg" alt="Estate topology (placeholder)"></a>
</div>
<div class="prose">
<p>Each component is one of three things, and switching between them should be
a one-line change rather than a rewrite:</p>
<code>examples/data</code> carries postgres, redis and airflow as an overlay's own
addons. A project can also carry rig at <code>&lt;project&gt;/rig/</code> and be
the overlay itself, with a three-line forwarding Makefile — see
<code>docs/notes/overlay.md</code>.</p>
<h3>What runs in it</h3>
<p>Each component is one of three things, and switching between them is a
one-line change:</p>
<dl>
<dt>real</dt><dd>Built from source and hot-reloaded. The thing you are actually working on — usually exactly one.</dd>
<dt>real</dt><dd>Built from source and hot-reloaded. What you are working on — usually exactly one.</dd>
<dt>mock</dt><dd>A generic stub with canned responses. Everything you do not care about today.</dd>
<dt>remote</dt><dd>No pod at all: a Service of type ExternalName pointing at the real system. In-cluster DNS resolves identically, so callers never change.</dd>
<dt>remote</dt><dd>No pod at all: a Service of type <code>ExternalName</code> pointing at the real system. In-cluster DNS resolves identically, so callers never change.</dd>
</dl>
<p>The intended end state is that this diagram is <b>generated from the
running cluster</b> rather than drawn by hand — so it becomes a report of
what exists instead of a picture of what was once intended.</p>
</div>
</section>
<section class="section" id="troubleshooting">
<h2>Troubleshooting</h2>
<p class="lede">The failures that are hard to diagnose from their symptoms.</p>
<div class="prose">
<h3>Tilt stops noticing file changes</h3>
<p>Almost always <code>inotify</code> limits, and it fails <i>silently</i> —
nothing errors, changes just stop being picked up. Defaults on WSL are far too
low. <code>make check</code> reports it and prints the fix.</p>
<p>Almost always inotify limits, and it fails silently: nothing errors, changes
just stop being picked up. Defaults on WSL are far too low.
<code>make check</code> reports it and prints the fix.</p>
<h3>Cluster creation dies halfway with a port error</h3>
<p>Docker reports <code>failed to bind host port … address already in use</code>
partway through creating the cluster. Run <code>make check</code> first — it
checks every port in this environment's block before anything is built.</p>
partway through creating the cluster. <code>make check</code> tests every port in
this environment's block before anything is built.</p>
<h3>Every node stays NotReady</h3>
<p>Usually a cluster created with the default CNI disabled but the real CNI
never installed — typically an interrupted first run. Just run
<code>make cluster up</code> again: it converges rather than exiting early, and
will finish the missing steps.</p>
<p>Usually a cluster created with the default CNI disabled and the real CNI never
installed, after an interrupted first run. Run <code>make cluster up</code> again:
it finishes the missing steps instead of stopping because the cluster exists.</p>
<h3>x509: certificate signed by unknown authority</h3>
<p>Corporate CA trust has not reached one of the three places it needs to be.
See <a href="#registry">Registry</a>.</p>
<p>Corporate CA trust has not reached one of the three places it needs to be. See
<a href="#environments">Environments</a>.</p>
<h3>kubectl says the context does not exist</h3>
<p>The cluster can exist while its context does not — a reset or a switched