5.8. Travailler avec des images groupées

Procédure

1. Exécutez les commandes make suivantes dans le répertoire de votre projet Operator pour construire et pousser votre image Operator. Modifiez l'argument IMG dans les étapes suivantes pour référencer un référentiel auquel vous avez accès. Vous pouvez obtenir un compte pour stocker des conteneurs sur des sites de dépôt tels que Quay.io.

   1. Construire l'image :

      $ make docker-build IMG=<registry>/<user>/<operator_image_name>:<tag>

      Note

      Le fichier Docker généré par le SDK pour l'Operator fait explicitement référence à GOARCH=amd64 pour go build. Cette référence peut être modifiée en GOARCH=$TARGETARCH pour les architectures non-AMD64. Docker définira automatiquement la variable d'environnement à la valeur spécifiée par –platform. Avec Buildah, il faudra utiliser –build-arg à cette fin. Pour plus d'informations, voir Architectures multiples.

   2. Transférer l'image dans un référentiel :

      $ make docker-push IMG=<registry>/<user>/<operator_image_name>:<tag>

2. Créez votre manifeste Operator bundle en exécutant la commande make bundle, qui invoque plusieurs commandes, dont les sous-commandes Operator SDK generate bundle et bundle validate:

   $ make bundle IMG=<registry>/<user>/<operator_image_name>:<tag>

   Les manifestes de l'offre groupée d'un opérateur décrivent la manière d'afficher, de créer et de gérer une application. La commande make bundle crée les fichiers et répertoires suivants dans votre projet Operator :

   • Un répertoire bundle manifests nommé bundle/manifests qui contient un objet ClusterServiceVersion
   • Un répertoire de métadonnées de la liasse nommé bundle/metadata
   • Toutes les définitions de ressources personnalisées (CRD) dans un répertoire config/crd
   • Un fichier Docker bundle.Dockerfile

   Ces fichiers sont ensuite automatiquement validés à l'aide de operator-sdk bundle validate afin de s'assurer que la représentation du paquet sur le disque est correcte.

3. Construisez et poussez votre image de bundle en exécutant les commandes suivantes. OLM consomme les liasses d'opérateurs à l'aide d'une image d'index, qui fait référence à une ou plusieurs images de liasses.

   1. Créez l'image de l'ensemble. Définissez BUNDLE_IMG avec les détails du registre, de l'espace de noms de l'utilisateur et de la balise d'image où vous avez l'intention de pousser l'image :

      $ make bundle-build BUNDLE_IMG=<registry>/<user>/<bundle_image_name>:<tag>

   2. Pousser l'image de la liasse :

      $ docker push <registry>/<user>/<bundle_image_name>:<tag>

Procédure

1. Saisissez la commande suivante pour exécuter l'opérateur sur le cluster :

   $ operator-sdk run bundle \1
       -n <namespace> \2
       <registry>/<user>/<bundle_image_name>:<tag> 3

   1

   La commande run bundle crée un catalogue de fichiers valide et installe le paquet Operator sur votre cluster à l'aide d'OLM.

   2

   Facultatif : Par défaut, la commande installe l'opérateur dans le projet actif dans votre fichier ~/.kube/config. Vous pouvez ajouter l'option -n pour définir un espace de noms différent pour l'installation.

   3

   Si vous ne spécifiez pas d'image, la commande utilise quay.io/operator-framework/opm:latest comme image d'index par défaut. Si vous spécifiez une image, la commande utilise l'image du paquet elle-même comme image d'index.

   Important

   Depuis OpenShift Container Platform 4.11, la commande run bundle prend en charge par défaut le format de catalogue basé sur des fichiers pour les catalogues Operator. Le format de base de données SQLite déprécié pour les catalogues Operator continue d'être pris en charge ; cependant, il sera supprimé dans une prochaine version. Il est recommandé aux auteurs d'Operator de migrer leurs flux de travail vers le format de catalogue basé sur des fichiers.

   Cette commande permet d'effectuer les actions suivantes :

   • Créez une image d'index faisant référence à votre image de liasse. L'image d'index est opaque et éphémère, mais elle reflète fidèlement la manière dont un paquet serait ajouté à un catalogue en production.
   • Créez une source de catalogue qui pointe vers votre nouvelle image d'index, ce qui permet à OperatorHub de découvrir votre opérateur.
   • Déployez votre opérateur sur votre cluster en créant un site OperatorGroup, Subscription, InstallPlan, et toutes les autres ressources nécessaires, y compris RBAC.

