10.7. Modèles d'écriture

Vous pouvez définir de nouveaux modèles pour faciliter la recréation de tous les objets de votre application. Le modèle définit les objets qu'il crée ainsi que certaines métadonnées pour guider la création de ces objets.

Voici un exemple de définition d'un objet modèle simple (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

10.7.1. Rédaction de la description du modèle

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
1
Le nom unique du modèle.
2
Un nom bref et convivial, qui peut être utilisé par les interfaces utilisateurs.
3
Une description du modèle. Elle doit être suffisamment détaillée pour que les utilisateurs comprennent ce qui est déployé et les éventuelles mises en garde qu'ils doivent connaître avant de procéder au déploiement. Elle doit également fournir des liens vers des informations supplémentaires, telles qu'un fichier README. Les nouvelles lignes peuvent être incluses pour créer des paragraphes.
4
Description supplémentaire du modèle. Elle peut être affichée par le catalogue de services, par exemple.
5
Balises à associer au modèle pour la recherche et le regroupement. Ajoutez des balises qui l'incluent dans l'une des catégories de catalogue fournies. Reportez-vous à id et categoryAliases dans CATALOG_CATEGORIES dans le fichier des constantes de la console. Les catégories peuvent également être personnalisées pour l'ensemble du cluster.
6
Une icône à afficher avec votre modèle dans la console web.

Exemple 10.1. Icônes disponibles

  • icon-3scale
  • icon-aerogear
  • icon-amq
  • icon-angularjs
  • icon-ansible
  • icon-apache
  • icon-beaker
  • icon-camel
  • icon-capedwarf
  • icon-cassandra
  • icon-catalog-icon
  • icon-clojure
  • icon-codeigniter
  • icon-cordova
  • icon-datagrid
  • icon-datavirt
  • icon-debian
  • icon-decisionserver
  • icon-django
  • icon-dotnet
  • icon-drupal
  • icon-eap
  • icon-elastic
  • icon-erlang
  • icon-fedora
  • icon-freebsd
  • icon-git
  • icon-github
  • icon-gitlab
  • icon-glassfish
  • icon-go-gopher
  • icon-golang
  • icon-grails
  • icon-hadoop
  • icon-haproxy
  • icon-helm
  • icon-infinispan
  • icon-jboss
  • icon-jenkins
  • icon-jetty
  • icon-joomla
  • icon-jruby
  • icon-js
  • icon-knative
  • icon-kubevirt
  • icon-laravel
  • icon-load-balancer
  • icon-mariadb
  • icon-mediawiki
  • icon-memcached
  • icon-mongodb
  • icon-mssql
  • icon-mysql-database
  • icon-nginx
  • icon-nodejs
  • icon-openjdk
  • icon-openliberty
  • icon-openshift
  • icon-openstack
  • icon-other-linux
  • icon-other-unknown
  • icon-perl
  • icon-phalcon
  • icon-php
  • icon-play
  • iconpostgresql
  • icon-processserver
  • icon-python
  • icon-quarkus
  • icon-rabbitmq
  • icon-rails
  • icon-redhat
  • icon-redis
  • icon-rh-integration
  • icon-rh-spring-boot
  • icon-rh-tomcat
  • icon-ruby
  • icon-scala
  • icon-serverlessfx
  • icon-shadowman
  • icon-spring-boot
  • icon-spring
  • icon-sso
  • icon-stackoverflow
  • icon-suse
  • icon-symfony
  • icon-tomcat
  • icon-ubuntu
  • icon-vertx
  • icon-wildfly
  • icon-windows
  • icon-wordpress
  • icon-xamarin
  • icon-zend
7
Le nom de la personne ou de l'organisation qui fournit le modèle.
8
Une URL renvoyant à une documentation supplémentaire pour le modèle.
9
URL où l'on peut obtenir de l'aide pour le modèle.
10
Un message d'instruction qui s'affiche lorsque ce modèle est instancié. Ce champ doit informer l'utilisateur sur la manière d'utiliser les ressources nouvellement créées. La substitution des paramètres est effectuée sur le message avant qu'il ne soit affiché afin que les informations d'identification générées et d'autres paramètres puissent être inclus dans la sortie. Inclure des liens vers toute documentation sur les étapes suivantes que les utilisateurs doivent suivre.

