ansible-role-shipyard

Shipyardについて

Shipyardは、AnsibleプレイブックからDocker Swarmクラスタとスタックを管理するためのツールです。

これは、Helmやhelmfileに強く影響を受けており、KubernetesではなくSwarm対応の環境で同様の概念を提供します。

概念:

• Shipyardチャート: Docker Composeスタックとその関連ファイル（設定ファイル、環境変数など）を定義するパッケージで、Helmチャート、YUM RPMファイル、Homebrewフォーミュラに似ています。チャートは、Docker Swarmスタックとしてアプリケーションを展開および実行するために必要なすべてのリソース定義を特定のレイアウトで含むものです。チャートは、単純なアプリケーションを展開するために使用されたり、HTTPサーバー、データベース、キャッシュなどの複数の依存関係を持つ完全なWebアプリケーションスタックを展開するために使用されたりします。（Helmチャートに似ています）
• Shipyardスタック: values.yamlファイルを通じてカスタマイズされたShipyardチャートのインスタンスです。（Helmリリースに似ています）
• shipyard.yaml: どのチャートをどの値でどのDockerホストに展開するかを定義するファイルです。（helmfile.yamlファイルに似ています）

ご覧のように、これらの概念はHelmおよびhelmfileに非常に似ています。主な違いは、ShipyardがKubernetes固有ではなく、Kubernetesクラスターを必要としないことです。代わりに、スタックを展開するためにDocker Swarmを使用します。

前提条件

Ansibleロールは、ターゲットホストが以下で事前に設定されていることを前提としています：

• Docker Swarm（つまり、docker swarm deployが動作すること）
• Docker Compose（つまり、docker-composeが動作すること）
• 使用するイメージのDockerプル認証（つまり、docker pull my-imageが動作すること）

ロール変数

ロールは、いくつかの任意の変数でカスタマイズできます：

• shipyard_filename: shipyard.yamlファイルへのパス。デフォルト: {{inventory_path}}/shipyard.yaml。このファイルはJinja2テンプレートであることができます。
• shipyard_charts_path: チャートディレクトリへのパス。デフォルト: {{inventory_path}}/shipyard/charts
• shipyard_stacks_path: スタック（values.yaml / values.sops.yaml）ディレクトリへのパス。デフォルト: {{inventory_path}}/shipyard/stacks
• shipyard_stacks_docker_secrets: Docker Secretsのリスト。デフォルト []
• shipyard_tag: オプションで、このタグを持つスタックのみを展開します。デフォルト: 空

使用法

Ansible Galaxyからロールを取得

requirements.ymlファイルにロールを含めるように設定します：

roles:
  - name: linkorb.shipyard

その後、ansible-galaxy install -r requirements.ymlを実行してロールをインストールします。

shipyard.yamlファイルの作成：

shipyard.yamlファイルは、どのスタックがどのホストに展開されるかを定義します。これは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

AnsibleプレイブックにShipyardロールを追加

Ansibleプレイブック（通常はsite.yml）に以下を追加します：

- name: Docker shipyard host configuration
  hosts: my-swarm-hosts # またはホストのグループ - Dockerイメージプル認証が設定されたDocker Swarmマネージャーである必要があります
  tags:
    - shipyard # またはこのプレイブックを実行するために使用したい他のタグ
  roles:
    - role: linkorb.shipyard # Ansible Galaxyからのロール
      vars:
        shipyard_tag: apps

これにより、プレイブックディレクトリのルートにあるshipyard.yamlファイルが検索されます。 それに記載されたappsタグのスタックが管理ホストに展開されます。

Shipyardチャートの作成

Shipyardチャートのディレクトリ構造：

my-shipyard-chart/
  Chart.yaml # チャートのメタデータ
  LICENSE # このチャートのライセンス
  README.md # このチャートのREADME
  values.yaml # このチャートのデフォルト値
  templates/ # このチャートのJinja2テンプレート
    docker-compose.yml # このチャートのDocker Composeテンプレートファイル
    example.conf # このチャートの例の設定ファイルテンプレート
    env.example # このチャートの別の例の設定ファイルテンプレート
    a-directory/ # ターゲットホストにコピーされるディレクトリ

Shipyardロールは、templates/ディレクトリ内のすべてのファイルとフォルダをターゲットホストにコピーし、その後、チャートおよびスタックの値を使用してファイルをレンダリングします（詳細は次のセクションを参照）。

values.yaml / values.sops.yamlとチャートのデフォルト値

すべてのスタック（チャートのインスタンスの1つ）は、そのインスタンスの値を含む値ファイルを持ちます。 値は、{{shipyard_stacks_path}}/{{stack_name}}/values.yamlからロードされます。values.sops.yamlが検出されると、それも自動的にロードされて復号化されます（あなたのリポジトリのルートにある.sops.yamlに基づいて）。

すべてのチャートはデフォルトのvalues.yamlを提供します。未定義のスタックレベルの値は、チャートのデフォルト値に設定されます。

ロード（および上書きの優先順位）順序は次のとおりです：

1. チャートのデフォルト値
2. スタックからのvalues.yaml
3. スタックからのvalues.sops.yaml

特別な値

• primed_volumes: スタックのために作成されるDockerボリューム情報オブジェクトのリスト。

  この値は、チャートがそれをサポートしている場合にのみ意味があります。

  各ボリューム情報オブジェクトは、以下のプロパティを持っています：

  • name: ボリュームの名前
  • target: コンテナ内でボリュームをマウントする場所
  • path: リモートホスト上のスタックパスの下に再帰的にコピーするためのパス。

  例えば、MariaDBデータベース初期化スクリプトを含むボリュームを次のように作成できます：

  # my-stack/values.yaml
  primed_volumes:
  - name: mariadb_init_data
    target: /docker-entrypoint-initdb.d # これはMariaDBコンテナが初期データを探す場所
    path: docker-entrypoint-initdb.d # このディレクトリはチャートのtemplates/ディレクトリに存在します
  

ターゲットホストのディレクトリ構造

ターゲットホスト（Docker Swarmマネージャー）上で、ロールは以下のディレクトリ構造を作成します：

/opt/shipyard/stacks/
  my-shipyard-stack/
    docker-compose.yml # レンダリングされたDocker Composeファイル
    example.conf # レンダリングされた例の設定ファイル
    # ...など

Docker Swarmへのスタックのデプロイ

テンプレートがレンダリングされ、ホストに書き込まれた後、ロールはターゲットホストでdocker stack deployを実行してDocker Swarmスタックをデプロイします。

例のShipyardチャート

例のShipyardチャートについては、example/shipyard/charts/whoamiディレクトリを参照してください。

貢献

このリポジトリをさらに良くするための貢献を歓迎します。バグの修正、機能の追加、ドキュメントの改善など、あなたの助けは非常に感謝されます。始めるには、このリポジトリをフォークしてからフォークをクローンしてください。

変更を提出する前に、私たちのコミット、ブランチ、プルリクエストに関する基準が含まれたLinkORBの貢献ガイドラインや行動規範をよく読んでください。

ご自身で好みの変更を実装できない場合は、新しい課題を開いて、私たちや他の人が対処できるようにしてください。

LinkORBエンジニアリングチームから提供されています

私たちの他のプロジェクトをlinkorb.com/engineeringでチェックしてください。 ちなみに、私たちは人材を募集しています！