Entrypoint per contenidors distroless amb .NET single-file

2026-03-25T00:00:00+00:00
.NET 10 porta una novetat que em sembla més important del que pot semblar a primera vista: dotnet run app.cs</code> i dotnet publish app.cs</code>. En resum: pots agafar un sol fitxer C#, sense .csproj</code>, i executar-lo o publicar-lo directament.</p>
Quan ho vaig veure, la lectura fàcil era "ah, finalment .NET té un mode script decent". I sí, una mica va per aquí. Microsoft ho va presentar a l'article Announcing dotnet run app.cs</a> i també hi ha algun resum ràpid com aquest de dev.to</a>.</p>
Però aquest post no va d'explicar la feature en abstracte. Va d'un use-case molt concret que em sembla especialment bo: fer servir un .cs</code> solt com a entrypoint compilat amb Native AOT per a contenidors hardened, distroless, rootless i sense shell. L'exemple real surt de vegops/containers</a>, concretament de la imatge de qBittorrent.</p>
El problema: contenidors sense shell</a></h2>
Quan dius "distroless" aquí no parles només de fer una imatge petita.
Parles d'una imatge amb el mínim imprescindible a runtime.
En aquest cas concret, l'entorn va sobre Wolfi/Chainguard, sense busybox</code>, sense sh</code>, sense apt</code>, i sense tota la ferralla habitual que acostuma a venir amb una distribució generalista.</p>
A més a més, el contenidor arrenca com a nonroot</code> amb UID 65532</code>.
Això és exactament el que vols en una imatge hardened: menys superfície, menys privilegis, menys sorpreses.
El problema és que abans d'arrencar el procés principal sovint encara necessites una mica de lògica d'init.</p>
Pot ser copiar una configuració per defecte, o injectar un secret via variable d'entorn, o bé, substituir el procés correctament perquè el teu servei quedi com a PID 1 i rebi senyals directament.
Amb shell això és trivial.
Sense shell, has de buscar un altre mètode.
Les opcions típiques són un binari petit en Go</code>, Rust</code>, tini</code>, o ara també un fitxer C# compilat amb Native AOT.</p>

