5.4. Opérateurs basés sur Ansible

Procédure

1. Create a project.

   1. Créez votre répertoire de projet :

      $ mkdir memcached-operator

   2. Allez dans le répertoire du projet :

      $ cd memcached-operator

   3. Exécutez la commande operator-sdk init avec le plugin ansible pour initialiser le projet :

      $ operator-sdk init \
          --plugins=ansible \
          --domain=example.com

2. Create an API.

   Créer une API Memcached simple :

   $ operator-sdk create api \
       --group cache \
       --version v1 \
       --kind Memcached \
       --generate-role 1

   1

   Génère un rôle Ansible pour l'API.

3. Build and push the Operator image.

   Utilisez les cibles par défaut de Makefile pour construire et pousser votre opérateur. Définissez IMG avec une spécification d'extraction pour votre image qui utilise un registre vers lequel vous pouvez pousser :

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

4. Run the Operator.

   1. Installer le CRD :

      $ make install

   2. Déployez le projet sur le cluster. Définissez IMG sur l'image que vous avez poussée :

      $ make deploy IMG=<registry>/<user>/<image_name>:<tag>

5. Create a sample custom resource (CR).

   1. Créer un échantillon de CR :

      $ oc apply -f config/samples/cache_v1_memcached.yaml \
          -n memcached-operator-system

   2. Il faut s'attendre à ce que le CR réconcilie l'opérateur :

      $ oc logs deployment.apps/memcached-operator-controller-manager \
          -c manager \
          -n memcached-operator-system

      Exemple de sortie

      ...
      I0205 17:48:45.881666       7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator
      {"level":"info","ts":1612547325.8819902,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
      {"level":"info","ts":1612547325.98242,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
      {"level":"info","ts":1612547325.9824686,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4}
      {"level":"info","ts":1612547348.8311093,"logger":"runner","msg":"Ansible-runner exited successfully","job":"4037200794235010051","name":"memcached-sample","namespace":"memcached-operator-system"}

6. Delete a CR

   Supprimez un CR en exécutant la commande suivante :

   $ oc delete -f config/samples/cache_v1_memcached.yaml -n memcached-operator-system

7. Clean up.

   Exécutez la commande suivante pour nettoyer les ressources qui ont été créées dans le cadre de cette procédure :

   $ make undeploy

Procédure

1. Créer un répertoire pour le projet :

   $ mkdir -p $HOME/projects/memcached-operator

2. Accédez au répertoire :

   $ cd $HOME/projects/memcached-operator

3. Exécutez la commande operator-sdk init avec le plugin ansible pour initialiser le projet :

   $ operator-sdk init \
       --plugins=ansible \
       --domain=example.com

Procédure

1. Mettez à jour le fichier roles/memcached/tasks/main.yml avec la structure suivante :

   ---
   - name: start memcached
     community.kubernetes.k8s:
       definition:
         kind: Deployment
         apiVersion: apps/v1
         metadata:
           name: '{{ ansible_operator_meta.name }}-memcached'
           namespace: '{{ ansible_operator_meta.namespace }}'
         spec:
           replicas: "{{size}}"
           selector:
             matchLabels:
               app: memcached
           template:
             metadata:
               labels:
                 app: memcached
             spec:
               containers:
               - name: memcached
                 command:
                 - memcached
                 - -m=64
                 - -o
                 - modern
                 - -v
                 image: "docker.io/memcached:1.4.36-alpine"
                 ports:
                   - containerPort: 11211

   Ce rôle memcached garantit l'existence d'un déploiement memcached et définit la taille du déploiement.

2. Définissez des valeurs par défaut pour les variables utilisées dans votre rôle Ansible en modifiant le fichier roles/memcached/defaults/main.yml:

   ---
   # defaults file for Memcached
   size: 1

3. Mettez à jour l'exemple de ressource Memcached dans le fichier config/samples/cache_v1_memcached.yaml avec la structure suivante :

   apiVersion: cache.example.com/v1
   kind: Memcached
   metadata:
     name: memcached-sample
   spec:
     size: 3

   Les paires clé-valeur de la spécification des ressources personnalisées (CR) sont transmises à Ansible en tant que variables supplémentaires.

Procédure

1. Ajoutez les variables d'environnement au déploiement en mettant à jour le fichier roles/memcached/tasks/main.yml avec ce qui suit :

   ...
   env:
      - name: HTTP_PROXY
        value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}'
      - name: http_proxy
        value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}'
   ...

