Ein Connection String, jede Plattform: Verbindung zu Zaris

Die Hälfte der „funktioniert in Dev, bricht in Prod"-Verbindungsfehler hat dieselbe Ursache: Die Verbindungsdetails wurden an drei Stellen auf drei verschiedene Arten geschrieben. In der appsettings.json stand eine Host-Liste, im Betriebshandbuch wurde eine andere in eine PowerShell-Sitzung kopiert, und der Connection String, den jemand aus einem Wiki kopiert hat, enthielt ein veraltetes Token.

Zaris nimmt diese ganze Problemklasse mit einem einzigen, plattformunabhängigen Connection-String-Format vom Tisch. Exakt derselbe String funktioniert, wenn Ihre .NET-Anwendung ihn aus der Konfiguration liest, wenn ein Operator ihn einem PowerShell-Cmdlet übergibt und wenn jemand ihn direkt aus der Web-Konsole kopiert. Eine kanonische Schreibweise, überall.

Dieser Beitrag zerlegt den String Teil für Teil, zeigt alle drei Verwendungsarten und plädiert für die wichtigste Regel in der Produktion: Legen Sie niemals ein rohes Token in den String.

Der Aufbau des Strings

Ein Zaris-Connection-String ist ein URI. Hier ein vollständig ausgestatteter:

zariss://zaris-a.example.com:7861,zaris-b.example.com:7861/?store=orders&token=env:ZARIS_TOKEN

Jeder Teil davon hat eine Aufgabe:

• Schema → Transportsicherheit. zaris:// ist Klartext; zariss:// ist TLS (das zusätzliche s, dieselbe Konvention wie bei http/https). Über das Schema schalten Sie die Transportverschlüsselung ein — es gibt kein separates Flag, das man vergessen könnte.
• Kommagetrennte Hosts → Failover-/Seed-Liste. Sie können mehr als ein host:port angeben, und der Client behandelt sie als Seed-Liste für das Failover. Er verbindet sich über den Seed, der antwortet, und ermittelt den Rest des Clusters von dort; ein beim Start ausgefallener Node sperrt Sie also nicht aus.
• Ein erforderlicher Store-Name. Jede Verbindung zielt auf genau einen Store, und der Store-Name ist erforderlich — es gibt keinen impliziten Default. Das ist Absicht: Ein String sagt immer, für welchen Store er gilt, und Sie können einen Job nicht versehentlich auf den falschen Store richten, weil das Ziel leer gelassen wurde.
• Ein sicher bereitgestelltes Token. Authentifizierungs-Tokens sind Geheimnisse, deshalb hält das Format sie aus dem Literal-String heraus. Statt das Token einzufügen, verweisen Sie darauf, woher es zu lesen ist — token=env:ZARIS_TOKEN liest es aus einer Umgebungsvariable, und token=file:/path/to/token liest es aus einer Datei auf dem Datenträger. Das Geheimnis steht nie im String selbst und landet damit nie in der Versionsverwaltung, in einer Shell-History oder auf einem Screenshot.

Der letzte Punkt ist der, den man verinnerlichen sollte: Der String trägt einen Verweis auf die Zugangsdaten, nicht die Zugangsdaten selbst.

Verwendung aus .NET

.NET-Anwendungen lesen den String aus der Standard-ConnectionStrings-Konfiguration — demselben appsettings.json-/IConfiguration-Mechanismus, den Sie bereits für Datenbanken nutzen. Legen Sie ihn dorthin, wo jeder andere Connection String liegt:

{
  "ConnectionStrings": {
    "Orders": "zariss://zaris-a.example.com:7861,zaris-b.example.com:7861/?store=orders&token=env:ZARIS_TOKEN"
  }
}

Lesen Sie ihn dann wie alles andere über die Konfiguration:

var connectionString = builder.Configuration.GetConnectionString("Orders");
var store = await ZarisStore.ConnectAsync(connectionString);

