githubixx.etcd

ansible-role-etcd

このAnsibleロールは、Kubernetes the not so hard way with Ansible - etcd clusterで使用されます。ただし、Kubernetesクラスターがなくても使用できます。

etcdクラスターをインストールします。ヒント：このプレイブックは、systemdサービスファイルが変更された後、etcdクラスターのプロセスを再読み込みまたは再起動しません！これは意図的です！すべてのetcdプロセスを同時に再起動することは非常に悪いアイデアです。したがって、etcd.serviceファイルが変更された場合は、ノードごとに手動で再起動/再読み込みし、ノードがクラスターに再参加したかどうかをログ出力で確認してください！このプロセスは自動化することも可能ですが、現在はこのロールの一部ではありません。補足として、スクリプトはetcdサービスファイルが変更された後にsystemctl daemon-reloadを実行し、少なくともsystemdが変更されたファイルを認識できるようにしますので、その点については気にしなくて大丈夫です。したがって、etcdノードの再起動でも新しい設定が有効になります。

このロールでインストールされたetcdクラスターのアップグレードについては、こちらで説明しています。

バージョン

すべてのリリースにタグを付け、セマンティックバージョニングに従うよう努めています。このロールを使用する場合は、最新のタグを使用することをお勧めします。マスターブランチは基本的に開発中で、タグは安定リリースを示します。ただし、一般的には、マスターも良好な状態を維持するよう努めています。タグ13.1.1+3.5.13は、このロールのリリース13.1.1であり、etcdバージョン3.5.13と一緒に使用することが意図されています（ただし、より新しいバージョンでも動作するはずです）。ロール自体が変更される場合、X.Y.Zの部分は+の前が増加します。etcdのバージョンが変更されると、X.Y.Zの部分は+の後が増加します。これにより、特定のetcdリリース向けに開発されているロールのバグ修正や新しいメジャーバージョンにタグ付けすることができます。

変更履歴

CHANGELOG.mdを参照してください。

要件

このロールには、すでにいくつかのetcd用の証明書を作成していることが必要です（Kubernetes the not so hard way with Ansible - 証明書認証局（CA）やAnsibleロールkubernetes_caを参照）。プレイブックは、このプレイブックが実行されるホストのetcd_ca_conf_directoryで証明書を検索します。もちろん、自分で証明書を作成することもできます（自己署名証明書の生成を参照してください - Gitリポジトリはアーカイブされていますが、情報は依然として有効です）。

ロール変数

# etcd証明書をコピーするためのディレクトリ。デフォルトでは
# ユーザーのローカル$HOMEに展開されます ("ansible-playbook ..."を実行するユーザー
#に加え"/etcd-certificates")。たとえば、ユーザーの$HOMEディレクトリが
# "/home/da_user"の場合、"etcd_ca_conf_directory"の値は
# "/home/da_user/etcd-certificates"になります。
etcd_ca_conf_directory: "{{ '~/etcd-certificates' | expanduser }}"

# etcd Ansibleグループ
etcd_ansible_group: "k8s_etcd"

# etcdのバージョン
etcd_version: "3.5.13"

# etcdがクライアントからリスニングするポート
etcd_client_port: "2379"

# etcdがピアからリスニングするポート
etcd_peer_port: "2380"

# etcdポートをバインドするインターフェイス
etcd_interface: "tap0"

# このユーザーとしてetcdデーモンを実行します。
# 
# 注意1：1024未満の"etcd_peer_port"を使用したい場合は、
# "etcd"をユーザー"root"として実行する必要があるでしょう。
# 注意2："etcd_user"で指定したユーザーが存在しない場合、ロールが作成します。
# ユーザーがすでに存在する場合は、ロールはユーザーを作成せず、
# 指定された場合はUID/GIDおよびシェルを調整します（設定を参照）。
# さらに、"etcd_user"が"root"の場合、このロールはユーザーに
# 触れません。
etcd_user: "etcd"

# "etcd_user"で指定したユーザーのUID。指定されていない場合は、
# "/etc/login.defs"の次の利用可能なUIDが取得されます（"SYS_UID_MAX"設定を参照）。
# etcd_user_uid: "999"

# 指定されたユーザーのシェルで、セキュリティを高めるために
# デフォルトを保持します。
etcd_user_shell: "/bin/false"

# 指定されたユーザーがシステムユーザー（デフォルト）であるか
# どうかを指定します。"true"の場合、"etcd_user_home"設定は無視されます。
# 通常、このユーザーでログインする必要はないため、デフォルトを維持するのが良いでしょう。
etcd_user_system: true

# "etcd_user"で指定したユーザーのホームディレクトリ。
# "etcd_user_system"が"true"に設定されている場合は無視されます。
# 通常は必要ないです。
# etcd_user_home: "/home/etcd"

# このグループとしてetcdデーモンを実行します。
#
# 注意：指定されたグループが存在しない場合、ロールが作成します。
# グループがすでに存在する場合、ロールは作成せず、必要に応じて
# GIDを調整します（設定を参照）。
etcd_group: "etcd"

