创建负载平衡虚拟服务器的样本

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

标头

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

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"

标头部分包含以下详细信息:

  • name:此样本的名称。
  • description:定义此样本做什么的说明。此描述将显示在 Citrix Application Delivery Management (ADM) 上。
  • 显示名称:Citrix ADM 上显示的样本的描述性名称。
  • namespace:样本的唯一标识符的命名空间形式部分,以避免发生名称冲突。
  • 模式版本:始终采用此版本中的值 “1.0”。
  • version:样本的版本号。可以在更新样本时更改版本号。

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

注意

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

导入样本

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

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

import-stylebooks:
 -
  namespace: netscaler.nitro.config
  prefix: ns
  version: "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: 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

注意

如果未提供参数的标签,则 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,表示参数是必需的,用户必须在使用此样本创建配置时提供此参数值。默认情况下,所有参数都是可选的。在此示例中,nameip 是必需参数,而 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
  description: This StyleBook component (a Builtin Nitro StyleBook) builds a Citrix ADC lbvserver configuration object.
  type: ns::lbvserver
  properties:
   name: $parameters.name
   ipv46: $parameters.vip-ipaddress
   lbmethod: $parameters.lb-alg
   servicetype: HTTP
   port: 80

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

  • 内置类型:此类型由系统提供,不必定义,例如 NITRO 实体类型“lbvserver”或“servicegroup”。在此示例中, 您使用的是内置组件类型。
  • 复合类型:此类型是您创建并导入到 Citrix ADM 中的样本,或者是随 Citrix ADM 附带的默认样本。您可以在中了解有关复合样本的详细信息创建复合样本

在此示例中,您定义了一个名为 lbv/服务器comp的组件。此组件的类型为 ns::lbvserver(内置 Nitro 类型),其中“ns”是指代在 import-stylebooks 部分中指定的命名空间 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”始终用于指定“import-stylebooks”部分中的 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 lbvserver configuration object.
  type: ns::lbvserver
  properties:
   name: $parameters.name
   ipv46: $parameters.vip-ipaddress
   lbmethod: $parameters.lb-alg
   servicetype: HTTP
   port: 80

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

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

创建负载平衡虚拟服务器的样本