2. Définissez la variable d'environnement sur le déploiement de l'opérateur en ajoutant ce qui suit au fichier config/manager/manager.yaml:

   containers:
    - args:
      - --leader-elect
      - --leader-election-id=ansible-proxy-demo
      image: controller:latest
      name: manager
      env:
        - name: "HTTP_PROXY"
          value: "http_proxy_test"

Procédure

1. Passez à l'espace de noms dans lequel votre opérateur est installé. Par exemple, si vous avez déployé l'opérateur à l'aide de la commande make deploy:

   $ oc project memcached-operator-system

2. Modifiez l'exemple de manifeste Memcached CR à l'adresse config/samples/cache_v1_memcached.yaml pour qu'il contienne la spécification suivante :

   apiVersion: cache.example.com/v1
   kind: Memcached
   metadata:
     name: memcached-sample
   ...
   spec:
   ...
     size: 3

3. Créer le CR :

   $ oc apply -f config/samples/cache_v1_memcached.yaml

4. Assurez-vous que l'opérateur Memcached crée le déploiement pour l'échantillon de CR avec la taille correcte :

   $ oc get deployments

   Exemple de sortie

   NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
   memcached-operator-controller-manager   1/1     1            1           8m
   memcached-sample                        3/3     3            3           1m

5. Vérifiez l'état des pods et du CR pour confirmer que l'état est mis à jour avec les noms des pods Memcached.

   1. Vérifier les gousses :

      $ oc get pods

      Exemple de sortie

      NAME                                  READY     STATUS    RESTARTS   AGE
      memcached-sample-6fd7c98d8-7dqdr      1/1       Running   0          1m
      memcached-sample-6fd7c98d8-g5k7v      1/1       Running   0          1m
      memcached-sample-6fd7c98d8-m7vn7      1/1       Running   0          1m

   2. Vérifier l'état de la CR :

      $ oc get memcached/memcached-sample -o yaml

      Exemple de sortie

      apiVersion: cache.example.com/v1
      kind: Memcached
      metadata:
      ...
        name: memcached-sample
      ...
      spec:
        size: 3
      status:
        nodes:
        - memcached-sample-6fd7c98d8-7dqdr
        - memcached-sample-6fd7c98d8-g5k7v
        - memcached-sample-6fd7c98d8-m7vn7

6. Mettre à jour la taille du déploiement.

   1. Mettre à jour le fichier config/samples/cache_v1_memcached.yaml pour modifier le champ spec.size dans le CR Memcached de 3 à 5:

      $ oc patch memcached memcached-sample \
          -p '{"spec":{"size": 5}}' \
          --type=merge

   2. Confirmez que l'opérateur modifie la taille du déploiement :

      $ oc get deployments

      Exemple de sortie

      NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
      memcached-operator-controller-manager   1/1     1            1           10m
      memcached-sample                        5/5     5            5           3m

7. Supprimez le CR en exécutant la commande suivante :

   $ oc delete -f config/samples/cache_v1_memcached.yaml

8. Nettoyer les ressources qui ont été créées dans le cadre de ce tutoriel.

   • Si vous avez utilisé la commande make deploy pour tester l'opérateur, exécutez la commande suivante :

     $ make undeploy

   • Si vous avez utilisé la commande operator-sdk run bundle pour tester l'opérateur, exécutez la commande suivante :

     $ operator-sdk cleanup <nom_du_projet>

Procédure

1. Apportez les modifications suivantes au fichier config/default/manager_auth_proxy_patch.yaml:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: controller-manager
     namespace: system
   spec:
     template:
       spec:
         containers:
         - name: kube-rbac-proxy
           image: registry.redhat.io/openshift4/ose-kube-rbac-proxy:v4.12 1
           args:
           - "--secure-listen-address=0.0.0.0:8443"
           - "--upstream=http://127.0.0.1:8080/"
           - "--logtostderr=true"
           - "--v=0"
   ...

   1

   Mettre à jour la version de la balise de v4.11 à v4.12.

