Änderungen von Dokument NATS - Technisches Setup

Zusammenfassung

• Seiteneigenschaften (3 geändert, 0 hinzugefügt, 0 gelöscht)
• Objekte (1 geändert, 0 hinzugefügt, 0 gelöscht)
  • Confluence.Code.ConfluencePageClass[0]

Details

Seiteneigenschaften

Titel

...	...	@@ -1,1 +1,1 @@
1		-NATS - Technisches Setup
	1	+NATS Setup

Übergeordnete Seite

...	...	@@ -1,1 +1,0 @@
1		-PROJ.Digitale Mitgliederverwaltung.Technische Dokumentation.WebHome

Inhalt

...	...	@@ -2,9 +2,9 @@
2	2
3	3	Unser Backend (oder auch andere Systeme) publizieren Events in NATS, die dann beispielsweise in N8n über ein Trigger konsumiert werden.
4	4
5		-= Grundlagen =
	5	+= {{id name="NATSSetup-Grundlagen"/}}Grundlagen =
6	6
7		-== Übersicht ==
	7	+== {{id name="NATSSetup-Übersicht"/}}Übersicht ==
8	8
9	9	NATS kann grob in zwei Varianten unterteilt werden, **NATS Core** und **NATS JetStream**.
10	10
...	...	@@ -12,17 +12,17 @@
12	12
13	13	NATS JetStream erweitert NATS Core um Funktionen wie **Persistenz, wiederholtes Lesen von Nachrichten und zeitversetzte Verarbeitung**. Nachrichten können gespeichert werden, was eine zuverlässige Zustellung, Wiederholungen und komplexe Workflows ermöglicht. JetStream ist damit besonders geeignet für Szenarien, in denen eine dauerhafte Verarbeitung oder Event-Sourcing erforderlich ist, während Core eher für schnelle, vorübergehende Nachrichtenübertragung optimiert ist.
14	14
15		-== Accounts ==
	15	+== {{id name="NATSSetup-Accounts"/}}Accounts ==
16	16
17		-(% style="color:var(--ds-text,#333333); text-decoration:none" %)Accounts sind eine Möglichkeit, Mandanten oder Anwendungen innerhalb eines Clusters oder NATS Servers voneinander abzugrenzen. Jeder Account besitzt einen eigenen Namespace für Subjekte, verwaltet seine Benutzer und deren Berechtigungen und bietet so eine klare Trennung zwischen unterschiedlichen Workloads. Gleichzeitig lassen sich über Exports und Imports bestimmte Subjekte gezielt mit anderen Accounts teilen, sodass Kommunikation zwischen getrennten Bereichen möglich bleibt. Auf diese Weise stellen Accounts die Grundlage für Multi-Tenancy, Sicherheit und flexible Skalierung in NATS dar.
	17	+(% style="text-decoration: none;color:var(--ds-text,#333333);" %)Accounts sind eine Möglichkeit, Mandanten oder Anwendungen innerhalb eines Clusters oder NATS Servers voneinander abzugrenzen. Jeder Account besitzt einen eigenen Namespace für Subjekte, verwaltet seine Benutzer und deren Berechtigungen und bietet so eine klare Trennung zwischen unterschiedlichen Workloads. Gleichzeitig lassen sich über Exports und Imports bestimmte Subjekte gezielt mit anderen Accounts teilen, sodass Kommunikation zwischen getrennten Bereichen möglich bleibt. Auf diese Weise stellen Accounts die Grundlage für Multi-Tenancy, Sicherheit und flexible Skalierung in NATS dar.
18	18
19		-(% style="color:var(--ds-text,#333333); text-decoration:none" %)Wir verwenden zwei verschiedene Accounts:
	19	+(% style="text-decoration: none;color:var(--ds-text,#333333);" %)Wir verwenden zwei verschiedene Accounts:
20	20
21		-|=(((
	21	+|=(% scope="col" %)(((
22	22	Account
23		-)))|=(((
	23	+)))|=(% scope="col" %)(((
24	24	Berechtigungen
25		-)))|=(((
	25	+)))|=(% scope="col" %)(((
26	26	Beschreibung
27	27	)))
28	28	|(((
...	...	@@ -42,9 +42,9 @@
42	42
43	43	Benutzer können jeweils nur einem Account zugeordnet werden.
44	44
45		-== Authentifizierung ==
	45	+== {{id name="NATSSetup-Authentifizierung"/}}Authentifizierung ==
46	46
47		-Die Kommunikation ist TLS verschlüsselt, es kommen die TLS Zertifikate aus [[HashiCorp KeyVault>>doc:xwiki:IN.IT Infrastruktur.Services.Hashicorp Vault.WebHome]] zum Einsatz. Diese werden dann einzelnen Accounts zugewiesen. Der NATS Server validiert das Zertifikat an Hand der Zertifikatskette und mapt dann die Zertifikatsinformationen zu einem User. Üblicherweise wird dabei ein SAN (Subject Alternative Name) in Form einer Mail-Adresse verwendet. Diese gibt es in unserem Fall nicht, sodass das Subject verwendet wird. Wichtig ist, dass das Subject in RFC2253 Form verwendet werden muss.
	47	+Die Kommunikation ist TLS verschlüsselt, es kommen die TLS Zertifikate aus [[HashiCorp KeyVault>>confluencePage:page:IN.Hashicorp Vault]] zum Einsatz. Diese werden dann einzelnen Accounts zugewiesen. Der NATS Server validiert das Zertifikat an Hand der Zertifikatskette und mapt dann die Zertifikatsinformationen zu einem User. Üblicherweise wird dabei ein SAN (Subject Alternative Name) in Form einer Mail-Adresse verwendet. Diese gibt es in unserem Fall nicht, sodass das Subject verwendet wird. Wichtig ist, dass das Subject in RFC2253 Form verwendet werden muss.
48	48
49	49	{{code language="shell"}}
50	50	$ openssl x509 -noout -text -nameopt RFC2253 -in backend.mksp-da.de.crt
...	...	@@ -56,7 +56,7 @@
56	56
57	57	Diese Subject wird dann dem Account zugeordnet:
58	58
59		-{{code}}
	59	+{{code language="json"}}
60	60	system_account: SYS
61	61	accounts: {
62	62	MKSP: {
...	...	@@ -83,11 +83,11 @@
83	83
84	84	Da ein User nur einem Account zugeordnet werden kann, gibt es einen admin User für administrative Tätigkeiten sowie einen JetStream Admin User für die Account-Verwaltung.
85	85
86		-== NATS Core mit Accounts ==
	86	+== {{id name="NATSSetup-NATSCoremitAccounts"/}}NATS Core mit Accounts ==
87	87
88	88	Damit die NATS Core Messages auch weiterhin funktionieren müssen publish und subscribe Berechtigungen vergeben werden. NATS wird neben dem Eventmanagement auch noch für die Task Queue mit Taskiq eingesetzt, hier werden zur Zeit noch Core Funktionalitäten verwendet. Daher muss die Berechtigung für den backend User erweitert werden:
89	89
90		-{{code}}
	90	+{{code language="json"}}
91	91	accounts: {
92	92	MKSP: {
93	93	users: [
...	...	@@ -103,11 +103,11 @@
103	103
104	104	Wichtig sind hier die zusätzlichen Permissions, die den Zugriff auf Core Events regeln.
105	105
106		-== JetStream Konfiguration ==
	106	+== {{id name="NATSSetup-JetStreamKonfiguration"/}}JetStream Konfiguration ==
107	107
108	108	In unserem Fall ist Persistenz auch bei einem zeitweisen Ausfall der Internetverbindung im Makerspace notwendig, sodass wir JetStream mit Message Retention verwenden. Dabei müssen die wichtigen Komponenten vorab angelegt werden.
109	109
110		-=== NATS CLI konfigurieren ===
	110	+=== {{id name="NATSSetup-NATSCLIkonfigurieren"/}}NATS CLI konfigurieren ===
111	111
112	112	Zur Administration bietet sich die Verwendung der [[NATS CLI >>url:https://github.com/nats-io/natscli||shape="rect"]]an. Diese muss einmalig eingerichtet werden, dafür sind die entsprechenden Zertifikatsdateien notwendig. Wir legen zwei Kontexte an, einen für den Cluster Admin, einen für den JetStream Admin:
113	113
...	...	@@ -114,7 +114,7 @@
114	114	{{code language="shell"}}
115	115	nats context add mksp-sysadmin --server ds-hetzner.mksp-da.de:4222 --description "MKSP NATS SYS Admin" --tlscert /path/to/admin.mksp-da.de.crt --tlskey /path/to/admin.mksp-da.de.key --tlsca /path/to/mksp_root_x1_ca.crt
116	116
117		-nats context add mksp-jsadmin --server ds-hetzner.mksp-da.de:4222 --description "MKSP NATS JetStream" --tlscert /path/to/js-admin.mksp-da.de.crt --tlskey /path/to/js-admin.mksp-da.de.key --tlsca /path/to/mksp_root_x1_ca.crt
	117	+nats context add mksp-jsadmin --server ds-hetzner.mksp-da.de:4222 --description "MKSP NATS JetStream" --tlscert /path/to/jsadmin.mksp-da.de.crt --tlskey /path/to/jsadmin.mksp-da.de.key --tlsca /path/to/mksp_root_x1_ca.crt
118	118	{{/code}}
119	119
120	120	Anschließend wählen wir den richtigen Kontext aus, in diesem Fall den JetStream Admin Context:
...	...	@@ -123,7 +123,7 @@
123	123	nats context select mksp-jsadmin
124	124	{{/code}}
125	125
126		-=== JetStream initialisieren ===
	126	+=== {{id name="NATSSetup-JetStreaminitialisieren"/}}JetStream initialisieren ===
127	127
128	128	JetStream ist in so genannte **Streams** unterteilt, welche bestimmte **Subjects** in einem Stream zusammenfassen. Wir nutzen für alle Events einen gemeinsamen Präfix (mksp), sodass wir den Stream hierfür erstellen. Die NATS Dokumentation selbst beschreibt die Konzepte sehr gut:
129	129
...	...	@@ -136,89 +136,83 @@
136	136	nats stream add backend_events --subjects "mksp.>" --retention work --max-age 7d --storage file --defaults
137	137	{{/code}}
138	138
139		-=== JetStream Consumer ===
	139	+=== {{id name="NATSSetup-JetStreamConsumer"/}}JetStream Consumer ===
140	140
141	141	Consumer sind eine Auswahl / Ansicht von Teilen eines Streams. Details finden sich wieder in der NATS Dokumentation: [[https:~~/~~/docs.nats.io/nats-concepts/jetstream/consumers>>url:https://docs.nats.io/nats-concepts/jetstream/consumers||shape="rect"]]
142	142
143	143	Consumer können entweder persistent sein (dauerhaft, ein Client kann dann den bestehenden Consumer neben) oder flüchtig (ephemeral), in diesem Fall wird der Consumer beim Erstellen des Clients (beispielsweise durch N8n) angelegt. In der Regel werden Consumer durch einen Filter auf bestimmte Subjects beschränkt, diese dürfen sich nicht überschneiden. Da die NATS JavaScript Client Library (die von n8n verwendet wird) es leider nicht sinnvoll erlaubt, ephemeral Consumer anzulegen verwenden wir dauerhafte Consumer-Namen.
144	144
145		-|=(((
	145	+|=(% scope="col" %)(((
146	146	Backend Event
147		-)))|=(((
	147	+)))|=(% scope="col" %)(((
148	148	Consumer Name
149		-)))|=(((
	149	+)))|=(% scope="col" %)(((
150	150	Schema
151	151	)))
152	152	|(((
153		-{{{mksp.backend.briefing.offer.cancelled}}}
154		-
155		-(((
156		-
157		-)))
	153	+{{code language="none"}}
	154	+mksp.backend.briefing.offer.cancelled
	155	+{{/code}}
158	158	)))|(((
159	159	backend_briefing_offer_cancelled
160	160	)))|(((
161		-(% class="nc" %)##BriefingOfferEvent##
	159	+##(% class="nc" %)BriefingOfferEvent(%%)##
162	162	)))
163	163	|(((
164		-{{{mksp.backend.briefing.offer.created}}}
165		-
166		-(((
167		-
168		-)))
	162	+{{code language="none"}}
	163	+mksp.backend.briefing.offer.created
	164	+{{/code}}
169	169	)))|(((
170	170	backend_briefing_offer_created
171	171	)))|(((
172		-(% class="nc" %)##BriefingOfferEvent##
	168	+##(% class="nc" %)BriefingOfferEvent(%%)##
173	173	)))
174	174	|(((
175		-{{{mksp.backend.briefing.offer.updated}}}
	171	+##(% class="s" %)mksp.backend.briefing.offer.updated(%%)##
176	176	)))|(((
177	177	backend_briefing_offer_updated
178	178	)))|(((
179		-(% class="nc" %)##BriefingOfferEvent##
	175	+##(% class="nc" %)BriefingOfferEvent(%%)##
180	180	)))
181	181	|(((
182		-{{{mksp.backend.briefing.created}}}
183		-
184		-(((
185		-
186		-)))
	178	+{{code language="none"}}
	179	+mksp.backend.briefing.created
	180	+{{/code}}
187	187	)))|(((
188	188	backend_briefing_created
189	189	)))|(((
190		-(% class="n" %)##BriefingEvent##
	184	+##(% class="n" %)BriefingEvent(%%)##
191	191	)))
192	192	|(((
193		-{{{mksp.backend.key.assigned}}}
	187	+##(% class="s" %)mksp.backend.key.assigned(%%)##
194	194	)))|(((
195	195	backend_key_assigned
196	196	)))|(((
197		-(% class="nc" %)##KeyEvent##
	191	+##(% class="nc" %)KeyEvent(%%)##
198	198	)))
199	199	|(((
200		-{{{mksp.backend.key.unassigned}}}
	194	+##(% class="s" %)mksp.backend.key.unassigned(%%)##
201	201	)))|(((
202	202	backend_key_unassigned
203	203	)))|(((
204		-(% class="nc" %)##KeyEvent##
	198	+##(% class="nc" %)KeyEvent(%%)##
205	205	)))
206	206	|(((
207		-{{{mksp.backend.storage.reserved}}}
	201	+##(% class="s" %)mksp.backend.storage.reserved(%%)##
208	208	)))|(((
209	209	backend_storage_reserved
210	210	)))|(((
211		-(% class="nc" %)##StorageSpaceEvent##
	205	+##(% class="nc" %)StorageSpaceEvent(%%)##
212	212	)))
213	213	|(((
214		-mksp.backend.storage.released
	208	+(% class="s" %){{code language="none"}}mksp.backend.storage.released{{/code}}
215	215	)))|(((
216	216	backend_storage_released
217	217	)))|(((
218		-(% class="nc" %)##StorageSpaceEvent##
	212	+##(% class="nc" %)StorageSpaceEvent(%%)##
219	219	)))
220	220	|(((
221		-mksp.backend.storage.expired
	215	+(% class="s" %){{code language="none"}}mksp.backend.storage.expired{{/code}}
222	222	)))|(((
223	223	backend_storage_expired
224	224	)))|(((
...	...	@@ -225,7 +225,7 @@
225	225	(% class="nc" %){{code language="none"}}StorageSpaceEvent{{/code}}
226	226	)))
227	227	|(((
228		-mksp.backend.user.converted_to_member
	222	+(% class="s" %){{code language="none"}}mksp.backend.user.converted_to_member{{/code}}
229	229	)))|(((
230	230	backend_user_converted_to_member
231	231	)))|(((
...	...	@@ -232,49 +232,19 @@
232	232	(% class="nc" %){{code language="none"}}UserEvent{{/code}}
233	233	)))
234	234	|(((
235		-mksp.backend.user.converted_to_guest
	229	+(% class="s" %){{code language="none"}}mksp.backend.user.converted_to_guest{{/code}}
236	236	)))|(((
237	237	backend_user_converted_to_guest
238	238	)))|(((
239	239	(% class="nc" %){{code language="none"}}UserEvent{{/code}}
240	240	)))
241		-|(((
242		-mksp.backend.user.created
243		-)))|backend_user_created|UserEvent
244		-|(((
245		-mksp.docuseal.document.signed
246		-)))|docuseal_document_signed|(((
247		-SignatureEvent
248		-)))
249		-|(((
250		-mksp.docuseal.signature.expired
251		-)))| |(((
252		-SignatureEvent
253		-)))
254		-|(((
255		-mksp.docuseal.signature.completed
256		-)))| |(((
257		-SignatureEvent
258		-)))
259	259
260		-Die Consumer können dann wie folgt angelegt werden:
	236	+= {{id name="NATSSetup-Troubleshooting"/}}Troubleshooting =
261	261
262		-{{code}}
263		-$ nats consumer add backend_events <name> --pull --filter="<filter>" --defaults
264		-
265		-# Beispiel
266		-nats consumer add backend_events backend_briefing_offer_cancelled --pull --filter="mksp.backend.briefing.offer.cancelled" --defaults
267		-nats consumer add backend_events backend_key_assigned --pull --filter="mksp.backend.key.assigned" --defaults
268		-{{/code}}
269		-
270		-= Troubleshooting =
271		-
272	272	Man kann über die NATS CLI mit dem Server interagieren.
273	273
274		-== JetStream ==
	240	+== {{id name="NATSSetup-JetStream"/}}JetStream ==
275	275
276		-=== Streams ===
277		-
278	278	Man kann sich die vorhandenen Streams und die Anzahl der Nachrichten anschauen. Die Anzahl sollte üblicherweise 0 sein, wenn die Zahl höher ist, werden Events nicht richtig abgearbeitet.
279	279
280	280	{{code language="shell"}}
...	...	@@ -299,63 +299,8 @@
299	299	{"timestamp":"2025-09-08T09:06:00.062358","stora
300	300	{{/code}}
301	301
302		-=== Consumer ===
	266	+== {{id name="NATSSetup-Server"/}}Server ==
303	303
304		-Die bestehenden Consumer kann man sich ebenfalls im Jetstream Context anzeigen lassen:
305		-
306		-{{code}}
307		-$ nats consumer ls backend_events
308		-╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
309		-│ Consumers │
310		-├──────────────────────────────────┬─────────────┬─────────────────────┬─────────────┬─────────────┬───────────────┤
311		-│ Name │ Description │ Created │ Ack Pending │ Unprocessed │ Last Delivery │
312		-├──────────────────────────────────┼─────────────┼─────────────────────┼─────────────┼─────────────┼───────────────┤
313		-│ backend_briefing_created │ │ 2025-09-10 08:30:12 │ 0 │ 12 │ never │
314		-│ backend_briefing_offer_cancelled │ │ 2025-09-10 08:21:02 │ 0 │ 0 │ never │
315		-│ backend_briefing_offer_created │ │ 2025-09-10 08:28:25 │ 0 │ 0 │ never │
316		-│ backend_briefing_offer_updated │ │ 2025-09-10 08:29:19 │ 0 │ 0 │ never │
317		-│ backend_key_assigned │ │ 2025-09-10 08:21:04 │ 0 │ 0 │ never │
318		-╰──────────────────────────────────┴─────────────┴─────────────────────┴─────────────┴─────────────┴───────────────╯
319		-{{/code}}
320		-
321		-In dieser Tabelle sieht man bereits die "unprocessed" Nachrichten. Ist diese Zahl größer als 0 s sieht also gut, wenn n8n die Nachrichten nicht korrekt verarbeitet. Man kann sich ebenfalls die Details eines Consumers anzeigen lassen:
322		-
323		-{{code}}
324		-$ nats consumer info backend_events backend_briefing_offer_cancelled
325		-
326		-Information for Consumer backend_events > backend_briefing_offer_cancelled created 2025-09-09 22:53:26
327		-
328		-Configuration:
329		-
330		- Name: backend_briefing_offer_cancelled
331		- Pull Mode: true
332		- Filter Subject: mksp.backend.briefing.offer.cancelled
333		- Deliver Policy: All
334		- Ack Policy: Explicit
335		- Ack Wait: 30.00s
336		- Replay Policy: Instant
337		- Max Ack Pending: 1,000
338		- Max Waiting Pulls: 512
339		-
340		-State:
341		-
342		- Host Version: 2.11.8
343		- Required API Level: 0 hosted at level 1
344		- Last Delivered Message: Consumer sequence: 0 Stream sequence: 10
345		- Acknowledgment Floor: Consumer sequence: 0 Stream sequence: 0
346		- Outstanding Acks: 0 out of maximum 1,000
347		- Redelivered Messages: 0
348		- Unprocessed Messages: 0
349		- Waiting Pulls: 1 of maximum 512
350		-{{/code}}
351		-
352		-Insbesondere die letzten beiden Zeilen sind wichtig:
353		-
354		-* **Unprocessed Messages** sind Nachrichten, die noch nicht abgerufen wurden. Dies sollte immer 0 sein
355		-* **Waiting Pulls**: die Anzahl der verbundenen Clients. Üblicherweise sollte das nur n8n sein, also immer 1.
356		-
357		-== Server ==
358		-
359	359	Man kann sich ebenfalls die aktiven Verbindungen anzeigen:
360	360
361	361	{{code language="shell"}}
...	...	@@ -388,15 +388,15 @@
388	388
389	389	Der Name ist hierbei frei vergeben, in unserem Fall im Backend Code. Wir erwarten die folgenden Clients:
390	390
391		-|=(((
	300	+|=(% scope="col" %)(((
392	392	Client
393		-)))|=(((
	302	+)))|=(% scope="col" %)(((
394	394	Anzahl
395		-)))|=(((
	304	+)))|=(% scope="col" %)(((
396	396	Komponente
397		-)))|=(((
	306	+)))|=(% scope="col" %)(((
398	398	Art
399		-)))|=(((
	308	+)))|=(% scope="col" %)(((
400	400	Beschreibung
401	401	)))
402	402	|(((
...	...	@@ -504,4 +504,4 @@
504	504	]
505	505	{{/code}}
506	506
507		-
	416	+\\

Confluence.Code.ConfluencePageClass[0]

Id

...	...	@@ -1,1 +1,1 @@
1		-207814660
	1	+207814676

URL

...	...	@@ -1,1 +1,1 @@
1		-https://wiki.makerspace-darmstadt.de/spaces/PROJ/pages/207814660/NATS Setup
	1	+https://wiki.makerspace-darmstadt.de/spaces/PROJ/pages/207814676/NATS Setup