10.7. 编写模板

模板描述向用户介绍模板的作用，有助于用户在 web 控制台中搜索查找模板。除模板名称以外的其他元数据均为可选，但若有则会非常有用。除常规描述性信息外，元数据还应包含一组标签。实用标签包括与模板相关的语言名称（如 java 、 php 、 ruby 等）。 以下是模板描述性元数据的示例：

kind: Template
apiVersion: v1
metadata:
  name: cakephp-mysql-example 1
  annotations:
    openshift.io/display-name: "CakePHP MySQL Example (Ephemeral)" 2
    description: >-
      An example CakePHP application with a MySQL database. For more information
      about using this template, including OpenShift considerations, see
      https://github.com/sclorg/cakephp-ex/blob/master/README.md.
      WARNING: Any data stored will be lost upon pod destruction. Only use this
      template for testing." 3
    openshift.io/long-description: >-
      This template defines resources needed to develop a CakePHP application,
      including a build configuration, application DeploymentConfig, and
      database DeploymentConfig.  The database is stored in
      non-persistent storage, so this configuration should be used for
      experimental purposes only. 4
    tags: "quickstart,php,cakephp" 5
    iconClass: icon-php 6
    openshift.io/provider-display-name: "Red Hat, Inc." 7
    openshift.io/documentation-url: "https://github.com/sclorg/cakephp-ex" 8
    openshift.io/support-url: "https://access.redhat.com" 9
message: "Your admin credentials are ${ADMIN_USERNAME}:${ADMIN_PASSWORD}" 10

模板可包括一组标签。这些标签将添加至模板实例化时创建的各个对象中。采用这种方式定义标签可方便用户查找和管理从特定模板创建的所有对象。 以下是模板对象标签的示例：

kind: "Template"
apiVersion: "v1"
labels:
  template: "cakephp-mysql-example" 1
  app: "${NAME}" 2

允许用户提供一个值或在实例化模板时生成一个值作为参数。然后，该值将在引用参数的任意位置上被替换。可在对象列表字段中的任意字段中定义引用。这有助于生成随机密码，或允许用户提供自定义模板时所需的主机名或其他用户特定值。可通过以下两种方式引用参数： 作为字符串值，将格式为 ${PARAMETER_NAME} 的值放在模板的任意字符串字段中。 作为 json/yaml 值，将格式为 ${PARAMETER_NAME} 的值放在模板的任意字段中。 使用 ${PARAMETER_NAME} 语法时，可将多个参数引用合并到一个字段中，并可将引用嵌入到固定数据中，如 "http://${PARAMETER_1}${PARAMETER_2}" 。两个参数值均将被替换，结果值将是一个带引号的字符串。 使用 ${{PARAMETER_NAME}} 语法时，仅允许单个参数引用，不允许使用前导/尾随字符。执行替换后，结果值将不加引号，除非结果不是有效的 json 对象。如果结果不是有效的 json 值，则结果值将加引号并被视为标准字符串。 单个参数可在模板中多次引用，且可在单个模板中使用两种替换语法来引用。 可提供默认值，如果用户未提供其他值则使用默认值： 以下是将确切值设置为默认值的示例：

parameters:
  - name: USERNAME
    description: "The user name for Joe"
    value: joe

还可根据参数定义中指定的规则生成参数值，例如：

parameters:
  - name: PASSWORD
    description: "The random user password"
    generate: expression
    from: "[a-zA-Z0-9]{12}"

在前面的示例中，处理将生成一个全部由大小写字母和数字组成的 12 个字符长的随机密码。 可用语法并非完整的正则表达式语法。但是，您可以使用 \w 、 \d 和 \a 修饰符： [\w]{10} 生成 10 个字母字符、数字和下划线。这遵循 PCRE 标准，等同于 [a-zA-Z0-9_]{10} 。 [\d]{10} 生成 10 个数字。等同于 [0-9]{10} 。 [\a]{10} 生成 10 个字母字符。等同于 [a-zA-Z]{10} 。 下面是附带参数定义和参考的完整模板示例：

kind: Template
apiVersion: v1
metadata:
  name: my-template
objects:
  - kind: BuildConfig
    apiVersion: v1
    metadata:
      name: cakephp-mysql-example
      annotations:
        description: Defines how to build the application
    spec:
      source:
        type: Git
          uri: "${SOURCE_REPOSITORY_URL}" 1
          ref: "${SOURCE_REPOSITORY_REF}"
        contextDir: "${CONTEXT_DIR}"
  - kind: DeploymentConfig
    apiVersion: v1
    metadata:
      name: frontend
    spec:
      replicas: "${{REPLICA_COUNT}}" 2
parameters:
  - name: SOURCE_REPOSITORY_URL 3
    displayName: Source Repository URL 4
    description: The URL of the repository with your application source code 5
    value: https://github.com/sclorg/cakephp-ex.git 6
    required: true 7
  - name: GITHUB_WEBHOOK_SECRET
    description: A secret string used to configure the GitHub webhook
    generate: expression 8
    from: "[a-zA-Z0-9]{40}" 9
  - name: REPLICA_COUNT
    description: Number of replicas to run
    value: "2"
    required: true
message: "... The GitHub webhook secret is ${GITHUB_WEBHOOK_SECRET} ..." 10

模板主要部分为对象列表，将在模板实例化时创建。这可以是任何有效的 API 对象，如 BuildConfig 、 DeploymentConfig 、 Service 等。该对象将完全按照此处定义创建，创建前替换任意参数值。这些对象的定义可引用前面定义的参数。 以下是对象列表的示例：

kind: "Template"
apiVersion: "v1"
metadata:
  name: my-template
objects:
  - kind: "Service" 1
    apiVersion: "v1"
    metadata:
      name: "cakephp-mysql-example"
      annotations:
        description: "Exposes and load balances the application pods"
    spec:
      ports:
        - name: "web"
          port: 8080
          targetPort: 8080
      selector:
        name: "cakephp-mysql-example"

Template Service Broker 会在目录中为其知晓的每个模板对象公告一个服务。默认情况下，每个服务均会公告为“可绑定”，表示允许最终用户绑定制备的服务。 模板创建者可以防止最终用户绑定从给定模板制备的服务。 通过将注解 template.openshift.io/bindable: "false" 添加至模板中，防止最终用户绑定从给定模板制备的服务。