Ansible Atlassian BambooAgent Rolle

Diese Rolle führt die notwendigen Schritte aus, um einen Atlassian Bamboo Remote-Agenten auf einer Zielmaschine auszuführen.

Die Rolle führt folgende Aktionen aus:

• Erstellt den Benutzer, der den Bamboo-Agenten betreibt,
• Installiert das Zertifikat des Bamboo-Servers, sodass es möglich ist, die jar-Datei des Bamboo-Agenten direkt vom Server herunterzuladen, ohne Sicherheitsmaßnahmen zu umgehen (optional).
• Erstellt die Startskripte für den Bamboo-Agenten, fügt zusätzliche Pfade (Build-Tools) und zusätzliche Optionen hinzu (entweder vom System wie CUDA_VISIBLE_DEVICES oder zusätzliche Bamboo-Agent-Konfigurationen).
• Registriert das Startskript des Bamboo-Agenten, um den Agenten beim Booten zu starten.
• Registriert einen Autostartdienst im Betriebssystem.
• Füllt die Fähigkeiten des Agenten aus.
• Ändert den Build-Ordner und den Namen des Agenten.

Anforderungen

Java sollte auf dem Zielbetriebssystem installiert sein. Ziehen Sie in Betracht, die Rolle ansible-atlassian-bambooagent-oracle-java dafür zu verwenden.

Rollenvariablen

Die folgenden Variablen müssen für die Rolle gesetzt werden.

Java

Die Version des Agenten sollte gut mit dem installierten Java funktionieren. Zum Beispiel benötigt die Version 5.11 des Bamboo-Agenten Java 8. JAVA_HOME wird automatisch während des Starts des Agenten auf OSX gesetzt.

Bamboo-Fähigkeit

Spezifische Fähigkeiten können automatisch durch den Agenten mithilfe einer Funktion von Atlassian Bamboo erklärt werden: der Fähigkeitsdatei. Diese Datei hat ein einfaches Format und befindet sich im Installationsordner.

Die Fähigkeits-Datei erhält die Fähigkeiten, die durch das Ausführen des Playbooks erklärt werden. Dies ist eine Liste von Paaren (Wörterbuch), die den Namen der Fähigkeit zusammen mit ihrem Wert angeben.

- name: '[BAMBOO] leere Fähigkeitsdeklaration'
  set_fact:
    bamboo_capabilities: {}

Es ist möglich, die Fähigkeiten zunächst zu aktualisieren, indem man diese von der Festplatte liest, z.B. mit einer pre_task:

pre_tasks:
    - name: Lesen der Fähigkeitsdatei des Agenten
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

Und dann sie auf der Festplatte zu schreiben, z.B. in einer post_task:

post_tasks:
  - name: Aktualisierung der Fähigkeitsdatei des Agenten
    include_role:
      name: atlassian_bambooagent_role
      tasks_from: write_capability

Das Lesen und Schreiben verwenden beide das Wörterbuch bamboo_capabilities (als fact) als Eingabe/Ausgabe. Die Funktionen kümmern sich um die richtige Escape-Behandlung von / und \ auf den verschiedenen Plattformen.

Ein typisches Play in einem Playbuch würde so aussehen:

- hosts: my-bamboo-agents
  vars:
    # Diese Variable muss gesetzt werden, um die Fähigkeitsdatei abzurufen
    - bambooagent_agent_root: "der angegebene Agentenstamm oder der Standard"

  pre_tasks:
    # Das wird die Fähigkeitsdatei lesen, wenn sie existiert
    - name: Lesen der Fähigkeitsdatei des Agenten
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # Das wird die Fähigkeitsdatei aktualisieren und erstellen, wenn sie benötigt wird
    - name: Aktualisierung der Fähigkeitsdatei des Agenten
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  tasks:
    # ... Aufgaben

    - name: 'Fähigkeit aktualisieren'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'bamboo_custom_capability'
          value: "bamboo_custom_capability_value"
        # ...

Fähigkeiten entfernen

