Secret anlegen oder ändern¶

Secrets nie im Klartext committen

Bearbeite creds-*.enc.yaml nur mit sops edit, nie direkt im Editor, und leite sops -d nie in eine Datei im Repo um. Ein Secret, das einmal im Klartext committet wurde, steht für immer in der Git-Historie und muss ausgetauscht werden.

Ziel¶

Ein neues oder geändertes Secret liegt verschlüsselt im Repo und kommt beim Ausrollen in den Container, der es braucht.

Voraussetzungen¶

dein age-Schlüssel ist eingetragen, und sops -d syslet/werner/creds-mailjet.enc.yaml zeigt Klartext (Arbeitsrechner einrichten)
du kannst eine Änderung ausrollen (Änderung ausrollen)
gelesen: Secrets im Repo, Podman Secrets und syslet in diesem Repo, Secret-Namen

Schritte¶

1. Neuesten Stand holen und plan ausführen¶

Wie in Änderung ausrollen, Schritt 1 bis 3, im Ordner des Hosts, auf dem der Container läuft, etwa syslet/werner.

Erwartet: No changes detected. All units are up to date.

2. Datei mit SOPS öffnen¶

Bleib im Ordner des Hosts; nur dort findet SOPS die Regeln aus syslet/.sops.yaml, mit denen es eine neue Datei verschlüsselt.

Bash
1	`sops edit creds-<name>.enc.yaml`

<name> ist der Name des Containers, der das Secret nutzt, etwa creds-hedgedoc-server.enc.yaml. Gibt es die Datei schon, ergänzt oder änderst du sie; sonst legt SOPS sie an.

Erwartet: Dein Editor öffnet sich mit den Secrets im Klartext. Bei einer neuen Datei steht darin ein Beispiel von SOPS, das mit hello: Welcome to SOPS! beginnt; lösche es vollständig.

Meldet SOPS no matching creation rules found oder config file not found, bist du nicht im Ordner eines Hosts.

3. Wert eintragen und speichern¶

Je Secret eine Zeile <schlüssel>: <wert>, der Schlüssel klein und ohne Trennzeichen, etwa:

YAML
sessionsecret: 5f0c…

Braucht die App einen zufälligen Wert, erzeugst du ihn zum Beispiel mit openssl rand -hex 32. Kommt der Wert von woanders, etwa die Client-ID und das Client-Secret aus Authentik, steht in der Anleitung dazu, woher (App per OIDC anbinden).

Speichere und schließe den Editor. Erwartet: SOPS beendet sich ohne Ausgabe; es verschlüsselt die Datei beim Schließen.

4. Prüfen, dass die Datei verschlüsselt ist¶

Bash
1	`git diff creds-<name>.enc.yaml`

Bei einer neuen Datei zeigt git diff nichts; nimm dann head -5 creds-<name>.enc.yaml.

Erwartet: Jeder Schlüssel steht im Klartext, jeder Wert als ENC[AES256_GCM,data:…]; dazu ändern sich im Block sops: am Ende lastmodified und mac. Steht irgendwo ein Wert im Klartext, committe nichts, sondern öffne die Datei noch einmal mit sops edit.

Ob der Wert stimmt, siehst du mit:

Bash
1	`sops -d creds-<name>.enc.yaml`

5. Secret im Stack einbinden¶

Nur für einen neuen Schlüssel; änderst du nur den Wert eines bestehenden, weiter mit Schritt 6.

Trag das Secret in der Stack-Datei beim Container unter Secret: ein. Sein Name ist <name>-<schlüssel>, aus sessionsecret in creds-hedgedoc-server.enc.yaml wird also hedgedoc-server-sessionsecret.

Kann die App das Secret aus einer Datei lesen (oft eine Variable, die auf _FILE endet), binde es als Datei ein, wie in syslet/werner/stack-membertool.cue bei mailjet-password. Sonst als Umgebungsvariable, wie in syslet/werner/stack-hedgedoc.cue:

Text Only
1 2 3	`Secret: { "hedgedoc-server-sessionsecret": "type=env,target=CMD_SESSION_SECRET" }`

Steht der Wert bisher im Klartext unter Environment:, lösch die Zeile dort. Ein vollständiges Beispiel für beides ist der Commit dc06690.

Formatieren wie in Änderung ausrollen, Schritt 5.

6. plan ausführen¶

Bash
1	`cue cmd plan`

Erwartet: unter Secret changes: die Datei mit allen ihren Schlüsseln, die Werte versteckt, und in der Zusammenfassung jeder Container, der eines dieser Secrets nutzt, mit secret updated, restarted:

Text Only

Secret changes:
  hedgedoc-server:
    + oidcclientid=(secret)
    + oidcclientsecret=(secret)
    + sessionsecret=(secret)

Summary:
UNIT                                     STATUS     CHANGES
hedgedoc-server.container                updated    unit updated, secret updated, restarted (desired: running)

unit updated steht nur dabei, wenn du in Schritt 5 die Stack-Datei geändert hast. Mehr zu den Abschnitten: Plan output in der syslet-Doku.

Zeigt plan mehr, roll nicht aus, sondern geh nach plan zeigt unerwartete Änderungen vor.

7. Ausrollen¶

Bash
1	`cue cmd apply`

Erwartet: dieselbe Ausgabe wie bei plan, dann Continue? (yes/no); tippe yes. Die Container aus der Zusammenfassung starten dabei neu und sind kurz nicht erreichbar.

8. App prüfen¶

Sieh in die Logs der neu gestarteten Container, etwa:

Bash
cue cmd -t unit=hedgedoc-server.service logs

Erwartet: kein Fehler, der auf den neuen Wert hinweist, etwa eine abgelehnte Anmeldung; mit Ctrl+C beendest du die Ausgabe. Probier dann im Browser aus, wofür das Secret da ist, etwa die Anmeldung über Authentik.

Danach noch einmal cue cmd plan; erwartet: No changes detected. All units are up to date.

9. Committen und pushen¶

Wie in Änderung ausrollen, Schritt 9 und 10, mit der creds-*.enc.yaml und, falls geändert, der Stack-Datei. Die Commit-Message nennt, welches Secret neu ist oder geändert wurde und warum, nie den Wert, etwa rotate hedgedoc session secret.

Prüfen¶

sops -d creds-<name>.enc.yaml zeigt den neuen Wert, und git show HEAD zeigt in der creds-*.enc.yaml nur Werte in ENC[…].
Die App tut, wofür sie das Secret braucht.
cue cmd plan zeigt „No changes“.

Wenn etwas schiefgeht¶

SOPS meldet Failed to get the data key required to decrypt the SOPS file.: Dein age-Schlüssel fehlt auf deinem Rechner oder ist für diese Datei nicht eingetragen; siehe Arbeitsrechner einrichten und Neue Person freischalten.
plan bricht ab mit key "…" not found in secret "…": Der Name unter Secret: passt nicht zu einem Schlüssel in der Datei, meist ein Tippfehler.
Die App startet nach dem apply nicht: Container-Status und Logs ansehen
Ein Secret ist im Klartext committet, gepusht oder nicht: Es gilt als bekannt (siehe Secrets im Repo). Sag in Signal Bescheid, erzeuge dort, wo das Secret herkommt, einen neuen Wert und trag ihn nach dieser Anleitung ein.
Allgemeines: Rotate a secret und Pass a secret to a container in der syslet-Doku