×

理解模板

模板描述了一组可以参数化并处理以生成对象列表的对象,这些对象列表可由Red Hat OpenShift Service on AWS创建。模板可以处理以创建您有权在项目中创建的任何内容,例如服务、构建配置和部署配置。模板还可以定义一组标签,将其应用于模板中定义的每个对象。

您可以使用CLI或(如果模板已上传到您的项目或全局模板库)使用Web控制台从模板创建对象列表。

上传模板

如果您有定义模板的JSON或YAML文件,则可以使用CLI将模板上传到项目。这会将模板保存到项目中,以便任何具有该项目相应访问权限的用户重复使用。本主题后面提供了有关编写您自己的模板的说明。

步骤
  • 使用以下方法之一上传模板

    • 将模板上传到您当前项目的模板库,使用以下命令传递JSON或YAML文件

      $ oc create -f <filename>
    • 使用带有项目名称的-n选项将模板上传到不同的项目

      $ oc create -f <filename> -n <project>

现在可以使用Web控制台或CLI选择该模板。

使用Web控制台创建应用程序

您可以使用Web控制台从模板创建应用程序。

步骤
  1. 从Web控制台导航菜单顶部的上下文选择器中选择**开发者**。

  2. 在所需项目中,单击**+添加**。

  3. 在**开发者目录**磁贴中单击**所有服务**。

  4. 单击**类型**下的**构建器镜像**以查看可用的构建器镜像。

    只有在注释中列出builder标签的镜像流标签才会显示在此列表中,如下所示

    kind: "ImageStream"
    apiVersion: "image.openshift.io/v1"
    metadata:
      name: "ruby"
      creationTimestamp: null
    spec:
    # ...
      tags:
        - name: "2.6"
          annotations:
            description: "Build and run Ruby 2.6 applications"
            iconClass: "icon-ruby"
            tags: "builder,ruby" (1)
            supports: "ruby:2.6,ruby"
            version: "2.6"
    # ...
    1 在此处包含builder可确保此镜像流标签在Web控制台中显示为构建器。
  5. 修改新应用程序屏幕中的设置以配置支持您的应用程序的对象。

使用CLI从模板创建对象

您可以使用CLI处理模板并使用生成的配置来创建对象。

添加标签

标签用于管理和组织生成的对象,例如pod。模板中指定的标签将应用于从模板生成的每个对象。

步骤
  • 从命令行在模板中添加标签

    $ oc process -f <filename> -l name=otherLabel

列出参数

您可以覆盖的参数列表列在模板的parameters部分中。

步骤
  1. 您可以使用以下命令并指定要使用的文件来使用CLI列出参数

    $ oc process --parameters -f <filename>

    或者,如果模板已上传

    $ oc process --parameters -n <project> <template_name>

    例如,以下显示在列出默认openshift项目中快速入门模板之一的参数时的输出

    $ oc process --parameters -n openshift rails-postgresql-example
    示例输出
    NAME                         DESCRIPTION                                                                                              GENERATOR           VALUE
    SOURCE_REPOSITORY_URL        The URL of the repository with your application source code                                                                  https://github.com/sclorg/rails-ex.git
    SOURCE_REPOSITORY_REF        Set this to a branch name, tag or other ref of your repository if you are not using the default branch
    CONTEXT_DIR                  Set this to the relative path to your project if it is not in the root of your repository
    APPLICATION_DOMAIN           The exposed hostname that will route to the Rails service                                                                    rails-postgresql-example.openshiftapps.com
    GITHUB_WEBHOOK_SECRET        A secret string used to configure the GitHub webhook                                                     expression          [a-zA-Z0-9]{40}
    SECRET_KEY_BASE              Your secret key for verifying the integrity of signed cookies                                            expression          [a-z0-9]{127}
    APPLICATION_USER             The application user that is used within the sample application to authorize access on pages                                 openshift
    APPLICATION_PASSWORD         The application password that is used within the sample application to authorize access on pages                             secret
    DATABASE_SERVICE_NAME        Database service name                                                                                                        postgresql
    POSTGRESQL_USER              database username                                                                                        expression          user[A-Z0-9]{3}
    POSTGRESQL_PASSWORD          database password                                                                                        expression          [a-zA-Z0-9]{8}
    POSTGRESQL_DATABASE          database name                                                                                                                root
    POSTGRESQL_MAX_CONNECTIONS   database max connections                                                                                                     10
    POSTGRESQL_SHARED_BUFFERS    database shared buffers                                                                                                      12MB

    输出标识了几个参数,这些参数在处理模板时使用类似正则表达式的生成器生成。