En un contenidor sense shell, el problema no és "com executo una comanda".
El problema real és "on poso la lògica d'entrada sense reintroduir dependències i complexitat".</p>
</blockquote>
La solució: un entrypoint.cs</code> amb Native AOT</a></h2>
L'exemple de qBittorrent ho resolc amb un únic fitxer: entrypoint.cs</code>.
No hi ha projecte, ni dependències externes, ni tan sols runtime .NET dins la imatge final.
Durant el build es compila amb Native AOT i el resultat és un binari autocontingut que acaba a /usr/bin/entrypoint</code>.</p>
La part interessant és que el mateix fitxer porta directives #:property</code> per controlar la compilació.
Aquí és on defineixes que vols PublishAot=true</code>, que vols treure símbols, optimitzar per mida, retallar metadades i desactivar coses que no calen com el suport de stack traces.</p>
El programa fa tres coses i prou: garantir que hi ha configuració, rotar la password per defecte si encara hi és, i fer un execv()</code> sobre el binari real de qBittorrent.
Res més.
Just el tipus d'entrypoint petit, específic i visible que vols en un contenidor distroless.</p>
Aquest és l'entrypoint sencer:</p>
#</span>:</span>property</span> PublishAot</span>=</span>true</span></span>
#</span>:</span>property</span> InvariantGlobalization</span>=</span>true</span></span>
#</span>:</span>property</span> StripSymbols</span>=</span>true</span></span>
#</span>:</span>property</span> OptimizationPreference</span>=</span>Size</span></span>
#</span>:</span>property</span> IlcOptimizationPreference</span>=</span>Size</span></span>
#</span>:</span>property</span> StackTraceSupport</span>=</span>false</span></span>
#</span>:</span>property</span> UseSystemResourceKeys</span>=</span>true</span></span>
#</span>:</span>property</span> IlcTrimMetadata</span>=</span>true</span></span>
#</span>:</span>property</span> AssemblyName</span>=</span>entrypoint</span></span>
</span>
using</span> System</span>.</span>Runtime</span>.</span>InteropServices</span>;</span></span>
using</span> System</span>.</span>Security</span>.</span>Cryptography</span>;</span></span>
using</span> System</span>.</span>Text</span>;</span></span>
</span>
const</span> string</span> AppBin</span> =</span> "</span>/usr/bin/qbittorrent</span>"</span>;</span></span>
const</span> string</span> ConfigPath</span> =</span> "</span>/qbittorrent/etc/qBittorrent.conf</span>"</span>;</span></span>
const</span> string</span> DefaultConfigPath</span> =</span> "</span>/usr/share/qbittorrent/qBittorrent.conf</span>"</span>;</span></span>
const</span> string</span> DefaultPasswordHash</span> =</span> "</span>@ByteArray(188J/h/wfAYQ9H+mTl/7lA==:j/+e2SwJUi9g+IPiEG2+Pix9W0IOv2c20QjrmBUhr4TBUXO3fcMv6leeU6qK8834xiq8fngh8ShwYDfYO0w6lg==)</span>"</span>;</span></span>
const</span> string</span> Alphabet</span> =</span> "</span>abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789</span>"</span>;</span></span>
</span>
try</span></span>
{</span></span>
    EnsureConfig</span>(</span>)</span>;</span></span>
    RotateDefaultPassword</span>(</span>)</span>;</span></span>
    Exec</span>(</span>)</span>;</span></span>
}</span></span>
catch</span> (</span>Exception</span> ex</span>)</span></span>
{</span></span>
    Console</span>.</span>Error</span>.</span>WriteLine</span>(</span>ex</span>.</span>Message</span>)</span>;</span></span>
    Environment</span>.</span>Exit</span>(</span>1</span>)</span>;</span></span>
}</span></span>
</span>
static</span> void</span> EnsureConfig</span>(</span>)</span></span>
{</span></span>
    Directory</span>.</span>CreateDirectory</span>(</span>Path</span>.</span>GetDirectoryName</span>(</span>ConfigPath</span>)</span>!</span>)</span>;</span></span>
</span>
    var</span> inlineConfig</span> =</span> Environment</span>.</span>GetEnvironmentVariable</span>(</span>"</span>QBITTORRENT_CONFIG</span>"</span>)</span>;</span></span>
    if</span> (</span>!</span>string</span>.</span>IsNullOrEmpty</span>(</span>inlineConfig</span>)</span>)</span></span>
    {</span></span>
        File</span>.</span>WriteAllText</span>(</span>ConfigPath</span>,</span> inlineConfig</span>)</span>;</span></span>
        return</span>;</span></span>
    }</span></span>
</span>
    if</span> (</span>!</span>File</span>.</span>Exists</span>(</span>ConfigPath</span>)</span>)</span></span>
        File</span>.</span>Copy</span>(</span>DefaultConfigPath</span>,</span> ConfigPath</span>)</span>;</span></span>
}</span></span>
</span>
static</span> void</span> RotateDefaultPassword</span>(</span>)</span></span>
{</span></span>
    var</span> content</span> =</span> File</span>.</span>ReadAllText</span>(</span>ConfigPath</span>)</span>;</span></span>
    if</span> (</span>!</span>content</span>.</span>Contains</span>(</span>DefaultPasswordHash</span>,</span> StringComparison</span>.</span>Ordinal</span>)</span>)</span></span>
        return</span>;</span></span>
</span>
    var</span> password</span> =</span> RandomString</span>(</span>12</span>)</span>;</span></span>
    var</span> salt</span> =</span> RandomString</span>(</span>16</span>)</span>;</span></span>
</span>
    var</span> hash</span> =</span> Rfc2898DeriveBytes</span>.</span>Pbkdf2</span>(</span></span>
        password</span>,</span></span>
        Encoding</span>.</span>UTF8</span>.</span>GetBytes</span>(</span>salt</span>)</span>,</span></span>
        100000</span>,</span></span>
        HashAlgorithmName</span>.</span>SHA512</span>,</span></span>
        64</span>)</span>;</span></span>
</span>
    var</span> replacement</span> =</span> $"</span>@ByteArray(</span>{</span>Convert</span>.</span>ToBase64String</span>(</span>Encoding</span>.</span>UTF8</span>.</span>GetBytes</span>(</span>salt</span>)</span>)</span>}</span>:</span>{</span>Convert</span>.</span>ToBase64String</span>(</span>hash</span>)</span>}</span>)</span>"</span>;</span></span>
    var</span> updated</span> =</span> content</span>.</span>Replace</span>(</span>DefaultPasswordHash</span>,</span> replacement</span>,</span> StringComparison</span>.</span>Ordinal</span>)</span>;</span></span>
</span>
    File</span>.</span>WriteAllText</span>(</span>ConfigPath</span>,</span> updated</span>)</span>;</span></span>
    Console</span>.</span>WriteLine</span>(</span>$"</span>qBittorrent admin password: </span>{</span>password</span>}</span>"</span>)</span>;</span></span>
}</span></span>
</span>
static</span> string</span> RandomString</span>(</span>int</span> length</span>)</span></span>
{</span></span>
    var</span> bytes</span> =</span> RandomNumberGenerator</span>.</span>GetBytes</span>(</span>length</span>)</span>;</span></span>
    var</span> chars</span> =</span> new</span> char</span>[</span>length</span>]</span>;</span></span>
</span>
    for</span> (</span>var</span> i</span> =</span> 0</span>;</span> i</span> <</span> bytes</span>.</span>Length</span>;</span> i</span>++</span>)</span></span>
        chars</span>[</span>i</span>]</span> =</span> Alphabet</span>[</span>bytes</span>[</span>i</span>]</span> %</span> Alphabet</span>.</span>Length</span>]</span>;</span></span>
</span>
    return</span> new</span> string</span>(</span>chars</span>)</span>;</span></span>
}</span></span>
</span>
static</span> void</span> Exec</span>(</span>)</span></span>
{</span></span>
    var</span> args</span> =</span> Environment</span>.</span>GetCommandLineArgs</span>(</span>)</span>;</span></span>
    var</span> argv</span> =</span> new</span> string</span>?</span>[</span>args</span>.</span>Length</span> +</span> 1</span>]</span>;</span></span>
    argv</span>[</span>0</span>]</span> =</span> "</span>qbittorrent</span>"</span>;</span></span>
    Array</span>.</span>Copy</span>(</span>args</span>,</span> 1</span>,</span> argv</span>,</span> 1</span>,</span> args</span>.</span>Length</span> -</span> 1</span>)</span>;</span></span>
    argv</span>[</span>^</span>1</span>]</span> =</span> null</span>;</span></span>
</span>
    var</span> result</span> =</span> NativeMethods</span>.</span>execv</span>(</span>AppBin</span>,</span> argv</span>)</span>;</span></span>
    throw</span> new</span> Exception</span>(</span>$"</span>execv(</span>{</span>AppBin</span>}</span>) failed: errno </span>{</span>Marshal</span>.</span>GetLastPInvokeError</span>(</span>)</span>}</span>, result </span>{</span>result</span>}</span>"</span>)</span>;</span></span>
}</span></span>
</span>
static</span> class</span> NativeMethods</span></span>
{</span></span>
    [</span>DllImport</span>(</span>"</span>libc</span>"</span>,</span> SetLastError</span> =</span> true</span>)</span>]</span></span>
    internal</span> static</span> extern</span> int</span> execv</span>(</span>string</span> filename</span>,</span> string</span>?</span>[</span>]</span> argv</span>)</span>;</span></span>
}</span></span></code></pre>Desglossament del codi</a></h2>
Configuració: EnsureConfig()</code></a></h3>
La primera responsabilitat és assegurar que qBittorrent té un fitxer de configuració usable.
Si existeix la variable d'entorn QBITTORRENT_CONFIG</code>, el contingut s'escriu directament a /qbittorrent/etc/qBittorrent.conf</code>.
Si no, i encara no hi ha config, es copia el fitxer per defecte des de /usr/share/qbittorrent/qBittorrent.conf</code>.</p>
És una lògica simple, però és exactament la mena de coses que abans acabaven en un entrypoint.sh</code>.
La diferència és que aquí no depens de tenir shell ni eines externes a runtime.</p>

