Citrix Application Delivery Management 服务

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

在此示例中,设计一个创建协议类型为 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"
<!--NeedCopy-->

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

  • 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"
<!--NeedCopy-->

直接使用任何一个 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: 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
<!--NeedCopy-->

注意

如果未提供参数的标签,则 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 会显示一个包含这三个参数的表单。为名称和 IP 显示的字段允许输入字符串和值为 ipaddress 的类型,而 lb-alg 字段将显示为下拉列表,并选择 ROUNDROLIN 作为默认值。

注意

除了内置类型外,参数的类型还可以是另一个样本。这就是重用其他样本中定义的参数的方式。

组件

此样本的最后一部分称为 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
<!--NeedCopy-->

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

  • 内置类型:此类型由系统提供,您无需定义它,例如 NITRO 实体类型 lbvserverservicegroup。在此示例中, 您使用的是内置组件类型。
  • 复合类型:此类型是您创建并导入到 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.<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 lbvserver 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-stylebooks 构造)。或者,可以修改此样本以包含更多参数和组件,如下一节中所述。

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