2. Apportez les modifications suivantes à votre site Makefile:

   1. Pour activer la prise en charge des architectures multiples, ajoutez la cible docker-buildx à votre projet Makefile:

      Exemple Makefile

      # PLATFORMS defines the target platforms for  the manager image be build to provide support to multiple
      # architectures. (i.e. make docker-buildx IMG=myregistry/mypoperator:0.0.1). To use this option you need to:
      # - able to use docker buildx . More info: https://docs.docker.com/build/buildx/
      # - have enable BuildKit, More info: https://docs.docker.com/develop/develop-images/build_enhancements/
      # - be able to push the image for your registry (i.e. if you do not inform a valid value via IMG=<myregistry/image:<tag>> than the export will fail)
      # To properly provided solutions that supports more than one platform you should use this option.
      PLATFORMS ?= linux/arm64,linux/amd64,linux/s390x,linux/ppc64le
      .PHONY: docker-buildx
      docker-buildx: test ## Build and push docker image for the manager for cross-platform support
      	# copy existing Dockerfile and insert --platform=${BUILDPLATFORM} into Dockerfile.cross, and preserve the original Dockerfile
      	sed -e '1 s/\(^FROM\)/FROM --platform=\$$\{BUILDPLATFORM\}/; t' -e ' 1,// s//FROM --platform=\$$\{BUILDPLATFORM\}/' Dockerfile > Dockerfile.cross
      	- docker buildx create --name project-v3-builder
      	docker buildx use project-v3-builder
      	- docker buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile.cross
      	- docker buildx rm project-v3-builder
      	rm Dockerfile.cross

   2. Pour permettre la prise en charge des architectures arm64 dans votre projet Operator, apportez les modifications suivantes à votre projet Makefile:

      Ancienne Makefile

      OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
      ARCH := $(shell uname -m | sed 's/x86_64/amd64/')

      Nouveau Makefile

      OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
      ARCH := $(shell uname -m | sed 's/x86_64/amd64/' |  sed 's/aarch64/arm64/')

   3. Mettez à jour la version de Kustomize à v4.5.5 comme indiqué dans l'exemple suivant :

      Ancienne Makefile

      .PHONY: kustomize
      KUSTOMIZE = $(shell pwd)/bin/kustomize
      kustomize: ## Download kustomize locally if necessary.
      ifeq (,$(wildcard $(KUSTOMIZE)))
      ifeq (,$(shell which kustomize 2>/dev/null))
      	@{ \
      	set -e ;\
      	mkdir -p $(dir $(KUSTOMIZE)) ;\
      	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v3.8.7/kustomize_v3.8.7_$(OS)_$(ARCH).tar.gz | \
      	tar xzf - -C bin/ ;\
      	}
      else

      Nouveau Makefile

      .PHONY: kustomize
      KUSTOMIZE = $(shell pwd)/bin/kustomize
      kustomize: ## Download kustomize locally if necessary.
      ifeq (,$(wildcard $(KUSTOMIZE)))
      ifeq (,$(shell which kustomize 2>/dev/null))
      	@{ \
      	set -e ;\
      	mkdir -p $(dir $(KUSTOMIZE)) ;\
      	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v4.5.5/kustomize_v4.5.5_$(OS)_$(ARCH).tar.gz | \ 1
      	tar xzf - -C bin/ ;\
      	}
      else

      1

      Mise à jour de la version v3.8.7 vers v4.5.5.

      Important

      La version de Kustomize 4.0.0 a supprimé le plugin go-getter et a introduit des changements qui ne sont pas compatibles avec les versions antérieures. Les projets d'opérateurs qui s'appuient sur des versions antérieures de Kustomize pourraient ne pas fonctionner avec les nouvelles versions.

   4. Pour appliquer les changements à votre Makefile et reconstruire votre Opérateur, entrez la commande suivante :

      $ make

3. Mettez à jour votre fichier config/default/kustomizations.yaml comme indiqué dans les exemples suivants :

   Exemple de fichier kustomizations.yaml

   # Adds namespace to all resources.
   namespace: memcached-operator-system
   # Value of this field is prepended to the
   # names of all resources, e.g. a deployment named
   # "wordpress" becomes "alices-wordpress".
   # Note that it should also match with the prefix (text before '-') of the namespace
   # field above.
   namePrefix: memcached-operator-
   
   # Labels to add to all resources and selectors.
   #labels: 1
   #- includeSelectors: true 2
   #  pairs:
   #    someName: someValue
   
   resources: 3
   - ../crd
   - ../rbac
   - ../manager

   1

   Remplacer le champ commonLabels par le champ labels.

   2

   Ajouter includeSelectors: true.

   3

   Remplacer le champ bases par le champ resources.