Procédure

1. Exécutez la commande suivante make dans le répertoire de votre projet Operator pour créer une image d'indexation contenant votre bundle Operator :

   $ make catalog-build CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>

   où l'argument CATALOG_IMG fait référence à un dépôt auquel vous avez accès. Vous pouvez obtenir un compte pour stocker des conteneurs sur des sites de dépôt tels que Quay.io.

2. Pousser l'image de l'index construit vers un référentiel :

   $ make catalog-push CATALOG_IMG=<registry>/<user>/<index_image_name>:<tag>

   Astuce

   Vous pouvez utiliser les commandes Operator SDK make ensemble si vous préférez effectuer plusieurs actions en séquence à la fois. Par exemple, si vous n'avez pas encore construit d'image bundle pour votre projet Operator, vous pouvez construire et pousser à la fois une image bundle et une image index avec la syntaxe suivante :

   $ make bundle-build bundle-push catalog-build catalog-push \
       BUNDLE_IMG=<bundle_image_pull_spec> \
       CATALOG_IMG=<index_image_pull_spec>

   Vous pouvez également définir le champ IMAGE_TAG_BASE dans votre Makefile en fonction d'un référentiel existant :

   IMAGE_TAG_BASE=quay.io/example/my-operator

   Vous pouvez ensuite utiliser la syntaxe suivante pour construire et pousser des images avec des noms générés automatiquement, tels que quay.io/example/my-operator-bundle:v0.0.1 pour l'image bundle et quay.io/example/my-operator-catalog:v0.0.1 pour l'image index :

   $ make bundle-build bundle-push catalog-build catalog-push

3. Définissez un objet CatalogSource qui fait référence à l'image d'index que vous venez de générer, puis créez l'objet à l'aide de la commande oc apply ou de la console web :

   Exemple CatalogSource YAML

   apiVersion: operators.coreos.com/v1alpha1
   kind: CatalogSource
   metadata:
     name: cs-memcached
     namespace: default
   spec:
     displayName: My Test
     publisher: Company
     sourceType: grpc
     grpcPodConfig:
       securityContextConfig: <security_mode> 1
     image: quay.io/example/memcached-catalog:v0.0.1 2
     updateStrategy:
       registryPoll:
         interval: 10m

   1

   Spécifiez la valeur de legacy ou restricted. Si le champ n'est pas défini, la valeur par défaut est legacy. Dans une prochaine version d'OpenShift Container Platform, il est prévu que la valeur par défaut soit restricted. Si votre catalogue ne peut pas s'exécuter avec les autorisations restricted, il est recommandé de définir manuellement ce champ sur legacy.

   2

   Définissez image comme la spécification de tirage d'image que vous avez utilisée précédemment avec l'argument CATALOG_IMG.

4. Vérifier la source du catalogue :

   $ oc get catalogsource

   Exemple de sortie

   NAME           DISPLAY     TYPE   PUBLISHER   AGE
   cs-memcached   My Test     grpc   Company     4h31m

Vérification

1. Installez l'opérateur à l'aide de votre catalogue :

   1. Définissez un objet OperatorGroup et créez-le à l'aide de la commande oc apply ou de la console web :

      Exemple OperatorGroup YAML

      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: my-test
        namespace: default
      spec:
        targetNamespaces:
        - default

   2. Définissez un objet Subscription et créez-le à l'aide de la commande oc apply ou de la console web :

      Exemple Subscription YAML

      apiVersion: operators.coreos.com/v1alpha1
      kind: Subscription
      metadata:
        name: catalogtest
        namespace: default
      spec:
        channel: "alpha"
        installPlanApproval: Manual
        name: catalog
        source: cs-memcached
        sourceNamespace: default
        startingCSV: memcached-operator.v0.0.1