Da das Token env:ZARIS_TOKEN ist, kann die eingecheckte appsettings.json gefahrlos committet werden — sie nennt die Umgebungsvariable, statt das Geheimnis zu enthalten. Jede Umgebung liefert ihr eigenes ZARIS_TOKEN, und der String bleibt vom Laptop des Entwicklers bis zu den Produktions-Pods identisch.

Verwendung aus PowerShell

Die Admin-Cmdlets nehmen den identischen String. Connect-ZrStore akzeptiert ihn direkt mit -ConnectionString:

$conn = "zariss://zaris-a.example.com:7861,zaris-b.example.com:7861/?store=orders&token=env:ZARIS_TOKEN"
Connect-ZrStore -ConnectionString $conn

Beachten Sie, dass dies derselbe String ist, der in der appsettings.json steht. Ein Operator, der ein Produktionsproblem debuggt, und ein Dienst, der in der Produktion läuft, werden auf exakt dieselbe Weise auf den Cluster gerichtet — kein Übersetzungsschritt, in dem sich ein feiner Unterschied bei Host-Liste oder Store-Name einschleichen könnte. Die env:-Indirektion funktioniert auch hier: Setzen Sie ZARIS_TOKEN in der Umgebung der Shell, und das Cmdlet löst es beim Verbindungsaufbau auf.

Direkt aus der Konsole kopieren

Die dritte Quelle ist die Web-Konsole. Für jeden Store zeigt die Konsole einen kopierbaren Connection String — einen korrekten, bereits in der kanonischen Schreibweise, mit den richtigen Hosts und dem Store-Namen. Ein Operator, der sich verbinden muss, baut keinen URI aus dem Gedächtnis zusammen; er kopiert den von der Konsole erzeugten String und fügt ihn in seine Anwendungskonfiguration oder einen Connect-ZrStore-Aufruf ein.

Damit schließt sich der Kreis. Die Konsole erzeugt den kanonischen String, die .NET-Konfiguration konsumiert ihn, und PowerShell konsumiert ihn — drei Oberflächen, ein Format, kein erneutes Umschreiben.

Die eine Regel für die Produktion

Verwenden Sie in echten Deployments immer die Token-Indirektion über env: oder file:. Fügen Sie niemals ein rohes Token in den String ein.

In einem schnellen Test ist es verlockend, die Zugangsdaten direkt einzubetten, nur um zu sehen, dass es funktioniert. Das Problem ist, was danach passiert: Der String wird in eine Konfigurationsdatei kopiert, committet, in einem Chat geteilt oder in ein Ticket gelegt — und nun liegt ein gültiges Credential irgendwo, wo es nicht liegen sollte, und niemand weiß einfach nachzuvollziehen, wohin es überall gelangt ist. Die Formen env: und file: existieren genau dafür, dass der funktionierende String und das Geheimnis getrennte Wege gehen:

# Good — the secret lives in the environment, the string references it
zariss://zaris-a.example.com:7861/?store=orders&token=env:ZARIS_TOKEN

# Good — the secret lives in a mounted file, the string references it
zariss://zaris-a.example.com:7861/?store=orders&token=file:/var/run/secrets/zaris-token

In Kubernetes passt file: natürlich zu einem eingebundenen Secret; in einer VM oder einem Container passt env: zu allem, was Umgebungsvariablen injiziert. In beiden Fällen bedeutet die Rotation des Tokens, das Geheimnis zu ändern, nicht jeden Connection String zu bearbeiten.

Der Gewinn

Ein kanonischer String bedeutet eine Stelle, an der man es richtig machen muss, und eine Sache, über die man nachdenken muss. Host-Liste, TLS-Wahl, Store und Credential-Quelle sind stets gleich kodiert, egal ob der Leser die .NET-Konfiguration, ein PowerShell-Cmdlet oder ein Mensch ist, der aus der Konsole kopiert. So wird der „funktioniert in Dev, bricht in Prod"-Verbindungsfehler abgeschafft: Es gibt schlicht keine zweite Schreibweise der Verbindung, der Prod widersprechen könnte.