10.7.2. Rédaction de modèles d'étiquettes

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
1
Une étiquette appliquée à tous les objets créés à partir de ce modèle.
2
Une étiquette paramétrée qui est également appliquée à tous les objets créés à partir de ce modèle. L'expansion des paramètres est effectuée à la fois sur les clés et les valeurs de l'étiquette.

10.7.3. Écriture des paramètres du modèle

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 :

  • Comme une valeur de chaîne en plaçant des valeurs dans le formulaire ${PARAMETER_NAME} dans n'importe quel champ de chaîne du modèle.
  • En tant que valeur JSON ou YAML en plaçant des valeurs dans le formulaire ${{PARAMETER_NAME}} à la place de n'importe quel champ du modèle.

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:

  • [\w]{10} produit 10 caractères alphabétiques, des chiffres et des traits de soulignement. Cette valeur est conforme à la norme PCRE et correspond à [a-zA-Z0-9_]{10}.
  • [\d]{10} produit 10 nombres. Ce nombre est égal à [0-9]{10}.
  • [\a]{10} produit 10 caractères alphabétiques. Cela correspond à [a-zA-Z]{10}.
  • [\A]{10} produces 10 punctuation or symbol characters. This is equal to [~!@#$%\^&*()\-_+={}\[\]\\|<,>.?/"';:`]{10}.
Note

Selon que le modèle est écrit en YAML ou en JSON, et selon le type de chaîne dans laquelle le modificateur est intégré, il peut être nécessaire d'échapper à la barre oblique inverse par une seconde barre oblique inverse. Les exemples suivants sont équivalents :

Exemple de modèle YAML avec un modificateur

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

Exemple de modèle JSON avec un modificateur

{
    "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
1
Cette valeur est remplacée par la valeur du paramètre SOURCE_REPOSITORY_URL lors de l'instanciation du modèle.
2
Cette valeur est remplacée par la valeur non citée du paramètre REPLICA_COUNT lorsque le modèle est instancié.
3
Le nom du paramètre. Cette valeur est utilisée pour référencer le paramètre dans le modèle.
4
Nom convivial du paramètre. Il est affiché aux utilisateurs.
5
Description du paramètre. Fournissez des informations plus détaillées sur l'objectif du paramètre, y compris toute contrainte sur la valeur attendue. Les descriptions doivent utiliser des phrases complètes afin de respecter les normes textuelles de la console. Cette description ne doit pas être un doublon du nom d'affichage.
6
Une valeur par défaut pour le paramètre qui est utilisée si vous ne remplacez pas la valeur lors de l'instanciation du modèle. Évitez d'utiliser des valeurs par défaut pour des éléments tels que les mots de passe ; utilisez plutôt des paramètres générés en combinaison avec des secrets.
7
Indique que ce paramètre est obligatoire, ce qui signifie que vous ne pouvez pas le remplacer par une valeur vide. Si le paramètre ne fournit pas de valeur par défaut ou générée, vous devez fournir une valeur.
8
Un paramètre dont la valeur est générée.
9
L'entrée du générateur. Dans ce cas, le générateur produit une valeur alphanumérique de 40 caractères comprenant des majuscules et des minuscules.
10
Des paramètres peuvent être inclus dans le message du modèle. Cela vous informe des valeurs générées.

10.7.4. Écriture de la liste des objets du modèle

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"
1
La définition d'un service, qui est créé par ce modèle.
Note

Si les métadonnées d'une définition d'objet comprennent une valeur fixe du champ namespace, le champ est supprimé de la définition lors de l'instanciation du modèle. Si le champ namespace contient une référence à un paramètre, la substitution normale du paramètre est effectuée et l'objet est créé dans l'espace de noms auquel la substitution du paramètre a résolu la valeur, à condition que l'utilisateur soit autorisé à créer des objets dans cet espace de noms.

10.7.5. Marquer un modèle comme liant

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.

Procédure

Les auteurs de modèles peuvent empêcher les utilisateurs finaux de se lier aux services fournis à partir d'un modèle donné.

  • Empêcher l'utilisateur final de se lier aux services fournis à partir d'un modèle donné en ajoutant l'annotation template.openshift.io/bindable: "false" au modèle.

10.7.6. Exposition des champs de l'objet modèle

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.

Note

Bind les paires clé-valeur de réponse peuvent être utilisées dans d'autres parties du système en tant que variables d'environnement. Il est donc recommandé que chaque clé d'annotation dont le préfixe a été supprimé soit un nom de variable d'environnement valide - commençant par un caractère A-Z, a-z, ou _, et suivi d'au moins zéro caractère A-Z, a-z, 0-9, ou _.

Note

Unless escaped with a backslash, Kubernetes' JSONPath implementation interprets characters such as ., @, and others as metacharacters, regardless of their position in the expression. Therefore, for example, to refer to a ConfigMap datum named my.key, the required JSONPath expression would be {.data['my\.key']}. Depending on how the JSONPath expression is then written in YAML, an additional backslash might be required, for example "{.data['my\\.key']}".

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

Procédure

  • Utilisez l'annotation template.openshift.io/expose- pour renvoyer la valeur du champ sous forme de chaîne de caractères. C'est pratique, mais cela ne permet pas de gérer des données binaires arbitraires.
  • Si vous souhaitez renvoyer des données binaires, utilisez plutôt l'annotation template.openshift.io/base64-expose- pour encoder base64 les données avant qu'elles ne soient renvoyées.

10.7.7. En attendant que le modèle soit prêt

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 :

GenrePréparationÉchec

Build

La phase des rapports sur les objets est terminée.

L'objet signale une phase annulée, une erreur ou un échec.

BuildConfig

Le dernier objet de construction associé signale que la phase est terminée.

Le dernier objet de construction associé signale une phase annulée, une erreur ou un échec.

Deployment

L'objet signale un nouvel ensemble de répliques et un déploiement disponible. Cela permet d'honorer les sondes de disponibilité définies sur l'objet.

L'objet signale que la condition de progression est fausse.

DeploymentConfig

L'objet signale la disponibilité d'un nouveau contrôleur de réplication et d'un nouveau déploiement. Ceci honore les sondes de disponibilité définies sur l'objet.

L'objet signale que la condition de progression est fausse.

Job

L'objet signale l'achèvement.

L'objet signale qu'une ou plusieurs défaillances se sont produites.

StatefulSet

L'objet signale que toutes les répliques sont prêtes. Cela permet d'honorer les sondes de disponibilité définies sur l'objet.

Sans objet.

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

Recommandations supplémentaires

  • Définissez les tailles par défaut de la mémoire, du processeur et du stockage pour vous assurer que votre application dispose de suffisamment de ressources pour fonctionner correctement.
  • Évitez de faire référence à la balise latest à partir des images si cette balise est utilisée dans plusieurs versions majeures. Les applications en cours d'exécution risquent en effet de s'interrompre lorsque de nouvelles images sont ajoutées à cette balise.
  • Un bon modèle se construit et se déploie proprement, sans nécessiter de modifications après son déploiement.

10.7.8. Création d'un modèle à partir d'objets existants

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.

Procédure

  • Exporter les objets d'un projet au format YAML :

    $ oc get -o yaml all > <yaml_filename>

    Vous pouvez également remplacer all par un type de ressource particulier ou par plusieurs ressources. Exécutez oc get -h pour plus d'exemples.

    Les types d'objets inclus dans oc get -o yaml all sont les suivants :

    • BuildConfig
    • Build
    • DeploymentConfig
    • ImageStream
    • Pod
    • ReplicationController
    • Route
    • Service
Note

L'utilisation de l'alias all n'est pas recommandée car son contenu peut varier selon les clusters et les versions. Il est préférable de spécifier toutes les ressources nécessaires.