生成对象列表

使用CLI,您可以处理定义模板的文件以将对象列表返回到标准输出。

步骤
  1. 处理定义模板的文件以将对象列表返回到标准输出

    $ oc process -f <filename>

    或者,如果模板已上传到当前项目

    $ oc process <template_name>
  2. 通过处理模板并将输出传递到oc create来从模板创建对象

    $ oc process -f <filename> | oc create -f -

    或者,如果模板已上传到当前项目

    $ oc process <template> | oc create -f -
  3. 您可以通过为要覆盖的每个<name>=<value>对添加-p选项来覆盖文件中定义的任何参数值。参数引用出现在模板项目内的任何文本字段中。

    例如,在下面的示例中,模板的POSTGRESQL_USERPOSTGRESQL_DATABASE参数被覆盖,以输出具有自定义环境变量的配置

    1. 从模板创建对象列表

      $ oc process -f my-rails-postgresql \
          -p POSTGRESQL_USER=bob \
          -p POSTGRESQL_DATABASE=mydatabase
    2. JSON文件可以重定向到文件,也可以通过将处理后的输出传递到oc create命令来直接应用,而无需上传模板。

      $ oc process -f my-rails-postgresql \
          -p POSTGRESQL_USER=bob \
          -p POSTGRESQL_DATABASE=mydatabase \
          | oc create -f -
    3. 如果您有大量参数,可以将它们存储在文件中,然后将此文件传递给oc process

      $ cat postgres.env
      POSTGRESQL_USER=bob
      POSTGRESQL_DATABASE=mydatabase
      $ oc process -f my-rails-postgresql --param-file=postgres.env
    4. 您还可以通过使用"-"作为--param-file的参数来读取标准输入中的环境。

      $ sed s/bob/alice/ postgres.env | oc process -f my-rails-postgresql --param-file=-

修改上传的模板

您可以编辑已上传到项目的模板。

步骤
  • 修改已上传的模板

    $ oc edit template <template>

编写模板

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

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

apiVersion: template.openshift.io/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

编写模板描述

模板描述会告知您模板的功能,并帮助您在Web控制台中搜索时找到它。除了模板名称之外的其他元数据是可选的,但很有用。除了常规描述性信息之外,元数据还包括一组标签。有用的标签包括与模板相关的语言的名称,例如Java、PHP、Ruby等等。

以下是模板描述元数据的示例

kind: Template
apiVersion: template.openshift.io/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 模板的描述。包含足够的细节,以便用户了解正在部署的内容以及在部署之前必须知道的任何注意事项。它还应提供指向其他信息的链接,例如自述文件。可以包含换行符来创建段落。
4 其他模板描述。例如,服务目录可能会显示此信息。
5 用于搜索和分组的模板关联标签。将包含它的标签添加到提供的目录类别之一中。请参考控制台常量文件中的CATALOG_CATEGORIES中的idcategoryAliases
6 在 Web 控制台中显示与您的模板一起显示的图标。
可用图标
  • 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

  • icon-postgresql

  • 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 实例化此模板时显示的指导消息。此字段应告知用户如何使用新创建的资源。在显示消息之前,对消息执行参数替换,以便生成的凭据和其他参数可以包含在输出中。包含用户应遵循的任何后续步骤文档的链接。

编写模板标签

模板可以包含一组标签。这些标签将添加到实例化模板时创建的每个对象。以这种方式定义标签使用户可以轻松查找和管理从特定模板创建的所有对象。

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

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

编写模板参数

