Clustering¶

Bemerkung

This feature is currently a technical preview with the following temporary limitation:

Active/passive setup to support two-node clusters, either by utilizing etcd Learner or Mirror, is not yet available. Use a Witness node instead.
Es wurde noch nicht in einer ausreichenden Anzahl von Produktivumgebungen getestet, und es könnten Fehler vorhanden sein.

NetHSM ab Version 4.0 unterstützt Clustering, um Daten zwischen mehreren NetHSMs direkt zu synchronisieren. Dies unterstützt eine hohe Frequenz der Schlüsselgenerierung, realisiert Hochverfügbarkeit und Lastausgleich. Ein NetHSM-Cluster basiert auf etcd, das den Raft-Konsensalgorithmus für starke Konsistenz verwendet. Dadurch wird sichergestellt, dass die Daten (z. B. Schlüssel) in allen NetHSMs jederzeit korrekt sind.

Machen Sie sich vor dem Einrichten eines NetHSM-Clusters mit dieser Technologie und ihren Einschränkungen vertraut, um versehentliche Ausfälle und Datenverluste zu vermeiden. Zusätzlich zu diesem Dokument können Sie auch die Dokumentation von etcd einsehen.

Operational Redundancy¶

Als „Knoten“ wird ein NetHSM bezeichnet, von dem erwartet wird, dass er Teil eines Clusters ist. Ein Cluster aus N Knoten wird so lange weiterarbeiten, wie mindestens (N/2)+1 Knoten gesund und erreichbar sind. Diese minimale Anzahl von gesunden, erreichbaren Knoten wird als quorum bezeichnet.

In einem Cluster, der diesen Schwellenwert unterschreitet (z. B. aufgrund eines Netzwerkproblems), kann kein Leader gewählt werden, und die lokale Instanz von etcd auf jedem Knoten kann keine Lese- und Schreibvorgänge mehr ausführen. Daraus ergeben sich die folgenden Szenarien.

Ein Knoten fällt aus und das Quorum wird trotzdem erreicht¶

Wenn in einem Cluster mit drei Knoten ein Knoten ausfällt (abstürzt oder aufgrund von Netzwerkbedingungen unerreichbar wird), arbeiten die beiden anderen Knoten weiter und bedienen Anfragen.

If the failed node is still healthy (e.g. it was just a network problem), it will be in the Failed state while isolated, refusing normal operations (not even read-only).

However if the node recovers, it will cleanly resynchronize with the rest of the cluster and exit the Failed state, resuming normal operation without losing data.

Sollte es sich nicht wieder erholen, muss es aus dem Cluster entfernt werden und entweder einer Wiederherstellung unterzogen werden, um auf seine Daten zugreifen zu können (es ist dann jedoch nicht mehr Teil des Clusters), oder auf die Werkseinstellungen zurückgesetzt und der Beitrittsprozess von Grund auf neu durchlaufen werden.

Es kommt zu einer Netzwerktrennung und das Quorum wird trotzdem erreicht¶

Dies ist nur eine Verallgemeinerung des vorherigen Szenarios. In einem 5-Knoten-Cluster, in dem sich z. B. 3 Knoten an einem physischen Standort A und 2 Knoten an einem anderen Standort B befinden, würde ein Netzwerkproblem, das A und B isoliert, Folgendes bedeuten:

Die 3 Knoten am Standort A erfüllen das Quorum (in diesem Fall 3), so dass sie weiterarbeiten.
The 2 nodes in location B are not meeting the quorum (still 3), so they will enter the Failed state and stop operating (even read-only).
Wenn das Netzwerkproblem behoben ist, werden die 2 Knoten wieder mit den 3 anderen verbunden.

Mit anderen Worten: Im schlimmsten Fall einer Netzwerkpartition (in einem Cluster mit einer ungeraden Anzahl von Knoten) bleibt die größere Hälfte des Clusters funktionsfähig, während die kleinere Hälfte so lange nicht einsatzfähig ist, bis die Partition behoben ist.

Das Quorum ist auf Dauer verloren¶

A failure causing all subsets of the cluster to lose quorum will render the cluster completely inoperable (all remaining nodes will be in the Failed state), unless the failure is resolved. In this case, manual recovery must be performed.

Dies kann zum Beispiel passieren, wenn ein einzelner Knoten in einem Cluster mit 2 Knoten ausfällt (wo das Quorum 2 ist). In diesem Fall kann der ausgefallene Knoten nicht nachträglich sauber aus dem Cluster entfernt werden, da der verbleibende gesunde Knoten bereits nicht mehr funktionsfähig ist, da er das Quorum verloren hat.

Daher ist es ratsam, immer eine ungerade Anzahl von Knoten in einem Cluster zu haben und häufig Backups durchzuführen.