2. Vérifiez que l'opérateur installé fonctionne :

   1. Vérifier le groupe d'opérateurs :

      $ oc get og

      Exemple de sortie

      NAME             AGE
      my-test           4h40m

   2. Vérifiez la version du service de cluster (CSV) :

      $ oc get csv

      Exemple de sortie

      NAME                        DISPLAY   VERSION   REPLACES   PHASE
      memcached-operator.v0.0.1   Test      0.0.1                Succeeded

   3. Vérifier la présence de l'opérateur dans les nacelles :

      $ oc get pods

      Exemple de sortie

      NAME                                                              READY   STATUS      RESTARTS   AGE
      9098d908802769fbde8bd45255e69710a9f8420a8f3d814abe88b68f8ervdj6   0/1     Completed   0          4h33m
      catalog-controller-manager-7fd5b7b987-69s4n                       2/2     Running     0          4h32m
      cs-memcached-7622r                                                1/1     Running     0          4h33m

Procédure

1. Si votre opérateur n'a pas encore été installé avec OLM, installez la version antérieure soit en utilisant la sous-commande run bundle, soit en procédant à une installation traditionnelle d'OLM.

   Note

   Si la version précédente de l'ensemble a été installée traditionnellement à l'aide d'OLM, l'ensemble plus récent vers lequel vous souhaitez effectuer la mise à niveau ne doit pas exister dans l'image d'index référencée par la source du catalogue. Sinon, l'exécution de la sous-commande run bundle-upgrade entraînera l'échec du pod de registre, car l'ensemble plus récent est déjà référencé par l'index qui fournit le package et la version du service de cluster (CSV).

   Par exemple, vous pouvez utiliser la sous-commande run bundle suivante pour un opérateur Memcached en spécifiant l'image du bundle précédent :

   $ operator-sdk run bundle <registry>/<user>/memcached-operator:v0.0.1

   Exemple de sortie

   INFO[0006] Creating a File-Based Catalog of the bundle "quay.io/demo/memcached-operator:v0.0.1"
   INFO[0008] Generated a valid File-Based Catalog
   INFO[0012] Created registry pod: quay-io-demo-memcached-operator-v1-0-1
   INFO[0012] Created CatalogSource: memcached-operator-catalog
   INFO[0012] OperatorGroup "operator-sdk-og" created
   INFO[0012] Created Subscription: memcached-operator-v0-0-1-sub
   INFO[0015] Approved InstallPlan install-h9666 for the Subscription: memcached-operator-v0-0-1-sub
   INFO[0015] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.1" to reach 'Succeeded' phase
   INFO[0015] Waiting for ClusterServiceVersion ""my-project/memcached-operator.v0.0.1" to appear
   INFO[0026] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Pending
   INFO[0028] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Installing
   INFO[0059] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.1" phase: Succeeded
   INFO[0059] OLM has successfully installed "memcached-operator.v0.0.1"

2. Mettez à niveau l'opérateur installé en spécifiant l'image du paquet pour la version la plus récente de l'opérateur :

   $ operator-sdk run bundle-upgrade <registry>/<user>/memcached-operator:v0.0.2

   Exemple de sortie

   INFO[0002] Found existing subscription with name memcached-operator-v0-0-1-sub and namespace my-project
   INFO[0002] Found existing catalog source with name memcached-operator-catalog and namespace my-project
   INFO[0008] Generated a valid Upgraded File-Based Catalog
   INFO[0009] Created registry pod: quay-io-demo-memcached-operator-v0-0-2
   INFO[0009] Updated catalog source memcached-operator-catalog with address and annotations
   INFO[0010] Deleted previous registry pod with name "quay-io-demo-memcached-operator-v0-0-1"
   INFO[0041] Approved InstallPlan install-gvcjh for the Subscription: memcached-operator-v0-0-1-sub
   INFO[0042] Waiting for ClusterServiceVersion "my-project/memcached-operator.v0.0.2" to reach 'Succeeded' phase
   INFO[0019] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Pending
   INFO[0042] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: InstallReady
   INFO[0043] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Installing
   INFO[0044] Found ClusterServiceVersion "my-project/memcached-operator.v0.0.2" phase: Succeeded
   INFO[0044] Successfully upgraded to "memcached-operator.v0.0.2"

