Rôle Ansible Atlassian BambooAgent

Ce rôle effectue les actions nécessaires pour exécuter un agent distant Atlassian Bamboo sur une machine cible.

Le rôle effectue les actions suivantes :

• crée l'utilisateur qui exécute l'agent Bamboo,
• installe le certificat du serveur Bamboo afin de pouvoir télécharger le fichier JAR de l'agent Bamboo directement à partir du serveur sans contourner la sécurité (optionnel),
• crée des scripts de démarrage pour l'agent Bamboo, remplit des chemins supplémentaires (outils de construction) et des options supplémentaires (soit du système comme CUDA_VISIBLE_DEVICES ou des configurations supplémentaires de l'agent Bamboo),
• enregistre le script de démarrage de l'agent Bamboo pour le lancer au démarrage,
• enregistre un service de démarrage automatique sur le système d'exploitation,
• remplit les capacités de l'agent,
• change le dossier de construction et le nom de l'agent.

Exigences

Java doit être installé sur le système d'exploitation cible. Envisagez d'utiliser le rôle ansible-atlassian-bambooagent-oracle-java à cet effet.

Variables de rôle

Les variables suivantes doivent être définies pour le rôle.

Java

La version de l'agent doit bien fonctionner avec le Java installé. Par exemple, la version 5.11 de l'agent Bamboo nécessite Java 8. Le JAVA_HOME est défini automatiquement sur OSX lors du démarrage de l'agent.

Capacité Bamboo

Des capacités spécifiques peuvent être déclarées automatiquement par l'agent en utilisant une fonctionnalité d'Atlassian Bamboo : le fichier de capacités. Ce fichier a un format très simple et se trouve dans le dossier d'installation.

Le fichier capacité recevra les capacités déclarées en exécutant le playbook. Il s'agit d'une liste de paires (dictionnaire) indiquant le nom de la capacité ainsi que sa valeur.

- name: '[BAMBOO] déclaration de capacités vides'
  set_fact:
    bamboo_capabilities: {}

Il est possible de mettre à jour les capacités d'abord en les lisant à partir du disque, en utilisant par exemple une pre_task :

pre_tasks:
    - name: Lecture du fichier de capacité de l'agent
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

et ensuite les écrire sur disque comme par exemple une post_task :

post_tasks:
  - name: Mise à jour du fichier de capacité de l'agent
    include_role:
      name: atlassian_bambooagent_role
      tasks_from: write_capability

La lecture et l'écriture utilisent toutes deux le dictionnaire bamboo_capabilities (en tant que fait) comme entrée/sortie. Les fonctions gèrent correctement l'échappement de / et \ selon les différentes plateformes.

Un play typique dans un playbook ressemblerait à ceci :

- hosts: mes-agents-bamboo
  vars:
    # cette variable doit être définie pour récupérer le fichier de capacité
    - bambooagent_agent_root: "la racine spécifiée de l'agent ou celle par défaut"

  pre_tasks:
    # cela lira le fichier de capacité s'il existe
    - name: Lecture du fichier de capacité de l'agent
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # cela mettra à jour le fichier de capacité et le créera si nécessaire
    - name: Mise à jour du fichier de capacité de l'agent
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  tasks:
    # ... tâches

    - name: 'mettre à jour la capacité'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'capacité_personnalisée_bamboo'
          value: "valeur_capacité_personnalisée_bamboo"
        # ...

Suppression de capacités

Au fil du temps, il est important de pouvoir maintenir les capacités, surtout lorsque le nombre d'agents augmente. En utilisant les mêmes outils que ci-dessus, il est possible de supprimer des capacités devenues obsolètes. Cela peut être fait en indiquant dans la liste bamboo_capabilities_to_remove les noms des capacités qui doivent être supprimées.

- hosts: mes-agents-bamboo
  vars:
    - bambooagent_agent_root: "la racine spécifiée de l'agent ou celle par défaut"

  tasks:
    - name: '[BAMBOO] supprimer les capacités obsolètes'
      set_fact:
        bamboo_capabilities_to_remove:
          - cache_folder1
          - qt_version3

  post_tasks:
    # cela mettra à jour le fichier de capacité et le créera si nécessaire
    - name: Mise à jour du fichier de capacité de l'agent
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

