第10章 Templates (テンプレート)

「ラベル」は 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=-

テンプレートの説明では、テンプレートの内容に関する情報を提供でき、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 deployment configuration, and
      database deployment configuration.  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

パラメーターにより、テンプレートがインスタンス化される時に値を生成するか、ユーザーが値を指定できるようになります。値は、パラメーターが参照されると、置換されます。参照は、オブジェクト一覧フィールドであればどこでも定義できます。これは、無作為にパスワードを作成したり、テンプレートのカスタマイズに必要なユーザー固有の値やホスト名を指定したりできるので便利です。パラメーターは、2 種類の方法で参照可能です。

${PARAMETER_NAME} 構文を使用すると、複数のパラメーター参照を 1 つフィールドに統合でき、"http://${PARAMETER_1}${PARAMETER_2}" などのように、参照を固定のデータ内に埋め込むことができます。どちらのパラメーター値も置換されて、引用された文字列が最終的な値になります。

${{PARAMETER_NAME}} 構文のみを使用する場合は、単一のパラメーター参照のみが可能で、先頭文字や終了文字は使用できません。結果値は、置換した後に結果が有効な json オブジェクトでない限り、引用されません。結果が有効な json 値でない場合に、結果値は引用され、標準の文字列として処理されます。

単一のパラメーターは、テンプレート内で複数回参照でき、また、1 つのテンプレート内で両方の置換構文を使用して参照することができます。

デフォルト値を指定でき、ユーザーが別の値を指定していない場合に使用されます。

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

テンプレートの主な部分は、テンプレートがインスタンス化される時に作成されるオブジェクトの一覧です。これには、BuildConfig、DeploymentConfig、Service など、「有効な 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 オブジェクトに公開されたフィールドを認識し、ユーザーがブローカーでバックされているサービスをバンドした場合に公開されたフィールドの値を返します。

オブジェクトのフィールドを 1 つまたは複数公開するには、テンプレート内のオブジェクトに、プレフィックスが template.openshift.io/expose- または template.openshift.io/base64-expose- のアノテーションを追加します。

各アノテーションキーは、bind 応答のキーになるように、プレフィックスが削除されてパススルーされます。

各アノテーションの値は Kubernetes JSONPath 表現 で、バインド時に解決され、bind 応答で返すべき値が含まれるオブジェクトフィールドを指定します。

template.openshift.io/expose- アノテーションを使用して、文字列としてフィールドの値を返します。これは、任意のバイナリーデータを処理しませんが、使用すると便利です。バイナリーデータを返す場合には、バイナリーデータを返す前にデータのエンコードに base64b を使用するのではなく、template.openshift.io/base64-expose- アノテーションを使用します。

以下は、公開されるさまざまなオブジェクトのフィールドの例です。

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 のオブジェクト 1 つ以上に、次のアノテーションでマークを付けてください。

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

テンプレートのインスタンス化は、アノテーションのマークが付けられたすべてのオブジェクトが準備できたと報告されるまで、完了しません。同様に、アノテーションが追加オブジェクトが失敗したと報告されるか、固定タイムアウトである 1 時間以内にテンプレートの準備が整わなかった場合に、テンプレートのインスタンス化は失敗します。

インスタンス化の目的で、各オブジェクトの種類の準備状態および失敗は以下のように定義されます。

以下は、テンプレートサンプルを一部抜粋したものです。この例では、wait-for-ready アノテーションが使用されています。他のサンプルは、OpenShift クイックスタートテンプレートにあります。

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:
    ...

テンプレートをゼロから作成するのではなく、プロジェクトから既存のオブジェクトをテンプレート形式でエクスポートして、パラメーターを追加したり、カスタマイズしたりして、テンプレートを変更することもできます。プロジェクトのオブジェクトをテンプレート形式でエクスポートするには、以下を実行します。

$ oc export all --as-template=<template_name> > <template_filename>

all ではなく、特定のリソースタイプや複数のリソースを置き換えることも可能です。他の例については、oc export -h を実行してください。

以下は、oc export all に含まれるオブジェクトタイプです。