4. Mettez à jour votre fichier molecule/default/kustomize.yml en y apportant les modifications suivantes :

   Exemple de fichier molecule/default/kustomize.yml

   ---
   - name: Build kustomize testing overlay
     # load_restrictor must be set to none so we can load patch files from the default overlay
     command: '{{ kustomize }} build --load-restrictor LoadRestrictionsNone' 1
     args:
       chdir: '{{ config_dir }}/testing'
     register: resources
     changed_when: false

   1

   Remplacer --load_restrictor none . par --load-restrictor LoadRestrictionNone.

Procédure

1. Installer Ansible 2.9 :

   $ sudo dnf install ansible

2. Installez le paquetage client OpenShift python:

   $ pip3 install openshift

3. Installez la collection Kubernetes en utilisant l'une des méthodes suivantes :

   • Vous pouvez installer la collection directement depuis Ansible Galaxy :

     $ ansible-galaxy collection install community.kubernetes

   • Si vous avez déjà initialisé votre Opérateur, il se peut que vous ayez un fichier requirements.yml au niveau supérieur de votre projet. Ce fichier spécifie les dépendances Ansible qui doivent être installées pour que votre opérateur fonctionne. Par défaut, ce fichier installe la collection community.kubernetes ainsi que la collection operator_sdk.util, qui fournit des modules et des plugins pour les fonctions spécifiques à l'opérateur.

     Pour installer les modules dépendants du fichier requirements.yml:

     $ ansible-galaxy collection install -r requirements.yml

Procédure

1. Dans le répertoire de votre projet Operator basé sur Ansible, modifiez le fichier roles/<kind>/tasks/main.yml avec la logique Ansible que vous souhaitez. Le répertoire roles/<kind>/ est créé lorsque vous utilisez l'indicateur --generate-role lors de la création d'une API. Le remplaçable <kind> correspond au type que vous avez spécifié pour l'API.

   L'exemple suivant crée et supprime une carte de configuration en fonction de la valeur d'une variable nommée state:

   ---
   - name: set ConfigMap example-config to {{ state }}
     community.kubernetes.k8s:
       api_version: v1
       kind: ConfigMap
       name: example-config
       namespace: default 1
       state: "{{ state }}"
     ignore_errors: true 2

   1

   Modifiez cette valeur si vous souhaitez que la carte de configuration soit créée dans un espace de noms différent de celui de default.

   2

   Le fait de définir ignore_errors: true permet de s'assurer que la suppression d'une carte de configuration inexistante n'échoue pas.

2. Modifiez le fichier roles/<kind>/defaults/main.yml pour que state soit remplacé par present par défaut :

   ---
   state: present

3. Créez un playbook Ansible en créant un fichier playbook.yml dans le niveau supérieur de votre répertoire de projet, et incluez votre rôle <kind>:

   ---
   - hosts: localhost
     roles:
       - <kind>