Obtention de l'UUID de l'agent

Le rôle contient un helper dédié pour récupérer l'UUID de l'agent, ce qui facilite la gestion des agents approuvés dans la vue d'administration des agents Bamboo. Cela peut être utilisé comme dans l'exemple suivant, qui remplira la variable bamboo_agent_UUID.

- hosts: mes-agents-bamboo
  vars:
    - bambooagent_agent_root: "la racine spécifiée de l'agent ou celle par défaut"

  tasks:
    - name: Récupère l'UUID de l'agent
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: get_agent_uuid
      tags: ['never', 'bamboo_agent_uuid']

    - name: Affiche l'UUID de l'agent
      debug:
        var: bamboo_agent_UUID
      tags: ['never', 'bamboo_agent_uuid']

Certificat HTTPS pour le service

Le certificat doit être dans la variable certificate_files (une liste de certificats qui sont des paires alias/nom de fichier) comme suit :

- certificate_files:
  - alias: "alias_certificat_serveur_bamboo"
    file: "{{some_root_location}}/bamboo_server_certificate.crt"

Dossier de construction

Le dossier de construction peut être changé après l'installation et l'enregistrement appropriés de l'agent auprès du serveur Bamboo. Cela est particulièrement pertinent dans les scénarios suivants :

• l'agent est installé sur Windows : la longueur des chemins est importante pour la plupart des outils que vous utiliseriez, réduire le préfixe du chemin est essentiel. Il est donc possible d'installer l'agent dans un emplacement, puis de pointer le dossier de construction vers un dossier directement sous la racine d'une partition.
• lorsque vous souhaitez séparer les données de construction des données et de configuration de l'agent : vous pouvez alors utiliser des disques différents (rapides pour le dossier de construction, plus petits pour ceux de l'agent), ou avoir une politique de sauvegarde distincte sur ces dossiers.

Comme mentionné, le dossier de construction ne peut être défini qu'après que l'agent ait été correctement installé et enregistré auprès du serveur Bamboo. Après cela, la structure de dossier correcte et le fichier de configuration apparaissent dans le dossier d'installation et il est possible de changer le dossier de construction.

Un exemple de changement de dossier de construction serait le suivant :

- hosts: agents-windows
  vars:
    - bambooagent_agent_root: "{{ bamboo_agents[inventory_hostname].bamboo_folder }}"

  tasks:
    - name: Mise à jour de la configuration des agents
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: update_agent_configuration
      vars:
        bamboo_agent_name: "nouveau-nom-pour-l-agent"
        bamboo_agent_description: "Agent distant sur XYZ"
        bamboo_build_folder: "D:\\"
        bambooagent_user: "utilisateur_bamboo" # optionnel pour créer le dossier de construction avec les droits appropriés
      tags: ['never', 'update_bamboo_config']

La tâche précédente ne sera pas exécutée sauf spécifiée explicitement sur la ligne de commande. Il est préférable d'arrêter le service avant d'exécuter cette mise à jour. Depuis la ligne de commande, cela peut être réalisé de cette manière, ou entièrement intégré dans un play :

ansible \
  remote-machine-name-or-group \
  -m win_service \
  -a "name=bamboo-remote-agent state=stopped" \
  --inventory inventory-bamboo.yml \
  --become

# nous modifions certains des paramètres d'installation
ansible-playbook \
  --limit remote-machine-name-or-group\
  --inventory inventory-bamboo.yml \
  --become \
  --tags=update_bamboo_config \
  playbooks/my-windows-play.yml

# nous redémarrons à nouveau le service
ansible \
  remote-machine-name-or-group \
  -m win_service \
  -a "name=bamboo-remote-agent state=restarted" \
  --inventory inventory-bamboo.yml \
  --become

Notez que certains des champs mis à jour n'apparaîtront pas sur le serveur. Retirer l'agent du serveur et le réenregistrer ensuite devrait fonctionner (bug connu dans les agents Bamboo).

