nickjj.docker

ansible-dockerとは？

これは、以下の機能を持つAnsibleロールです：

• Dockerをインストールする（エディション、チャンネル、バージョンの固定に対応）
• Docker Compose v2および/またはDocker Compose v1をインストールする（バージョンの固定に対応）
• Ansibleのdocker_*モジュールが動作するために、dockerのPIPパッケージをインストールする
• Dockerレジストリのログイン認証情報を管理する
• ルートアクセスなしでDockerを実行できるユーザーを1人以上設定する
• Dockerデーモンのオプションや環境変数を設定する
• Dockerのクリーンアップコマンドを実行するためのcronジョブを設定する

なぜこのロールを使いたいのか？

私のようにDockerが好きな人にとって、このロールは本番環境に適したDockerホストを始めるために必要なすべてを提供します。

ちなみに、Dockerとは何か知らない、または専門家になりたい場合は、Dockerに飛び込もう: 開発者のための完全なDockerコースをチェックしてください。

サポートされているプラットフォーム

• Ubuntu 20.04 LTS (Focal Fossa)
• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Debian 11 (Bullseye)
• Debian 12 (Bookworm)

以前のリリースは動作するかもしれませんが、公式にはサポートされていません。

これはマスターブランチのドキュメントです。最新のリリースを見るには、最新のリリースに切り替えてください。

クイックスタート

私のすべてのロールの理念は、簡単に始められるようにすることですが、ほとんどすべてをカスタマイズする手段を提供することです。

デフォルトで設定されているものは？

最新の安定版Docker CEとDocker Compose v2がインストールされ、Dockerのディスククリーンアップが毎週行われ、Dockerコンテナのログがjournaldに送信されます。

例のプレイブック

---

# docker.yml

- name: 例
  hosts: "all"
  become: true

  roles:
    - role: "nickjj.docker"
      tags: ["docker"]

使用法: ansible-playbook docker.yml

インストール

$ ansible-galaxy install nickjj.docker

デフォルトのロール変数

Dockerのインストール

チャンネル

「stable」または「test」チャンネルを使用しますか？複数選択が可能（順序も重要です）。

docker__channel: ["stable"]

バージョン

• 空に設定すると、最新のDockerがインストールされます
• 特定のバージョンを設定すると、そのバージョンがインストールされ固定されます

docker__version: ""

# 例えば、25.0に固定する場合。
docker__version: "25.0"

# より正確なバージョン25.0.5に固定する場合。
docker__version: "25.0.5"

バージョンの末尾に*を付けることで、マイナーバージョンやセキュリティパッチが適用されます。

アップグレード戦略

• "present"に設定すると、将来このロールを実行しても新しいバージョン（利用可能な場合）はインストールされません
• "latest"に設定すると、将来このロールを実行すると新しいバージョン（利用可能な場合）がインストールされます

docker__state: "present"

ダウングレード戦略

ダウングレードする最も簡単な方法は、Dockerパッケージを手動でアンインストールし、その後に固定したい特定のDockerバージョンを持つロールを実行することです。

# すべてのホストでDocker CEパッケージを停止し削除するアドホックAnsibleコマンド。
ansible all -m systemd -a "name=docker-ce state=stopped" \
  -m apt -a "name=docker-ce autoremove=true purge=true state=absent" -b

Docker Compose v2のインストール

Docker Compose v2は、Dockerが管理する公式のdocker-compose-pluginを使ってaptでインストールされます。

バージョン

• 空に設定すると、最新のDocker Compose v2がインストールされます
• 特定のバージョンを設定すると、そのバージョンがインストールされ固定されます

docker__compose_v2_version: ""

# 例えば、2.29に固定する場合。
docker__compose_v2_version: "2.29"

# より正確なバージョン2.29.1に固定する場合。
docker__compose_v2_version: "2.29.1"

アップグレード戦略

Dockerセクションのdocker__state変数と同じルールを再利用します。

ダウングレード戦略

Docker本体同様、Docker Compose v2のアンインストールは手動でコマンドを実行し、その後特定のDocker Compose v2バージョンを固定するのが最も簡単です。

# すべてのホストでDocker Compose Pluginパッケージを削除するアドホックAnsibleコマンド。
ansible all -m apt -a "name=docker-compose-plugin autoremove=true purge=true state=absent" -b

Docker Compose v1のインストール

デフォルトでは、このロールはDocker Compose v1をインストールしません。これは公式に廃止され、Dockerからの更新が行われていないためです。しかし、このロールではインストールが可能です。インストールしたい場合は、docker__pip_docker_compose_state: "present"を設定してください。この値のデフォルトはabsentです。

技術的には、v1はdocker-composeで、v2はdocker compose（ハイフンなし）でアクセスされるため、両バージョンを同時にインストールすることができます。

レガシーな目的以外では、v1をインストールすることはお勧めしません。インストールする場合は、以下でインストールするバージョンを設定できます。

