5.4. Opérateurs basés sur Ansible

Procédure

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

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

2. Changement dans le 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. Actualisez le fichier role/memcached/tasks/main.yml avec la structure suivante:

   ---
   - name: start memcached
     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 assure l’existence d’un déploiement mémcached et définit la taille du déploiement.

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

   ---
   # defaults file for Memcached
   size: 1

3. Actualisez la ressource de l’échantillon Memcached dans le fichier config/samples/cache_v1_memcached.yaml avec la structure suivante:

   apiVersion: cache.example.com/v1
   kind: Memcached
   metadata:
     labels:
       app.kubernetes.io/name: memcached
       app.kubernetes.io/instance: memcached-sample
       app.kubernetes.io/part-of: memcached-operator
       app.kubernetes.io/managed-by: kustomize
       app.kubernetes.io/created-by: memcached-operator
     name: memcached-sample
   spec:
     size: 3

   Les paires clé-valeur dans la spécification de ressource personnalisée (CR) sont transmises à Ansible sous forme de variables supplémentaires.

Procédure

1. Ajoutez les variables d’environnement au déploiement en mettant à jour le fichier role/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. Changer l’espace de noms où votre opérateur est installé. À titre d’exemple, si vous avez déployé l’opérateur à l’aide de la commande make deployment:

   $ oc project memcached-operator-system

2. Éditer l’échantillon Memcached CR manifeste à config/samples/cache_v1_memcached.yaml pour contenir les spécifications suivantes:

   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 de l’échantillon CR avec la bonne taille:

   $ 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. Consultez le statut des pods et CR pour confirmer que le statut est mis à jour avec les noms de pod de Memcached.

   1. Consultez 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. Consultez l’état 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. Actualisez la taille du déploiement.

   1. Actualisez 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. Nettoyez les ressources qui ont été créées dans le cadre de ce tutoriel.

   • Lorsque vous avez utilisé la commande make deployment pour tester l’opérateur, exécutez la commande suivante:

     $ make undeploy

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

     $ operator-sdk cleanup <project_name>

Procédure

1. Éditez le Makefile de votre projet Opérateur pour mettre à jour la version SDK de l’opérateur vers 1.38.0, comme indiqué dans l’exemple suivant:

   Exemple de Makefile

   # Set the Operator SDK version to use. By default, what is installed on the system is used.
   # This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit.
   OPERATOR_SDK_VERSION ?= v1.38.0 

   1

   1

   Changer la version de 1.36.1 à 1.38.0.

2. Éditez le Dockerfile de votre projet Opérateur pour mettre à jour la balise image ose-ansible-operator à 4, comme indiqué dans l’exemple suivant:

   Exemple Dockerfile

   FROM registry.redhat.io/openshift4/ose-ansible-operator:v4