Im Laufe der Zeit ist es wichtig, die Fähigkeiten zu pflegen, insbesondere wenn die Anzahl der Agenten steigt. Mit denselben Tools wie oben ist es möglich, Fähigkeiten zu entfernen, die veraltet sind. Dies kann durch Angabe der Namen der Fähigkeiten, die entfernt werden sollen, in der Liste bamboo_capabilities_to_remove erfolgen.

- hosts: my-bamboo-agents
  vars:
    - bambooagent_agent_root: "der angegebene Agentenstamm oder der Standard"

  tasks:
    - name: '[BAMBOO] veraltete Fähigkeiten entfernen'
      set_fact:
        bamboo_capabilities_to_remove:
          - cache_folder1
          - qt_version3

  post_tasks:
    # Das wird die Fähigkeitsdatei aktualisieren und erstellen, wenn sie benötigt wird
    - name: Aktualisierung der Fähigkeitsdatei des Agenten
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

Abrufen der Agenten-UUID

Die Rolle enthält einen speziellen Helfer zum Abrufen der UUID des Agenten, der die Verwaltung der genehmigten Agenten in der Admin-Ansicht der Bamboo-Agenten erleichtert. Dies kann wie im folgenden Beispiel verwendet werden, das die Variable bamboo_agent_UUID füllt.

- hosts: my-bamboo-agents
  vars:
    - bambooagent_agent_root: "der angegebene Agentenstamm oder der Standard"

  tasks:
    - name: Abrufen der Agenten-UUID
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: get_agent_uuid
      tags: ['never', 'bamboo_agent_uuid']

    - name: Ausgabe der Agenten-UUID
      debug:
        var: bamboo_agent_UUID
      tags: ['never', 'bamboo_agent_uuid']

HTTPS-Zertifikat für den Dienst

Das Zertifikat sollte in der Variablen certificate_files (eine Liste von Zertifikaten, die Alias/Namenpaare sind) wie folgt sein:

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

Build-Ordner

Der Build-Ordner kann nach der Installation und ordnungsgemäßen Registrierung des Agenten beim Bamboo-Server geändert werden. Dies ist besonders relevant in folgenden Szenarien:

• Der Agent wird unter Windows installiert: Die Länge der Pfade ist für die meisten der verwendeten Tools wichtig, eine Verkürzung des Pfadpräfixes ist wichtig. Es ist dann möglich, den Agenten an einem Speicherort zu installieren und dann den Build-Ordner auf einen Ordner direkt unter dem Stamm eines Laufwerks zu verweisen.
• Wenn Sie die Build-Daten von den Daten und Konfigurationen des Agenten trennen möchten: Sie können dann unterschiedliche Festplatten verwenden (schnelle für den Build-Ordner, kleinere für die des Agenten) oder eine separate Backup-Policy für diese Ordner haben.

Wie bereits erwähnt, kann der Build-Ordner nur geändert werden, nachdem der Agent ordnungsgemäß installiert und beim Bamboo-Server registriert wurde. Danach erscheinen die korrekte Ordnerstruktur und die Konfigurationsdatei im Installationsordner, und es ist möglich, den Build-Ordner zu ändern.

Ein Beispiel für die Änderung des Build-Ordners wäre dies:

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

  tasks:
    - name: Aktualisierung der Konfiguration der Agenten
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: update_agent_configuration
      vars:
        bamboo_agent_name: "neuer-name-für-den-agent"
        bamboo_agent_description: "Remote-Agent bei XYZ"
        bamboo_build_folder: "D:\\"
        bambooagent_user: "bamboo_user" # optional, um den Build-Ordner mit den richtigen Berechtigungen zu erstellen
      tags: ['never', 'update_bamboo_config']

Die vorherige Aufgabe wird nicht ausgeführt, es sei denn, sie wird explizit über die Befehlszeile angegeben. Es ist besser, den Dienst vor der Durchführung dieses Updates zu stoppen. Dies kann über die Befehlszeile erreicht werden, oder vollständig in ein Play integriert werden.

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

# Wir ändern einige der Installationsparameter
ansible-playbook \
  --limit remote-machine-name-or-group\
  --inventory inventory-bamboo.yml \
  --become \
  --tags=update_bamboo_config \
  playbooks/my-windows-play.yml