Um das klarzustellen: vorübergehend Verlust des Quorums (z. B. wenn Sie alle Knoten eines Clusters gemeinsam neu starten oder ein vorübergehender Netzwerkausfall die Knoten isoliert) ist kein Problem: Sobald genügend Knoten wieder verbunden sind (ohne dass sie sich manuell neu verbinden müssen), um das Quorum zu erreichen, nimmt der Cluster seinen normalen Betrieb wieder auf. Nur bei dauerhaften Ausfällen, wie z. B. Netzwerkpartitionen, Netzwerkfehlkonfigurationen, Authentifizierungsproblemen oder Hardwareausfällen, sind manuelle Maßnahmen erforderlich.

Weitere Informationen finden Sie unter etcd’s FAQ.

2-Knoten-Cluster¶

Ein aktiver/passiver Cluster mit zwei Knoten wird noch nicht unterstützt und soll in einer zukünftigen Version hinzugefügt werden. Wir empfehlen die Einführung eines dritten Knotens, entweder eines dritten NetHSM oder eines etcd-„Zeugen“, der auf einem beliebigen Host betrieben werden kann. Siehe den nächsten Abschnitt „Witness“.

Zeuge¶

The nature of clustering with etcd makes it more reliable the more nodes there are in the cluster. As explained in the Operational Redundancy section, clusters should ideally have at least 3 nodes to have room to fail, since a 2-node cluster will entirely fail if only one fails.

Die Funktion ist jedoch so konzipiert, dass Sie kein vollständiges, echtes NetHSM-Gerät zu Ihrem Cluster hinzufügen müssen, um eine stabile Anzahl von Knoten zu erreichen. Stattdessen können Sie selbst einen „Zeugen“-Knoten einrichten und hinzufügen. Ein solcher Knoten ist einfach eine Instanz von etcd, die auf einem Rechner Ihrer Wahl (oder in einem Container) läuft und mit dem Cluster verbunden ist. Er wird von den echten Geräten im Cluster als normaler Knoten erkannt und empfängt alle Daten und Aktualisierungen von den Geräten (aber natürlich können Sie mit ihm keine HSM-Operationen durchführen - er speichert nur Daten).

Security Considerations¶

Der Zeugenknoten (oder jeder, der Zugriff auf ihn hat) hat direkten Zugriff auf das Speicher-Backend aller Knoten im Cluster (z.B. können Sie alle Einträge und die entsprechenden Werte mit etcdctl get "/" "0" ausgeben).

Mit Ausnahme der Konfigurationsversion (/config/version, die immer „1“ sein sollte) sind jedoch grundsätzlich alle Werte verschlüsselt (entweder mit einem Geräteschlüssel für knotenspezifische Werte oder den Domänenschlüsseln für andere), wodurch die Vertraulichkeit sensibler Daten gewährleistet ist.

Beachten Sie jedoch, dass ein bösartiger Knoten dies tun kann:

Write garbage as the value for any entry in the store, which will cause nodes to fail decrypting it (which may lead to crashes for some system entries).
List entry names such as users, namespaces and keys, which you may consider sensitive.

Was zwischen den Knoten geteilt wird¶

Ein Cluster von NetHSMs bedeutet, dass die meisten Daten von allen gemeinsam genutzt werden. Jede Hinzufügung, Änderung oder Löschung von Schlüsseln, Benutzern oder Namensräumen auf einem Knoten wirkt sich schließlich auf alle anderen aus. Generell gilt, dass jeder Vorgang, der den Zustand verändert, den Zustand aller Knoten verändert. Dies gilt auch für den Vorgang der Sicherung Wiederherstellung, der wie üblich funktioniert.

In den folgenden Abschnitten wird erläutert, welche Daten vollständig lokal sind, welche Daten im gemeinsam genutzten Speicher etcd gespeichert werden, aber knotenspezifisch bleiben, und welche Daten von allen Knoten gemeinsam genutzt werden.

Nicht in etcd gespeichert¶

Der Geräteschlüssel eines jeden Knotens bleibt nur lokal gespeichert und wird niemals zwischen den Knoten ausgetauscht.

In etcd gespeichert, aber knotenspezifisch¶

Die folgenden Daten sind in etcd in verschiedenen Bereichen für jeden Knoten gespeichert. Sie sind daher ** für jeden Knoten zugänglich, aber nicht einheitlich über die Knoten hinweg (jeder Knoten kann einen anderen Wert für diese Daten haben).

Configuration:

TLS certificates
Clock configuration
Netzwerkkonfiguration
Logging configuration
Unattended boot configuration
Unlock salt (so each node has its own unlock passphrase)
Locked domain key

