Rola Ansible Atlassian BambooAgent

Ta rola wykonuje niezbędne kroki do uruchomienia zdalnego agenta Atlassian Bamboo na docelowej maszynie.

Rola wykonuje następujące działania:

• tworzy użytkownika uruchamiającego agenta Bamboo,
• instaluje certyfikat serwera Bamboo, dzięki któremu możliwe jest pobranie pliku jar agenta Bamboo bez pomijania jakichkolwiek zabezpieczeń (opcjonalnie),
• tworzy skrypty startowe dla agenta Bamboo, dodaje dodatkowe ścieżki (narzędzia do budowy) i dodatkowe opcje (np. z systemu, takie jak CUDA_VISIBLE_DEVICES lub dodatkowe konfiguracje agenta Bamboo),
• rejestruje skrypt startowy agenta Bamboo, aby agent uruchamiał się przy starcie systemu,
• rejestruje automatyczną usługę w systemie operacyjnym,
• uzupełnia możliwości agenta,
• zmienia folder budowy i nazwę agenta.

Wymagania

Java powinna być zainstalowana na docelowym systemie operacyjnym. Rozważ użycie roli ansible-atlassian-bambooagent-oracle-java w tym celu.

Zmienne roli

Poniższe zmienne muszą być ustawione dla roli.

Java

Wersja agenta powinna współpracować z zainstalowaną Javą. Na przykład, wersja 5.11 agenta Bamboo wymaga Javy 8. JAVA_HOME jest automatycznie ustawiane w systemie OSX podczas uruchamiania agenta.

Możliwości Bamboo

Specyficzne możliwości mogą być automatycznie zadeklarowane przez agenta, korzystając z funkcji Atlassian Bamboo: pliku możliwości. Ten plik ma bardzo prosty format i znajduje się w folderze instalacyjnym.

Plik możliwości otrzyma możliwości, które są zadeklarowane podczas uruchamiania playbooka. To jest lista par (słownik) wskazujących nazwę możliwości wraz z jej wartością.

- name: '[BAMBOO] deklaracja pustych możliwości'
  set_fact:
    bamboo_capabilities: {}

Można zaktualizować możliwości, najpierw odczytując je z dysku, używając np. pre_task:

pre_tasks:
    - name: Odczyt pliku możliwości agenta
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

a następnie zapisać je na dysku jako np. post_task:

post_tasks:
  - name: Aktualizacja pliku możliwości agenta
    include_role:
      name: atlassian_bambooagent_role
      tasks_from: write_capability

Odczyt i zapis używają słownika bamboo_capabilities (jako fact) jako wejścia/wyjścia. Funkcje dbają o odpowiednie kodowanie / i \ na różnych platformach.

Typowy play w playbooku wyglądałby tak:

- hosts: my-bamboo-agents
  vars:
    # ta zmienna musi być ustawiona, aby pobrać plik możliwości
    - bambooagent_agent_root: "określony folder agenta lub domyślny"

  pre_tasks:
    # to odczyta plik możliwości, jeśli istnieje
    - name: Odczyt pliku możliwości agenta
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # to zaktualizuje plik możliwości i utworzy go, jeśli to konieczne
    - name: Aktualizacja pliku możliwości agenta
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  tasks:
    # ... zadania

    - name: 'aktualizacja możliwości'
      set_fact:
        bamboo_capabilities: "{{ bamboo_capabilities | combine({item.key:item.value}) }}"
      loop:
        - key: 'bamboo_custom_capability'
          value: "bamboo_custom_capability_value"
        # ...

Usuwanie możliwości

Z biegiem czasu umiejętność utrzymania możliwości jest ważna, szczególnie gdy liczba agentów rośnie. Korzystając z tych samych narzędzi, można usunąć możliwości, które stały się nieaktualne. Można to zrobić, wskazując na liście bamboo_capabilities_to_remove nazwy możliwości, które należy usunąć.

- hosts: my-bamboo-agents
  vars:
    - bambooagent_agent_root: "określony folder agenta lub domyślny"

  tasks:
    - name: '[BAMBOO] usunięcie nieaktualnych możliwości'
      set_fact:
        bamboo_capabilities_to_remove:
          - cache_folder1
          - qt_version3

  post_tasks:
    # to zaktualizuje plik możliwości i utworzy go, jeśli to konieczne
    - name: Aktualizacja pliku możliwości agenta
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

Pobieranie UUID agenta

Rola zawiera dedykowaną pomoc do pobierania UUID agenta, co ułatwia zarządzanie zatwierdzonymi agentami w widoku administracyjnym agentów Bamboo. Może to być używane w następującym przykładzie, który wypełni zmienną bamboo_agent_UUID.

- hosts: my-bamboo-agents
  vars:
    - bambooagent_agent_root: "określony folder agenta lub domyślny"

  tasks:
    - name: Pobierz UUID agenta
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: get_agent_uuid
      tags: ['never', 'bamboo_agent_uuid']

    - name: Wyświetl UUID agenta
      debug:
        var: bamboo_agent_UUID
      tags: ['never', 'bamboo_agent_uuid']

Certyfikat HTTPS do usługi

Certyfikat powinien być w zmiennej certificate_files (lista certyfikatów jako par alias/nazwa pliku) jak poniżej:

- certificate_files:
  - alias: "alias_certifikatu_serwera_bamboo"
    file: "{{jakieś_miejsce_katalogu}}/bamboo_server_certificate.crt"

Folder budowy

Folder budowy może być zmieniany po zainstalowaniu i odpowiedniej rejestracji agenta z serwerem Bamboo. Jest to szczególnie istotne w następujących przypadkach:

• agent jest zainstalowany na Windows: długość ścieżek ma znaczenie dla większości narzędzi, które chciałbyś użyć, skrócenie prefiksu ścieżki jest ważne. Możliwe jest zainstalowanie agenta w pewnej lokalizacji, a następnie wskazanie folderu budowy na folder bezpośrednio pod korzeniem partycji.
• gdy chcesz oddzielić dane budowy od danych i konfiguracji agenta: możesz wtedy używać różnych dysków (szybkich dla folderu budowy, mniejszych dla danych agenta), lub mieć oddzielną politykę tworzenia kopii zapasowych na tych folderach.

Jak wspomniano, folder budowy można ustawić tylko po prawidłowej instalacji i rejestracji agenta z serwerem Bamboo. Po tym, w folderze instalacyjnym pojawia się odpowiednia struktura folderu i plik konfiguracyjny, co umożliwia zmianę folderu budowy.

Przykładem zmiany folderu budowy byłoby to:

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

  tasks:
    - name: Aktualizacja konfiguracji agentów
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: update_agent_configuration
      vars:
        bamboo_agent_name: "nowa-nazwa-dla-agenta"
        bamboo_agent_description: "Zdalny agent na XYZ"
        bamboo_build_folder: "D:\\"
        bambooagent_user: "bamboo_user" # opcjonalnie, aby utworzyć folder budowy z odpowiednimi uprawnieniami
      tags: ['never', 'update_bamboo_config']

Poprzednie zadanie nie będzie uruchamiane, chyba że określone explicite w linii poleceń. Lepiej zatrzymać usługę przed uruchomieniem tej aktualizacji. Z linii poleceń można to osiągnąć w ten sposób lub całkowicie zintegrować w play:

ansible \
  nazwa-lub-grupa-maszyny-zdalnej \
  -m win_service \
  -a "name=bamboo-remote-agent state=stopped" \
  --inventory inventory-bamboo.yml \
  --become

# modyfikujemy niektóre ustawienia instalacji
ansible-playbook \
  --limit nazwa-lub-grupa-maszyny-zdalnej\
  --inventory inventory-bamboo.yml \
  --become \
  --tags=update_bamboo_config \
  playbooks/my-windows-play.yml

# ponownie uruchamiamy usługę
ansible \
  nazwa-lub-grupa-maszyny-zdalnej \
  -m win_service \
  -a "name=bamboo-remote-agent state=restarted" \
  --inventory inventory-bamboo.yml \
  --become

Należy zauważyć, że niektóre aktualizowane pola nie będą widoczne na serwerze. Usunięcie agenta z serwera i ponowne zarejestrowanie go powinno to naprawić (znany błąd agenta Bamboo).

Zależności

Brak dodatkowych zależności.

Przykład Playbooka

- hosts: bambooagents

  vars:
    - program_location: /folder/zawierający/instalatory/
    - server_url: https://my.local.network/bamboo/

    # folder domowy agenta Bamboo (na przykład, powinien być inny dla Linux/OSX/etc)
    - local_var_bambooagent_install_root: "/somebigdrive/bambooagent"

    # używany do obliczenia nazwy pliku JAR agenta Bamboo, który będzie przesyłany do zdalnego
    - bambooagent_version: "6.8.1"

    # to wskazuje lokalną kopię pliku .jar, która może być pobrana z serwera.
    - local_copy_of_bamboo_agent_jar: "/some/folder/{{ bambooagent_jar_filename }}"

  pre_tasks:
    # Odczytuje możliwości, jeśli już istnieją, w przeciwnym razie zwraca pusty słownik
    - name: Odczyt pliku możliwości agenta
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: read_capability

  post_tasks:
    # Zapisuje możliwości z powrotem do pliku
    - name: Aktualizuje możliwości agenta
      include_role:
        name: atlassian_bambooagent_role
        tasks_from: write_capability

  roles:
    # Ta rola instaluje agenta Bamboo i nadpisuje zmienne
    - name: instalacja agenta bamboo
      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:
    # Przykład deklarowania niestandardowych możliwości
    - name: '[BAMBOO] domyślne możliwości'
      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('.') }}"

    # Przykład deklarowania możliwości budowy systemu (binarny python, już zainstalowany)
    - block:
      - name: '[BAMBOO] uruchamianie pythona'
        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] rejestracja pythona'
        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 }}'

Licencja

BSD

Informacje o autorze

Jakiekolwiek uwagi dotyczące Ansible, zgłoszenia PR lub błędów są mile widziane z odpowiedniego projektu na GitHubie.

Dziennik zmian

0.1

• pierwsza oficjalna wersja (naprawdę, ale wcześniejsze wydania nie miały dzienników zmian)
• Zmiana nazwy roli na atlassian_bambooagent_role, aby przestrzegać tych wytycznych
• dodatkowe linting
• nowa opcja bamboo_verify_certificates, aby unikać sprawdzania certyfikatu serwera przy pobieraniu JAR z Bamboo. Jest to przydatne tylko w systemie OSX (zobacz tutaj), gdy serwer ma publiczny certyfikat.
• W przypadku, gdy serwer używa własnego CA, ten CA jest już zainstalowany systemowo przez rolę.
• teraz zainstalowana usługa w Windows jest pobierana z zmiennej bambooagent_service_name (a nie domyślnie z bamboo-remote-agent). Umożliwia to uruchomienie kilku agentów na tej samej maszynie z Windows.
• naprawa błędu w systemie Windows podczas pobierania JAR z serwera Bamboo
• naprawa błędu przy zapisywaniu możliwości (Windows vs reszta świata)