StyleBook zum Erstellen eines Load-Balancing Virtual Servers
In diesem Beispiel entwerfen Sie ein grundlegendes StyleBook, das einen Load-Balancing 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 Load-Balancing-Methode 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 wird in der NetScaler Console angezeigt.
-
display-name: Ein beschreibender Name für das StyleBook, der in der NetScaler Console angezeigt wird.
-
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 der NetScaler Console 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 nun dieses StyleBook 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 anstelle des Namespaces und der Version, um auf das importierte StyleBook zu verweisen, die gewählte Präfixzeichenfolge verwenden, zum Beispiel ns im obigen Beispiel.
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 ab Version 10.5 verwendet werden können, empfehlen wir für maximale Kompatibilität, den Nitro 10.5-Namespace in Ihren StyleBooks zu importieren, die direkt Nitro-eingebaute 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 StyleBooks, die es importiert. Zum Beispiel kann ein StyleBook, das auf NITRO-Version 10.5 basiert, kein StyleBook 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 aufgebaut, dass seine Benutzer den Namen des Virtual Servers, seine IP-Adresse und die Load-Balancing-Methode 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 die NetScaler Console das Attribut
namebei der Anzeige dieses Parameters. Sie müssen immer ein Label für Ihre Parameter definieren, damit Sie steuern können, wie sie in der NetScaler Console 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 Load-Balancing-Methode.
-
type. Der Typ des Werts, den diese Parameter annehmen können. Zum Beispiel können
nameundlb-algeinen String-Wert annehmen, und derip-Wert muss vom Typipaddresssein. Parameter in einem StyleBook können einen der folgenden integrierten Typen haben: -
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-lengthundmax-lengthbegrenzen. -
number. Eine ganze Zahl. Sie können die minimale und maximale Zahl, die dieser Typ annehmen kann, durch die Verwendung der Attribute
min-valueundmax-valueangeben. -
boolean. Kann entweder
trueoderfalsesein. Beachten Sie auch, dass alle Literale von YAML als Booleans betrachtet werden (zum BeispielYesoderNo). - 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 die NetScaler Console 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
truegesetzt 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 die NetScaler Console ein Formular mit diesen drei Parametern an. Die für name und ip angezeigten Felder ermöglichen die Eingabe von String- und ipaddress-Werten, und das lb-alg-Feld 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, type und properties. 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 die NetScaler Console importiert haben, oder das Standard-StyleBook, das mit der NetScaler Console geliefert 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 deren 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
Konventionell 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 die Konsistenz zu verwenden.
Ihr StyleBook erstellen
Nachdem Sie alle erforderlichen Abschnitte dieses StyleBooks definiert haben, fügen Sie diese 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. Wir empfehlen Ihnen, 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 die NetScaler Console 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.