10.7. Modèles d'écriture

La description du modèle vous informe de ce que fait le modèle et vous aide à le trouver lors d'une recherche dans la console web. L'ajout de métadonnées autres que le nom du modèle est facultatif, mais utile. En plus des informations descriptives générales, les métadonnées comprennent également un ensemble de balises. Les balises utiles comprennent le nom du langage auquel le modèle est lié, par exemple Java, PHP, Ruby, etc.

Voici un exemple de métadonnées de description de modèle :

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

Les modèles peuvent inclure un ensemble d'étiquettes. Ces étiquettes sont ajoutées à chaque objet créé lorsque le modèle est instancié. La définition d'une étiquette de cette manière permet aux utilisateurs de trouver et de gérer facilement tous les objets créés à partir d'un modèle particulier.

Voici un exemple d'étiquettes d'objets de modèle :

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

Les paramètres permettent à une valeur d'être fournie par vous ou générée lors de l'instanciation du modèle. Cette valeur est ensuite substituée partout où le paramètre est référencé. Les références peuvent être définies dans n'importe quel champ de la liste des objets. Ceci est utile pour générer des mots de passe aléatoires ou pour vous permettre de fournir un nom d'hôte ou une autre valeur spécifique à l'utilisateur qui est nécessaire pour personnaliser le modèle. Les paramètres peuvent être référencés de deux manières :

En utilisant la syntaxe ${PARAMETER_NAME}, plusieurs références de paramètres peuvent être combinées dans un seul champ et la référence peut être intégrée dans des données fixes, telles que "http://${PARAMETER_1}${PARAMETER_2}". Les deux valeurs des paramètres sont substituées et la valeur résultante est une chaîne de caractères entre guillemets.

Lors de l'utilisation de la syntaxe ${{PARAMETER_NAME}}, une seule référence de paramètre est autorisée et les caractères de tête et de fin ne sont pas autorisés. La valeur résultante n'est pas mise entre guillemets, sauf si, après substitution, le résultat n'est pas un objet JSON valide. Si le résultat n'est pas une valeur JSON valide, la valeur résultante est citée et traitée comme une chaîne de caractères standard.

Un même paramètre peut être référencé plusieurs fois dans un modèle et il peut être référencé à l'aide des deux syntaxes de substitution dans un même modèle.

Une valeur par défaut peut être fournie, qui est utilisée si vous ne fournissez pas de valeur différente :

Voici un exemple de définition d'une valeur explicite comme valeur par défaut :

parameters:
  - name: USERNAME
    description: "The user name for Joe"
    value: joe

Les valeurs des paramètres peuvent également être générées sur la base de règles spécifiées dans la définition du paramètre, par exemple en générant une valeur de paramètre :

parameters:
  - name: PASSWORD
    description: "The random user password"
    generate: expression
    from: "[a-zA-Z0-9]{12}"

Dans l'exemple précédent, le traitement génère un mot de passe aléatoire de 12 caractères composé de toutes les lettres de l'alphabet, majuscules et minuscules, et de chiffres.

La syntaxe disponible n'est pas une syntaxe d'expression régulière complète. Cependant, vous pouvez utiliser les modificateurs \w, \d, \a, et \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}"
       }
    ]
}

Voici un exemple de modèle complet avec les définitions des paramètres et les références :

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

La partie principale du modèle est la liste des objets créés lors de l'instanciation du modèle. Il peut s'agir de n'importe quel objet API valide, tel qu'une configuration de construction, une configuration de déploiement ou un service. L'objet est créé exactement comme il est défini ici, les valeurs des paramètres étant substituées avant la création. La définition de ces objets peut faire référence à des paramètres définis précédemment.

Voici un exemple de liste d'objets :

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"

Le Template Service Broker annonce un service dans son catalogue pour chaque objet modèle dont il a connaissance. Par défaut, chacun de ces services est annoncé comme étant liant, ce qui signifie qu'un utilisateur final est autorisé à se lier au service fourni.

Les auteurs de modèles peuvent indiquer que les champs de certains objets d'un modèle doivent être exposés. Le Template Service Broker reconnaît les champs exposés sur les objets ConfigMap, Secret, Service, et Route, et renvoie les valeurs des champs exposés lorsqu'un utilisateur lie un service soutenu par le broker.

Pour exposer un ou plusieurs champs d'un objet, ajoutez des annotations préfixées par template.openshift.io/expose- ou template.openshift.io/base64-expose- à l'objet dans le modèle.

Chaque clé d'annotation, dont le préfixe a été supprimé, est transmise pour devenir une clé dans une réponse bind.

Chaque valeur d'annotation est une expression JSONPath de Kubernetes, qui est résolue au moment de la liaison pour indiquer le champ d'objet dont la valeur doit être renvoyée dans la réponse bind.

Voici un exemple d'exposition des champs de différents objets :

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

Voici un exemple de réponse à une opération bind à partir du modèle partiel ci-dessus :

{
  "credentials": {
    "username": "foo",
    "password": "YmFy",
    "service_ip_port": "172.30.12.34:8080",
    "uri": "http://route-test.router.default.svc.cluster.local/mypath"
  }
}

Les auteurs de modèles peuvent indiquer que certains objets d'un modèle doivent être attendus avant que l'instanciation d'un modèle par le catalogue de services, le Template Service Broker ou l'API TemplateInstance ne soit considérée comme terminée.

Pour utiliser cette fonctionnalité, marquez un ou plusieurs objets du type Build, BuildConfig, Deployment, DeploymentConfig, Job, ou StatefulSet dans un modèle avec l'annotation suivante :

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

L'instanciation du modèle n'est pas terminée tant que tous les objets marqués par l'annotation ne sont pas prêts. De même, si l'un des objets annotés signale un échec ou si le modèle n'est pas prêt dans un délai fixe d'une heure, l'instanciation du modèle échoue.

Pour les besoins de l'instanciation, la disponibilité et l'échec de chaque type d'objet sont définis comme suit :

Voici un exemple d'extrait de modèle qui utilise l'annotation wait-for-ready. D'autres exemples peuvent être trouvés dans les modèles de démarrage rapide de 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:
    ...

Plutôt que d'écrire un modèle complet à partir de zéro, vous pouvez exporter des objets existants de votre projet sous forme de YAML, puis modifier le YAML à partir de là en ajoutant des paramètres et d'autres personnalisations sous forme de modèle.