Beachten Sie, dass zwar jeder Knoten seine eigene Version des gesperrten Domänenschlüssels hat (weil jeder Knoten ihn mit seinem eigenen Geräteschlüssel oder seiner eigenen Passphrase zum Entsperren sperrt), der zugrundeliegende Domänenschlüssel jedoch von allen Knoten gemeinsam genutzt wird: **** (für den Zugriff auf ihre gemeinsamen HSM-Daten, z. B. Schlüssel).

Gespeichert in etcd und gemeinsam genutzt¶

Alle folgenden Daten werden in etcd im globalen Bereich gespeichert, so dass sie für alle Knoten eines Clusters einheitlich sind:

HSM-Daten:

Keys
Benutzer
Namespaces

Configuration:

Config/domain store version
Cluster CA (used to authenticate nodes across cluster)
Backup passphrase and backup salt

Note that for now the config/domain store version can only be version 1 (if your software version supports clustering, then that is what you have). Refer to the Software Updates in Clusters section for more details on the safety of installing software updates within a cluster.

Creating a Cluster¶

Jeder Cluster beginnt zunächst mit einem einzigen Knoten. Neue Knoten werden dem Cluster nach und nach hinzugefügt.

Preparing Nodes¶

Der Netzwerkverkehr zwischen den Knoten wird verschlüsselt und mit ihrem TLS-Zertifikat authentifiziert.

Alle Knoten, die Teil desselben Clusters sein sollen, müssen zunächst eine gemeinsame Zertifizierungsstelle (CA) installieren, die es ihnen ermöglicht, die Legitimität der anderen Knoten zu überprüfen.

Im Folgenden gehen wir davon aus, dass alle Knoten frisch eingerichtet und betriebsbereit sind.

Networking¶

Nodes must first be reconfigured with their expected final network configuration as described in the section Network.

Erstellen und Installieren einer CA¶

Die Benutzer sollten eine CA mit ihren eigenen Mitteln und nach ihren eigenen betrieblichen Zwängen erstellen und sicherstellen, dass sie mindestens die Verwendung des Schlüssels keyCertSign zulässt.

Eine minimale CA kann zum Beispiel mit openssl erstellt werden:

$ openssl genrsa -out CA.key 2048 # create a key
$ openssl req -x509 -new -nodes -key CA.key -sha256 -days 1825 -out CA.pem -addext keyUsage=critical,keyCertSign

Diese CA muss nun auf jedem Knoten installiert werden.

Erstellen Sie dazu zunächst eine Zertifikatssignierungsanforderung (Certificate Signing Request, CSR) vom Knoten aus, wie im Abschnitt „ “ unter „TLS-Zertifikat“ beschrieben. Bei „ “ nitropy erfolgt dies mit nitropy nethsm --host $NETHSM_HOST csr --api.

Bemerkung

To properly authenticate nodes, the clustering backend (etcd) expects that each node has a certificate with a properly filled Subject Alt Names (SAN) field. Nodes are expected to be reached only via their IP and need to have a proper IP SAN in their certificate. IP SANs can be requested for the CSR by prefixing „IP:“ to the names, as in openssl:

"subjectAltNames": [ "normalname.org", "IP:192.168.1.1" ]

Bei „ “ und „nitropy“ verwenden Sie die Option „ ` “ –san`, z. B. --san "IP:192.168.1.1".

Wenn Sie eine öffentliche Zertifizierungsstelle (CA) zum Signieren Ihrer Zertifikate verwenden möchten, müssen Ihre Knoten öffentliche IP-Adressen verwenden. Dies ist auf eine Sicherheitsanforderung zurückzuführen, die es einer öffentlichen Zertifizierungsstelle untersagt, Zertifikate auszustellen, deren IP-SAN eine private IP-Adresse enthält.

Mit der erhaltenen CSR (nennen wir sie nethsm.csr) können wir dann ein Zertifikat für sie erzeugen, das installiert werden kann. Zum Beispiel mit openssl:

$ openssl x509 -req -days 1825 -in nethsm.csr -CA CA.pem -copy_extensions copy \
    -CAkey CA.key -out new_cert.pem -set_serial 01 -sha256

Installieren Sie anschließend die erhaltene Datei „ ` “ new_cert.pem`, wie im Abschnitt „ “ beschrieben: TLS-Zertifikat (mit nitropy: nitropy nethsm --host $NETHSM_HOST set-certificate --api new_cert.pem).

Finally, the CA (CA.pem) can now be installed. This is only possible once the installed TLS certificate is signed by it. Otherwise, the operation will be rejected.

Argumente

Argument	Beschreibung
`FILENAME`	The path of the CA file

Beispiel

$ nitropy nethsm --host $NETHSM_HOST set-cluster-ca-certificate CA.pem