3. Il faut mettre à niveau les versions Kubernetes de votre projet Opérateur pour utiliser 1.30 et Kubebuilder v4.

   Astuce

   Cette mise à jour comprend des changements complexes d’échafaudage en raison de l’élimination du kube-rbac-proxy. Lorsque ces migrations deviennent difficiles à suivre, échafauder un nouveau projet d’échantillon à des fins de comparaison.

   1. Actualisez la version Kustomize dans votre Makefile en apportant les modifications suivantes:

      - curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v5.3.0/kustomize_v5.3.0_$(OS)_$(ARCH).tar.gz | \
      + curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v5.4.2/kustomize_v5.4.2_$(OS)_$(ARCH).tar.gz | \

   2. Actualisez votre fichier config/default/kustomization.yaml avec les modifications suivantes:

        # [PROMETHEUS] To enable prometheus monitor, uncomment all sections with 'PROMETHEUS'.
        #- ../prometheus
      + # [METRICS] Expose the controller manager metrics service.
      + - metrics_service.yaml
      
      + # Uncomment the patches line if you enable Metrics, and/or are using webhooks and cert-manager
        patches:
      - # Protect the /metrics endpoint by putting it behind auth.
      - # If you want your controller-manager to expose the /metrics
      - # endpoint w/o any authn/z, please comment the following line.
      - - path: manager_auth_proxy_patch.yaml
      + # [METRICS] The following patch will enable the metrics endpoint using HTTPS and the port :8443.
      + # More info: https://book.kubebuilder.io/reference/metrics
      + - path: manager_metrics_patch.yaml
      +   target:
      +     kind: Deployment

   3. Enlevez les fichiers config/default/manager_auth_proxy_patch.yaml et config/default/manager_config_patch.yaml.

   4. Créez un fichier config/default/manager_metrics_patch.yaml avec le contenu suivant:

      # This patch adds the args to allow exposing the metrics endpoint using HTTPS
      - op: add
        path: /spec/template/spec/containers/0/args/0
        value: --metrics-bind-address=:8443
      # This patch adds the args to allow securing the metrics endpoint
      - op: add
        path: /spec/template/spec/containers/0/args/0
        value: --metrics-secure
      # This patch adds the args to allow RBAC-based authn/authz the metrics endpoint
      - op: add
        path: /spec/template/spec/containers/0/args/0
        value: --metrics-require-rbac

   5. Créez un fichier config/default/metrics_service.yaml avec le contenu suivant:

      apiVersion: v1
      kind: Service
      metadata:
        labels:
          control-plane: controller-manager
          app.kubernetes.io/name: <operator-name>
          app.kubernetes.io/managed-by: kustomize
        name: controller-manager-metrics-service
        namespace: system
      spec:
        ports:
          - name: https
            port: 8443
            protocol: TCP
            targetPort: 8443
        selector:
          control-plane: controller-manager

   6. Actualisez votre fichier config/manager/manager.yaml avec les modifications suivantes:

        - --leader-elect
      + - --health-probe-bind-address=:6789

   7. Actualisez votre fichier config/prometheus/monitor.yaml avec les modifications suivantes:

           - path: /metrics
      -      port: https
      +      port: https # Ensure this is the name of the port that exposes HTTPS metrics
             tlsConfig:
      +        # TODO(user): The option insecureSkipVerify: true is not recommended for production since it disables
      +        # certificate verification. This poses a significant security risk by making the system vulnerable to
      +        # man-in-the-middle attacks, where an attacker could intercept and manipulate the communication between
      +        # Prometheus and the monitored services. This could lead to unauthorized access to sensitive metrics data,
      +        # compromising the integrity and confidentiality of the information.
      +        # Please use the following options for secure configurations:
      +        # caFile: /etc/metrics-certs/ca.crt
      +        # certFile: /etc/metrics-certs/tls.crt
      +        # keyFile: /etc/metrics-certs/tls.key
               insecureSkipVerify: true

   8. Supprimez les fichiers suivants du répertoire config/rbac/:

      • auth_proxy_client_clusterrole.yaml
      • auth_proxy_role.yaml
      • auth_proxy_role_binding.yaml
      • auth_proxy_service.yaml

   9. Actualisez votre fichier config/rbac/kustomization.yaml avec les modifications suivantes:

        - leader_election_role_binding.yaml
      - # Comment the following 4 lines if you want to disable
      - # the auth proxy (https://github.com/brancz/kube-rbac-proxy)
      - # which protects your /metrics endpoint.
      - - auth_proxy_service.yaml
      - - auth_proxy_role.yaml
      - - auth_proxy_role_binding.yaml
      - - auth_proxy_client_clusterrole.yaml
      + # The following RBAC configurations are used to protect
      + # the metrics endpoint with authn/authz. These configurations
      + # ensure that only authorized users and service accounts
      + # can access the metrics endpoint. Comment the following
      + # permissions if you want to disable this protection.
      + # More info: https://book.kubebuilder.io/reference/metrics.html
      + - metrics_auth_role.yaml
      + - metrics_auth_role_binding.yaml
      + - metrics_reader_role.yaml

   10. Créez un fichier config/rbac/metrics_auth_role_binding.yaml avec le contenu suivant:

       apiVersion: rbac.authorization.k8s.io/v1
       kind: ClusterRoleBinding
       metadata:
         name: metrics-auth-rolebinding
       roleRef:
         apiGroup: rbac.authorization.k8s.io
         kind: ClusterRole
         name: metrics-auth-role
       subjects:
         - kind: ServiceAccount
           name: controller-manager
           namespace: system

   11. Créez un fichier config/rbac/metrics_reader_role.yaml avec le contenu suivant:

       apiVersion: rbac.authorization.k8s.io/v1
       kind: ClusterRole
       metadata:
         name: metrics-reader
       rules:
       - nonResourceURLs:
         - "/metrics"
         verbs:
         - get