Un bon detall és que la configuració inline via variable d'entorn evita haver de muntar scripts auxiliars només per injectar quatre línies de config.</p>
</blockquote>
Rotació de password: RotateDefaultPassword()</code></a></h3>
La segona responsabilitat és evitar que qBittorrent arrenqui amb el hash per defecte.
El codi llegeix el fitxer, busca el DefaultPasswordHash</code> conegut, i si encara hi es genera una password aleatòria i un salt nou.</p>
Després deriva el hash amb Rfc2898DeriveBytes.Pbkdf2</code>, fent servir SHA512</code>, 100000</code> iteracions i una sortida de 64</code> bytes.
Amb això construeix el format @ByteArray(...)</code> que qBittorrent espera, substitueix el hash per defecte i escriu el fitxer actualitzat.</p>
Finalment imprimeix la nova password a stdout.
En un contenidor això és pràctic perquè la pots recuperar directament dels logs de la primera arrencada, sense inventar un mecanisme paral·lel.</p>
Process replacement: Exec()</code></a></h3>
La tercera peça és la més pròpia de contenidors "de debò": fer un execv()</code> via P/Invoke a libc</code>.
Això substitueix el procés actual pel binari real de qBittorrent, en lloc de llançar un subprocess i quedar-te amb un wrapper pel mig.</p>
Aquest detall importa perquè l'entrypoint acaba desapareixent i qBittorrent queda com a PID 1.
Això vol dir senyals directes, menys problemes de reaping, i un comportament molt més net quan el runtime del contenidor envia SIGTERM</code>.</p>
Si has fet servir scripts shell com a entrypoint, ja saps el patró: o fas exec</code>, o tard o d'hora acabes amb shutdowns estranys.
Aquí es resol igual, però sense shell.</p>
Com es compila i s'integra</a></h2>
Al pipeline de build, el fitxer es compila directament des de melange.yaml</code>:</p>
-</span> n</span>ame</span>:</span> B</span>uild entrypoint (Native AOT)</span></span>
  r</span>uns</span>:</span> |</span></span>
    arch="$(uname -m | sed 's/aarch64/arm64/;s/x86_64/x64/')"</span></span>
    dotnet publish entrypoint.cs -c Release -r "linux-${arch}" -o .</span></span>
