10.7. 编写模板

您可以定义新模板,以便轻松重新创建应用程序的所有对象。该模板将定义由其创建的对象以及一些元数据,以指导创建这些对象。

以下是简单模板对象定义 (YAML) 的示例:

apiVersion: v1
kind: Template
metadata:
  name: redis-template
  annotations:
    description: "Description"
    iconClass: "icon-redis"
    tags: "database,nosql"
objects:
- apiVersion: v1
  kind: Pod
  metadata:
    name: redis-master
  spec:
    containers:
    - env:
      - name: REDIS_PASSWORD
        value: ${REDIS_PASSWORD}
      image: dockerfile/redis
      name: master
      ports:
      - containerPort: 6379
        protocol: TCP
parameters:
- description: Password used for Redis authentication
  from: '[A-Z0-9]{8}'
  generate: expression
  name: REDIS_PASSWORD
labels:
  redis: master

10.7.1. 编写模板描述

模板描述向用户介绍模板的作用,有助于用户在 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
1
模板的唯一名称。
2
可由用户界面使用的简单、用户友好型名称。
3
模板的描述。包含充足的详细信息,方便用户了解所部署的内容以及部署前须知的注意事项。还应提供其他信息链接,如 README 文件。可包括换行符来创建段落。
4
其他模板描述。例如,这可按照服务目录显示。
5
要与模板关联的标签,用于搜索和分组。添加将包含在其中一个提供的目录类别中的标签。请参见控制台常量文件中 CATALOG_CATEGORIES 中的 idcategoryAliases。此外,还可为整个集群自定义类别。
6
在 web 控制台中与模板一同显示的图标。

例 10.1. 可用图标

  • icon-3scale
  • icon-aerogear
  • icon-amq
  • icon-angularjs
  • icon-ansible
  • icon-apache
  • icon-beaker
  • icon-camel
  • icon-capedwarf
  • icon-cassandra
  • icon-catalog-icon
  • icon-clojure
  • icon-codeigniter
  • icon-cordova
  • icon-datagrid
  • icon-datavirt
  • icon-debian
  • icon-decisionserver
  • icon-django
  • icon-dotnet
  • icon-drupal
  • icon-eap
  • icon-elastic
  • icon-erlang
  • icon-fedora
  • icon-freebsd
  • icon-git
  • icon-github
  • icon-gitlab
  • icon-glassfish
  • icon-go-gopher
  • icon-golang
  • icon-grails
  • icon-hadoop
  • icon-haproxy
  • icon-helm
  • icon-infinispan
  • icon-jboss
  • icon-jenkins
  • icon-jetty
  • icon-joomla
  • icon-jruby
  • icon-js
  • icon-knative
  • icon-kubevirt
  • icon-laravel
  • icon-load-balancer
  • icon-mariadb
  • icon-mediawiki
  • icon-memcached
  • icon-mongodb
  • icon-mssql
  • icon-mysql-database
  • icon-nginx
  • icon-nodejs
  • icon-openjdk
  • icon-openliberty
  • icon-openshift
  • icon-openstack
  • icon-other-linux
  • icon-other-unknown
  • icon-perl
  • icon-phalcon
  • icon-php
  • icon-play
  • iconpostgresql
  • icon-processserver
  • icon-python
  • icon-quarkus
  • icon-rabbitmq
  • icon-rails
  • icon-redhat
  • icon-redis
  • icon-rh-integration
  • icon-rh-spring-boot
  • icon-rh-tomcat
  • icon-ruby
  • icon-scala
  • icon-serverlessfx
  • icon-shadowman
  • icon-spring-boot
  • icon-spring
  • icon-sso
  • icon-stackoverflow
  • icon-suse
  • icon-symfony
  • icon-tomcat
  • icon-ubuntu
  • icon-vertx
  • icon-wildfly
  • icon-windows
  • icon-wordpress
  • icon-xamarin
  • icon-zend
7
提供模板的个人或组织的名称。
8
用于参考更多模板文档的 URL。
9
用于获取模板支持的 URL。
10
模板实例化时显示的说明消息。该字段应向用户介绍如何使用新建资源。显示消息前,对消息进行参数替换,以便输出中包含所生成的凭据和其他参数。其中包括用户应遵守的所有后续步骤文档链接。

10.7.2. 编写模板标签

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

以下是模板对象标签的示例:

kind: "Template"
apiVersion: "v1"
...
labels:
  template: "cakephp-mysql-example" 1
  app: "${NAME}" 2
1
标签(label)应用于从该模板创建的所有对象。
2
参数化标签也应用于从该模板创建的所有对象。对标签键和值均执行参数扩展。

10.7.3. 编写模板参数

