5.7. Définition des versions de service de cluster (CSV)

La commande make bundle crée les fichiers et répertoires suivants dans votre projet Operator :

Les ressources suivantes sont généralement incluses dans un CSV :

L'option --version de la sous-commande generate bundle fournit une version sémantique de votre bundle lors de sa création et de la mise à jour d'un bundle existant.

En définissant la variable VERSION dans votre Makefile, l'indicateur --version est automatiquement invoqué en utilisant cette valeur lorsque la sous-commande generate bundle est exécutée par la commande make bundle. La version du CSV est la même que celle de l'opérateur, et un nouveau CSV est généré lors de la mise à niveau des versions de l'opérateur.

Les développeurs d'opérateurs peuvent définir manuellement certaines annotations dans les métadonnées d'une version de service de cluster (CSV) pour activer des fonctionnalités ou mettre en évidence des capacités dans les interfaces utilisateur (UI), telles que OperatorHub.

Le tableau suivant énumère les annotations de métadonnées de l'opérateur qui peuvent être définies manuellement à l'aide des champs metadata.annotations.

Exemples de cas d'utilisation

operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'

operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'

operators.openshift.io/valid-subscription: '["3Scale Commercial License", "Red Hat Managed Integration"]'

operators.openshift.io/infrastructure-features: '["disconnected", "proxy-aware"]'
operators.openshift.io/valid-subscription: '["OpenShift Container Platform"]'

Les chaînes suivantes sont prises en charge dans Operator Lifecycle Manager (OLM) sur OpenShift Container Platform lors de l'étiquetage ou du filtrage des opérateurs qui prennent en charge plusieurs architectures et systèmes d'exploitation :

Lorsque vous déployez un opérateur avec des webhooks à l'aide d'Operator Lifecycle Manager (OLM), vous devez définir les éléments suivants :

Lorsque le webhook est créé, OLM veille à ce qu'il n'agisse que sur les espaces de noms qui correspondent au groupe d'opérateurs dans lequel l'opérateur est déployé.

Contraintes de l'autorité de certification

OLM est configuré pour fournir à chaque déploiement une seule autorité de certification (CA). La logique qui génère et monte l'autorité de certification dans le déploiement était à l'origine utilisée par la logique du cycle de vie du service API. En conséquence :

Contraintes liées aux règles d'admission des webhooks

Pour éviter qu'un opérateur ne configure le cluster dans un état irrécupérable, OLM place le CSV dans la phase d'échec si les règles définies dans un webhook d'admission interceptent l'une des demandes suivantes :

Contraintes de conversion des webhooks

OLM place le CSV dans la phase d'échec si la définition d'un webhook de conversion ne respecte pas les contraintes suivantes :

Les définitions de ressources personnalisées (CRD) appartenant à votre opérateur constituent la partie la plus importante de votre CSV. Elles établissent le lien entre votre opérateur et les règles RBAC requises, la gestion des dépendances et d'autres concepts Kubernetes.

Il est courant que votre opérateur utilise plusieurs CRD pour relier des concepts, tels que la configuration de la base de données de premier niveau dans un objet et une représentation des ensembles de répliques dans un autre. Chacun d'entre eux doit être répertorié dans le fichier CSV.

L'exemple suivant décrit un CRD MongoDB Standalone qui nécessite une entrée utilisateur sous la forme d'un secret et d'une carte de configuration, et qui orchestre des services, des ensembles avec état, des pods et des cartes de configuration :

      - displayName: MongoDB Standalone
        group: mongodb.com
        kind: MongoDbStandalone
        name: mongodbstandalones.mongodb.com
        resources:
          - kind: Service
            name: ''
            version: v1
          - kind: StatefulSet
            name: ''
            version: v1beta2
          - kind: Pod
            name: ''
            version: v1
          - kind: ConfigMap
            name: ''
            version: v1
        specDescriptors:
          - description: Credentials for Ops Manager or Cloud Manager.
            displayName: Credentials
            path: credentials
            x-descriptors:
              - 'urn:alm:descriptor:com.tectonic.ui:selector:core:v1:Secret'
          - description: Project this deployment belongs to.
            displayName: Project
            path: project
            x-descriptors:
              - 'urn:alm:descriptor:com.tectonic.ui:selector:core:v1:ConfigMap'
          - description: MongoDB version to be installed.
            displayName: Version
            path: version
            x-descriptors:
              - 'urn:alm:descriptor:com.tectonic.ui:label'
        statusDescriptors:
          - description: The status of each of the pods for the MongoDB cluster.
            displayName: Pod Status
            path: pods
            x-descriptors:
              - 'urn:alm:descriptor:com.tectonic.ui:podStatuses'
        version: v1
        description: >-
          MongoDB Deployment consisting of only one host. No replication of
          data.