# Wir starten den Dienst erneut
ansible \
  remote-machine-name-or-group \
  -m win_service \
  -a "name=bamboo-remote-agent state=restarted" \
  --inventory inventory-bamboo.yml \
  --become

Beachten Sie, dass einige der aktualisierten Felder nicht auf dem Server angezeigt werden. Das Entfernen des Agenten vom Server und die anschließende erneute Registrierung sollten dies beheben (bekannter Fehler bei Bamboo-Agenten).

Abhängigkeiten

Keine zusätzlichen Abhängigkeiten.

Beispiel Playbook

- hosts: bambooagents

  vars:
    - program_location: /folder/containing/installers/
    - server_url: https://my.local.network/bamboo/

    # Der Heimatordner des Bamboo-Agenten (z.B. sollte auf Linux/OSX/etc. unterschiedlich sein)
    - local_var_bambooagent_install_root: "/somebigdrive/bambooagent"

    # Wird verwendet, um den Namen der JAR-Datei des Bamboo-Agenten zu berechnen, die an die Remote-Instanz übertragen werden soll.
    - bambooagent_version: "6.8.1"

    # Dies verweist auf eine lokale Kopie der .jar, die vom Server heruntergeladen werden kann.
    - local_copy_of_bamboo_agent_jar: "/some/folder/{{ bambooagent_jar_filename }}"

  pre_tasks:
    # Liest Fähigkeiten, wenn sie bereits existieren, andernfalls gibt sie ein leeres Dictionary zurück.
    - name: Lesen der Fähigkeitsdatei des Agenten
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # Schreibt die Fähigkeiten zurück in die Datei
    - name: Aktualisiert die Fähigkeiten des Agenten
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  roles:
    # Diese Rolle installiert den Bamboo-Agenten und überschreibt die Variablen.
    - name: Installation des Bamboo-Agenten
      role: atlassian_bambooagent_role
      vars:
        bambooagent_user: "bamboo_service_user"
        bambooagent_group: "bamboo_service_group"
        bambooagent_agent_root: "/mount/folder/fast/disk/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:
    # Beispiel zur Deklaration benutzerdefinierter Fähigkeiten
    - name: '[BAMBOO] Standardfähigkeiten'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'operating_system'
          value: "{{ bamboo_operating_system }}"
        - key: agent_name
          value: "{{ ansible_fqdn }}"
        - key: osversion
          value: "{{ ansible_distribution_version.split('.')[:2] | join('.') }}"

    # Beispiel für die Deklaration von Systembuilderfähigkeiten (Python-Binärdatei, bereits installiert)
    - block:
      - name: '[BAMBOO] Ausführung von 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] registriere Python'
        set_fact:
          bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
        loop:
          - key: 'system.builder.command.python{{bamboo_capability_python_version.stdout_lines.0}}'
            value: '{{ bamboo_capability_python_version.stdout_lines.1 }}'

Lizenz

BSD

Autoreninformationen

Kommentare zu Ansible, PR oder Fehlerberichte sind willkommen im entsprechenden Github-Projekt.

Änderungsprotokoll

0.1

• erste offizielle Version (nicht wirklich, aber frühere Versionen hatten keine Änderungsprotokolle)
• Ändern des Rollennamens in atlassian_bambooagent_role, um diesen Richtlinien zu folgen.
• zusätzliche Linting
• neue Option bamboo_verify_certificates, um die Überprüfung des Serverzertifikats beim Abrufen der JAR aus Bamboo zu vermeiden. Dies ist nur auf OSX nützlich (siehe hier), wenn der Server ein öffentliches Zertifikat hat. Falls der Server seine eigene CA verwendet, ist diese CA bereits systemweit durch die Rolle installiert.
• jetzt wird der installierte Dienst auf Windows aus der Variable bambooagent_service_name abgerufen (und nicht aus dem Standard bamboo-remote-agent). Dies ermöglicht die Ausführung mehrerer Agenten auf derselben Windows-Maschine.
• Fehlerbehebung bei Windows beim Abrufen der JAR vom Bamboo-Server.
• Fehlerbehebung beim Schreiben der Fähigkeiten (Windows vs. der Rest der Welt).