允许用户提供一个值或在实例化模板时生成一个值作为参数。然后,该值将在引用参数的任意位置上被替换。可在对象列表字段中的任意字段中定义引用。这有助于生成随机密码,或允许用户提供自定义模板时所需的主机名或其他用户特定值。可通过以下两种方式引用参数:

  • 作为字符串值,将格式为 ${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\A 修饰符:

  • [\w]{10} 生成 10 个字母字符、数字和下划线。这遵循 PCRE 标准,等同于 [a-zA-Z0-9_]{10}
  • [\d]{10} 生成 10 个数字。等同于 [0-9]{10}
  • [\a]{10} 生成 10 个字母字符。等同于 [a-zA-Z]{10}
  • [\A]{10} 生成 10 个模态或符号字符。这等同于 [~!@#$%\^&*()\-_+={}\[\]\\|<,>.?/"';:`]{10}
注意

取决于模板是以 YAML 还是以 JSON 编写,以及其中的修饰符的字符串类型,您可能需要用第二个反斜杠转义反斜杠。以下示例等同于:

带有修饰程序的 YAML 模板示例

  parameters:
  - name: singlequoted_example
    generate: expression
    from: '[\A]{10}'
  - name: doublequoted_example
    generate: expression
    from: "[\\A]{10}"

带有修饰符的 JSON 模板示例

{
    "parameters": [
       {"name": "json_example",
        "generate": "expression",
        "from": "[\\A]{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
        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
1
模板实例化时,该值将被替换为 SOURCE_REPOSITORY_URL 参数的值。
2
模板实例化时,该值将被替换为 REPLICA_COUNT 参数的不加引号值。
3
参数的名称。该值用于引用模板中的参数。
4
参数的用户友好型名称。这会为用户显示。
5
参数的描述。出于参数目的提供更详细的信息,包括对预期值的任何限制。描述应当按照控制台的文本标准使用完整句子。不可与显示名称重复。
6
如果您实例化该模板时不覆盖该值,则使用该参数的默认值。密码之类避免使用默认值,而应结合使用生成的参数与 secret。
7
指示此参数是必需的,这意味着您无法使用空值覆盖它。如果参数未提供默认值或生成值,您必须提供一个值。
8
生成其值的参数。
9
生成器的输入。这种情况下,生成器会生成一个 40 个字符的字母数字值,其中包括大写和小写字符。
10
参数可包含在模板消息中。这将告知您生成的值。

10.7.4. 编写模板对象列表

模板主要部分为对象列表,将在模板实例化时创建。这可以是任何有效的 API 对象,如构建配置、部署配置或服务。该对象按照此处定义创建,创建前替换任意参数值。这些对象的定义可引用前面定义的参数。

以下是对象列表的示例:

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"
1
服务的定义,由该模板创建。
注意

如果对象定义元数据包含固定的 namespace 字段值,则会在模板实例化过程中从定义中分离。如果 namespace 字段包含参数引用,则将执行正常的参数替换,并参数替换将值解析到的任何命名空间中创建对象,假定用户有权在该命名空间中创建对象。

10.7.5. 将模板标记为可绑定

Template Service Broker 会在目录中为其了解的每个模板对象公告一个服务。默认情况下,每个服务均会公告为“可绑定”,表示允许最终用户绑定制备的服务。

流程

模板创建者可以防止最终用户绑定从给定模板制备的服务。

  • 通过将注解 template.openshift.io/bindable: "false" 添加至模板中,防止最终用户绑定从给定模板制备的服务。

10.7.6. 公开模板对象字段

模板创建者可指定模板中的特定对象字段应公开。Template Service Broker 会识别 ConfigMapSecretServiceRoute 上公开的字段,并在用户绑定代理支持的服务时返回公开字段的值。

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

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

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

注意

Bind 响应键/值对可在系统其他部分用作环境变量。因此,建议删除前缀的每个注解键均应为有效的环境变量名称,以字符 A-Za-z_ 开头,后跟 0 或 A-Za-z0-9_ 等更多字符。

注意

除非用反斜杠转义,否则 Kubernetes 的 JSONPath 实现会将 .@ 字符等解析为元字符,而无关其在表达式中的位置。因此,例如要引用名为 my.keyConfigMap 数据,所需 JSONPath 表达式应为 {.data['my\.key']}。根据 JSONPath 表达式在 YAML 中的编写方式,可能需要额外增加反斜杠,如 "{.data['my\\.key']}"

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

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.openshift.io/expose- 注解来以字符串形式返回字段值。这样很方便,尽管没有处理任意二进制数据。
  • 如果要返回二进制数据,请在返回前使用 template.openshift.io/base64-expose- 注解对数据进行 base64 编码。

10.7.7. 等待模板就绪

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

要使用该功能,请使用以下注解在模板中标记一个或多个BuildBuildConfigDeploymentDeploymentConfigJobStatefulSet 类型的对象:

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

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

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

类型就绪失败

Build

对象报告阶段完成。

对象报告阶段取消、错误或失败

BuildConfig

最新关联构建对象报告阶段完成

最新关联构建对象报告阶段取消、错误或失败

Deployment

对象报告新副本集和部署可用。这遵循对象上定义的就绪探针。

对象报告进度状况为 false。

DeploymentConfig

对象报告新的复制控制器和部署可用。这遵循对象上定义的就绪探针。

对象报告进度状况为 false。

Job

对象报告完成。

对象报告出现一个或多个故障。

StatefulSet

对象报告所有副本就绪。这遵循对象上定义的就绪探针。

不适用。

以下是使用 wait-for-ready 注解的模板提取示例。更多示例可在 OpenShift Container Platform 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:
    ...

其他建议

  • 设置内存、CPU 和存储的默认大小,以确保您的应用程序获得足够资源使其平稳运行。
  • 如果要在主版本中使用该标签,请避免引用来自镜的 latest 标签。当新镜像被推送(push)到该标签时,这可能会导致运行中的应用程序中断。
  • 良好的模板可整洁地构建和部署,无需在部署模板后进行修改。

10.7.8. 从现有对象创建模板

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

流程

  • 以 YAML 格式导出项目中的对象:

    $ oc get -o yaml --export all > <yaml_filename>

    您还可替换特定资源类型或多个资源,而非 all 资源。运行 oc get -h 获取更多示例。

    oc get --export all 中包括的对象类型是:

    • BuildConfig
    • Build
    • DeploymentConfig
    • ImageStream
    • Pod
    • ReplicationController
    • Route
    • Service