Le recours à d'autres CRD obligatoires est totalement facultatif et n'existe que pour réduire la portée des opérateurs individuels et fournir un moyen de composer plusieurs opérateurs ensemble pour résoudre un cas d'utilisation de bout en bout.

Par exemple, un opérateur peut configurer une application et installer un cluster etcd (provenant d'un opérateur etcd) pour le verrouillage distribué et une base de données Postgres (provenant d'un opérateur Postgres) pour le stockage des données.

Operator Lifecycle Manager (OLM) vérifie que les CRD et les opérateurs disponibles dans le cluster répondent à ces exigences. Si des versions appropriées sont trouvées, les opérateurs sont démarrés dans l'espace de noms souhaité et un compte de service est créé pour chaque opérateur afin de créer, surveiller et modifier les ressources Kubernetes requises.

    required:
    - name: etcdclusters.etcd.database.coreos.com
      version: v1beta2
      kind: EtcdCluster
      displayName: etcd Cluster
      description: Represents a cluster of etcd nodes.

OLM met à niveau une définition de ressource personnalisée (CRD) immédiatement si elle appartient à une seule version de service de cluster (CSV). Si une CRD appartient à plusieurs CSV, elle est mise à niveau lorsqu'elle remplit toutes les conditions de compatibilité ascendante suivantes :

Les utilisateurs de votre opérateur doivent savoir quelles options sont obligatoires ou facultatives. Vous pouvez fournir des modèles pour chacune de vos définitions de ressources personnalisées (CRD) avec un ensemble minimum de configurations sous la forme d'une annotation nommée alm-examples. Les interfaces utilisateur compatibles rempliront ce modèle à l'avance pour que les utilisateurs puissent le personnaliser davantage.

L'annotation consiste en une liste du type, par exemple, le nom du CRD et les adresses metadata et spec correspondantes de l'objet Kubernetes.

L'exemple complet suivant fournit des modèles pour EtcdCluster, EtcdBackup et EtcdRestore:

metadata:
  annotations:
    alm-examples: >-
      [{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdCluster","metadata":{"name":"example","namespace":"default"},"spec":{"size":3,"version":"3.2.13"}},{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdRestore","metadata":{"name":"example-etcd-cluster"},"spec":{"etcdCluster":{"name":"example-etcd-cluster"},"backupStorageType":"S3","s3":{"path":"<full-s3-path>","awsSecret":"<aws-secret>"}}},{"apiVersion":"etcd.database.coreos.com/v1beta2","kind":"EtcdBackup","metadata":{"name":"example-etcd-cluster-backup"},"spec":{"etcdEndpoints":["<etcd-cluster-endpoints>"],"storageType":"S3","s3":{"path":"<full-s3-path>","awsSecret":"<aws-secret>"}}}]

Il est courant que les opérateurs utilisent des définitions de ressources personnalisées (CRD) en interne pour accomplir une tâche. Ces objets ne sont pas destinés à être manipulés par les utilisateurs et peuvent prêter à confusion pour les utilisateurs de l'opérateur. Par exemple, un opérateur de base de données peut avoir un CRD Replication qui est créé chaque fois qu'un utilisateur crée un objet Base de données avec replication: true.

En tant qu'auteur d'un opérateur, vous pouvez masquer dans l'interface utilisateur les CRD qui ne sont pas destinés à être manipulés par l'utilisateur en ajoutant l'annotation operators.operatorframework.io/internal-objects à la version du service de cluster (CSV) de votre opérateur.

Un opérateur peut exiger de l'utilisateur qu'il instancie une ressource personnalisée avant que l'opérateur ne soit pleinement fonctionnel. Cependant, il peut être difficile pour un utilisateur de déterminer ce qui est nécessaire ou comment définir la ressource.

En tant que développeur Operator, vous pouvez spécifier une seule ressource personnalisée requise en ajoutant operatorframework.io/initialization-resource à la version du service de cluster (CSV) lors de l'installation d'Operator. Vous êtes alors invité à créer la ressource personnalisée à l'aide d'un modèle fourni dans la CSV. L'annotation doit inclure un modèle qui contient une définition YAML complète nécessaire pour initialiser la ressource lors de l'installation.

Si cette annotation est définie, après avoir installé l'opérateur à partir de la console web d'OpenShift Container Platform, l'utilisateur est invité à créer la ressource en utilisant le modèle fourni dans le CSV.

Lorsqu'un CSV possède un service API, il est responsable de la description du déploiement de l'extension api-server qui le soutient et du groupe/version/genre (GVK) qu'il fournit.

Un service API est identifié de manière unique par le groupe/la version qu'il fournit et peut être listé plusieurs fois pour indiquer les différents types de services qu'il est censé fournir.

OLM s'assure que tous les CSV requis disposent d'un service API disponible et que tous les GVK attendus peuvent être découverts avant de tenter l'installation. Cela permet à un CSV de s'appuyer sur des types spécifiques fournis par des services API qu'il ne possède pas.