Application Delivery Management

用于创建负载平衡虚拟服务器的样书

在此示例中,设计一个创建协议类型为 HTTP 且侦听端口 80 的负载平衡虚拟服务器的基本样书。虚拟服务器名称、IP 地址和负载平衡方法参数接受用户定义的值,即它们是样本的参数。

标题

样本的前六行构成标头部分。在此示例中,标头部分编写如下:

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:此样书的名称。

  • description:定义此样书做什么的说明。此描述显示在 Citrix ADM 上。

  • display-name:出现在 Citrix ADM 上的样书的描述性名称。

  • namespace:样书的唯一标识符的命名空间形式部分,以避免发生名称冲突。

  • schema-version:在此版本中,其值总是“1.0”。

  • version:样书的版本号。可以在更新样本时更改版本号。

namenamespaceversion 组合在系统中唯一标识样书。在 Citrix ADM 中不能有两本具有相同名称、命名空间和版本组合的样书。但可以有两个 name 和 version 相同但 namespace 不同或 namespace 和 version 相同但 name 不同的样书。

注意

假定您已更新您的样书,且您有更新的 version 号。现在,如果您要在其他样书中引用(即您要导入)此样书,请务必也在其他样书中更新 version 号,以便它们使用正确版本的导入样书。

导入样书

标头后面的部分称为“import-样书”。在此部分中,必须在当前样书中声明要引用的任何其他样书的 namespace 和 version 号。这样可以导入并重用其他样本,而不是在您自己的样本中重新构建相同的配置。

在此示例中,import-样书部分编写如下:

import-stylebooks:
 -
  namespace: netscaler.nitro.config
  prefix: ns
  version: "10.5"
<!--NeedCopy-->

直接使用任何一个 NITRO 配置对象的每个样书都必须引用 netscaler.nitro.config 命名空间。此命名空间包含所有 Citrix ADC NITRO 类型,例如 LBVServer。由于支持 10.5 及更高版本的软件版本,因此您可以使用样书在运行 10.5 及更高版本的任何 Citrix ADC 实例上创建和运行配置。

import-样书部分中使用的前缀是指代命名空间和版本组合的简写。在此示例中,ns 是指版本为 10.5 的 netscaler.nitro.config。在样书的后面部分,并非使用命名空间和版本来指代被导入样书,可以使用上述示例中选择的前缀字符串,例如 ns。

样本中使用的版本是 Citrix ADC NITRO 版本。基于 Nitro 版本 X 的样本可用于配置 X 或更高版本的任何 Citrix ADC。

注意

为确保您的样本可用于配置 10.5 或更高版本的任何 Citrix ADC 实例,Citrix 建议您在直接使用 Nitro 内置样本的样本中导入 Nitro 10.5 命名空间 (namespace: netscaler.nitro.config, version: 10.5)。

重要的是,导入其他样书的样书必须基于与其导入的样书相同或更高版本的 Nitro 版本。例如,基于 Nitro 版本 10.5 的样书不能依赖或使用或导入基于 11.1 的样书。但是,基于版本 11.1 的样书可以导入基于小于 11.1 的任何版本的样书。  

样书 也有可能根本不导入 Nitro 命名空间。这意味着样书无需直接定义 Nitro 组件,但可以导入(依赖)定义 Nitro 组件的样书。导入其他样本的样本始终获取其依赖关系层次结构中的最高 Nitro 版本,因此可用于配置该版本或更高版本的 Citrix ADC。

参数

parameters 部分用于声明样本中需要的所有参数。作为样本开发人员,您必须决定您希望样本的用户要指定哪些输入。在此示例中,构建的样本要求其用户提供虚拟服务器的名称、其 IP 地址以及负载平衡方法。

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-->

注意

如果您不提供参数的标签,则 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)。
  • ipaddress。表示有效 IPv4 或 IPv6 地址的字符串。
  • tcp 端口。一个介于 0 到 65535 之间的数字,代表 TCP 或 UDP 端口。
  • 密码。一个不透明/秘密的字符串值。当 Citrix ADM 显示此参数的值时,它将显示为星号 (*****)。
  • certfile。证书文件。
  • 密钥文件。证书私钥文件。
  • 文件。这种类型的参数要求用户上载文件,例如证书或密钥文件。
  • 对象。由多个元素组成,每个元素都是一个参数。此类型可以用于对一个父参数下多个相关参数进行分组。
  • 必需的。说明参数是必需的还是可选的。如果设置为 true,表示参数是必需的,用户必须在使用此样书创建配置时提供此参数值。默认情况下,所有参数都是可选的。在此示例中, 名称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-comp
  type: ns::lbvserver
  properties:
   name: $parameters.name
   servicetype: HTTP
   ipv46: $parameters.ip
   port: 80
   lbmethod: $parameters.lb-alg
<!--NeedCopy-->

此示例仅包含一个组件。组件的主要属性是 name、type 和 properties。组件的类型确定此组件提供哪些属性。组件有两种类型:

  • 内置类型。此类型由系统提供,您无需对其进行定义,例如,NITRO 实体类型“lbvserver”或“servicegroup”。在此实例中,使用的是内置组件类型。

  • 复合类型。此类型是您创建并导入到 Citrix ADM 中的样书或 Citrix ADM 附带的默认样书。您可以在创建复合样书中了解有关复合样本的更多信息。

在此示例中,您定义了一个名为 lbvserver-comp的组件。此组件的类型为 ns::lbvserver(内置的 Nitro 类型),其中“ns”是指您在导入样式书籍部分中指定的命名空间 netscaler.nitro.config 和版本 10.5 的前缀,“lbvserver”是该命名空间中的 Nitro 资源。

此处定义的 properties 是“lbvserver”资源的属性。要了解有关所有可用的 Citrix ADC Nitro 资源及其属性的更多信息,请参阅 Citrix ADC NITRO REST API 文档

此部分中的属性包括“lbvserver”资源的必需属性,用于为这些属性指定值。在此示例中,为 servicetype 和 port 指定静态值,而 name、ipv46 和 lbmethod 属性从输入参数获取其值。在样书的其余部分中,可以使用 $parameters.<parameter-name> 表示法(例如 $parameters.ip)来引用在 parameters 部分定义的参数名称。

注意

按照惯例,在“导入样式手册”部分中始终使用前缀“ns”来指定 Citrix ADC Nitro 命名空间。尽管这不是必需的,但 Citrix 建议在您自己的样书中采用相同的约定以保持一致性。

构建您的样书

现在已定义了此样书的所有必要部分,将它们全部汇聚在一起即可构建您的第一个样书。将样书内容复制并粘贴到一个文本编辑器,然后将文件保存为 lb-vserver.yaml。Citrix 建议您使用样书中的内置 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 Citrix ADC 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-->

要开始使用样本创建配置,您必须将其导入 Citrix ADM,然后使用它。有关详细信息,请参阅如何使用用户定义的样书

还可以将此样书导入其他样书(使用 import-样书构造)。或者,可以修改此样书以包含更多参数和组件,如下一节中所述。

用于创建负载平衡虚拟服务器的样书