$ oc create -f <filename>
模板描述了一组可以参数化并处理以生成对象列表的对象,这些对象列表可由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控制台导航菜单顶部的上下文选择器中选择**开发者**。
在所需项目中,单击**+添加**。
在**开发者目录**磁贴中单击**所有服务**。
单击**类型**下的**构建器镜像**以查看可用的构建器镜像。
只有在注释中列出 |
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=-
您可以定义新模板,以便轻松地重新创建应用程序的所有对象。模板定义其创建的对象以及一些元数据,以指导这些对象的创建。
以下是一个简单的模板对象定义示例(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 | 也应用于从此模板创建的所有对象的带参数的标签。参数扩展在标签键和值上执行。 |
参数允许您提供值或在实例化模板时生成值。然后,该值将替换参数引用的任何位置。引用可以在对象列表字段中的任何字段中定义。这对于生成随机密码或允许您提供自定义模板所需的 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 模板
带有修饰符的示例 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"
只有当所有标有该注释的对象都报告就绪时,模板实例化才算完成。类似地,如果任何带注释的对象报告失败,或者如果模板在 1 小时的固定超时时间内未能就绪,则模板实例化将失败。
出于实例化的目的,每种对象的准备就绪和失败定义如下
类型 | 准备就绪 | 失败 |
---|---|---|
|
对象报告阶段完成。 |
对象报告阶段已取消、出错或失败。 |
|
最新关联的构建对象报告阶段完成。 |
最新关联的构建对象报告阶段已取消、出错或失败。 |
|
部署 |
对象报告新的副本集和部署可用。这会遵循对象上定义的就绪探测。 |
|
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 |