負荷分散仮想サーバー作成用StyleBook
この例では、HTTPプロトコルタイプでポート80をリッスンする負荷分散仮想サーバーを作成する基本的なStyleBookを設計します。仮想サーバー名、IPアドレス、および負荷分散方式のパラメーターは、ユーザー定義の値を受け入れます。つまり、これらはStyleBookのパラメーターです。
ヘッダー
StyleBookの最初の6行はヘッダーセクションを構成します。この例では、ヘッダーセクションは次のように記述されています。
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-->
ヘッダーセクションには、次の詳細が含まれます。
- name: このStyleBookの名前
- description: このStyleBookの機能を示す説明。この説明はNetScaler Consoleに表示されます。
- display-name: NetScaler Consoleに表示されるStyleBookの記述名
- namespace: 名前空間は、名前の衝突を避けるためにStyleBookの一意の識別子の一部を形成します。
- schema-version: このリリースでは常に「1.0」の値を取ります。
- version: StyleBookのバージョン番号。StyleBookを更新するときにバージョン番号を変更できます。
name、namespace、およびversionの組み合わせは、システム内でStyleBookを一意に識別します。NetScaler Consoleでは、同じ名前、名前空間、およびバージョンの組み合わせを持つ2つのStyleBookを持つことはできません。ただし、同じ名前とバージョンでも異なる名前空間を持つStyleBook、または同じ名前空間とバージョンでも異なる名前を持つStyleBookを持つことはできます。
注
StyleBookを更新し、更新されたバージョン番号を持っているとします。このStyleBookを他のStyleBookで参照している（つまり、インポートしている）場合は、インポートされたStyleBookの正しいバージョンを使用するように、他のStyleBookでもバージョン番号を更新してください。
StyleBookのインポート
ヘッダーの後のセクションは「import-stylebooks」と呼ばれます。このセクションでは、現在のStyleBookで参照したい他のStyleBookの名前空間とバージョン番号を宣言する必要があります。これにより、同じ構成を独自のStyleBookで再構築する代わりに、他のStyleBookをインポートして再利用できます。
この例では、import-stylebooksセクションは次のように記述されています。
import-stylebooks:
-
namespace: netscaler.nitro.config
prefix: ns
version: "10.5"
<!--NeedCopy-->
すべてのStyleBookは、NITRO構成オブジェクトを直接使用する場合、netscaler.nitro.config名前空間を参照する必要があります。この名前空間には、lbvserverなどのすべてのNetScaler NITROタイプが含まれています。ソフトウェアバージョン10.5以降がサポートされているため、StyleBookを使用して、リリース10.5以降を実行している任意のNetScalerインスタンスで構成を作成および実行できます。
import-stylebooksセクションで使用されるプレフィックスは、名前空間とバージョンの組み合わせを参照するための短縮形です。この場合、nsはバージョン10.5のnetscaler.nitro.configを参照します。StyleBookの後のセクションでは、インポートされたStyleBookを参照するために名前空間とバージョンを使用する代わりに、上記の例のように、選択したプレフィックス文字列（nsなど）を使用できます。
StyleBookで使用されるバージョンはNetScaler NITROバージョンです。NitroバージョンXに基づくStyleBookは、バージョンX以降の任意のNetScalerを構成するために使用できます。
注
StyleBookがバージョン10.5以降の任意のNetScalerインスタンスを構成するために使用できるようにするには、最大限の互換性のために、Nitro組み込みStyleBookを直接使用するStyleBook（名前空間: netscaler.nitro.config、バージョン: 10.5）でNitro 10.5名前空間をインポートすることをお勧めします。
他のStyleBookをインポートするStyleBookは、インポートするStyleBookと同じかそれ以上のバージョンのNitroに基づいている必要があることが重要です。たとえば、Nitroバージョン10.5に基づくStyleBookは、11.1に基づくStyleBookに依存したり、使用したり、インポートしたりすることはできません。しかし、バージョン11.1に基づくStyleBookは、11.1未満の任意のバージョンに基づくStyleBookをインポートできます。
Nitro名前空間をまったくインポートしないStyleBookも可能です。つまり、StyleBookはNitroコンポーネントを直接定義する必要はありませんが、Nitroコンポーネントを定義するStyleBookをインポート（依存）できます。他のStyleBookをインポートするStyleBookは、常にその依存関係の階層で最高のNitroバージョンを取得するため、そのバージョン以降のNetScalerを構成するために使用できます。
パラメーター
パラメーターセクションでは、StyleBookで必要となるすべてのパラメーターを宣言できます。StyleBook開発者として、StyleBookのユーザーに指定してもらいたい入力内容を決定する必要があります。この例では、仮想サーバーの名前、IPアドレス、および負荷分散方式をユーザーが提供する必要があるようにStyleBookを構築しました。
パラメーターセクションは次のようになります。
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-->
注
パラメーターのラベルを指定しない場合、NetScaler Consoleはこのパラメーターを表示するときにname属性を使用します。NetScaler Consoleでどのように表示されるかを制御できるように、常にパラメーターのラベルを定義する必要があります。
ただし、APIを使用する場合、パラメーターはその名前で指定されます。
このセクションでは、name属性値で示される3つのパラメーターを宣言しました。仮想サーバー名にはname、仮想サーバーのIPアドレスにはip、負荷分散方式にはlb-algです。
- type: これらのパラメーターが取ることができる値のタイプ。たとえば、nameとlb-algは文字列値を取ることができ、ip値はipアドレスタイプである必要があります。StyleBookのパラメーターは、次の組み込みタイプのいずれかになります。
- string: 文字の配列。長さが指定されていない場合、文字列値は任意の数の文字を取ることができます。ただし、min-length属性とmax-length属性を使用することで、文字列タイプの長さを制限できます。
- number: 整数。min-value属性とmax-value属性を使用することで、このタイプが取ることができる最小値と最大値を指定できます。
- boolean: trueまたはfalseのいずれかになります。また、すべてのリテラルはYAMLによってブール値として扱われることに注意してください（例: YesまたはNo）。
- ipaddress: 有効なIPv4またはIPv6アドレスを表す文字列。
- tcp-port: TCPまたはUDPポートを表す0から65535までの数値。
- password: 不透明/秘密の文字列値。NetScaler Consoleがこのパラメーターの値を表示するときは、アスタリスク（*****）として表示されます。
- certfile: 証明書ファイル。
- keyfile: 証明書秘密鍵ファイル。
- file: このタイプのパラメーターは、ユーザーがファイルをアップロードすることを要求します。たとえば、証明書ファイルやキーファイルなどです。
- object: 複数の要素で構成され、これらの各要素はパラメーターです。このタイプは、複数の関連するパラメーターを1つの親パラメーターの下にグループ化するために使用できます。
- required: パラメーターが必須かオプションかを示します。trueに設定されている場合、パラメーターは必須であり、ユーザーはこのStyleBookを使用して構成を作成するときにこのパラメーターの値を指定する必要があります。デフォルトでは、すべてのパラメーターはオプションです。この例では、nameとipは必須パラメーターであり、lb-algはオプションパラメーターで、そのデフォルト値は「ROUNDROBIN」です。
オプションパラメーターにデフォルト値を割り当てるには、default属性を使用します。構成を作成するときに、ユーザーが値を指定しない場合、デフォルト値が使用されます。たとえば、lb-algパラメーターの場合、デフォルト値はROUNDROBINです。
構成を作成するときにユーザーが選択できる特定の値を定義するには、allowed-values属性を使用します。この例では、lb-algパラメーターにROUNDROBINとLEASTCONNECTIONの2つの値を指定しました。
StyleBookをインポートして使用すると、NetScaler Consoleはこれら3つのパラメーターを含むフォームを表示します。nameとipに表示されるフィールドでは文字列とipアドレスタイプの値を入力でき、lb-algフィールドはROUNDROBINがデフォルト値として選択されたドロップダウンリストとして表示されます。
注
組み込みタイプに加えて、パラメーターは別のStyleBookをそのタイプとして持つことができます。これは、他のStyleBookで定義されたパラメーターを再利用する方法です。
コンポーネント
このStyleBookの最後のセクションはコンポーネントセクションと呼ばれ、StyleBookの中で最も重要なセクションと見なされます。このセクションでは、SyleBookによって作成される構成オブジェクトを定義します。
この例では、コンポーネントセクションを次のように記述する必要があります。
components:
-
name: lbvserver-comp
type: ns::lbvserver
properties:
name: $parameters.name
servicetype: HTTP
ipv46: $parameters.ip
port: 80
lbmethod: $parameters.lb-alg
<!--NeedCopy-->
この例には1つのコンポーネントのみが含まれています。コンポーネントの主な属性は、name、type、およびpropertiesです。コンポーネントのタイプは、このコンポーネントが提供するプロパティを決定します。コンポーネントには次の2つのタイプがあります。
- 組み込みタイプ: このタイプはシステムによって提供され、定義する必要はありません。たとえば、NITROエンティティタイプ「lbvserver」や「servicegroup」などです。この例では、組み込みコンポーネントタイプを使用しています。
- 複合タイプ: このタイプは、作成してNetScaler ConsoleにインポートしたStyleBook、またはNetScaler Consoleに付属しているデフォルトのStyleBookです。複合StyleBookの詳細については、「複合StyleBookの作成」を参照してください。
この例では、lbvserver-compというコンポーネントを定義しました。このコンポーネントはns::lbvserver（組み込みのNitroタイプ）タイプです。ここで「ns」は、import-stylebooksセクションで指定したnetscaler.nitro.config名前空間とバージョン10.5を参照するプレフィックスであり、「lbvserver」はこの名前空間のNitroリソースです。
ここで定義されているpropertiesは、「lbvserver」リソースの属性です。利用可能なすべてのNetScaler Nitroリソースとその属性の詳細については、「NetScaler NITRO REST API documentation」を参照してください。
このセクションのプロパティには、「lbvserver」リソースの必須属性が含まれており、これらの属性の値を指定できます。この例では、servicetypeとportに静的な値を指定していますが、name、ipv46、およびlbmethodプロパティは入力パラメーターから値を取得します。StyleBookの残りの部分では、$parameters.<parameter-name>式（例: $parameters.ip）を使用して、parametersセクションで定義されたパラメーター名を参照できます。
注
慣例として、「ns」プレフィックスは「import-stylebooks」セクションでNetScaler Nitro名前空間を指定するために常に使用されます。必須ではありませんが、Citrixは一貫性のために独自のStyleBookでも同じ慣例を使用することを推奨しています。
StyleBookの構築
このStyleBookのすべての必須セクションを定義したので、それらをすべてまとめて最初のStyleBookを構築します。StyleBookの内容をテキストエディターにコピーして貼り付け、ファイルをlb-vserver.yamlとして保存します。StyleBookに組み込まれているYAMLバリデーターを使用して、YAMLコンテンツを検証およびインポートすることをお勧めします。
ファイルlb-vserver.yamlの全内容は以下のとおりです。
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-->
構成を作成するためにStyleBookの使用を開始するには、NetScaler Consoleにインポートしてから使用する必要があります。詳細については、「ユーザー定義StyleBookの使用方法」を参照してください。
このStyleBookを他のStyleBookにインポートすることもできます（import-stylebooksコンストラクトを使用）。または、次のセクションで説明するように、このStyleBookを修正して、より多くのパラメーターとコンポーネントを含めることもできます。