負荷分散仮想サーバーを作成するStyleBook
この例で設計する基本的なStyleBookでは、プロトコルのタイプがHTTPで、ポート80でリッスンする負荷分散仮想サーバーを作成します。仮想サーバーの名前、IPアドレス、負荷分散方式の各パラメーターには、ユーザーが定義した値を指定できます（これらはStyleBookのパラメーターです）。
Header
StyleBookの先頭の6行は、Headerセクションです。この例の場合、Headerセクションは、次のように記述されています。
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-->
Headerセクションには、次の情報が記述されています。
-
name：このStyleBookの名前。
-
description：このStyleBookの実行内容を示す説明。この説明は NetScaler ADM に表示されます。
-
表示名：NetScaler ADM に表示されるStyleBookの説明的な名前。
-
namespace：名前空間は、StyleBookの一意の識別子の一部で、これにより名前の衝突を回避できます。
-
schema-version：このリリースでは、値は常に「1.0」です。
-
version：StyleBookのバージョン番号。バージョン番号は、StyleBookの更新時に変更できます。
name、namespace、およびversionの組み合わせにより、システム内でStyleBookが一意に識別されます。NetScaler ADM では、名前、名前空間、およびバージョンの組み合わせが同じ2つのStyleBookを使用することはできません。ただし、nameとversionが同じであってもnamespaceが異なる場合、またはnamespaceとversionが同じであってもnameが異なる場合は、それらの2つのStyleBookを使用できます。
注
StyleBookを更新して、versionの番号が更新された場合を想定してください。別の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-->
いずれかのNITRO構成オブジェクトを直接使用する場合、StyleBookでは、netscaler.nitro.config名前空間を必ず参照する必要があります。この名前空間には、lbvServerなど、すべてのNetScaler ADC NITRO タイプが含まれています。ソフトウェアバージョン10.5以降がサポートされているため、StyleBookを使用して、リリース10.5以降を実行する任意のNetScaler ADCインスタンスで構成を作成して実行できます。
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（名前空間：netscaler.nitro.config、バージョン：10.5）を直接使用するStyleBookにNitro 10.5名前空間をインポートすることをCitrix では推奨しています。
他のStyleBookをインポートするStyleBookは、インポートするStyleBookと同じかそれ以上のバージョンのNitroバージョンをベースにしている必要があることが重要です。たとえば、Nitroバージョン10.5をベースにしたStyleBookは、11.1をベースにしたStyleBookに依存したり、使用したり、インポートしたりすることはできません。しかし、バージョン11.1に基づくStyleBookは、11.1未満のバージョンに基づくStyleBookをインポートすることができます。
StyleBookがNitro名前空間をまったくインポートしない可能性もあります。つまり、StyleBookはNitroコンポーネントを直接定義する必要はありませんが、Nitroコンポーネントを定義するStyleBookをインポート（依存）できます。他のStyleBookをインポートするStyleBookは、依存関係の階層の中で常に最上位のNitroバージョンを取得するため、そのバージョン以上のNetScalerの構成に使用できます。
パラメーター
Parametersセクションでは、StyleBookで必要なすべてのパラメーターを宣言できます。StyleBookの作成者は、StyleBookのユーザーが指定する入力項目を決定する必要があります。この例の場合、ユーザーが、仮想サーバーの名前、IPアドレス、負荷分散方式を指定するようにStyleBookを設計しました。
Parametersセクションは、次のようになっています。
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 ADM はこのパラメーターを表示するときに名前属性を使用します。NetScaler ADM での表示方法を制御できるように、必ずパラメーターにラベルを定義する必要があります。
ただし、APIで使われる場合、パラメーターはそのnameで指定されます。
このセクションでは、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。真でも偽でもかまいません。YAMLでは、すべてのリテラルがブール値（例：YesまたはNo）と見なされることに注意してください。
- ipaddress。有効な IPv4 または IPv6 アドレスを表す文字列。
- tcp-port。TCP ポートまたは UDP ポートを表す 0 から 65535 までの数値です。
- password。不透明/秘密の文字列値。NetScaler ADM でこのパラメータの値が表示される場合は、アスタリスク（*****）として表示されます。
- 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 ADM はこれらの3つのパラメータを含むフォームが表示されます。nameおよびipに対して表示されるフィールドでは、文字列タイプとIPアドレスタイプの値を入力できます。lb-algのフィールドは、ボックスの一覧として表示されます。デフォルトでは、ROUNDROBINという値が選択されています。
注
組み込みタイプに加えて、パラメーターには他のStyleBookをタイプにすることができます。こうして他のStyleBookで定義されたパラメーターを再利用できます。
コンポーネント
このStyleBookの最後のセクションは、Componentsセクションです。Componentsセクションは、StyleBookで最も重要なセクションです。このセクションでは、StyleBookで作成する必要がある構成オブジェクトを定義します。
この例の場合、Componentsセクションは、次のように記述する必要があります。
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 ADMにインポートしたStyleBook、またはNetScaler ADMに同梱されているデフォルトのStyleBookです。複合StyleBookの詳細については、「 複合StyleBookの作成」を参照してください。
この例では、 lbvserver-compというコンポーネントを定義しました。このコンポーネントのタイプは ns:: lbvserver(組み込みの Nitro タイプ) で、「ns」は import-stylebooks セクションで指定した名前空間netscaler.nitro.configとバージョン10.5を指すプレフィックスで、「lbvserver」はこの名前空間のNitroリソースです。
ここで定義されているpropertiesは、「lbvserver」リソースの属性です。使用可能なすべてのNetScaler ADC Nitroリソースとその属性の詳細については、 NetScaler NITRO REST APIのドキュメントを参照してください。
このセクションのプロパティには、「lbvserver」リソースの必須属性が含まれています。そのため、これらの属性の値を指定できます。この例では、servicetypeとportには静的な値が指定されていますが、name、ipv46、およびlbmethodの各プロパティは、入力パラメーターから値を取得します。StyleBookの残りの部分では、 を使用して、パラメータ・セクションで定義されたパラメータ名を参照できます。 $parameters.<parameter-name>式 (例: $パラメータ.ip) です。
注
慣例によって、プレフィックス「ns」は常に「import-stylebooks」セクションのNetScaler Nitro名前空間を指定します。これは必須ではありませんが、一貫性を保つためにお使いのStyleBookで慣例に従うことをお勧めします。
StyleBookを構築する
StyleBookの必須セクションをすべて定義しました。これらのセクションをまとめて、最初のStyleBookを作成します。StyleBookの内容をコピーして、テキストエディターに貼り付け、lb-vserver.yamlという名前でファイルを保存します。Citrixでは、StyleBooksに組み込まれている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 ADM にインポートしてから使用する必要があります。詳しくは、「ユーザー定義のStyleBookを使用する方法」を参照してください。
またこのStyleBookを他のStyleBookに（import-stylebooks構造を使って）インポートすることもできます。または、次のセクションで説明されるように、より多くのパラメーターとコンポーネントを含むようにこのStyleBookを修正することもできます。