</span>
-</span> n</span>ame</span>:</span> I</span>nstall artifacts</span></span>
  r</span>uns</span>:</span> |</span></span>
    install -Dm755 entrypoint "${{targets.destdir}}/usr/bin/entrypoint"</span></span></code></pre>
Després, a apko.yaml</code>, la imatge final defineix aquest binari com a entrypoint i arrenca com a usuari nonroot</code>:</p>
a</span>ccounts</span>:</span></span>
  g</span>roups</span>:</span></span>
    -</span> g</span>roupname</span>:</span> n</span>onroot</span></span>
      g</span>id</span>:</span> 65532</span></span>
  u</span>sers</span>:</span></span>
    -</span> u</span>sername</span>:</span> n</span>onroot</span></span>
      u</span>id</span>:</span> 65532</span></span>
      g</span>id</span>:</span> 65532</span></span>
  r</span>un-as</span>:</span> "</span>65532</span>"</span></span>
</span>
e</span>ntrypoint</span>:</span></span>
  c</span>ommand</span>:</span> /</span>usr/bin/entrypoint</span></span></code></pre>
El resultat és bastant elegant: el binari viu a /usr/bin/entrypoint</code>, la imatge no necessita ni runtime de .NET ni shell, i tota la lògica d'inicialització queda encapsulada en una peça petita i auditable.</p>
Per què C# i no Go/Rust/shell?</a></h2>
Si ja tens .NET disponible al pipeline de build, afegir un fitxer .cs</code> és gairebé trivial.
No has de crear cap projecte, no has de mantenir dependències de tercers, i no has d'obrir un repositori auxiliar només per un entrypoint de poques línies.</p>
Go</code> i Rust</code> continuen sent opcions perfectament bones i vàlides per això.
I si tens shell disponible, un script encara pot ser suficient en casos simples.
Però en un entorn on ja tens dotnet-10-sdk</code> al build i vols un binari Native AOT petit i autocontingut, C# passa de ser una opció curiosa a ser probablement la més convenient.</p>







    
        
            
        
    </div>
    
        
            No dic que sigui l'única resposta bona.
Dic que, si ja vius dins l'ecosistema .NET, ara tens una resposta molt pragmàtica.</p>

        </div>
    </div>
</div>
Tancament</a></h2>
La novetat de single-file C# a .NET 10 és fàcil de vendre com una millora de DX.
Però crec que el més interessant és una altra cosa: obre la porta a un scripting "seriós" amb C#, prou simple per a tasques petites i prou sòlid per acabar a producció.</p>
En aquest cas, no estem parlant d'un hello world.
Estem parlant d'un entrypoint Native AOT per a una imatge rootless, distroless i sense shell.
I això, sincerament, em sembla un use-case molt millor que qualsevol demo.</p>
Si vols veure l'exemple complet, amb entrypoint.cs</code>, melange.yaml</code> i apko.yaml</code>, aquí el tens: vegops/containers qBittorrent</a>.</p>
El web de l'Eudald

Entrypoint per contenidors distroless amb .NET single-file
