ansible-role-shipyard

Über Shipyard

Shipyard ist ein Tool zur Orchestrierung von Docker Swarm Clustern und Stacks aus Ansible Playbooks.

Es ist stark inspiriert von Helm und helmfile und bietet die gleichen Konzepte in einer nicht-Kubernetes, aber Swarm-fähigen Umgebung.

Konzepte:

• Shipyard Chart: Ein Paket, das einen Docker Compose Stack und alle zugehörigen Dateien (Konfigurationsdateien, Umgebungsvariablen usw.) definiert, ähnlich einem Helm Chart, einer yum RPM-Datei oder einer Homebrew-Formel. Ein Chart enthält alle Ressourcendefinitionen, die erforderlich sind, um eine Anwendung als Docker Swarm Stack bereitzustellen und auszuführen, angeordnet in einem bestimmten Layout. Ein Chart kann verwendet werden, um eine einfache Anwendung oder einen vollständigen Webanwendungs-Stack mit mehreren Abhängigkeiten wie HTTP-Servern, Datenbanken, Caches usw. bereitzustellen. (ähnlich wie ein Helm Chart)
• Shipyard Stack: eine Instanz eines Shipyard Charts, die durch eine values.yaml-Datei angepasst wird. (ähnlich einem Helm Release)
• shipyard.yaml: eine Datei, die definiert, welche Charts mit welchen Werten auf welchen Docker-Hosts instanziiert werden sollen. (ähnlich einer helmfile.yaml-Datei)

Wie Sie sehen können, sind die Konzepte sehr ähnlich wie bei Helm und helmfile. Der Hauptunterschied besteht darin, dass Shipyard nicht kubernetes-spezifisch ist und keinen Kubernetes-Cluster zum Ausführen benötigt. Stattdessen verwendet es Docker Swarm, um die Stacks bereitzustellen.

Voraussetzungen

Die Ansible Rolle setzt voraus, dass Sie die Zielhosts mit Folgendem vorkonfiguriert haben:

• Docker Swarm (d.h. docker swarm deploy funktioniert)
• Docker Compose (d.h. docker-compose funktioniert)
• Docker-Pull-Authentifizierung für verwendete Images (d.h. docker pull my-image funktioniert)

Rollenvariablen

Die Rolle kann durch einige optionale Variablen angepasst werden:

• shipyard_filename: Pfad zu Ihrer shipyard.yaml-Datei. Standard: {{inventory_path}}/shipyard.yaml. Diese Datei kann eine Jinja2-Vorlage sein.
• shipyard_charts_path: Pfad zu Ihrem Verzeichnis für Charts. Standard: {{inventory_path}}/shipyard/charts
• shipyard_stacks_path: Pfad zu Ihrem Verzeichnis für Stacks (values.yaml / values.sops.yaml). Standard: {{inventory_path}}/shipyard/stacks
• shipyard_stacks_docker_secrets: Eine Liste von Docker Secrets. Standard []
• shipyard_tag: Optional nur Stacks mit diesem Tag bereitstellen. Standard: leer

Nutzung

Rolle von Ansible Galaxy beziehen

Richten Sie Ihre requirements.yml-Datei so ein, dass die Rolle enthalten ist:

roles:
  - name: linkorb.shipyard

Führen Sie dann ansible-galaxy install -r requirements.yml aus, um die Rolle zu installieren.

Erstellen einer shipyard.yaml-Datei:

Die shipyard.yaml-Datei definiert, welche Stacks auf welchen Hosts bereitgestellt werden. Sie ist ähnlich wie eine helmfile.yaml-Datei.

# 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

Hinzufügen der Shipyard-Rolle zu Ihrem Ansible-Playbook

Fügen Sie in Ihrem Ansible-Playbook (normalerweise site.yml) Folgendes hinzu:

- name: Docker Shipyard Host-Konfiguration
  hosts: my-swarm-hosts # oder eine Gruppe von Hosts - erwartet, dass es sich um Docker Swarm-Manager handelt, die mit Docker-Image-Pull-Authentifizierung konfiguriert sind
  tags:
    - shipyard # oder ein anderer Tag, den Sie verwenden möchten, um dieses Playbook auszuführen
  roles:
    - role: linkorb.shipyard # die Rolle von Ansible Galaxy
      vars:
        shipyard_tag: apps

Dies sucht nach der shipyard.yaml-Datei im Stammverzeichnis des Playbook-Verzeichnisses. Es wird die Stacks bereitstellen, die im Managed Hosts mit dem Tag apps aufgeführt sind.

Erstellen eines Shipyard Charts

Verzeichnisstruktur eines Shipyard Charts:

my-shipyard-chart/
  Chart.yaml # die Chart-Metadaten
  LICENSE # die Lizenz für dieses Chart
  README.md # das README für dieses Chart
  values.yaml # die Standardwerte für dieses Chart
  templates/ # die Jinja2-Vorlagen für dieses Chart
    docker-compose.yml # die Docker Compose-Vorlagendatei für dieses Chart
    example.conf # eine Beispiel-Konfigurationsvorlagendatei für dieses Chart
    env.example # eine weitere Beispiel-Konfigurationsvorlagendatei für dieses Chart
    a-directory/ # ein Verzeichnis, das auf den Zielhost kopiert werden soll

Die Shipyard-Rolle wird alle Dateien und Ordner im Verzeichnis templates/ auf den Zielhost kopieren und dann die Dateien mithilfe der Chart- und Stackwerte rendern (siehe nächsten Abschnitt für weitere Informationen dazu).

values.yaml / values.sops.yaml und Standardwerte des Charts

Jeder Stack (eine Instanz eines Charts) benötigt eine Values-Datei, die die Werte für diese Instanz des Charts enthält. Die Werte werden aus {{shipyard_stacks_path}}/{{stack_name}}/values.yaml geladen. Wenn eine values.sops.yaml erkannt wird, wird sie ebenfalls automatisch geladen und entschlüsselt (basierend auf der .sops.yaml im Stammverzeichnis Ihres Repos).

Jedes Chart bietet auch eine standardmäßige values.yaml. Jeder Wert auf Stack-Ebene, der undefiniert bleibt, wird auf den Standardwert des Charts gesetzt.

Die Lade- (und Überschreibreihenfolge) ist:

1. die Standardwerte aus dem Chart
2. die values.yaml aus dem Stack
3. die values.sops.yaml aus dem Stack

Besondere Werte

• primed_volumes: eine Liste von Docker-Volume-Info-Objekten, die für den Stack erstellt werden.

  Dieser Wert ist nur sinnvoll, wenn ein Chart dies unterstützt.

  Jedes Volume-Info-Objekt hat die folgenden Eigenschaften:

  • name: Der Name des Volumes
  • target: Der Ort im Container, um das Volume zu mounten
  • path: Der Pfad, unter dem Stack-Pfad auf dem Remote-Host, der rekursiv in das Volume kopiert werden soll.

  Zum Beispiel kann ein Volume, das Initialisierungsskripte für die MariaDB-Datenbank enthält, wie folgt erstellt werden:

  # my-stack/values.yaml
  primed_volumes:
  - name: mariadb_init_data
    target: /docker-entrypoint-initdb.d # hier sucht der MariaDB-Container nach Init-Daten
    path: docker-entrypoint-initdb.d # dieses Verzeichnis befindet sich im Chart-templates/-Verzeichnis
  

Verzeichnisstruktur für Zielhosts

Auf den Zielhosts (Docker Swarm-Manager) wird die Rolle die folgende Verzeichnisstruktur erstellen:

/opt/shipyard/stacks/
  my-shipyard-stack/
    docker-compose.yml # die gerenderte Docker-Compose-Datei
    example.conf # die gerenderte Beispiel-Konfigurationsdatei
    # ... usw.

Bereitstellung der Stacks auf Docker Swarm

Nachdem die Vorlagen gerendert und auf den Host geschrieben wurden, führt die Rolle docker stack deploy auf dem Zielhost aus, um den Docker Swarm Stack bereitzustellen.

Beispiel Shipyard Chart

Siehe das example/shipyard/charts/whoami Verzeichnis für ein Beispiel für ein Shipyard Chart.

Beitrag

Wir begrüßen Beiträge, um dieses Repository noch besser zu machen. Ob es nun darum geht, einen Fehler zu beheben, eine Funktion hinzuzufügen oder die Dokumentation zu verbessern, Ihre Hilfe wird sehr geschätzt. Um zu beginnen, forken Sie dieses Repository und klonen Sie Ihren Fork.

Bitte machen Sie sich mit den Beitragsrichtlinien von LinkORB vertraut, um unsere Standards für Commits, Branches und Pull-Requests sowie unseren Verhaltenskodex zu verstehen, bevor Sie Änderungen einreichen.

Wenn Sie nicht in der Lage sind, Änderungen selbst zu implementieren, zögern Sie nicht, einen neuen Issue-Report zu eröffnen, damit wir oder andere sich darum kümmern können.

Bereitgestellt vom LinkORB Engineering-Team

Schauen Sie sich unsere anderen Projekte auf linkorb.com/engineering an. Übrigens, wir stellen ein!