Die installierte Cluster-Zertifizierungsstelle kann mit dem Befehl „ nitropy nethsm --host $NETHSM_HOST get-cluster-ca-certificate“ abgerufen werden.

Bemerkung

Dieser Vorgang muss für jeden Knoten wiederholt werden.

Taktsynchronisation¶

Stellen Sie sicher, dass auf jedem Knoten eine korrekte Systemzeit eingerichtet wurde, idealerweise mithilfe von NTP/NTS anstelle einer manuellen Zeiteinstellung. Dies kann über die Konfiguration unter Time sowie NTS/NTP erfolgen.

Adding a New Node¶

Adding a node to a cluster is done in three steps:

Register the addition to the cluster (through any one of its members)
Tell the new node to join
Sobald er aufgeholt hat, befördere den Knoten vom Lernenden zum vollwertigen Mitglied.

Configure a Backup Passphrase¶

First make sure a backup passphrase is configured on the node that will be used to register a new joiner as described in the section Backup.

Registrierung eines neuen Knotens¶

Halten Sie die IP des Knotens bereit, der beitreten wird. Die vollständige URL (auch peer URL in etcd Terminologie genannt) dieses Knotens wird https://<IP_of_node>:2380 (z.B. https://192.168.1.1:2380) sein. Der Port muss 2380 sein, also stellen Sie sicher, dass jede Firewall zwischen den Knoten den TCP-Verkehr auf diesem Port zulässt.

You can double-check the URL is correct by listing the cluster members on the node that is expected to join. This should list just one member: itself.

Beispiel

$ nitropy nethsm --host $NETHSM_HOST list-cluster-members

Call GET /cluster/members (refer to the API documentation).

Then register that expected URL on any existing node of the cluster (if you don’t have a cluster yet, do this on the NetHSM that will serve as the initial node of the cluster).

Optionale Optionen

Option	Beschreibung
`--url` `TEXT`	Die Peer-URL des neuen Knotens (kann mehrfach festgelegt werden)

Argumente

Argument	Beschreibung
`JOIN_DATA_PATH`	Der Pfad der Datei, in die die Verknüpfungsdaten geschrieben werden

Beispiel

$ nitropy nethsm --host $NETHSM_HOST add-cluster-member --url https://192.168.1.1:2380 join-data.json

Der Befehl listet die Clustermitglieder auf und schreibt die Daten, die der neue Knoten für den Beitritt zum Cluster benötigt (einschließlich des Joiner-Kits), in die Datei. Bewahren Sie diese Datei für den nächsten Schritt auf.

Call the POST /cluster/members endpoint (refer to the API documentation), passing it a JSON body containing the URL.

A successful call returns a JSON body of the form:

{
  "members": [
    {
      "name": "",
      "urls": [
        "https://172.22.1.3:2380"
      ],
      "learner": true
    },
    {
      "name": "9ZVNM2MNWP",
      "urls": [
        "https://172.22.1.2:2380"
      ],
      "learner": false
    }
  ],
  "joinerKit": "eyJiYWNrdXBfc2FsdCI6IkVlUzNPOEhHSEc5NnlNRktrdG1NZmc9PSIsInVubG9ja19zYWx0IjoiU3phMkEvYW13NlhxVWsrdHZMMmFubm5SZFlWd2ZQUjdpZ3IxK1RSdTdVaU14dmh3d0x2NWIvYVNkY2c9IiwibG9ja2VkX2RvbWFpbl9rZXkiOiIyMnNGVlkyelhQUVZ6S1pQenI3MmkwTk1WM3lmQ2k5dGwzeDhUbGtuOXM0WjFOd3JoZkRQTFZIVHp1WVl0YkQxaVZCMlovV3JHUHJlMXlwN0t4U0w4WkxjY2ZUTmUzcFg0WXE4YXNlY0wwREhXNGlIaXlPMlZnPT0ifQ=="
}

die Informationen enthält, die der neue Knoten benötigt, um dem Cluster beizutreten. Insbesondere listet er alle Mitglieder des Clusters auf (wobei das Mitglied mit einem leeren Namen der neue Teilnehmer ist). Sie enthält auch den Domänenschlüssel, der sowohl durch die Entsperr- als auch durch die Sicherungspassphrase verschlüsselt ist - eine Sicherungspassphrase muss also zuvor konfiguriert worden sein.

Bemerkung

Notice in the list of members (learner: True in the nitropy output, "learner": true in the REST API response) that the new joiner is a „learner“: it can now connect to the cluster and receive data from it, but cannot participate until it is promoted, which will be covered below.

Zwar bedeutet dieses Konzept des „Learners“ einen zusätzlichen Schritt (die Beförderung), doch ermöglicht es einen sichereren Betrieb des Clusters, da etwaige Probleme mit dem neuen Knoten vor seiner Beförderung keine Instabilität im gesamten Cluster verursachen können.