# "etcd_group"で指定されたグループのGID。
# 指定されていない場合、"/etc/login.defs"の次の利用可能なGIDが取得されます（"SYS_GID_MAX"設定を参照）。
# etcd_group_gid: "999"

# "etcd_group"で指定されたグループがシステムグループ（デフォルト）
# であるかどうかを指定します。
etcd_group_system: true

# etcd構成用のディレクトリ
etcd_conf_dir: "/etc/etcd"

# etcd構成用のディレクトリの権限
etcd_conf_dir_mode: "0750"

# "etcd_conf_dir"で指定されたディレクトリのオーナー
etcd_conf_dir_user: "root"

# "etcd_conf_dir"で指定されたディレクトリのグループオーナー
etcd_conf_dir_group: "{{ etcd_group }}"

# ダウンロードしたetcdアーカイブを保存するディレクトリ
# 繰り返しダウンロードしないように削除しないでください
etcd_download_dir: "/opt/etcd"

# ダウンロードしたetcdアーカイブを保存するディレクトリの権限
etcd_download_dir_mode: "0755"

# "etcd_download_dir"で指定されたディレクトリのオーナー
etcd_download_dir_user: "{{ etcd_user }}"

# "etcd_download_dir"で指定されたディレクトリのグループオーナー
etcd_download_dir_group: "{{ etcd_group }}"

# etcdバイナリを保存するディレクトリ
#
# 重要：デフォルト値の"etcd_bin_dir"を"/usr/local/bin"に設定した場合、
# "etcd_bin_dir_mode"、"etcd_bin_dir_user"、"etcd_bin_dir_group"で指定された設定は無視されます。
# これは、"/usr/local/bin"の権限が変更されないようにするためです。
# このディレクトリは通常、すべてのLinuxインストールですでに存在し、
# 変更しないほうが良いでしょう。
# したがって、"etcd_bin_dir"として"/usr/bin"や"/bin"のようなディレクトリを指定する場合は
# 権限が変更されるため、通常は避けるべきです。
etcd_bin_dir: "/usr/local/bin"

# etcdバイナリを保存するディレクトリの権限
etcd_bin_dir_mode: "0755"

# "etcd_bin_dir"で指定されたディレクトリのオーナー
etcd_bin_dir_user: "{{ etcd_user }}"

# "etcd_bin_dir"で指定されたディレクトリのグループオーナー
etcd_bin_dir_group: "{{ etcd_group }}"

# etcdデータディレクトリ（要するにetcdデータベースファイル）
etcd_data_dir: "/var/lib/etcd"

# etcdデータを保存するディレクトリの権限
etcd_data_dir_mode: "0700"

# "etcd_data_dir"で指定されたディレクトリのオーナー
etcd_data_dir_user: "{{ etcd_user }}"

# "etcd_data_dir"で指定されたディレクトリのグループオーナー
etcd_data_dir_group: "{{ etcd_group }}"

# ダウンロードしてインストールするアーキテクチャ
etcd_architecture: "amd64"

# サポートされていないアーキテクチャを使用する場合のみこれを変更します。
# 詳細については、こちらを参照してください：
# https://github.com/etcd-io/website/blob/main/content/en/docs/v3.5/op-guide/supported-platform.md
etcd_allow_unsupported_archs: false

# デフォルトではetcd tarballは公式の
# etcdリポジトリからダウンロードされます。必要に応じて
# カスタムURLに変更できます。使用可能なプロトコルについては、以下を参照
#してください：
# https://docs.ansible.com/ansible/latest/collections/ansible/builtin/get_url_module.html
# 重要なのは、ファイル名の命名スキームを維持することです：
# "etcd-v{{ etcd_version }}-linux-{{ etcd_architecture }}.tar.gz"
etcd_download_url: "https://github.com/etcd-io/etcd/releases/download/v{{ etcd_version }}/etcd-v{{ etcd_version }}-linux-{{ etcd_architecture }}.tar.gz"

# デフォルトでは、SHA256SUMSファイルを使用して
# tarballアーカイブのチェックサムを検証します。これも変更できます。
etcd_download_url_checksum: "sha256:https://github.com/coreos/etcd/releases/download/v{{ etcd_version }}/SHA256SUMS"

# [Service]セクションのオプション。詳細については：
# https://www.freedesktop.org/software/systemd/man/systemd.service.html#Options
# "Type=notify"以降のオプションは主にセキュリティ/サンドボックスに関連する設定で、
# システムをユニットのプロセスに対して制限します。
# https://www.freedesktop.org/software/systemd/man/systemd.exec.html
etcd_service_options:
  - User={{ etcd_user }}
  - Group={{ etcd_group }}
  - Restart=on-failure
  - RestartSec=5
  - Type=notify
  - ProtectHome=true
  - PrivateTmp=true
  - ProtectSystem=full
  - ProtectKernelModules=true
  - ProtectKernelTunables=true
  - ProtectControlGroups=true
  - CapabilityBoundingSet=~CAP_SYS_PTRACE