Dépendances

Aucune dépendance supplémentaire.

Exemple de Playbook

- hosts: bambooagents

  vars:
    - program_location: /dossier/contenant/les/installateurs/
    - server_url: https://my.local.network/bamboo/

    # le dossier personnel de l'agent Bamboo (par exemple, devrait être différent sur Linux/OSX/etc)
    - local_var_bambooagent_install_root: "/somebigdrive/bambooagent"

    # utilisé pour calculer le nom du fichier JAR de l'agent Bamboo à transférer à distance
    - bambooagent_version: "6.8.1"

    # cela pointe vers une copie locale du .jar qui peut être téléchargée depuis le serveur.
    - local_copy_of_bamboo_agent_jar: "/some/folder/{{ bambooagent_jar_filename }}"

  pre_tasks:
    # Lit les capacités si elles existent déjà, sinon retourne un dict vide
    - name: Lecture du fichier de capacité de l'agent
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # Écrit les capacités de nouveau dans le fichier
    - name: Mise à jour des capacités de l'agent
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  roles:
    # Cela installe l'agent bamboo et remplace les variables
    - name: installation de l'agent bamboo
      role: atlassian_bambooagent_role
      vars:
        bambooagent_user: "utilisateur_service_bamboo"
        bambooagent_group: "groupe_service_bamboo"
        bambooagent_agent_root: "/dossier/montant/disque/rapide/bamboo-agent"
        bambooagent_service_name: atlassian-bambooagent
        bamboo_server_url: "{{ server_url }}"
        bamboo_java_jar_file: "{{ local_copy_of_bamboo_agent_jar }}"
        bambooagent_install_root: "{{ local_var_bambooagent_install_root }}"
        certificate_files:
          - alias: "my.certificate.authority.crt"
            file: "/some/local/folder/my.certificate.authority.crt"
      tags: bamboo

  tasks:
    # Exemple de déclaration de capacités personnalisées
    - name: '[BAMBOO] capacités par défaut'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'système_d'exploitation'
          value: "{{ bamboo_operating_system }}"
        - key: nom_de_l_agent
          value: "{{ ansible_fqdn }}"
        - key: version_os
          value: "{{ ansible_distribution_version.split('.')[:2] | join('.') }}"

    # Exemple de déclaration des capacités de constructeur système (binaire python, déjà installé)
    - block:
      - name: '[BAMBOO] exécution de python'
        command: python -c "import sys; print('%d.%d\n%s' % (sys.version_info.major, sys.version_info.minor, sys.executable))"
        register: bamboo_capability_python_version

      - name: '[BAMBOO] enregistrer python'
        set_fact:
          bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
        loop:
          - key: 'système.builder.command.python{{bamboo_capability_python_version.stdout_lines.0}}'
            value: '{{ bamboo_capability_python_version.stdout_lines.1 }}'

Licence

BSD

Informations sur l'auteur

Tous les commentaires concernant Ansible, les demandes de tirage ou les rapports de bogues sont les bienvenus sur le projet Github correspondant.

Journal des modifications

0.1

• première version officielle (pas vraiment, mais les versions précédentes n'avaient pas de journaux de modifications)
• Changement de nom de rôle à atlassian_bambooagent_role pour suivre ces directives
• linting supplémentaire
• nouvelle option bamboo_verify_certificates pour éviter de vérifier le certificat du serveur lors de la récupération du JAR depuis Bamboo. Ceci est utile uniquement sur OSX (voir ici) lorsque le serveur dispose d'un certificat public. Si le serveur utilise sa propre CA, cette CA est déjà installée systématiquement par le rôle.
• maintenant, le service installé sur Windows est pris à partir de la variable bambooagent_service_name (et non le bamboo-remote-agent par défaut). Cela rend possible l'exécution de plusieurs agents sur la même machine Windows.
• correction de bogues sur Windows lors de la récupération du JAR depuis le serveur Bamboo
• correction de bogues lors de l'écriture des capacités (Windows contre le reste du monde)