4. Exécutez le manuel de jeu :

   $ ansible-playbook playbook.yml

   Exemple de sortie

   [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
   
   PLAY [localhost] ********************************************************************************
   
   TASK [Gathering Facts] ********************************************************************************
   ok: [localhost]
   
   TASK [memcached : set ConfigMap example-config to present] ********************************************************************************
   changed: [localhost]
   
   PLAY RECAP ********************************************************************************
   localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

5. Vérifiez que la carte de configuration a été créée :

   $ oc get configmaps

   Exemple de sortie

   NAME               DATA   AGE
   example-config     0      2m1s

6. Exécutez à nouveau le manuel de jeu en remplaçant state par absent:

   $ ansible-playbook playbook.yml --extra-vars state=absent

   Exemple de sortie

   [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
   
   PLAY [localhost] ********************************************************************************
   
   TASK [Gathering Facts] ********************************************************************************
   ok: [localhost]
   
   TASK [memcached : set ConfigMap example-config to absent] ********************************************************************************
   changed: [localhost]
   
   PLAY RECAP ********************************************************************************
   localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

7. Vérifiez que la carte de configuration a été supprimée :

   $ oc get configmaps

Procédure

1. Installez votre définition de ressource personnalisée (CRD) et les définitions de contrôle d'accès basé sur les rôles (RBAC) appropriées pour votre ressource personnalisée (CR) :

   $ make install

   Exemple de sortie

   /usr/bin/kustomize build config/crd | kubectl apply -f -
   customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com created

2. Exécutez la commande make run:

   $ make run

   Exemple de sortie

   /home/user/memcached-operator/bin/ansible-operator run
   {"level":"info","ts":1612739145.2871568,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.10.1","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"}
   ...
   {"level":"info","ts":1612739148.347306,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":":8080"}
   {"level":"info","ts":1612739148.3488882,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2}
   {"level":"info","ts":1612739148.3490262,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false}
   {"level":"info","ts":1612739148.3490646,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"}
   {"level":"info","ts":1612739148.350217,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"}
   {"level":"info","ts":1612739148.3506632,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"}
   {"level":"info","ts":1612739148.350784,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
   {"level":"info","ts":1612739148.5511978,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
   {"level":"info","ts":1612739148.5512562,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8}

   L'opérateur surveillant désormais les événements de votre CR, la création d'un CR déclenchera l'exécution de votre rôle Ansible.

   Note

   Prenons l'exemple d'un manifeste config/samples/<gvk>.yaml CR :

   apiVersion: <group>.example.com/v1alpha1
   kind: <kind>
   metadata:
     name: "<kind>-sample"

   Comme le champ spec n'est pas défini, Ansible est invoqué sans variables supplémentaires. Le passage de variables supplémentaires d'un CR à Ansible est abordé dans une autre section. Il est important de définir des valeurs par défaut raisonnables pour l'opérateur.

3. Créez une instance de votre CR avec la variable par défaut state fixée à present:

   $ oc apply -f config/samples/<gvk>.yaml

4. Vérifiez que la carte de configuration example-config a été créée :

   $ oc get configmaps

   Exemple de sortie

   NAME                    STATUS    AGE
   example-config          Active    3s

5. Modifiez votre fichier config/samples/<gvk>.yaml pour que le champ state soit remplacé par absent. Par exemple :

   apiVersion: cache.example.com/v1
   kind: Memcached
   metadata:
     name: memcached-sample
   spec:
     state: absent

6. Appliquez les modifications :

   $ oc apply -f config/samples/<gvk>.yaml

7. Confirmez que la carte de configuration est supprimée :

   $ oc get configmap

Procédure

1. Exécutez les commandes make suivantes pour construire et pousser l'image de l'opérateur. 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>/<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>/<image_name>:<tag>

      Note

      Le nom et la balise de l'image, par exemple IMG=<registry>/<user>/<image_name>:<tag>, dans les deux commandes peuvent également être définis dans votre Makefile. Modifiez la valeur de IMG ?= controller:latest pour définir votre nom d'image par défaut.

2. Exécutez la commande suivante pour déployer l'opérateur :

   $ make deploy IMG=<registry>/<user>/<image_name>:<tag>

   Par défaut, cette commande crée un espace de noms avec le nom de votre projet Operator sous la forme <project_name>-system et est utilisé pour le déploiement. Cette commande installe également les manifestes RBAC à partir de config/rbac.

3. Exécutez la commande suivante pour vérifier que l'opérateur fonctionne :

   oc get deployment -n <nom_du_projet>-système

   Exemple de sortie

   NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
   <project_name>-controller-manager       1/1     1            1           8m

Procédure

1. Mettre à jour le fichier watches.yaml avec un champ manageStatus défini comme false:

   - version: v1
     group: api.example.com
     kind: <kind>
     role: <role>
     manageStatus: false

2. Utilisez le module Ansible operator_sdk.util.k8s_status pour mettre à jour la sous-ressource. Par exemple, pour mettre à jour la clé test et la valeur data, operator_sdk.util peut être utilisé comme indiqué :

   - operator_sdk.util.k8s_status:
       api_version: app.example.com/v1
       kind: <kind>
       name: "{{ ansible_operator_meta.name }}"
       namespace: "{{ ansible_operator_meta.namespace }}"
       status:
         test: data

3. Vous pouvez déclarer des collections dans le fichier meta/main.yml pour le rôle, qui est inclus pour les opérateurs basés sur Ansible :

   collections:
     - operator_sdk.util

4. Après avoir déclaré les collections dans le méta-rôle, vous pouvez invoquer directement le module k8s_status:

   k8s_status:
     ...
     status:
       key1: value1