创建负载平衡虚拟服务器的样本
在此示例中,设计一个创建协议类型为 HTTP 且侦听端口 80 的负载平衡虚拟服务器的基本样本。虚拟服务器名称、IP 地址和负载平衡方法参数接受用户定义的值,即它们是样本的参数。
标题
样本的前六行构成标头部分。在此示例中,标头部分编写如下:
name:lb-vservernamespace:com.example.stylebookversion:"1.0"display-name:Load Balancing Virtual Server (HTTP)description:"ThisstylebookdefinesaverysimpleloadbalancingHTTPvirtualserverconfiguration"schema-version:"1.0"
标头部分包含以下详细信息:
- name:此样本的名称。
- description:定义此样本做什么的说明。此描述将显示在 Citrix Application Delivery Management (ADM) 上。
- 显示名称:Citrix ADM 上显示的样本的描述性名称。
- namespace:样本的唯一标识符的命名空间形式部分,以避免发生名称冲突。
- 模式版本:始终采用此版本中的值 “1.0”。
- version:样本的版本号。可以在更新样本时更改版本号。
name、namespace和version组合在系统中唯一标识样书。Citrix ADM 中不能有两个具有相同名称、命名空间和版本组合的样本。但可以有两个 name 和 version 相同但 namespace 不同或 namespace 和 version 相同但 name 不同的样本。
注意
假定您已更新您的样本,且您有更新的 version 号。现在,如果您要在其他样本中引用(即您要导入)此样本,请务必也在其他样本中更新 version 号,以便它们使用正确版本的导入样本。
导入样本
标题后面的部分称为 “导入样本”。 “ 在此部分中,必须在当前样本中声明要引用的任何其他样本的 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.nit.config,版本:10.5)。
导入其他样书的样书必须基于与其导入的样书相同或更高版本的 NITRO 版本,这一点很重要。例如,基于 NITRO 10.5 版的样书不能依赖或使用或导入基于 11.1 的样书。但是,基于版本 11.1 的样本可以导入基于小于 11.1 的任何版本的样本。
也可能是根本不导入 NITRO 命名空间的样书。这意味着样书不需要直接定义 NITRO 组件,而是可以导入(依赖)定义 NITRO 组件的样书。导入其他样书的样书始终获得依赖项层次结构中最高的 NITRO 版本。此外,它用于配置该版本或更高版本的 Citrix ADC。
参数
parameters 部分用于声明样本中需要的所有参数。作为样本开发人员,您必须决定您希望样本的用户要指定哪些输入。在此示例中,构建的样本要求其用户提供虚拟服务器的名称、其 IP 地址以及负载平衡方法。
parameters 部分类似如下:
parameters:-name:namelabel:"ApplicationName"description:"Giveanametotheapplicationconfiguration."type:stringrequired:true-name:vip-ipaddresslabel:"LoadBalancerIPAddress"description:"TheApplicationVIP那tclientsaccess"type:ipaddressrequired:true-name:lb-alglabel:LB Algorithmdescription:Load Balancing Algorithmtype:stringdefault:ROUNDROBINallowed-values:-ROUNDROBIN-LEAST-CONNECTION
注意
如果未提供参数的标签,则 Citrix ADM 在显示此参数时使用 name 属性。必须始终为参数定义标签,以便控制参数在 Citrix ADM 中的显示方式。
但使用 API 时,参数由其 name 指定。
在此部分中,声明了三个参数,它们以其name属性值来指示 -name表示虚拟服务器名称,ip表示虚拟服务器的 IP 地址,以及lb-alg表示负载平衡方法。
- type是指这些参数可以接收的值类型。例如,name 和
lb-alg
可以取一个字符串值,IP 值必须是 IP 地址类型。样本中的参数可以是以下任何内置类型: - 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 之间的数字。
- 密码:不透明/秘密字符串值。Citrix ADM 显示此参数的值时,将显示为星号 (*****)。
- 证书文件:证书文件。
- 密钥文件:证书私钥文件。
- file:此类型的参数要求用户上载文件,例如证书或密钥文件。
- object:由多个元素构成,其中每个元素都是参数。此类型可以用于对一个父参数下多个相关参数进行分组。
- 必填项:说明参数是必填项还是可选项。如果设置为 true,表示参数是必需的,用户必须在使用此样本创建配置时提供此参数值。默认情况下,所有参数都是可选的。在此示例中,name和ip是必需参数,而lb-alg是一个可选参数,其默认值为“ROUNDROBIN”。“
可使用default属性为可选参数分配默认值。创建配置时,如果用户未指定值,则使用默认值。例如,lb-alg参数的默认值是 ROUNDROBIN。
可使用allowed-values属性来定义用户创建配置时可从中选择的特定值。在此示例中,为lb-alg参数指定了两个值 - ROUNDROBIN 和 LEASTCONNECTION。
当您导入样本并使用它时,Citrix ADM 会显示一个包含这三个参数的表单。为名称和 IP 显示的字段允许输入字符串和值为ipaddress
的类型,而lb-alg
字段将显示为下拉列表,并选择 ROUNDROLIN 作为默认值。
注意
除了内置类型外,参数的类型还可以是另一个样本。这就是重用其他样本中定义的参数的方式。
组件
此样本的最后一部分称为 components 部分,它被视为样本中最重要的部分。在本节中,您将定义必须由样书创建的配置对象。
例如,必须按如下所示编写 components 部分:
components:-name:lbvserver-compdescription:This StyleBook component (a Builtin Nitro StyleBook) builds a Citrix ADC lbvserver configuration object.type:ns::lbvserverproperties:name:$parameters.nameipv46:$parameters.vip-ipaddresslbmethod:$parameters.lb-algservicetype:HTTPport:80
此示例仅包含一个组件。组件的主要属性是 name、type 和 properties。组件的类型确定此组件提供哪些属性。组件有两种类型:
- 内置类型:此类型由系统提供,您无需定义它,例如 NITRO 实体类型
lbvserver
或servicegroup
。在此示例中, 您使用的是内置组件类型。 - 复合类型:此类型是您创建并导入到 Citrix ADM 中的样本,或者是随 Citrix ADM 附带的默认样本。您可以在中了解有关复合样本的详细信息创建复合样本。
在此示例中,您定义了一个名为lbvserver-comp的组件。此组件的类型为ns። lbvserver(内置的 NITRO 类型),其中 “ns” 是指向导入样书部分中指定的命名空间 netscaler.nit.config 和版本 10.5 的前缀,并且lbvserver
是此命名空间中的 NITRO 资源。
此处定义的属性是lbvserver
资源的属性。要了解有关所有可用 Citrix ADC NITRO 资源及其属性的更多信息,请参阅Citrix ADC NITRO REST API 文档。
本节中的属性包括lbvserver
资源的必填属性,允许您为这些属性指定值。在此示例中,您正在为servicetype
和 port 指定静态值,而名称 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:"TheApplicationVIP那tclientsaccess"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 lbvserver configuration object.type:ns::lbvserverproperties:name:$parameters.nameipv46:$parameters.vip-ipaddresslbmethod:$parameters.lb-algservicetype:HTTPport:80
要开始使用样本创建配置,您必须将其导入 Citrix ADM,然后使用它。有关详细信息,请参阅如何使用用户定义的样本。
还可以将此样本导入其他样本(使用 import-stylebooks 构造)。或者,可以修改此样本以包含更多参数和组件,如下一节中所述。