バージョン

• 空に設定すると、最新のDocker Compose v1がインストールされます
• 特定のバージョンを設定すると、そのバージョンがインストールされ固定されます

docker__compose_version: ""

# 例えば、1.29に固定する場合。
docker__compose_version: "1.29"

# より正確なバージョン1.29.2に固定する場合。
docker__compose_version: "1.29.2"

アップグレードとダウングレードの戦略は、このREADMEの他のセクションで説明します。

ルートなしでDockerを実行するためのユーザー設定

dockerグループに追加するユーザーのリスト。

このユーザーはすでに存在する必要があります。このロールはユーザーを作成しません。ユーザーを作成したい場合は、私のuser roleをチェックしてください。

このロールは、デフォルトでユーザーネームスペースや他のセキュリティ機能を設定しません。ここで追加したユーザーがサーバーにSSHアクセスできる場合、そのユーザーはsudoなしでDockerを実行できるため、実質的にサーバーへのルートアクセスを与えることになります。

管理された環境では安全ですが、セキュリティ関連のことは前もって理解しておくことが重要です。ユーザーネームスペースや他のオプションは、後述のdocker__daemon_json変数を使用して有効にできます。

# デフォルトではsudoユーザーを使用し、存在しない場合はrootにフォールバックします。
docker__users: ["{{ ansible_env.SUDO_USER | d('root') }}"]

# 例えば、設定したいユーザーがsudoユーザーとは異なる場合。
docker__users: ["admin"]

Dockerレジストリのログイン設定

1つまたは複数のDockerレジストリ（例：Docker Hubなど）にログインします。

# あなたのログイン認証情報はこのユーザーのホームディレクトリに保管されます。
docker__login_become_user: "{{ docker__users | first | d('root') }}"

# ログインするレジストリの数は0以上。
docker__registries:
  - #registry_url: "https://index.docker.io/v1/"
    username: "your_docker_hub_username"
    password: "your_docker_hub_password"
    #email: "[email protected]"
    #reauthorize: false
    #config_path: "$HOME/.docker/config.json"
    #state: "present"
docker__registries: []

アスタリスク付きのプロパティは必須です。

• registry_urlのデフォルトはhttps://index.docker.io/v1/
• *usernameはあなたのDockerレジストリのユーザー名です
• *passwordはあなたのDockerレジストリのパスワードです
• emailはデフォルトでは使用されません（すべてのレジストリが使用するわけではありません）
• reauthorizeはデフォルトでfalseです。trueにすると認証情報が更新されます
• config_pathはデフォルトであなたのdocker__login_become_userの$HOMEディレクトリです
• stateはデフォルトで"present"です。"absent"にするとログインが削除されます

Dockerデーモンオプションの設定（json）

デフォルトのDockerデーモンオプションは/etc/docker/daemon.jsonに表示されます。

docker__default_daemon_json: |
  "log-driver": "journald",
  "features": {
    "buildkit": true
  }

# デフォルトのオプションを上書きせずに独自のオプションを追加できます。
# フォーマットはデフォルトのオプションと同じですので、カンマで始める心配はありません。テンプレートが必要に応じてカンマを追加します。
docker__daemon_json: ""

Dockerデーモンオプションの設定（フラグ）

Dockerデーモンを起動する際に設定されたフラグは、daemon.jsonファイルでは変更できません。デフォルトではDockerが-H unix://を設定しているため、このオプションはjsonオプションでは変更できません。

Dockerデーモンフラグを、コマンドライン上に現れる状態で正確に指定することで追加または変更できます。

# 各コマンドラインフラグはリスト内の各項目として指定する必要があります。
#
# Dockerを18.09以前のバージョンを使用していますか？
#   `-H unix://`の代わりに`-H fd://`を設定する必要があります。
docker__daemon_flags:
  - "-H unix://"

ここで何らかの-Hフラグを指定しない場合、Dockerは起動に失敗します。

Dockerデーモンの環境変数の設定

docker__daemon_environment: []

# 例えば、プロキシ環境変数を設定する方法。
docker__daemon_environment:
  - "HTTP_PROXY=http://proxy.example.com:80"
  - "HTTPS_PROXY=https://proxy.example.com:443"

高度なsystemdディレクティブの設定

このロールは、Dockerパッケージが自分自身のsystemdユニットファイルを管理できるようにし、Dockerデーモンのフラグや環境変数をsystemdオーバーライドパターンを使って調整します。

自分のやり方が分かっている場合は、この変数を設定することでDockerのsystemdディレクティブのオーバーライドや追加を行うことができます。ここに入力した内容は、そのまま/etc/systemd/system/docker.service.d/custom.confに書き込まれます。

docker__systemd_override: ""

Docker関連のcronジョブの設定

デフォルトでは、毎週日曜日の真夜中にDockerが使用するディスクスペースのクリーンアップが安全に行われます。

