创建负载平衡虚拟服务器的样本
在此示例中,设计一个创建协议类型为 HTTP 且侦听端口 80 的负载平衡虚拟服务器的基本样本。虚拟服务器名称、IP 地址和负载平衡方法参数接受用户定义的值,即它们是样本的参数。
标题
样书的前六行构成标头部分。在此示例中,标头部分编写如下:
name:lb-vserverdescription:This StyleBook defines a load balancing virtual server configuration.display-name:Load Balancing Virtual Server (HTTP)namespace:com.example.stylebooksschema-version:"1.0"version:"0.1"
标头部分包含以下详细信息:
name:此样本的名称。
description:定义此样本做什么的说明。此描述将显示在 Citrix ADM 上。
显示名称:Citrix ADM 上显示的样本的描述性名称。
namespace:样本的唯一标识符的命名空间形式部分,以避免发生名称冲突。
schema-version:在此版本中,其值总是“1.0”。
version:样本的版本号。可以在更新样本时更改版本号。
name、namespace和version组合在系统中唯一标识样书。Citrix ADM 中不能有两个具有相同名称、命名空间和版本组合的样本。但可以有两个 name 和 version 相同但 namespace 不同或 namespace 和 version 相同但 name 不同的样本。
注意
假定您已更新您的样本,且您有更新的 version 号。现在,如果您要在其他样本中引用(即您要导入)此样本,请务必也在其他样本中更新 version 号,以便它们使用正确版本的导入样本。
导入样本
标头后面的部分称为“import-stylebooks”。在此部分中,必须在当前样书中声明要引用的任何其他样书的 namespace 和 version 号。这样可以导入并重用其他样书,而不是在您自己的样书中重新构建相同的配置。
在此示例中,import-stylebooks 部分编写如下:
import-stylebooks:-namespace:netscaler.nitro.configprefix:nsversion:"10.5"
直接使用任何一个 NITRO 配置对象的每个样本都必须引用 netscaler.nitro.config 命名空间。此命名空间包含所有 Citrix ADC NITRO 类型,例如 Lbvserver。由于支持 10.5 及更高版本的软件版本,您可以使用样本在运行 10.5 及更高版本的任何 Citrix ADC 实例上创建和运行配置。
import-stylebooks 部分中使用的前缀是指代命名空间和版本组合的简写。在此示例中,ns 是指版本为 10.5 的 netscaler.nitro.config。在样本的后面部分,并非使用命名空间和版本来指代被导入样本,可以使用上述示例中选择的前缀字符串,例如 ns。
样本中使用的版本是 Citrix ADC NITRO 版本。基于 Nitro 版本 X 的样本可用于配置 X 或更高版本的任何 Citrix ADC。
注意
为确保您的样本可用于配置 10.5 或更高版本的任何 Citrix ADC 实例,Citrix 建议您在直接使用 Nitro 内置样本的样本中导入 Nitro 10.5 命名空间(命名空间:netscaler.nitro.config,版本:10.5)。
重要的是,导入其他样本的样本必须基于与其导入的样本相同或更高版本的 Nitro 版本。例如,基于 Nitro 10.5 的样本不能依赖或使用或导入基于 11.1 的样本。但是,基于版本 11.1 的样本可以导入基于小于 11.1 的任何版本的样本。
也可能是一个样书根本不导入 Nitro 命名空间。这意味着样本不需要直接定义 Nitro 组件,但可以导入(取决于)定义 Nitro 组件的样本。导入其他样本的样本始终获取其依赖关系层次结构中的最高 Nitro 版本,因此可用于配置该版本或更高版本的 Citrix ADC。
参数
parameters 部分用于声明样本中需要的所有参数。作为样本开发人员,您必须决定您希望样本的用户要指定哪些输入。在此示例中,构建的样本要求其用户提供虚拟服务器的名称、其 IP 地址以及负载平衡方法。
parameters 部分类似如下:
parameters:-name:nametype:stringlabel:应用程序名称description: Name of the application configuration.required:true-name:iptype:ipaddresslabel:Application Virtual IP (VIP)description:Application VIP that the clients access.required:true-name:lb-algtype:stringlabel:LoadBalancing Algorithmdescription:Choose the load balancing algorithm (method) used for load balancing client request between the application servers.allowed-values:-ROUNDROBIN-LEASTCONNECTIONdefault:ROUNDROBIN
注意
如果不提供参数的标签,则Citrix ADM在显示此参数时使用名称属性。必须始终为参数定义标签,以便控制参数在 Citrix ADM 中的显示方式。
但使用 API 时,参数由其 name 指定。
在此部分中,声明了三个参数,它们以其name属性值来指示 -name表示虚拟服务器名称,ip表示虚拟服务器的 IP 地址,以及lb-alg表示负载平衡方法。
- 类型。这些参数可以采用的值的类型。例如,name 和 lb-alg 可以接收字符串值,ip 值必须属于 IP 地址类型。样本中的参数可以是以下任何内置类型:
- 字符串。字符数组。如果未指定长度,则字符串值可以接收任何数量的字符。但是,可以使用 min-length 和 max-length 属性限制字符串类型的长度。
- 号码。整数。可以使用 min-value 和 max-value 属性指定此类型可以接收的最小数和最大数。
- 布尔值。可以是真的,也可以是假的。另外请注意,所有文字都被 YAML 视为布尔值(例如 Yes 或 No)。
- IP 地址。表示有效 IPv4 或 IPv6 地址的字符串。
- TCP 端口。介于 0 到 65535 之间的数字,表示 TCP 或 UDP 端口。
- 密码。不透明/秘密字符串值。当 Citrix ADM 显示此参数的值时,它将显示为星号 (*****)。
- 证书文件。证书文件。
- 密钥文件。证书私钥文件。
- 文件。此类型的参数要求用户上传文件,例如证书或密钥文件。
- 对象。由多个元素组成,每个元素都是一个参数。此类型可以用于对一个父参数下多个相关参数进行分组。
- 需要。指出参数是强制参数还是可选参数。如果设置为真的,表示参数是必需的,用户必须在使用此样本创建配置时提供此参数值。默认情况下,所有参数都是可选的。在此示例中,name和ip是必需参数,而lb-alg是一个可选参数,其默认值为“ROUNDROBIN”。“
可使用default属性为可选参数分配默认值。创建配置时,如果用户未指定值,则使用默认值。例如,lb-alg参数的默认值是 ROUNDROBIN。
可使用allowed-values属性来定义用户创建配置时可从中选择的特定值。在此示例中,为lb-alg参数指定了两个值 - ROUNDROBIN 和 LEASTCONNECTION。
当您导入样本并使用它时,Citrix ADM会显示一个包含这三个参数的表单。显示的 name 和 ip 字段用于输入字符串和 IP 地址类型的值,lb-alg 字段显示为下拉列表,在其中 ROUNDROBIN 选为默认值。
注意
除了内置类型外,参数的类型还可以是另一个样本。这就是重用其他样本中定义的参数的方式。
组件
此样本的最后一部分称为 components 部分,它被视为样本中最重要的部分。在此部分,定义必须由样本创建的配置对象。
例如,必须按如下所示编写 components 部分:
components:-name:lbvserver-comptype:ns::lbvserverproperties:name:$parameters.nameservicetype:HTTPipv46:$parameters.ipport:80lbmethod:$parameters.lb-alg
此示例仅包含一个组件。组件的主要属性是 name、type 和 properties。组件的类型确定此组件提供哪些属性。组件有两种类型:
内置类型。此类型由系统提供,您不必定义它,例如,NITRO 实体类型为 “lbvserver” 或 “服务组”。在此实例中,使用的是内置组件类型。
复合类型。此类型是您创建并导入到 Citrix ADM 中的样书或 Citrix ADM 附带的默认样书。您可以在中了解有关复合样本的详细信息创建复合样书。
在此示例中,您定义了一个名为lbvserver-comp的组件。此组件的类型为ns። lbvserver(内置硝基类型),其中 “ns” 是引用命名空间 netscaler.nit.config 和版本 10.5 的前缀,而 “lbvserver” 是此命名空间中的硝基资源。
此处定义的properties是“lbvserver”资源的属性。要了解有关所有可用 Citrix ADC Nitro 资源及其属性的详细信息,请参阅Citrix ADC NITRO REST API 文档。
此部分中的属性包括“lbvserver”资源的必需属性,用于为这些属性指定值。在此示例中,为 servicetype 和 port 指定静态值,而 name、ipv46 和 lbmethod 属性从输入参数获取其值。在样书的其余部分中,可以使用$parameters.
注意
按照惯例,前缀 “ns” 始终用于在 “导入样书” 部分中指定 Citrix ADC Nitro 命名空间。尽管这不是必需的,但 Citrix 建议在您自己的样本中采用相同的约定以保持一致性。
构建您的样本
现在已定义了此样本的所有必要部分,将它们全部汇聚在一起即可构建您的第一个样本。将样本内容复制并粘贴到一个文本编辑器,然后将文件保存为lb-vserver.yaml。Citrix 建议您使用样本中的内置 YAML 验证程序来验证和导入 YAML 内容。
lb-vserver.yaml 文件的完整内容再现如下:
name:lb-vservernamespace:com.example.stylebookversion:"1.0"display-name:Load Balancing Virtual Server (HTTP)description:"ThisstylebookdefinesaverysimpleloadbalancingHTTPvirtualserverconfiguration"schema-version:"1.0"import-stylebooks:-namespace:netscaler.nitro.configversion:"10.5"prefix:ns-namespace:com.citrix.adc.stylebooksversion:"1.0"prefix:stlbparameters:-name:namelabel:"ApplicationName"description:"Giveanametotheapplicationconfiguration."type:stringrequired:true-name:vip-ipaddresslabel:"LoadBalancerIPAddress"description:"TheApplicationVIPthatclientsaccess"type:ipaddressrequired:true-name:lb-alglabel:LB Algorithmdescription:Load Balancing Algorithmtype:stringdefault:ROUNDROBINallowed-values:-ROUNDROBIN-LEAST-CONNECTIONcomponents:-name:lbvserver-compdescription:This StyleBook component (a Builtin Nitro StyleBook) builds a Citrix ADC load balancing virtual server configuration object.type:ns::lbvserverproperties:name:$parameters.nameipv46:$parameters.vip-ipaddresslbmethod:$parameters.lb-algservicetype:HTTPport:80
要开始使用样本创建配置,您必须将其导入 Citrix ADM,然后使用它。有关详细信息,请参阅如何使用用户定义的样本。
还可以将此样本导入其他样本(使用 import-stylebooks 构造)。或者,可以修改此样本以包含更多参数和组件,如下一节中所述。