3. Nettoyer les opérateurs installés :

   $ operator-sdk cleanup memcached-operator

Procédure

1. Si vous savez qu'un bundle spécifique de votre Operator n'est pas pris en charge et ne fonctionnera pas correctement sur OpenShift Container Platform après une certaine version de cluster, configurez la version maximale d'OpenShift Container Platform avec laquelle votre Operator est compatible. Dans la version de service de cluster (CSV) de votre projet Operator, définissez l'annotation olm.maxOpenShiftVersion pour empêcher les administrateurs de mettre à niveau leur cluster avant de mettre à niveau l'Operator installé vers une version compatible :

   Important

   Vous ne devez utiliser l'annotation olm.maxOpenShiftVersion que si la version de votre Operator bundle ne peut pas fonctionner dans les versions ultérieures. Sachez que les administrateurs de clusters ne peuvent pas mettre à niveau leurs clusters avec votre solution installée. Si vous ne fournissez pas de version ultérieure et un chemin de mise à niveau valide, les administrateurs de clusters peuvent désinstaller votre Operator et mettre à jour la version du cluster.

   Exemple de CSV avec olm.maxOpenShiftVersion annotation

   apiVersion: operators.coreos.com/v1alpha1
   kind: ClusterServiceVersion
   metadata:
     annotations:
       "olm.properties": '[{"type": "olm.maxOpenShiftVersion", "value": "<cluster_version>"}]' 1

   1

   Indiquez la version de cluster maximale d'OpenShift Container Platform avec laquelle votre opérateur est compatible. Par exemple, la définition de value sur 4.9 empêche les mises à niveau de cluster vers des versions d'OpenShift Container Platform postérieures à 4.9 lorsque ce bundle est installé sur un cluster.

2. Si votre bundle est destiné à être distribué dans un catalogue Operator fourni par Red Hat, configurez les versions compatibles d'OpenShift Container Platform pour votre Operator en définissant les propriétés suivantes. Cette configuration garantit que votre Operator est uniquement inclus dans les catalogues qui ciblent des versions compatibles d'OpenShift Container Platform :

   Note

   Cette étape n'est valable que pour la publication d'opérateurs dans les catalogues fournis par Red Hat. Si votre offre groupée est uniquement destinée à être distribuée dans un catalogue personnalisé, vous pouvez ignorer cette étape. Pour plus de détails, voir "Catalogues d'opérateurs fournis par Red Hat".

   1. Définissez l'annotation com.redhat.openshift.versions dans le fichier bundle/metadata/annotations.yaml de votre projet :

      Exemple de fichier bundle/metadata/annotations.yaml avec les versions compatibles

      com.redhat.openshift.versions : "v4.7-v4.9" 1

      1

      Définir une gamme ou une version unique.

   2. Pour éviter que votre bundle ne soit transféré vers une version incompatible d'OpenShift Container Platform, assurez-vous que l'image d'index est générée avec l'étiquette com.redhat.openshift.versions appropriée dans l'image du bundle de votre Operator. Par exemple, si votre projet a été généré en utilisant le SDK Operator, mettez à jour le fichier bundle.Dockerfile:

      Exemple bundle.Dockerfile avec versions compatibles

      LABEL com.redhat.openshift.versions="<versions>" 1

      1

      Définir une plage ou une version unique, par exemple, v4.7-v4.9. Ce paramètre définit les versions de cluster dans lesquelles l'opérateur doit être distribué, et l'opérateur n'apparaît pas dans le catalogue d'une version de cluster qui se situe en dehors de la plage.