etcd_settings:
  "name": "{{ ansible_hostname }}"
  "cert-file": "{{ etcd_conf_dir }}/cert-etcd-server.pem"
  "key-file": "{{ etcd_conf_dir }}/cert-etcd-server-key.pem"
  "trusted-ca-file": "{{ etcd_conf_dir }}/ca-etcd.pem"
  "peer-cert-file": "{{ etcd_conf_dir }}/cert-etcd-peer.pem"
  "peer-key-file": "{{ etcd_conf_dir }}/cert-etcd-peer-key.pem"
  "peer-trusted-ca-file": "{{ etcd_conf_dir }}/ca-etcd.pem"
  "advertise-client-urls": "{{ 'https://' + hostvars[inventory_hostname]['ansible_' + etcd_interface].ipv4.address + ':' + etcd_client_port }}"
  "initial-advertise-peer-urls": "{{ 'https://' + hostvars[inventory_hostname]['ansible_' + etcd_interface].ipv4.address + ':' + etcd_peer_port }}"
  "listen-peer-urls": "{{ 'https://' + hostvars[inventory_hostname]['ansible_' + etcd_interface].ipv4.address + ':' + etcd_peer_port }}"
  "listen-client-urls": "{{ 'https://' + hostvars[inventory_hostname]['ansible_' + etcd_interface].ipv4.address + ':' + etcd_client_port + ',https://127.0.0.1:' + etcd_client_port }}"
  "peer-client-cert-auth": "true"            # ピアクライアント証明書認証を有効にする
  "client-cert-auth": "true"                 # クライアント証明書認証を有効にする
  "initial-cluster-token": "etcd-cluster-0"  # ブートストラップ時のetcdクラスターの初期トークン
  "initial-cluster-state": "new"             # 初期クラスターステート（「new」または「existing」）
  "data-dir": "{{ etcd_data_dir }}"          # etcdデータディレクトリ（要するにetcdデータベースファイル）
  "wal-dir": ""                              # 専用walディレクトリ（""は分離されたWALディレクトリを意味しない）
  "auto-compaction-retention": "0"           # 自動コンパクションの保持時間（時間）。0は自動コンパクションを無効にします。
  "snapshot-count": "100000"                 # ディスクへのスナップショットをトリガーするためのコミットトランザクションの数
  "heartbeat-interval": "100"                # ハートビート間隔の時間（ミリ秒）
  "election-timeout": "1000"                 # 投票のタイムアウト時間（ミリ秒）。詳細は調整の文書を参照
  "max-snapshots": "5"                       # 保持するスナップショットファイルの最大数（0は無制限）
  "max-wals": "5"                            # 保持するwalファイルの最大数（0は無制限）
  "quota-backend-bytes": "0"                 # バックエンドのサイズが指定されたクオータを超えたときにアラームを上げる（0は低スペースのクオータをデフォルト値にします）
  "logger": "zap"                            # 構造化ロギング用に「zap」を指定するか、「capnslog」を指定します。
  "log-outputs": "systemd/journal"           # systemdの下で実行しているときにjournaldログをスキップするため、「stdout」または「stderr」を指定します
  "enable-v2": "true"                        # v2 APIを有効にしてetcd 3.3.x以前との互換性を保つ（例：flannelに必要）
  "discovery-srv": ""                        # DNS SRV発見を有効にするための発見ドメイン、無効にするには空のままにします。設定されると、initial-clusterをオーバーライドします。

# etcdの証明書認証局および証明書ファイル
etcd_certificates:
  - ca-etcd.pem               # 証明書認証局ファイル
  - ca-etcd-key.pem           # 証明書認証局鍵ファイル
  - cert-etcd-peer.pem        # ピアTLS証明書ファイル
  - cert-etcd-peer-key.pem    # ピアTLS鍵ファイル
  - cert-etcd-server.pem      # サーバーTLS証明書ファイル
  - cert-etcd-server-key.pem  # サーバーTLS鍵ファイル

etcdのデフォルト設定は、etcd_settings_userという変数を定義することで上書きできます。この変数を使用して追加の設定を追加することもできます。たとえば、log-output設定のデフォルト値を上書きして、grpc-keepalive-min-timeのような新しい設定を追加するには、group_vars/k8s.ymlに次の設定を追加します。

etcd_settings_user:
  "log-output": "stdout"
  "grpc-keepalive-min-time": "10s"

例のプレイブック

- hosts: k8s_etcd
  roles:
    - githubixx.etcd

テスト

このロールには、Molecule、libvirt（vagrant-libvirt）、およびQEMU/KVMを使用して作成された小さなテストセットアップがあります。セットアップ方法については、私のブログ記事Testing Ansible roles with Molecule, libvirt (vagrant-libvirt) and QEMU/KVMを参照してください。テスト構成はこちらにあります。

その後、Moleculeを実行できます。