Procédure

1. Installer Ansible 2.15+:

   $ sudo dnf install ansible

2. Installez le package client Python Kubernetes:

   $ pip install kubernetes

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

   • La collection peut être installée directement à partir d’Ansible Galaxy:

     $ ansible-galaxy collection install community.kubernetes

   • Lorsque vous avez déjà initialisé votre opérateur, vous pourriez avoir un fichier requirements.yml au niveau supérieur de votre projet. Ce fichier spécifie les dépendances anonymes qui doivent être installées pour que votre opérateur fonctionne. Ce fichier installe par défaut 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.

     Installer les modules dépendants à partir du fichier requirements.yml:

     $ ansible-galaxy collection install -r requirements.yml

Procédure

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

   L’exemple suivant crée et supprime une carte de configuration basée sur la valeur d’une variable nommée état:

   ---
   - name: set ConfigMap example-config to {{ state }}
     community.kubernetes.k8s:
       api_version: v1
       kind: ConfigMap
       name: example-config
       namespace: <operator_namespace> 

   1

   
       state: "{{ state }}"
     ignore_errors: true 

   2

   1

   Indiquez l’espace de noms où vous souhaitez créer la carte de configuration.

   2

   La configuration d’ignorer_erreurs: true s’assure que la suppression d’une carte de configuration inexistante ne échoue pas.

2. Changer le fichier role/<kind>/defaults/main.yml pour définir l’état à présenter 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 livre de lecture:

   $ 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. Assurez-vous 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 l’état de réglage du livre de lecture à l’absence:

   $ 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. Assurez-vous que la carte de configuration a été supprimée:

   $ oc get configmaps

Procédure

1. Installez votre définition de ressources personnalisées (CRD) et les définitions appropriées du contrôle d’accès basé sur les rôles (RBAC) 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}

   Avec l’opérateur qui surveille maintenant votre CR pour les événements, la création d’un CR déclenchera votre rôle Ansible à exécuter.

   Note

   Considérez un exemple de config/samples/<gvk>.yaml CR manifeste:

   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 couvert dans une autre section. Il est important de fixer des défauts raisonnables pour l’opérateur.

3. Créez une instance de votre CR avec l’état variable par défaut défini pour présenter:

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

4. Assurez-vous 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 définir le champ d’état à absent. À titre d’exemple:

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

6. Appliquer 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 suivantes pour construire et pousser l’image de l’opérateur. Modifiez l’argument IMG dans les étapes suivantes pour faire référence à un référentiel auquel vous avez accès. Il est possible d’obtenir un compte de stockage 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 Dockerfile généré par le SDK pour l’opérateur renvoie explicitement GOARCH=amd64 pour la construction de go. Cela peut être modifié à GOARCH=$TARGETARCH pour les architectures non-AMD64. Docker définira automatiquement la variable d’environnement à la valeur spécifiée par -platform. Avec Buildah, le -build-arg devra être utilisé à cet effet. En savoir plus, consultez Multiple Architectures.

   2. Appuyez sur l’image vers 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=&lt;registry&gt;/&lt;user&gt;/&lt;image_name&gt;:&lt;tag&gt;, dans les deux commandes peuvent également être définis dans votre Makefile. Changez la valeur IMG ?= Controller:dernière valeur 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>

   Cette commande crée un espace de noms avec le nom de votre projet Opérateur dans le formulaire &lt;project_name&gt;-system et est utilisée 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 est en cours d’exécution:

   $ oc get deployment -n <project_name>-system

   Exemple de sortie

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

Procédure

1. Actualisez le fichier watch.yaml avec un champ ManagStatus défini à false:

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

2. Utilisez le module operator_sdk.util.k8s_status Ansible pour mettre à jour la sous-ressource. À titre d’exemple, pour mettre à jour avec les données clés de test et de valeur, 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. Il est possible de déclarer les collections dans le fichier meta/main.yml pour le rôle, qui est inclus pour les opérateurs échafaudés basés sur Ansible:

   collections:
     - operator_sdk.util

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

   k8s_status:
     ...
     status:
       key1: value1