linkorb.shipyard

ansible-role-shipyard

O Shipyard

Shipyard to narzędzie do zarządzania klastrami Docker swarm i stosami aplikacji z użyciem skryptów Ansible.

Jest inspirowane Helm i helmfile i oferuje podobne koncepcje w środowisku obsługującym swarm, ale nie związanym z Kubernetes.

Koncepcje:

Shipyard Chart: Pakiet definiujący stos docker compose i wszystkie związane pliki (pliki konfiguracyjne, zmienne środowiskowe itp.), podobnie jak Helm Chart, plik RPM yum lub formuła Homebrew. Chart zawiera wszystkie definicje zasobów niezbędne do wdrożenia i uruchomienia aplikacji jako stos Docker Swarm, uporządkowane w określonym układzie. Może być użyty do wdrożenia prostej aplikacji lub pełnego stosu aplikacji webowej z wieloma zależnościami, takimi jak serwery HTTP, bazy danych, pamięci podręczne itp. (podobnie jak Helm Chart)
Shipyard Stack: Instancja Shipyard Chart, dostosowana za pomocą pliku values.yaml. (podobnie jak Helm Release)
shipyard.yaml: Plik definiujący, które Charty wdrożyć oraz jakie wartości użyć na jakich hostach Docker. (podobnie jak plik helmfile.yaml)

Jak widać, koncepcje są bardzo podobne do Helm i helmfile. Główna różnica polega na tym, że Shipyard nie jest specyficzny dla Kubernetes i nie wymaga klastra Kubernetes do działania. Zamiast tego używa Docker Swarm do wdrażania stosów.

Wymagania wstępne

Rola Ansible zakłada, że masz wstępnie skonfigurowane cele (target hosts) z:

Docker Swarm (np. działa docker swarm deploy)
Docker Compose (np. działa docker-compose)
Uwierzytelnianie do pobrania obrazów Docker (np. działa docker pull my-image)

Zmienne roli

Rola może być dostosowana za pomocą kilku opcjonalnych zmiennych:

shipyard_filename: Ścieżka do twojego pliku shipyard.yaml. Domyślnie: {{inventory_path}}/shipyard.yaml. Ten plik może być szablonem Jinja2.
shipyard_charts_path: Ścieżka do katalogu z chartami. Domyślnie: {{inventory_path}}/shipyard/charts
shipyard_stacks_path: Ścieżka do katalogu ze stosami (values.yaml / values.sops.yaml). Domyślnie: {{inventory_path}}/shipyard/stacks
shipyard_stacks_docker_secrets: Lista tajemnic Docker. Domyślnie []
shipyard_tag: opcjonalnie tylko wdrażaj stosy z tym tagiem. Domyślnie: pusty

Użycie

Pobierz rolę z Ansible galaxy

Skonfiguruj plik requirements.yml, aby zawierał rolę:

roles:
  - name: linkorb.shipyard

Następnie uruchom ansible-galaxy install -r requirements.yml, aby zainstalować rolę.

Tworzenie pliku shipyard.yaml:

Plik shipyard.yaml definiuje, które stosy są wdrażane na które hosty. Jest podobny do pliku helmfile.yaml.

# shipyard.yaml
stacks:
  - name: my-traefik
    chart: traefik
    host: swarm-host-a
    values: my-traefik/values.yaml
    tag: lb

  - name: my-whoami
    chart: whoami
    host: swarm-host-a
    values: my-whoami/values.yaml
    tag: apps

  - name: my-mariadb
    chart: mariadb
    host: swarm-host-a
    values: my-mariadb/values.yaml
    tag: db

  - name: my-whoami-b
    chart: whoami
    host: swarm-host-b
    values: my-whoami-b/values.yaml
    tag: apps

Dodanie roli shipyard do swojego playbooka Ansible

W swoim playbooku Ansible (zwykle site.yml), dodaj następujące:

- name: Konfiguracja hosta Docker shipyard
  hosts: my-swarm-hosts # albo grupa hostów - oczekiwane, że są managerami Docker Swarm z skonfigurowanym uwierzytelnianiem do pobierania obrazów
  tags:
    - shipyard # lub jakikolwiek inny tag, którego chcesz użyć do uruchomienia tego playbooka
  roles:
    - role: linkorb.shipyard # rola z ansible galaxy
      vars:
        shipyard_tag: apps

