$ oc create -f <filename>
模板描述一组可以参数化和处理的对象,以生成 OpenShift Container Platform 创建的对象列表。模板可以处理以创建您有权在项目中创建的任何内容,例如服务、构建配置和部署配置。模板还可以定义一组要应用于模板中定义的每个对象的标签。
您可以使用 CLI 从模板创建对象列表,或者如果模板已上传到您的项目或全局模板库,则可以使用 Web 控制台。
如果您有定义模板的 JSON 或 YAML 文件,则可以使用 CLI 将模板上传到项目。这会将模板保存到项目中,以便任何具有该项目相应访问权限的用户都可以重复使用。
使用以下方法之一上传模板
将模板上传到您当前项目的模板库,使用以下命令传递 JSON 或 YAML 文件
$ oc create -f <filename>
使用带有项目名称的 -n
选项将模板上传到不同的项目
$ oc create -f <filename> -n <project>
现在可以使用 Web 控制台或 CLI 选择该模板。
您可以使用 Web 控制台从模板创建应用程序。
从 Web 控制台导航菜单顶部的上下文选择器中选择**开发者**。
在所需的项目中,单击**+添加**
在**开发者目录**磁贴中单击**所有服务**。
点击**类型**下的构建器镜像查看可用的构建器镜像。
此列表中仅显示在注释中列出了 |
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 控制台中显示为构建器。 |
修改新应用程序屏幕中的设置以配置对象以支持您的应用程序。
您可以使用 CLI 处理模板并使用生成的配置来创建对象。
标签用于管理和组织生成的资源,例如 Pod。模板中指定的标签将应用于从模板生成的每个对象。
从命令行在模板中添加标签
$ oc process -f <filename> -l name=otherLabel
可以在模板的parameters
部分列出您可以覆盖的参数。
您可以使用以下命令并指定要使用的文件来使用 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,您可以处理定义模板的文件以将对象列表返回到标准输出。
处理定义模板的文件以将对象列表返回到标准输出
$ oc process -f <filename>
或者,如果模板已上传到当前项目
$ oc process <template_name>
通过处理模板并将输出传递到oc create
来从模板创建对象
$ oc process -f <filename> | oc create -f -
或者,如果模板已上传到当前项目
$ oc process <template> | oc create -f -
您可以通过为要覆盖的每个<name>=<value>
对添加-p
选项来覆盖文件中定义的任何参数值。参数引用出现在模板项内的任何文本字段中。
例如,在以下示例中,模板的POSTGRESQL_USER
和POSTGRESQL_DATABASE
参数被覆盖,以输出具有自定义环境变量的配置
从模板创建对象列表
$ oc process -f my-rails-postgresql \
-p POSTGRESQL_USER=bob \
-p POSTGRESQL_DATABASE=mydatabase
JSON 文件可以重定向到文件,也可以通过将处理后的输出传递到oc create
命令来直接应用,而无需上传模板。
$ oc process -f my-rails-postgresql \
-p POSTGRESQL_USER=bob \
-p POSTGRESQL_DATABASE=mydatabase \
| oc create -f -
如果您有大量参数,可以将它们存储在文件中,然后将此文件传递给oc process
$ cat postgres.env
POSTGRESQL_USER=bob
POSTGRESQL_DATABASE=mydatabase
$ oc process -f my-rails-postgresql --param-file=postgres.env
您还可以通过使用"-"
作为--param-file
的参数来从标准输入读取环境。
$ sed s/bob/alice/ postgres.env | oc process -f my-rails-postgresql --param-file=-
OpenShift Container Platform 提供了许多默认的即时应用程序和快速入门模板,以便您可以轻松快速地开始为不同的语言创建新的应用程序。提供了 Rails (Ruby)、Django (Python)、Node.js、CakePHP (PHP) 和 Dancer (Perl) 的模板。您的集群管理员必须在默认的全局openshift
项目中创建这些模板,以便您可以访问它们。
默认情况下,模板使用包含必要应用程序代码的 GitHub 上的公共源代码仓库进行构建。
您可以使用以下命令列出可用的默认即时应用程序和快速入门模板
$ oc get templates -n openshift
要修改源代码并构建您自己的应用程序版本
派生模板的默认SOURCE_REPOSITORY_URL
参数引用的仓库。
从模板创建时,覆盖SOURCE_REPOSITORY_URL
参数的值,指定您的派生仓库而不是默认值。
通过这样做,模板创建的构建配置现在指向您的应用程序代码派生仓库,您可以随意修改代码并重新构建应用程序。
一些即时应用程序和快速入门模板定义了数据库部署配置。它们定义的配置使用短暂存储来存储数据库内容。这些模板仅应用于演示目的,因为如果数据库 Pod 因任何原因重启,所有数据库数据都会丢失。 |
快速入门模板是在 OpenShift Container Platform 上运行的应用程序的基本示例。快速入门提供各种语言和框架,并定义在模板中,该模板由一组服务、构建配置和部署配置构成。此模板引用构建和部署应用程序所需的镜像和源代码仓库。
要浏览快速入门,请从模板创建应用程序。您的管理员必须已在您的 OpenShift Container Platform 集群中安装这些模板,在这种情况下,您可以直接从 Web 控制台中选择它。
快速入门引用包含应用程序源代码的源代码仓库。要自定义快速入门,请派生仓库,并在从模板创建应用程序时,用您的派生仓库替换默认的源代码仓库名称。这将导致使用您的源代码而不是提供的示例源代码执行构建。然后,您可以更新源代码仓库中的代码并启动新的构建以查看部署的应用程序中反映的变化。
您可以定义新模板,以便轻松地重新创建应用程序的所有对象。模板定义其创建的对象以及一些元数据,以指导这些对象的创建。
以下是一个简单的模板对象定义示例 (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 中的id 和categoryAliases 。还可以为整个集群自定义类别。 |
6 | 在 Web 控制台中与您的模板一起显示的图标。可用图标
|
7 | 提供模板的个人或组织名称。 |
8 | 引用模板进一步文档的 URL。 |
9 | 可以获得模板支持的 URL。 |
10 | 在实例化此模板时显示的说明性消息。此字段应告知用户如何使用新创建的资源。在显示之前,会对消息执行参数替换,以便生成的凭据和其他参数可以包含在输出中。包含用户应遵循的任何后续步骤文档的链接。 |
模板可以包含一组标签。这些标签将添加到实例化模板时创建的每个对象中。以这种方式定义标签使用户可以轻松查找和管理从特定模板创建的所有对象。
以下是模板对象标签的示例
kind: "Template"
apiVersion: "v1"
...
labels:
template: "cakephp-mysql-example" (1)
app: "${NAME}" (2)
1 | 应用于从此模板创建的所有对象的标签。 |
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
和\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 模板
包含修饰符的示例 JSON 模板
|
这是一个包含参数定义和引用的完整模板示例
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 | 此模板创建的服务的定义。 |
如果对象定义元数据包含固定的 |
模板服务代理在其目录中为其已知的每个模板对象宣传一项服务。默认情况下,这些服务的每一项都被宣传为可绑定的,这意味着最终用户被允许针对已供应的服务进行绑定。
模板作者可以阻止最终用户绑定针对从给定模板供应的服务。
通过向模板添加注释template.openshift.io/bindable: "false"
来阻止最终用户绑定针对从给定模板供应的服务。
模板作者可以指示应该公开模板中特定对象的字段。模板服务代理识别ConfigMap
、Secret
、Service
和Route
对象上的公开字段,并在用户绑定由代理支持的服务时返回公开字段的值。
要公开对象的字段,请向模板中的对象添加以template.openshift.io/expose-
或template.openshift.io/base64-expose-
为前缀的注释。
每个注释键(去除其前缀)都会被传递到bind
响应中,成为其中的一个键。
每个注释值都是一个Kubernetes JSONPath表达式,该表达式在绑定时被解析以指示应该在bind
响应中返回其值的字段。
|
除非使用反斜杠转义,否则Kubernetes的JSONPath实现会将诸如 |
以下是不同对象字段公开的示例
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 认为模板实例化完成之前,应等待模板中的某些对象。
要使用此功能,请使用以下注释标记模板中一种或多种类型为Build
、BuildConfig
、Deployment
、DeploymentConfig
、Job
或StatefulSet
的对象
"template.alpha.openshift.io/wait-for-ready": "true"
只有当所有标有该注释的对象都报告就绪后,模板实例化才算完成。同样,如果任何带注释的对象报告失败,或者模板在固定的一个小时超时时间内未能就绪,则模板实例化失败。
出于实例化的目的,每种对象的准备就绪和失败定义如下
类型 | 就绪 | 失败 |
---|---|---|
|
对象报告阶段完成。 |
对象报告阶段取消、错误或失败。 |
|
最新的关联构建对象报告阶段完成。 |
最新的关联构建对象报告阶段取消、错误或失败。 |
|
对象报告新的副本集和部署可用。这遵循对象上定义的就绪探测。 |
对象报告progressing条件为false。 |
|
对象报告新的复制控制器和部署可用。这遵循对象上定义的就绪探测。 |
对象报告progressing条件为false。 |
|
对象报告完成。 |
对象报告已发生一个或多个失败。 |
|
对象报告所有副本就绪。这遵循对象上定义的就绪探测。 |
不适用。 |
以下是一个使用wait-for-ready
注释的模板摘录示例。更多示例可在OpenShift Container Platform快速入门模板中找到。
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:
...
设置内存、CPU和存储的默认大小,以确保您的应用程序拥有足够的资源来平稳运行。
如果跨主要版本使用该标签,请避免引用映像的latest
标签。当新的映像被推送到该标签时,这可能会导致正在运行的应用程序中断。
一个好的模板可以在部署后无需修改即可干净地构建和部署。
您可以从项目的YAML表单中导出现有对象,然后通过添加参数和其他自定义项作为模板表单来修改YAML,而不是从头开始编写整个模板。
以YAML形式导出项目中的对象
$ oc get -o yaml all > <yaml_filename>
您也可以替换特定的资源类型或多个资源,而不是all
。运行oc get -h
以获取更多示例。
oc get -o yaml all
中包含的对象类型为:
BuildConfig
Build
DeploymentConfig
ImageStream
Pod
ReplicationController
Route
Service
不建议使用 |