# `a`は使用されていないイメージを削除します（本番環境で便利）。
# `f`は、確認のためのプロンプトなしで強制的に実行します。
docker__cron_jobs_prune_flags: "af"

# dockerのシステムプルーンのスケジュールを制御します。
docker__cron_jobs_prune_schedule: ["0", "0", "*", "*", "0"]

docker__cron_jobs:
  - name: "Dockerディスククリーンアップ"
    job: "docker system prune -{{ docker__cron_jobs_prune_flags }} > /dev/null 2>&1"
    schedule: "{{ docker__cron_jobs_prune_schedule }}"
    cron_file: "docker-disk-clean-up"
    #user: "{{ (docker__users | first) | d('root') }}"
    #state: "present"

アスタリスク付きのプロパティは必須です。

• *nameはcronジョブの説明です
• *jobはcronジョブで実行されるコマンドです
• *scheduleは標準cronジョブフォーマットで、毎週日曜日の真夜中を示します
• *cron_fileは、/etc/cron.dに対するcronファイルを書き込みます
• userはデフォルトで最初のdocker__usersユーザーに設定されます（利用できない場合はroot）
• stateはデフォルトで"present"です。"absent"にするとcronファイルが削除されます

APTパッケージ管理の設定

Dockerが動作するために必要な依存パッケージをいくつかインストールする必要があります。これらの変数を編集する必要はありません。

# インストールされるパッケージのリスト。
docker__package_dependencies:
  - "apt-transport-https"
  - "ca-certificates"
  - "cron"
  - "gnupg2"
  - "software-properties-common"

# AnsibleはCPUアーキテクチャをDockerとは異なる方法で識別します。
docker__architecture_map:
  "x86_64": "amd64"
  "aarch64": "arm64"
  "aarch": "arm64"
  "armhf": "armhf"
  "armv7l": "armhf"

# DockerのGPGキーのURL。
docker__apt_repository_url: "https://download.docker.com/linux/{{ ansible_distribution | lower }}"

# DockerのGPGキーのチェックサム値。
docker__apt_key_checksum: "sha256:1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570"

# Dockerの上流APTリポジトリ。
docker__apt_repository: >
  deb [arch={{ docker__architecture_map[ansible_architecture] }}
  signed-by=/etc/apt/keyrings/docker.asc]
  {{ docker__apt_repository_url }}
  {{ ansible_distribution_release }} {{ docker__channel | join(' ') }}

VirtualenvとPIPでPythonパッケージをインストール

Virtualenvの設定

サーバーのPythonのバージョンを汚染しないために、すべてのPIPパッケージは選んだVirtualenvにインストールされます。

docker__pip_virtualenv: "/usr/local/lib/docker/virtualenv"

PIPとその依存関係のインストール

このロールはPIPをインストールします。なぜなら、Docker Compose v1はdocker-composeのPIPパッケージでインストールされ、Ansibleのdocker_*モジュールもdockerのPIPパッケージを使用するためです。

docker__pip_dependencies:
  - "gcc"
  - "python3-setuptools"
  - "python3-dev"
  - "python3-pip"
  - "virtualenv"

PIPパッケージのインストール

docker__default_pip_packages:
  - name: "docker"
    state: "{{ docker__pip_docker_state }}"
  - name: "docker-compose"
    version: "{{ docker__compose_version }}"
    path: "/usr/local/bin/docker-compose"
    src: "{{ docker__pip_virtualenv + '/bin/docker-compose' }}"
    state: "{{ docker__pip_docker_compose_state }}"

# 上記と同じプロパティを持つ独自のPIPパッケージを追加できます。
docker__pip_packages: []

アスタリスク付きのプロパティは必須です。

• *nameはパッケージ名です
• versionはインストールするパッケージのバージョンで、（未設定の場合は""）
• pathはシンボリックリンクの宛先パスです
• srcはシンボリックリンクの元パスです
• stateのデフォルトは"present"で、他の値は"forcereinstall"または"absent"にできます

PIPパッケージの状態

• "present"に設定すると、パッケージはインストールされますが将来の実行では更新されません
• "forcereinstall"に設定すると、将来の実行で常に（再）インストールおよび更新されます
• "absent"に設定すると、パッケージはスキップまたは削除されます

docker__pip_docker_state: "present"
docker__pip_docker_compose_state: "absent"

Ansibleのdocker_*モジュールとの連携

このロールはDockerレジストリにログインするためにdocker_loginを使用しますが、他のdocker_*モジュールは自身のロール内で使用できます。これらは、このロールのVirtualenvをAnsibleに使用させなければ機能しません。

インベントリ、プレイブック、またはタスクレベルで、以下を設定する必要があります：ansible_python_interpreter: "/usr/local/bin/python3-docker"。これにより、このロールはVirtualenvのPythonバイナリからpython3-dockerへのプロキシスクリプトを作成します。

タスクレベルでの方法については、このロールのdocker_loginタスクを参考にしてください。

ライセンス

MIT