Bewahren Sie die Join-Datendatei für den nächsten Schritt auf (oder die Antwort, falls Sie die REST-API verwendet haben).

Joining the Cluster as a Learner¶

Treten Sie dem Cluster auf dem Knoten bei, der dem Cluster beitreten soll, und verwenden Sie dabei die Daten aus dem letzten Schritt sowie die Sicherungs-Passphrase des Knotens, auf dem der neue Teilnehmer registriert wurde.

Erforderliche Optionen

Option	Beschreibung
`--backup-passphrase` `TEXT`	Die Sicherungspassphrase des Knotens, auf dem der neue Teilnehmer registriert wurde

Argumente

Argument	Beschreibung
`JOIN_DATA_PATH`	Der Pfad der Verknüpfungsdatendatei aus dem letzten Schritt

Beispiel

$ nitropy nethsm --host $NETHSM_HOST join-cluster --backup-passphrase $BACKUP_PASSPHRASE join-data.json

Take the response from the last step and append to it a backupPassphrase field containing the backup passphrase, and pass that data to a call to POST /cluster/join (refer to the API documentation).

Warnung

The join call (nitropy nethsm join-cluster or POST /cluster/join) will hang until the new node is manually promoted (see below). This is normal. When the call returns successfully, it indicates that join and promotion have been successful. Don’t cancel this join call.

Assuming both the cluster and the node can reach each other, this will enact the actual join, wiping the data on the new joiner to instead synchronize its state with that of the cluster. If this operation fails immediately (e.g. the cluster was not reachable or authentication failed), this node’s state will not be wiped and the join will be reverted. However as soon as a first join is successful, this operation is final and can only be reverted by a factory reset.

Zu diesem Zeitpunkt ist der neue Knoten als „ -Lerner“ ( ) dem Cluster beigetreten: Er synchronisiert sich gerade mit dem Cluster, ist jedoch noch nicht betriebsbereit. Andererseits würde ein eventuelles Problem mit dem Knoten in dieser Phase keine Auswirkungen auf den Cluster haben, sodass dieser Vorgang sicher ist.

Der letzte Schritt zum Abschluss des Beitritts besteht darin, den neuen Knoten zum vollwertigen Mitglied zu ernennen.

Promoting the New Learner¶

Je nach Netzwerk- und Clusterbedingungen kann es eine Weile dauern, bis das neue Mitglied den Rückstand zum Cluster aufgeholt hat. Sobald dies geschehen ist, kann es vom Lernmitglied zum Vollmitglied befördert werden.

Warnung

Promoting a node increases the cluster’s quorum threshold (refer to the API documentation and the Operational Redundancy section of this document). Ensure this new node has a stable connection to the cluster before promoting it.

Sie können wie folgt versuchen, das neue Mitglied zu befördern. Die Mitglieds-ID finden Sie, indem Sie die Cluster-Mitglieder auflisten.

Argumente

Argument	Beschreibung
`MEMBER_ID`	The ID of the learner to be promoted

Beispiel

$ nitropy nethsm --host $NETHSM_HOST promote-cluster-member $MEMBER_ID

Call POST /cluster/members/{MemberID}/promote (refer to the API documentation).

Wenn der Lernende noch nicht aufgeholt hat, schlägt dies fehl (HTTP-Code 412 in der REST-API) und die Versetzung sollte später erneut versucht werden.

If this promotion is successful, the node will now have fully joined the cluster and the earlier call to /cluster/join will have returned. The node ends up in a Locked state and has to be unlocked with the unlock passphrase of the node that was used for registration. Afterwards the unlock passphrase can be changed (unlock passphrases remain node-specific and are not shared across nodes).

Adding a Witness Node¶

Prepare a Witness¶

Sie benötigen eine Umgebung, in der etcd v3.6 verfügbar ist, mit einer IPv4-Adresse (mindestens), die für die anderen Mitglieder Ihres Clusters erreichbar ist. Der TCP-Verkehr von und zu Port 2380 muss zugelassen werden.

Erstellen Sie ein leeres Verzeichnis, in dem etcd seine Daten speichern wird, und notieren Sie den Pfad (wir verwenden /var/etcd/data). Stellen Sie sicher, dass der Benutzer, der den Prozess starten wird, Lese- und Schreibrechte für das Verzeichnis hat.

Transfer to the machine the CA certificate that is being used to authenticate nodes in the cluster. You should have created one in the Creating and Installing a CA section. We’ll store it in /var/etcd/CA.pem.

Anschließend müssen Sie ein Zertifikat für den Zeugen erstellen und es mit der Zertifizierungsstelle signieren, damit er mit seinen Kollegen kommunizieren kann. Dies kann zum Beispiel über openssl erfolgen:

# Create a key
$ openssl genrsa -out witness.key 2048
# Create a CSR with a SAN that corresponds to the witness's IP or hostname
$ openssl req -new -sha256 -key own.key -subj "/C=US/ST=CA/O=MyOrg, Inc./CN=witness" \
    -addext "subjectAltName=IP:172.22.1.3" --out witness.csr
# Sign it
$ openssl x509 -req -days 1825 -in witness.csr -CA CA.pem -copy_extensions copy \
    -CAkey CA.key -out witness.pem -set_serial 01 -sha256

Speichern Sie die Ergebnisse witness.key und witness.pem auch in /var/etcd.

Register Witness to Cluster¶

Follow the normal instructions from the Registering a New Node section to signal the existing cluster the addition of a new member with the given URL(s).

Keep the join data file written by nitropy nethsm add-cluster-member (or the response from the cluster, if you used the REST API): it contains the list of cluster members and a joiner kit (you won’t need this part).

Configure etcd¶

Im Gegensatz zu NetHSMs, die automatisch einen Knotennamen für sich selbst wählen (unter Verwendung der Geräte-ID), müssen Sie für jeden hinzugefügten Zeugen einen Namen wählen, und sicherstellen, dass die Namen eindeutig sind. In den folgenden Beispielen wird „witness1“ verwendet.

Mit der Antwort des NetHSM auf die Registrierung des Zeugen bereiten Sie die Variablen des Formulars vor:

export ETCD_NAME="witness1"
export ETCD_DATA_DIR="/var/etcd/data"
export ETCD_INITIAL_CLUSTER="peer1=url1,peer1=url2,peer2=url1,peer2=url2,..."
export ETCD_INITIAL_ADVERTISE_PEER_URLS="my_url1,my_url2,..."

Assuming the join data file written by nitropy (or the NetHSM REST API response) is stored in a response.json file, you can generate these last two variables automatically with the following jq expressions:

export ETCD_INITIAL_CLUSTER=$(jq --raw-output '[.members[] | ["\(if .name == "" then "witness1" else .name end)=\(.urls[])"]] | flatten | join(",")' < response.json)
export ETCD_INITIAL_ADVERTISE_PEER_URLS=$(jq --raw-output '.members[] | select(.name=="") | .urls | join(",")' < response.json)

For example with the example response provided in the Registering a New Node section, you will have:

ETCD_NAME="witness1"
ETCD_DATA_DIR="/var/etcd/data"
ETCD_INITIAL_CLUSTER="witness1=https://172.22.1.3:2380,9ZVNM2MNWP=https://172.22.1.2:2380"
ETCD_INITIAL_ADVERTISE_PEER_URLS="https://172.22.1.3:2380"

Erstellen Sie schließlich eine Datei etcd.conf.yml unter Verwendung der in docs/etcd_witness.conf.template bereitgestellten Vorlagendatei:

$ envsubst < NETHSM_ROOT/docs/etcd_witness.conf.template > /var/etcd/witness.conf.yml
$ cat witness.conf.yml

Damit sollten Sie eine Datei des Formulars erhalten:

name: witness1
data-dir: /var/etcd/data
log-level: warn
log-format: console

listen-peer-urls: https://0.0.0.0:2380
listen-client-urls: http://localhost:2379

initial-advertise-peer-urls: https://172.22.1.3:2380
advertise-client-urls: http://localhost:2379
initial-cluster: witness1=https://172.22.1.3:2380,9ZVNM2MNWP=https://172.22.1.2:2380
initial-cluster-state: 'existing'

peer-transport-security:
  cert-file: witness.pem
  key-file: witness.key
  client-cert-auth: true
  trusted-ca-file: CA.pem
  skip-client-san-verification: true

Start etcd¶

Starten Sie etcd auf die von Ihnen bevorzugte Weise (manuell, systemd Dienst, Container usw.) und verweisen Sie dabei auf die im vorherigen Schritt erstellte Konfigurationsdatei:

$ cd /var/etcd
$ etcd --config-file witness.conf.yml

Sie sollten sehen, wie es startet, sich dem Cluster als „Lerner“ anschließt und die Daten nachholt.

Promote the Witness¶

Befolgen Sie schließlich nach einiger Zeit die üblichen Anweisungen aus dem Abschnitt „ : Beförderung des neuen Lernenden“, um den Zeugen zu befördern. Sollte dies nicht funktionieren, versuchen Sie es später erneut.

After a successful promotion, you should be able to check that it is healthy with the etcdctl client:

etcdctl get /config/version

Dieser Schlüssel muss vorhanden sein und eine „1“ enthalten.

Make sure this process keeps running, as it is now a proper member of your cluster. If you need to decommission it, first properly remove it from the cluster. If its reachable IP changes, update its URL from the cluster.

