8.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} 语法时，可将多个参数引用合并到一个字段中，并可将引用嵌入到固定数据中，如 "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 修饰符：

下面是附带参数定义和参考的完整模板示例：

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
        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 Service Broker 会识别 ConfigMap、Secret、Service 和 Route 上的公开字段，并在用户绑定代理所支持的服务时返回公开字段的值。

要公开对象的一个或多个字段，请在模板中为对象添加以 template.openshift.io/expose- 或 template.openshift.io/base64-expose- 为前缀的注解。

每个移除前缀的注解键均会被传递成为 bind 响应中的一个键。

每个注解值是一个 Kubernetes JSONPath 表达式，该表达式将在绑定时解析，以指示应在 bind 响应中返回值的对象字段。

以下是被公开的不同对象字段的示例：

kind: Template
apiVersion: v1
metadata:
  name: my-template
objects:
- kind: ConfigMap
  apiVersion: v1
  metadata:
    name: my-template-config
    annotations:
      template.openshift.io/expose-username: "{.data['my\\.username']}"
  data:
    my.username: foo
- kind: Secret
  apiVersion: v1
  metadata:
    name: my-template-config-secret
    annotations:
      template.openshift.io/base64-expose-password: "{.data['password']}"
  stringData:
    password: bar
- kind: Service
  apiVersion: v1
  metadata:
    name: my-template-service
    annotations:
      template.openshift.io/expose-service_ip_port: "{.spec.clusterIP}:{.spec.ports[?(.name==\"web\")].port}"
  spec:
    ports:
    - name: "web"
      port: 8080
- kind: Route
  apiVersion: v1
  metadata:
    name: my-template-route
    annotations:
      template.openshift.io/expose-uri: "http://{.spec.host}{.spec.path}"
  spec:
    path: mypath

下面是在遵守上述部分模板情况下，对 bind 操作的一个响应示例：

{
  "credentials": {
    "username": "foo",
    "password": "YmFy",
    "service_ip_port": "172.30.12.34:8080",
    "uri": "http://route-test.router.default.svc.cluster.local/mypath"
  }
}

模板创建者可指定：在服务目录、Template Service Broker 或 TemplateInstance API 进行的模板实例化被视为完成之前，应等待模板中的某些对象。

要使用该功能，请使用以下注解在模板中标记一个或多个Build、BuildConfig、Deployment、DeploymentConfig、Job 或 StatefulSet 类型的对象：

"template.alpha.openshift.io/wait-for-ready": "true"

直到标有注解的所有对象报告就绪时，模板实例化才算完成。同样，如果任何注解的对象报告失败，或者模板未能在一小时的固定超时内就绪，则模板实例化将失败。

就实例化而言，各种对象类型的就绪和失败定义如下：

以下是使用 wait-for-ready 注解的模板提取示例。更多示例可在 OpenShift quickstart 模板中找到。

kind: Template
apiVersion: v1
metadata:
  name: my-template
objects:
- kind: BuildConfig
  apiVersion: v1
  metadata:
    name: ...
    annotations:
      # wait-for-ready used on BuildConfig ensures that template instantiation
      # will fail immediately if build fails
      template.alpha.openshift.io/wait-for-ready: "true"
  spec:
    ...
- kind: DeploymentConfig
  apiVersion: v1
  metadata:
    name: ...
    annotations:
      template.alpha.openshift.io/wait-for-ready: "true"
  spec:
    ...
- kind: Service
  apiVersion: v1
  metadata:
    name: ...
  spec:
    ...

您可以 YAML 格式从项目中导出现有对象，然后通过添加参数和其他自定义作为模板表单来修改 YAML，而无需从头开始编写整个模板。