参数允许您提供值或在实例化模板时生成值。然后,该值将替换参数引用的任何位置。引用可以在对象列表字段中的任何字段中定义。这对于生成随机密码或允许您提供自定义模板所需的 hostname 或其他用户特定值非常有用。参数可以通过两种方式引用

  • 作为字符串值,方法是在模板中的任何字符串字段中以${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: template.openshift.io/v1
metadata:
  name: my-template
objects:
  - kind: BuildConfig
    apiVersion: build.openshift.io/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: apps.openshift.io/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 参数的默认值,如果您在实例化模板时不覆盖该值,则使用该值。避免对密码等使用默认值,而应将生成的的参数与密钥结合使用。
7 指示此参数是必需的,这意味着您不能使用空值覆盖它。如果参数不提供默认值或生成的值,则必须提供一个值。
8 其值已生成的的参数。
9 生成器的输入。在本例中,生成器会生成一个包含大小写字母的 40 个字符的字母数字值。
10 参数可以包含在模板消息中。这会通知您生成的值。

编写模板对象列表

模板的主要部分是实例化模板时创建的对象列表。这可以是任何有效的 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字段包含参数引用,则会执行正常的参数替换,并且对象将在参数替换解析到的任何命名空间中创建,前提是用户有权在该命名空间中创建对象。

将模板标记为可绑定

模板服务代理在其目录中为其了解的每个模板对象宣传一项服务。默认情况下,这些服务中的每一个都被宣传为可绑定的,这意味着最终用户可以针对已配置的服务进行绑定。

步骤

模板作者可以阻止最终用户绑定针对从给定模板配置的服务。

  • 通过向模板添加注释template.openshift.io/bindable: "false" 来阻止最终用户绑定针对从给定模板配置的服务。

公开模板对象字段

模板作者可以指示应公开模板中特定对象的字段。模板服务代理识别ConfigMapSecretServiceRoute对象上的公开字段,并在用户绑定由代理支持的服务时返回公开字段的值。

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

每个注释键(去除其前缀)都将被传递以成为bind响应中的键。

每个注释值都是 Kubernetes JSONPath 表达式,它在绑定时被解析以指示应在bind响应中返回其值的字段。

Bind响应键值对可以在系统的其他部分用作环境变量。因此,建议每个注释键(去除其前缀)都应是一个有效的环境变量名称——以字符A-Za-z_开头,后跟零个或多个字符A-Za-z0-9_

除非用反斜杠转义,否则 Kubernetes 的 JSONPath 实现会将诸如.@之类的字符解释为元字符,而不管它们在表达式中的位置如何。因此,例如,要引用名为my.keyConfigMap数据,所需的 JSONPath 表达式将是{.data['my\.key']}。根据 YAML 中 JSONPath 表达式的编写方式,可能需要额外的反斜杠,例如"{.data['my\\.key']}"

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

kind: Template
apiVersion: template.openshift.io/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: <password>
- 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: route.openshift.io/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 编码后再返回。

等待模板就绪

模板作者可以指示在服务目录、模板服务代理或TemplateInstance API 认为模板实例化完成之前,应等待模板中的某些对象。

要使用此功能,请使用以下注释标记模板中类型为BuildBuildConfigDeploymentDeploymentConfigJobStatefulSet的一个或多个对象

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

只有当所有标有该注释的对象都报告就绪时,模板实例化才算完成。类似地,如果任何带注释的对象报告失败,或者如果模板在 1 小时的固定超时时间内未能就绪,则模板实例化将失败。

出于实例化的目的,每种对象的准备就绪和失败定义如下

类型 准备就绪 失败

构建

对象报告阶段完成。

对象报告阶段已取消、出错或失败。

BuildConfig

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

最新关联的构建对象报告阶段已取消、出错或失败。

部署

部署

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

对象报告正在进行的条件为假。

DeploymentConfig

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

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

作业

对象报告已完成。

对象报告已发生一个或多个故障。

StatefulSet

对象报告所有副本都已准备就绪。这会遵循对象上定义的就绪探测。

不适用。

kind: Template
apiVersion: template.openshift.io/v1
metadata:
  name: my-template
objects:
- kind: BuildConfig
  apiVersion: build.openshift.io/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: apps.openshift.io/v1
  metadata:
    name: ...
    annotations:
      template.alpha.openshift.io/wait-for-ready: "true"
  spec:
    ...
- kind: Service
  apiVersion: v1
  metadata:
    name: ...
  spec:
    ...
以下是使用wait-for-ready注释的模板摘录示例。更多示例可以在 Red Hat OpenShift Service on AWS 快速入门模板中找到。
  • 其他建议

  • 设置内存、CPU 和存储的默认大小,以确保您的应用程序获得足够的资源来平稳运行。

  • 如果该标签跨主要版本使用,请避免引用图像中的latest标签。当新的图像被推送到该标签时,这可能会导致正在运行的应用程序中断。

一个好的模板会在部署后无需修改即可干净地构建和部署。

从现有对象创建模板

步骤
  • 您可以不必从头开始编写整个模板,而是可以以 YAML 形式从您的项目中导出现有对象,然后通过添加参数和其他自定义项作为模板形式来修改 YAML。

    $ oc get -o yaml all > <yaml_filename>

    以 YAML 形式导出项目中的对象

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

    • BuildConfig

    • 构建

    • 对象报告正在进行的条件为假。

    • oc get -o yaml all中包含的对象类型为:

    • ImageStream

    • Pod

    • ReplicationController

    • Route

Service