To sprawdzi plik shipyard.yml w katalogu głównym playbooka. Wdrąży do zarządzanych hostów stosy oznaczone tagiem apps, które tam wymieniono.

Tworzenie Charty Shipyard

Struktura katalogu Charty Shipyard:

my-shipyard-chart/
  Chart.yaml # metadane charty
  LICENSE # licencja dla tej charty
  README.md # readme dla tej charty
  values.yaml # domyślne wartości dla tej charty
  templates/ # szablony jinja2 dla tej charty
    docker-compose.yml # szablon pliku docker compose dla tej charty
    example.conf # szablon przykładowego pliku konfiguracyjnego dla tej charty
    env.example # inny szablon przykładowego pliku konfiguracyjnego dla tej charty
    a-directory/ # katalog do skopiowania na docelowy host

Rola Shipyard skopiuje wszystkie pliki i foldery z katalogu templates/ na docelowy host, a następnie wykona szablony z wykorzystaniem wartości Chart i Stacks (zobacz następny rozdział w celu uzyskania dalszych informacji na ten temat).

values.yaml / values.sops.yaml i domyślne wartości charty

Każdy stos (jedna instancja chartu) pobiera plik values zawierający wartości dla tej instancji chartu. Wartości są ładowane z {{shipyard_stacks_path}}/{{stack_name}}/values.yaml. Jeśli wykryty zostanie plik values.sops.yaml, również zostanie załadowany i automatycznie odszyfrowany (na podstawie .sops.yaml w katalogu głównym repozytorium).

Każdy chart zapewnia również domyślne values.yaml. Każda wartość na poziomie stosu, która pozostaje niezdefiniowana, zostanie ustawiona na domyślną wartość chartu.

Kolejność ładowania (i pierwszeństwa nadpisania) jest następująca:

domyślne wartości z chartu
values.yaml ze stosu
values.sops.yaml ze stosu

Specjalne wartości

primed_volumes: lista obiektów informacji o woluminach Docker, które zostaną utworzone dla stosu.

Ta wartość ma znaczenie tylko, gdy Chart to obsługuje.

Każdy obiekt informacji o woluminie ma następujące właściwości:
- name: Nazwa woluminu
- target: Miejsce w kontenerze do zamontowania woluminu
- path: Ścieżka, w katalogu stosu na zdalnym hoście, do rekurencyjnego skopiowania do woluminu.
Na przykład, wolumin zawierający skrypty inicjalizacji bazy danych MariaDB można utworzyć w następujący sposób:
```
# my-stack/values.yaml
primed_volumes:
- name: mariadb_init_data
  target: /docker-entrypoint-initdb.d # tutaj kontener MariaDB szuka danych początkowych
  path: docker-entrypoint-initdb.d # ten katalog jest obecny w katalogu szablonów Chartu
```

Struktura katalogu na hoście docelowym

Na hościach docelowych (menedżerach Docker Swarm) rola utworzy następującą strukturę katalogów:

/opt/shipyard/stacks/
  my-shipyard-stack/
    docker-compose.yml # renderowany plik docker compose
    example.conf # renderowany przykład pliku konfiguracyjnego
    # ... itp.

Wdrażanie stosów do Docker Swarm

Po renderowaniu i zapisaniu szablonów na hoście, rola uruchomi docker stack deploy na hoście docelowym w celu wdrożenia stosu docker swarm.

Przykładowa Charta Shipyard

Zobacz katalog example/shipyard/charts/whoami dla przykładowej Charty Shipyard.

Wkład

Zachęcamy do wnoszenia wkładu, aby uczynić to repozytorium jeszcze lepszym. Czy to poprzez naprawę błędu, dodanie funkcji czy poprawę dokumentacji, twoja pomoc jest bardzo cenna. Aby rozpocząć, zrób forka tego repozytorium, a następnie sklonuj swój fork.

Zanim złożysz jakiekolwiek zmiany, zapoznaj się z Zasadami Wkładu LinkORB dla naszych standardów dotyczących commitów, gałęzi i żądań pull, a także z naszym kodeksem postępowania.

Jeśli nie możesz wdrożyć zmian samodzielnie, nie wahaj się otworzyć nowego zgłoszenia, abyśmy my lub inni mogli się tym zająć.