Operating a Cluster¶

Sichern und Wiederherstellen¶

Der Sicherungsvorgang funktioniert genauso wie ohne Cluster und kann von jedem Knoten des Clusters angefordert werden. Es werden die Daten des gesamten Clusters gesichert, einschließlich knotenspezifischer Felder (diese werden jedoch ignoriert, es sei denn, die Sicherung wird auf einem nicht bereitgestellten Knoten wiederhergestellt).

Eine auf einem Cluster erstellte Sicherung kann auf demselben Cluster wiederhergestellt werden, auch wenn seitdem einige Knoten hinzugefügt oder entfernt wurden. Solche Wiederherstellungen auf operativen Clustern wirken sich nicht auf die Konfigurationswerte aus (nur Schlüssel, Benutzer, Namespaces), wie jede andere teilweise Wiederherstellung.

Bei der Wiederherstellung eines Backups auf einem nicht bereitgestellten Knoten werden die knotenspezifischen Felder (wie Netzwerkkonfiguration, Zertifikate usw.) des Knotens wiederhergestellt, der zur Erstellung des Backups verwendet wurde.

Die Wiederherstellung einer umfangreichen Sicherung kann den Cluster für einige Zeit überlasten, während der Knoten, der die Wiederherstellung durchführt, Änderungen an die anderen weiterleitet.

Dieser Vorgang ist mit Sicherungen kompatibel, die mit früheren Versionen von NetHSM erstellt wurden.

Bemerkung

Wird auf einem Knoten A eine Sicherung wiederhergestellt, die auf einem anderen Knoten Z mit einem anderen Domänenschlüssel erstellt wurde, wird der Domänenschlüssel von A wie zuvor korrekt neu geschrieben. Befindet sich A jedoch in einem Cluster mit Knoten B, ist B nicht mehr funktionsfähig, da der Domänenschlüssel von Z auf B nicht wiederhergestellt wird.

Mit anderen Worten: Führen Sie eine Wiederherstellung nur in einem Cluster durch, dessen Sicherungen im selben Cluster erstellt wurden (auch wenn seitdem wieder Knoten entfernt oder hinzugefügt wurden). Wenn Sie eine fremde Sicherung auf einem Knoten wiederherstellen wollen, entfernen Sie ihn zunächst sicher aus seinem Cluster, setzen ihn dann auf Werkseinstellungen zurück und stellen die Sicherung wieder her.

Sauberes Entfernen eines Knotens¶

Solange ein Teil des Clusters noch beschlussfähig ist, kann jedes seiner Mitglieder verwendet werden, um einen anderen Knoten aus dem Cluster zu entfernen, unabhängig davon, ob dieser Knoten bereits unerreichbar ist oder dies erwartet wird.

You first have to know the ID of the node you want to remove, by listing all nodes and looking for the right one. Then it can be removed. If the node in question was still healthy, this will isolate it from the rest of the cluster and transition it to the Failed state.

Argumente

Argument	Beschreibung
`MEMBER_ID`	The ID of the node to be removed

Beispiel

$ nitropy nethsm --host $NETHSM_HOST remove-cluster-member $MEMBER_ID

Bemerkung

Ein Knoten, der dem Cluster beigetreten ist, aber noch nicht befördert wurde, kann auf diese Weise ebenfalls sicher entfernt werden.

Recovering a Failed Node¶

Ein Knoten, der den Status „ “ („Fehler: “) meldet, reagiert auf die meisten normalen Befehle nicht mehr. Er kann dennoch heruntergefahren, neu gestartet, zurückgesetzt , diagnostiziert oder isoliert werden.

Warnung

Die folgenden Operationen – „ “, „Failed “, „ ` “, „diagnose` “ und „ ` “ sowie „force-new` “ – gelten nur für Version 5.0 und höher. In Version 4.0 reagiert ein Knoten mit verlorenem Quorum nicht mehr auf alle Anfragen. Er muss auf die Werkseinstellungen zurückgesetzt werden.

Zu den häufigen Ursachen dafür, dass sich ein Knoten im Status „ Failed“ befindet, gehören:

Ein dauerhaft fehlendes Quorum.
Ein vorübergehender Verlust der Beschlussfähigkeit (z. B. beim Hinzufügen eines zweiten Knotens zum Cluster, wenn dieser noch nicht dem Cluster beigetreten ist).
etcd wird derzeit neu gestartet (z. B. weil sich die Zertifikate geändert haben oder das Netzwerk neu konfiguriert wurde).
Der Cluster ist einer sehr hohen Auslastung ausgesetzt (z. B. während der Wiederherstellung eines sehr umfangreichen Backups).

