StyleBook zum Erstellen eines Lastausgleichs-Virtual-Servers
In diesem Beispiel entwerfen Sie ein grundlegendes StyleBook, das einen Lastausgleichs-Virtual-Server vom HTTP-Protokolltyp erstellt, der auf Port 80 lauscht. Die Parameter für den Namen des Virtual Servers, die IP-Adresse und die Lastausgleichsmethode akzeptieren benutzerdefinierte Werte, d. h. sie sind die Parameter des StyleBooks.
Header
Die ersten sechs Zeilen eines StyleBooks bilden den Header-Abschnitt. In diesem Beispiel ist der Header-Abschnitt wie folgt geschrieben:
name: lb-vserver
description: This StyleBook defines a load balancing virtual server configuration.
display-name: Load Balancing Virtual Server (HTTP)
namespace: com.example.stylebooks
schema-version: "1.0"
version: "0.1"
<!--NeedCopy-->
Der Header-Abschnitt enthält die folgenden Details:
-
name: Ein Name für dieses StyleBook.
-
description: Eine Beschreibung, die definiert, was dieses StyleBook tut. Diese Beschreibung erscheint in NetScaler® ADM.
-
display-name: Ein beschreibender Name für das StyleBook, der in NetScaler ADM erscheint.
-
namespace: Ein Namespace ist Teil eines eindeutigen Identifikators für ein StyleBook, um Namenskollisionen zu vermeiden.
-
schema-version: Nimmt in dieser Version immer den Wert „1.0“ an.
-
version: Die Versionsnummer des StyleBooks. Sie können die Versionsnummer ändern, wenn Sie das StyleBook aktualisieren.
Die Kombination aus name, namespace und version identifiziert ein StyleBook im System eindeutig. Sie können in NetScaler ADM keine zwei StyleBooks mit derselben Kombination aus Name, Namespace und Version haben. Sie können jedoch zwei StyleBooks mit demselben Namen und derselben Version, aber unterschiedlichen Namespaces, oder mit demselben Namespace und derselben Version, aber unterschiedlichen Namen haben.
Hinweis
Angenommen, Sie haben Ihr StyleBook aktualisiert und eine aktualisierte Versionsnummer. Wenn Sie dieses StyleBook nun in anderen StyleBooks referenzieren (d. h. importieren), stellen Sie sicher, dass Sie die Versionsnummer auch in den anderen StyleBooks aktualisieren, damit diese die korrekte Version des importierten StyleBooks verwenden.
StyleBooks importieren
Der Abschnitt nach dem Header wird „import-stylebooks“ genannt. In diesem Abschnitt müssen Sie den Namespace und die Versionsnummer jedes anderen StyleBooks deklarieren, auf das Sie in Ihrem aktuellen StyleBook verweisen möchten. Dies ermöglicht es Ihnen, andere StyleBooks zu importieren und wiederzuverwenden, anstatt dieselbe Konfiguration in Ihrem eigenen StyleBook neu zu erstellen.
In diesem Beispiel ist der Abschnitt „import-stylebooks“ wie folgt geschrieben:
import-stylebooks:
-
namespace: netscaler.nitro.config
prefix: ns
version: "10.5"
<!--NeedCopy-->
Jedes StyleBook muss auf den Namespace netscaler.nitro.config verweisen, wenn es NITRO-Konfigurationsobjekte direkt verwendet. Dieser Namespace enthält alle NetScaler NITRO-Typen, wie z. B. lbvserver. Da Softwareversionen 10.5 und höher unterstützt werden, können Sie Ihr StyleBook verwenden, um Konfigurationen auf jeder NetScaler-Instanz zu erstellen und auszuführen, die Release 10.5 und höher verwendet.
Das im Abschnitt „import-stylebooks“ verwendete Präfix ist eine Kurzform, um auf die Kombination aus Namespace und Version zu verweisen. In diesem Fall bezieht sich ns auf netscaler.nitro.config der Version 10.5. In den späteren Abschnitten Ihres StyleBooks können Sie, anstatt den Namespace und die Version zu verwenden, um auf das importierte StyleBook zu verweisen, die gewählte Präfixzeichenfolge, z. B. ns, im obigen Beispiel verwenden.
Die in den StyleBooks verwendete Version ist die NetScaler NITRO-Version. Ein StyleBook, das auf Nitro-Version X basiert, kann verwendet werden, um jeden NetScaler zu konfigurieren, der Version X oder höher ist.
Hinweis
Um sicherzustellen, dass Ihre StyleBooks zur Konfiguration jeder NetScaler-Instanz der Version 10.5 oder höher verwendet werden können, empfiehlt Citrix, dass Sie für maximale Kompatibilität den Nitro 10.5-Namespace in Ihren StyleBooks importieren sollten, die direkt integrierte Nitro-StyleBooks verwenden (Namespace: netscaler.nitro.config, Version: 10.5).
Es ist wichtig, dass ein StyleBook, das andere StyleBooks importiert, auf einer Nitro-Version basieren muss, die gleich oder höher ist als die Version der StyleBooks, die es importiert. Zum Beispiel kann ein StyleBook, das auf Nitro-Version 10.5 basiert, nicht von einem StyleBook abhängen, es verwenden oder importieren, das auf 11.1 basiert. Ein StyleBook, das auf Version 11.1 basiert, kann jedoch ein StyleBook importieren, das auf einer Version kleiner als 11.1 basiert.
Es ist auch möglich, dass ein StyleBook den Nitro-Namespace überhaupt nicht importiert. Das bedeutet, dass ein StyleBook Nitro-Komponenten nicht direkt definieren muss, sondern StyleBooks importieren (von ihnen abhängen) kann, die Nitro-Komponenten definieren. Das StyleBook, das andere StyleBooks importiert, übernimmt immer die höchste Nitro-Version in der Hierarchie seiner Abhängigkeiten und könnte daher verwendet werden, um NetScaler zu konfigurieren, die diese Version oder höher sind.
Parameter
Der Abschnitt „parameters“ ermöglicht es Ihnen, alle Parameter zu deklarieren, die Sie in Ihrem StyleBook benötigen. Sie als StyleBook-Entwickler müssen entscheiden, welche Eingaben die Benutzer Ihres StyleBooks angeben sollen. In diesem Beispiel haben Sie Ihr StyleBook so erstellt, dass seine Benutzer den Namen des Virtual Servers, seine IP-Adresse und die Lastausgleichsmethode angeben müssen.
Der Abschnitt „parameters“ würde wie folgt aussehen:
parameters:
-
name: name
type: string
label: Application Name
description: Name of the application configuration.
required: true
-
name: ip
type: ipaddress
label: Application Virtual IP (VIP)
description: Application VIP that the clients access.
required: true
-
name: lb-alg
type: string
label: LoadBalancing Algorithm
description: Choose the load balancing algorithm (method) used for load balancing client request between the application servers.
allowed-values:
- ROUNDROBIN
- LEASTCONNECTION
default: ROUNDROBIN
<!--NeedCopy-->
Hinweis
Wenn Sie das Label eines Parameters nicht angeben, verwendet NetScaler ADM das Attribut „name“ bei der Anzeige dieses Parameters. Sie müssen immer ein Label für Ihre Parameter definieren, damit Sie steuern können, wie sie in NetScaler ADM angezeigt werden.
Bei der Verwendung der APIs wird der Parameter jedoch durch seinen Namen bezeichnet.
In diesem Abschnitt haben Sie drei Parameter deklariert, die durch ihre name-Attributwerte gekennzeichnet sind – name für den Namen des Virtual Servers, ip für die IP-Adresse des Virtual Servers und lb-alg für die Lastausgleichsmethode.
- type. Der Typ des Werts, den diese Parameter annehmen können. Zum Beispiel können „name“ und „lb-alg“ einen String-Wert annehmen, und der „ip“-Wert muss vom Typ „ip address“ sein. Parameter in einem StyleBook können von einem der folgenden integrierten Typen sein:
- string. Eine Zeichenkette. Wenn keine Länge angegeben ist, kann der String-Wert eine beliebige Anzahl von Zeichen annehmen. Sie können die Länge eines String-Typs jedoch durch die Verwendung der Attribute „min-length“ und „max-length“ begrenzen.
- number. Eine ganze Zahl. Sie können die minimale und maximale Zahl, die dieser Typ annehmen kann, durch die Verwendung der Attribute „min-value“ und „max-value“ angeben.
- boolean. Kann entweder „true“ oder „false“ sein. Beachten Sie auch, dass alle Literale von YAML als Booleans betrachtet werden (zum Beispiel „Yes“ oder „No“).
- ipaddress. Eine Zeichenkette, die eine gültige IPv4- oder IPv6-Adresse darstellt.
- tcp-port. Eine Zahl zwischen 0 und 65535, die einen TCP- oder UDP-Port darstellt.
- password. Ein undurchsichtiger/geheimer String-Wert. Wenn NetScaler ADM einen Wert für diesen Parameter anzeigt, wird er als Sternchen (*****) dargestellt.
- certfile. Zertifikatsdatei.
- keyfile. Private Schlüsseldatei des Zertifikats.
- file. Ein Parameter dieses Typs erfordert, dass der Benutzer eine Datei hochlädt, zum Beispiel eine Zertifikats- oder Schlüsseldatei.
- object. Besteht aus mehreren Elementen, und jedes dieser Elemente ist ein Parameter. Dieser Typ kann verwendet werden, um mehrere verwandte Parameter unter einem übergeordneten Parameter zu gruppieren.
- required. Gibt an, ob ein Parameter obligatorisch oder optional ist. Wenn er auf „true“ gesetzt ist, ist der Parameter obligatorisch, und der Benutzer muss einen Wert für diesen Parameter angeben, wenn er Konfigurationen mit diesem StyleBook erstellt. Standardmäßig sind alle Parameter optional. In diesem Beispiel sind name und ip obligatorische Parameter, während lb-alg ein optionaler Parameter ist, dessen Standardwert „ROUNDROBIN“ ist.
Verwenden Sie das Attribut default, um einem optionalen Parameter einen Standardwert zuzuweisen. Wenn ein Benutzer beim Erstellen einer Konfiguration keinen Wert angibt, wird der Standardwert verwendet. Zum Beispiel ist für den Parameter lb-alg der Standardwert ROUNDROBIN.
Verwenden Sie das Attribut allowed-values, um spezifische Werte zu definieren, aus denen ein Benutzer beim Erstellen einer Konfiguration wählen kann. In diesem Beispiel haben Sie zwei Werte für den Parameter lb-alg angegeben – ROUNDROBIN und LEASTCONNECTION.
Wenn Sie Ihr StyleBook importieren und verwenden, zeigt NetScaler ADM ein Formular mit diesen drei Parametern an. Die für „name“ und „ip“ angezeigten Felder ermöglichen die Eingabe von String- und IP-Adresswerten, und das Feld „lb-alg“ wird als Dropdown-Liste mit „ROUNDROBIN“ als Standardwert angezeigt.
Hinweis
Zusätzlich zu den integrierten Typen kann ein Parameter ein anderes StyleBook als seinen Typ haben. Dies ist eine Möglichkeit, in anderen StyleBooks definierte Parameter wiederzuverwenden.
Komponenten
Der letzte Abschnitt in diesem StyleBook wird als Komponentenabschnitt bezeichnet und gilt als der wichtigste Abschnitt im StyleBook. In diesem Abschnitt definieren Sie die Konfigurationsobjekte, die vom StyleBook erstellt werden müssen.
Für dieses Beispiel müssen Sie den Komponentenabschnitt wie folgt schreiben:
components:
-
name: lbvserver-comp
type: ns::lbvserver
properties:
name: $parameters.name
servicetype: HTTP
ipv46: $parameters.ip
port: 80
lbmethod: $parameters.lb-alg
<!--NeedCopy-->
Dieses Beispiel enthält nur eine Komponente. Die Hauptattribute einer Komponente sind Name, Typ und Eigenschaften. Der Typ einer Komponente bestimmt, welche Eigenschaften diese Komponente bereitstellt. Komponenten sind von zwei Typen:
-
Integrierter Typ. Dieser Typ wird vom System bereitgestellt, und Sie müssen ihn nicht definieren, zum Beispiel die NITRO-Entitätstypen „lbvserver“ oder „servicegroup“. In diesem Beispiel verwenden Sie einen integrierten Komponententyp.
-
Zusammengesetzter Typ. Dieser Typ ist das StyleBook, das Sie erstellt und in NetScaler ADM importiert haben, oder das Standard-StyleBook, das mit NetScaler ADM ausgeliefert wird. Weitere Informationen zu zusammengesetzten StyleBooks finden Sie unter Ein zusammengesetztes StyleBook erstellen.
In diesem Beispiel haben Sie eine Komponente namens lbvserver-comp definiert. Diese Komponente ist vom Typ ns::lbvserver (ein integrierter Nitro-Typ), wobei „ns“ das Präfix ist, das sich auf den Namespace netscaler.nitro.config und die Version 10.5 bezieht, die Sie im Abschnitt „import-stylebooks“ angegeben hatten, und „lbvserver“ eine Nitro-Ressource in diesem Namespace ist.
Die hier definierten properties sind die Attribute der Ressource „lbvserver“. Weitere Informationen zu allen verfügbaren NetScaler Nitro-Ressourcen und ihren Attributen finden Sie in der NetScaler NITRO REST API-Dokumentation.
Die Eigenschaften in diesem Abschnitt umfassen die obligatorischen Attribute der Ressource „lbvserver“ und ermöglichen es Ihnen, Werte für diese Attribute anzugeben. In diesem Beispiel geben Sie statische Werte für „servicetype“ und „port“ an, während die Eigenschaften „name“, „ipv46“ und „lbmethod“ ihre Werte aus den Eingabeparametern erhalten. Im restlichen StyleBook können Sie auf die im Abschnitt „parameters“ definierten Parameternamen verweisen, indem Sie den Ausdruck $parameters.<parameter-name> verwenden, zum Beispiel $parameters.ip.
Hinweis
Konventionsgemäß wird das Präfix „ns“ immer verwendet, um einen NetScaler Nitro-Namespace im Abschnitt „import-stylebooks“ zu bezeichnen. Obwohl es nicht obligatorisch ist, empfiehlt Citrix, dieselbe Konvention in Ihren eigenen StyleBooks für Konsistenz zu verwenden.
Ihr StyleBook erstellen
Nachdem Sie alle erforderlichen Abschnitte dieses StyleBooks definiert haben, fügen Sie sie alle zusammen, um Ihr erstes StyleBook zu erstellen. Kopieren Sie den StyleBook-Inhalt in einen Texteditor und speichern Sie die Datei dann als lb-vserver.yaml. Citrix empfiehlt, den integrierten YAML-Validator in StyleBooks zu verwenden, um den YAML-Inhalt zu validieren und zu importieren.
Der vollständige Inhalt der Datei lb-vserver.yaml ist unten wiedergegeben:
name: lb-vserver
namespace: com.example.stylebook
version: "1.0"
display-name: Load Balancing Virtual Server (HTTP)
description: "This stylebook defines a very simple load balancing HTTP virtual server configuration"
schema-version: "1.0"
import-stylebooks:
-
namespace: netscaler.nitro.config
version: "10.5"
prefix: ns
-
namespace: com.citrix.adc.stylebooks
version: "1.0"
prefix: stlb
parameters:
-
name: name
label: "Application Name"
description: "Give a name to the application configuration."
type: string
required: true
-
name: vip-ipaddress
label: "Load Balancer IP Address"
description: "The Application VIP that clients access"
type: ipaddress
required: true
-
name: lb-alg
label: LB Algorithm
description: Load Balancing Algorithm
type: string
default: ROUNDROBIN
allowed-values:
- ROUNDROBIN
- LEAST-CONNECTION
components:
-
name: lbvserver-comp
description: This StyleBook component (a Builtin Nitro StyleBook) builds a NetScaler load balancing virtual server configuration object.
type: ns::lbvserver
properties:
name: $parameters.name
ipv46: $parameters.vip-ipaddress
lbmethod: $parameters.lb-alg
servicetype: HTTP
port: 80
<!--NeedCopy-->
Um Ihr StyleBook zum Erstellen von Konfigurationen zu verwenden, müssen Sie es in NetScaler ADM importieren und dann verwenden. Weitere Informationen finden Sie unter Benutzerdefinierte StyleBooks verwenden.
Sie können dieses StyleBook auch in andere StyleBooks importieren (mithilfe des „import-stylebooks“-Konstrukts). Oder Sie können dieses StyleBook ändern, um weitere Parameter und Komponenten aufzunehmen, wie im nächsten Abschnitt beschrieben.