10.7. 템플릿 작성

템플릿 설명은 템플릿의 기능을 사용자에게 알려주고 웹 콘솔에서 검색할 때 템플릿을 찾도록 도와줍니다. 템플릿 이름 이외의 추가 메타데이터는 선택사항이지만 있으면 유용합니다. 메타데이터에는 일반적인 설명 정보 외에도 태그 세트가 포함되어 있습니다. 유용한 태그에는 템플릿과 관련된 언어의 이름이 포함되어 있습니다(예: 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

템플릿에는 레이블 세트가 포함될 수 있습니다. 이러한 레이블은 템플릿이 인스턴스화될 때 생성되는 각 오브젝트에 추가됩니다. 이런 방식으로 레이블을 정의하면 사용자가 특정 템플릿에서 생성된 모든 오브젝트를 쉽게 찾아서 관리할 수 있습니다.

다음은 템플릿 오브젝트 레이블의 예입니다.

kind: "Template"
apiVersion: "v1"
...
labels:
  template: "cakephp-mysql-example" 1
  app: "${NAME}" 2

매개 변수를 사용하면 템플릿을 인스턴스화할 때 값을 제공하거나 생성할 수 있습니다. 그러면 해당 값이 매개변수가 참조될 때마다 대체됩니다. 참조는 오브젝트 목록 필드의 어떤 필드에서든 정의할 수 있습니다. 임의의 암호를 생성하거나 템플릿을 사용자 지정하는 데 필요한 호스트 이름 또는 기타 사용자 특정 값을 제공할 수 있도록 하는 데 유용합니다. 매개변수는 다음 두 가지 방법으로 참조할 수 있습니다.

${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, and \A 수정자를 사용할 수 있습니다.

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

{
    "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

템플릿의 주요 부분은 템플릿이 인스턴스화될 때 생성되는 오브젝트 목록입니다. 빌드 구성, 배포 구성 또는 서비스와 같은 유효한 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"

Template Service Broker는 해당 카탈로그에서 인식하는 템플릿 오브젝트마다 하나의 서비스를 알립니다. 기본적으로 이러한 각 서비스는 바인드 가능 상태로 알려집니다. 즉, 일반 사용자가 프로비저닝된 서비스에 대해 바인딩할 수 있습니다.

템플릿 작성자는 템플릿의 특정 오브젝트 필드가 노출되어야 함을 나타낼 수 있습니다. Template Service Broker는 ConfigMap, Secret, Service, Route 오브젝트에서 노출된 필드를 인식하고, 브로커가 지원하는 서비스를 사용자가 바인딩할 때 노출된 필드의 값을 반환합니다.

오브젝트의 필드를 하나 이상 노출하려면 template.openshift.io/expose- 또는 template.openshift.io/base64-expose-로 접두사를 붙인 주석을 템플릿의 오브젝트에 추가합니다.

접두사가 제거된 각 주석 키는 전달되어 bind 응답의 키가 됩니다.

각 주석 값은 Kubernetes JSONPath 표현식이며, 바인딩 시 이를 해석하여 bind 응답에서 값을 반환해야 하는 오브젝트 필드를 식별합니다.

다음은 노출되는 다양한 오브젝트 필드의 예입니다.

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: 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: 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 Service Broker 또는 TemplateInstance API의 템플릿 인스턴스화가 완료된 것으로 간주된다고 표시할 수 있습니다.

이 기능을 사용하려면 템플릿에서 다음 주석으로 하나 이상의 오브젝트를 Build, BuildConfig, Deployment, DeploymentConfig, Job 또는 StatefulSet 유형으로 표시하십시오.

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

이 주석이 표시된 모든 오브젝트가 준비되었다고 보고할 때까지 템플릿 인스턴스화는 완료되지 않습니다. 마찬가지로 주석이 있는 오브젝트 보고서 중 실패하는 보고서가 있거나 템플릿이 1시간이라는 고정된 제한 시간 내에 준비되지 않으면 템플릿 인스턴스화가 실패합니다.

인스턴스화를 위해 각 오브젝트 유형의 준비 및 실패는 다음과 같이 정의됩니다.

다음은 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:
    ...

전체 템플릿을 처음부터 작성하지 않고 프로젝트에서 기존 오브젝트를 YAML 형식으로 내보낸 후 템플릿 형식으로 매개변수 및 기타 사용자 정의를 추가하여 YAML을 수정할 수 있습니다.