Unabhängig vom Grund wechselt der NetHSM erst dann in den Status „ Failed“, nachdem mindestens eine volle Minute lang erfolglose Versuche unternommen wurden, mit seiner Datenbank zu kommunizieren. Damit sollen unerwünschte Statuswechsel vermieden werden, die durch sehr kurze Instabilitäten verursacht werden.

To help you understand which case your node is in, the diagnose function remains available and returns information about the current status of etcd and its database, including logs.

Beispiel

$ nitropy nethsm --host $NETHSM_HOST get-cluster-diagnostics

Bemerkung

Sobald die Datenbank wieder verfügbar ist (z. B. wenn das Quorum wiederhergestellt ist, weil das Netzwerkproblem behoben wurde), wechselt das NetHSM automatisch aus dem Status „ Failed“ in den vorherigen Status (oder setzt die normale Startsequenz fort, falls es gerade gestartet wurde), ohne dass manuelle Maßnahmen erforderlich sind. Es dauert bis zu einer Minute nach Behebung des Problems, bis sich der Cluster stabilisiert hat, das HSM die Behebung erkennt und den Zustand wechselt.

Wenn Sie zu dem Schluss kommen, dass der Fehler dauerhaft ist (z. B. Verlust des Quorums ohne Aussicht auf Behebung der zugrunde liegenden Ursache), haben Sie folgende Möglichkeiten:

Setzen Sie den Knoten auf die Werkseinstellungen zurück, wodurch alle Daten gelöscht werden, und stellen Sie ein Backup wieder her.
Isolate the node with nitropy nethsm force-new-cluster (REST API: POST /cluster/force-new), which will irreversibly forget all other cluster members, recover the etcd data present on disk and reboot. If the underlying failure was cluster-related, the node will follow the normal boot sequence and end up in either the Locked or Operational state depending on the unattended boot setting.

Bemerkung

If a node is isolated with force-new, it will desynchronized with the cluster: any new writes on it or the cluster cannot be reconciled. The node can still rejoin the cluster but will lose all its local modifications.

The force-new operation, which is only available in the Failed state, requires authentication as it is potentially destructive. However since HSM users and roles are not available in that state, the endpoint expects HTTPS clients to always authenticate with the unlock fake user, and the latest known unlock passphrase as the password. With nitropy, pass them as --username unlock --password $UNLOCK_PASSPHRASE:

$ nitropy nethsm --host $NETHSM_HOST --username unlock --password $UNLOCK_PASSPHRASE force-new-cluster

Warnung

Nach einem Update von einer Version < 5.0 wird der Endpunkt „ ` “ force-new` immer den Status „Unauthorized“ anzeigen, bis das HSM entsperrt oder die Entsperr-Passphrase mindestens einmal geändert wurde.

Software Updates in Clusters¶

Zukünftige Aktualisierungen werden als „cluster-safe“ (dies sollte die Mehrheit sein) oder „cluster-unsafe“ gekennzeichnet.

Cluster-sichere Aktualisierungen können auf Knoten angewandt werden, die Teil eines Clusters sind, ohne sie vorher aus dem Cluster zu entfernen. Wie bei allen Vorgängen sollten Sie jedoch sicherstellen, dass Sie dies jeweils auf einem Knoten und in einem Cluster tun, in dem das Entfernen eines Knotens nicht zu einer Unterschreitung des Quorums führt (z. B. wenn die Aktualisierung fehlschlägt).

Cluster-unsichere Updates müssen auf isolierte Knoten angewendet werden. Sie sollten den Cluster auflösen (indem Sie einen Knoten nach dem anderen entfernen), alle Knoten bis auf einen auf Werkseinstellungen zurücksetzen, das Update auf jeden Knoten anwenden und dann alle zurückgesetzten Knoten dem verbleibenden Knoten hinzufügen.

Stellen Sie sicher, dass Sie vor solchen Vorgängen ein Backup erstellen.

Rekonfigurieren eines bestehenden Clusters¶

Changing the Cluster CA¶

Ein bestehender Cluster (mit zwei oder mehr Knoten) kann seine Cluster-CA im laufenden Betrieb nicht ändern. Wenn Sie dieses Zertifikat ändern müssen: Wählen Sie einen Knoten aus, entfernen Sie alle anderen Knoten, aktualisieren Sie die CA, und lassen Sie die anderen Mitglieder wieder beitreten.

Changing the Network Configuration of Nodes¶

Wenn Sie die Netzwerkkonfiguration eines Knotens ändern (z. B. seine IP-Adresse), werden die anderen Knoten automatisch über die Aktualisierung informiert. Sie sollten jedoch sicherstellen, dass Sie solche Aktualisierungen jeweils nur an einem einzigen Knoten vornehmen, und zwar in einem Cluster, in dem der Verlust dieses Knotens nicht zum Verlust des Quorums führen würde.