StyleBook zum Erstellen eines virtuellen Lastausgleichsservers
In diesem Beispiel entwerfen Sie ein einfaches StyleBook, das einen virtuellen Lastausgleichsserver vom Typ HTTP-Protokoll erstellt und auf Port 80 überwacht. Die Parameter für den virtuellen Servernamen, die IP-Adresse und die Load-Balancing-Methode akzeptieren benutzerdefinierte Werte, d. h. sie sind die Parameter des StyleBook.
Header
Die ersten sechs Zeilen eines StyleBook bilden den Header-Bereich. In diesem Beispiel ist der Header-Abschnitt wie folgt geschrieben:
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"
<!--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, das auf der NetScaler Console angezeigt wird.
- Namespace: Ein Namespace ist Teil einer eindeutigen Kennung für ein StyleBook, um Namenskollisionen zu vermeiden.
- schema-version: Nimmt in diesem Release immer den Wert “1.0” an.
- version: Die Versionsnummer des StyleBook. 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 Console nicht 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
Bedenken Sie, dass Sie Ihr StyleBook aktualisiert haben und eine aktualisierte Versionsnummer haben. Wenn Sie nun in anderen StyleBooks auf dieses StyleBook verweisen (das heißt, wenn Sie es importieren), stellen Sie sicher, dass Sie die Versionsnummer auch in anderen StyleBooks aktualisieren, damit diese die richtige Version des importierten StyleBooks verwenden.
StyleBooks importieren
Der Abschnitt nach der Kopfzeile heißt “import-stylebooks”. 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. Auf diese Weise können Sie andere StyleBooks importieren und wiederverwenden, 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 eines der NITRO-Konfigurationsobjekte direkt verwendet. Dieser Namespace enthält alle NetScaler NITRO-Typen, 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, auf der Version 10.5 und höher ausgeführt wird.
Das im Abschnitt import-stylebooks verwendete Präfix ist eine Abkürzung für die Kombination von Namespace und Version. 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 im obigen Beispiel ausgewählt wurde, z. B. ns, 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 einer beliebigen NetScaler-Instanz der Version 10.5 oder höher verwendet werden können, empfiehlt Citrix, den NITRO 10.5-Namespace aus Gründen der maximalen Kompatibilität zu importieren, der direkt die in NITRO integrierten StyleBooks verwendet (Namespace: netscaler.nitro.config, Version: 10.5).
Es ist wichtig, dass ein StyleBook, das andere StyleBooks importiert, auf einer NITRO-Version basieren muss, die dieselbe oder höhere Version als die von ihm importierten StyleBooks hat. Beispielsweise kann ein StyleBook, das auf NITRO Version 10.5 basiert, nicht von einem StyleBook abhängen, das auf 11.1 basiert, nicht verwenden oder es verwenden oder importieren. Ein StyleBook basierend auf Version 11.1 kann jedoch ein StyleBook importieren, das auf einer beliebigen Version von weniger 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 kann, die NITRO-Komponenten definieren. Das StyleBook, das andere StyleBooks importiert, erhält immer die höchste NITRO-Version in der Hierarchie seiner Abhängigkeiten. Und es wird verwendet, um NetScaler dieser Version oder höher zu konfigurieren.
Parameter
Im Parameterbereich können Sie alle Parameter 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 die Benutzer den Namen des virtuellen Servers, seine IP-Adresse und die Lastausgleichsmethode angeben müssen.
Der Abschnitt “Parameter” würde wie folgt aussehen:
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
<!--NeedCopy-->
Hinweis
Wenn Sie die Bezeichnung eines Parameters nicht angeben, verwendet NetScaler Console bei der Anzeige dieses Parameters das Namensattribut. Sie müssen immer eine Bezeichnung für Ihre Parameter definieren, damit Sie steuern können, wie sie in NetScaler Console angezeigt werden.
Bei Verwendung der APIs wird der Parameter jedoch durch seinen Namen gekennzeichnet.
In diesem Abschnitt haben Sie drei Parameter deklariert, die durch ihre Namensattributwerte gekennzeichnet sind: Name für den virtuellen Servernamen, IP für die IP-Adresse des virtuellen Servers und lb-alg für die Lastausgleichsmethode.
-
Typ bezieht sich auf den Typ des Wertes, den diese Parameter annehmen können. Zum Beispiel
lb-algkann name und einen String-Wert annehmen, und der IP-Wert muss vom Typ IP-Adresse sein. Parameter in einem StyleBook können von einem der folgenden integrierten Typen sein: - string: Eine Reihe von Zeichen. Wenn keine Länge angegeben wird, kann der Zeichenfolgenwert beliebig viele Zeichen annehmen. Sie können jedoch die Länge eines String-Typs einschränken, indem Sie die Attribute min-length und max-length verwenden.
- Zahl: Eine Ganzzahl. Sie können die minimale und maximale Anzahl angeben, die dieser Typ annehmen kann, indem Sie die Attribute min-value und max-value verwenden.
- boolean: Kann entweder true oder false sein. Beachten Sie auch, dass alle Literale von YAML als boolesche Werte betrachtet werden (z. B. Ja oder Nein).
- ipaddress: Ein String, der 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 Console einen Wert für diesen Parameter anzeigt, wird er als Sternchen (*****) angezeigt.
- certfile: Eine Zertifikatsdatei.
- keyfile: Eine private Schlüsseldatei für ein Zertifikat.
- file: Für einen Parameter dieses Typs muss der Benutzer eine Datei hochladen, z. B. ein Zertifikat oder eine 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 beim Erstellen von Konfigurationen mit diesem StyleBook einen Wert für diesen Parameter angeben. 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 Standardattribut, um einem optionalen Parameter einen Standardwert zuzuweisen. Wenn ein Benutzer beim Erstellen einer Konfiguration keinen Wert angibt, wird der Standardwert verwendet. Für den Parameter lb-alg ist der Standardwert beispielsweise ROUNDROBIN.
Verwenden Sie das Attribut allowed-values, um bestimmte Werte zu definieren, aus denen ein Benutzer beim Erstellen einer Konfiguration auswä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 Console ein Formular mit diesen drei Parametern an. Die für Name und IP angezeigten Felder ermöglichen die Eingabe von Zeichenfolge und Werttyp ipaddress, und das Feld lb-alg wird als Dropdownliste angezeigt, wobei ROUNDROBIN als Standardwert ausgewählt ist.
Hinweis
Zusätzlich zu den integrierten Typen kann ein Parameter ein anderes StyleBook als Typ haben. Dies ist eine Möglichkeit, in anderen StyleBooks definierte Parameter wiederzuverwenden.
Komponenten
Der letzte Abschnitt in diesem StyleBook wird als Komponentenbereich 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
description: This StyleBook component (a Builtin Nitro StyleBook) builds a NetScaler lbvserver configuration object.
type: ns::lbvserver
properties:
name: $parameters.name
ipv46: $parameters.vip-ipaddress
lbmethod: $parameters.lb-alg
servicetype: HTTP
port: 80
<!--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 bietet. Komponenten sind von zwei Arten:
-
Eingebauter Typ: Dieser Typ wird vom System bereitgestellt und Sie müssen ihn nicht definieren, z. B. die NITRO-Entitätstypen
lbvserveroderservicegroup. In diesem Beispiel verwenden Sie einen integrierten Komponententyp. - Zusammengesetzter Typ: Dieser Typ ist das StyleBook, das Sie erstellt und in NetScaler Console importiert haben, oder das Standard-StyleBook, das mit NetScaler Console geliefert wird. Weitere Informationen zu Composite-StyleBooks finden Sie unter Erstellen Sie ein zusammengesetztes StyleBook .
In diesem Beispiel haben Sie eine Komponente namens lbvserver-compdefiniert. 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 Version 10.5 bezieht, den Sie im Abschnitt import-stylebooks angegeben haben, und eine NITRO-Ressource in diesem Namespace lbvserver ist.
Die hier definierten Eigenschaften sind die Attribute der lbvserver Ressource. Weitere Informationen zu allen verfügbaren NetScaler NITRO-Ressourcen und ihren Attributen finden Sie in der Dokumentation zur NetScaler NITRO REST API.
Die Eigenschaften in diesem Abschnitt enthalten 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 der Name, ipv46 und lbmethod ihre Werte aus den Eingabeparametern erhalten. Im Rest des StyleBook können Sie auf die Parameternamen verweisen, die im Parameterabschnitt definiert sind, indem Sie den Ausdruck $parameters.<parameter-name> verwenden, zum Beispiel $parameters.ip.
Hinweis
Die Konvention ist, das Präfix “ns” immer zu verwenden, um einen NetScaler NITRO-Namespace im Abschnitt “Import-Stylebooks” zu bezeichnen. Obwohl dies nicht obligatorisch ist, empfiehlt Citrix, die gleiche Konvention in Ihren eigenen StyleBooks zur Konsistenz zu verwenden.
Erstellen Sie Ihr StyleBook
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, fügen Sie ihn in einen Texteditor ein, und speichern Sie die Datei dann unter dem Namen 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 lbvserver 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 Verwenden von benutzerdefinierten StyleBooks.
Sie können dieses StyleBook auch in andere StyleBooks importieren (mit dem Import-StyleBooks-Konstrukt). Oder Sie können dieses StyleBook so ändern, dass es weitere Parameter und Komponenten enthält, wie im nächsten Abschnitt beschrieben.