hive-builder のインベントリは以下の2つからなります。
- hive 定義
サーバやネットワークで構成される基盤(infrastructure)を定義する
- サービス定義
コンテナイメージ、ボリューム、内部ネットワークで構成されるサービスを定義する
hive 定義では基盤を構成するサーバやネットワークを記述します。
IaaS 上にサイトを構築する場合、コンテナ収容サーバは3つの Availability Zone に分かれて配置されます。以下にその例を示します。
hive 定義のフォーマットは以下の通り。
パラメータ 選択肢/例 | デフォルト | 意味 | |
---|---|---|---|
plugin | hive_inventory | 必須 この | ファイルがhive定義で有ることを示す |
name | pdns | 必須 hi | ve の名前 |
stages |
ステージオブジェクトへの辞書 private, staging, production の3つが定義できる |
stages の下にステージ名をキーとしてステージオブエクトを指定します。以下に例を 示します。
plugin: hive_inventory
stages:
private:
provider: vagrant
separate_repository: False
cidr: 192.168.0.96/27
memory_size: 4096
mirrored_disk_size: 10
number_of_hosts: 1
production:
provider: aws
separate_repository: False
cidr: 192.168.0.0/24
instance_type: t3.medium
region: ap-northeast-1
mirrored_disk_size: 20
repository_instance_type: t3.large
subnets:
- cidr: 192.168.0.0/26
name: subnet-a
available_zone: ap-northeast-1d
- cidr: 192.168.0.64/26
name: subnet-b
available_zone: ap-northeast-1b
- cidr: 192.168.0.128/26
name: subnet-c
available_zone: ap-northeast-1c
この例では、private ステージと production ステージが定義されています。 private ステージは vagrant で VirtualBox 上に 4G のメモリの サーバ1台を構築します。
production ステージでは aws 上に t3.medium のサーバ3台を 東京リージョンの3つの可用性ゾーンに分けて構築します。 リポジトリサーバは3台目のコンテナ収容サーバと兼用し、 t3.large で構築します。
ステージオブジェクトのフォーマットは以下の通り。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
provider |
|
必須 | 基盤を提供するシステム |
cidr | 192.168.1.0/24 | 必須 | ネットワークのアドレス |
number_of_hosts | 1 | 4 if separate_repository else 3 | サーバの台数 |
separate_repository |
|
True | リポジトリサーバをコンテナ収容サーバとは別に建てるか否か |
subnets | 後述 | サブネットの定義のリスト | |
ip_address_list | ["192.168.20.5","192.168.20.6"] | IPアドレスのリスト | |
disk_size | 16 | プロバイダによる | コンテナ収容サーバの起動ディスクのサイズ(GBytes) |
repository_disk_size | 16 | プロバイダによる | リポジトリサーバの起動ディスクのサイズ(GBytes) |
mirrored_disk_size | 16 | 必須 | drbdで複製同期するディスクのサイズ(GBytes) |
root_password | X12bv5riykfid | "" | 最初に ssh でログインするためのユーザを作成する必要がある場合に root のパスワードを指定する |
internal_cidr | 10.254.0.0/16 | 172.31.252.0/22 | docker コンテナがコンテナ間やホストとの通信に使用するネットワークのアドレス |
nameservers | ["192.168.0.1", "192.168.0.2"] | "" | kickstart プロバイダの場合にDNSのサーバのIPアドレスを指定する |
上記はプロバイダ共通の属性ですが、プロバイダ固有の属性もあります。 以下にプロバイダ固有の属性をプロバイダごとに説明します。
IPアドレスと可用性ゾーンの割当は以下のルールで行われます。 ただし、subnet 属性はプロバイダごとに指定できなかったり、 必須であったりしますので、プロバイダごとに割当方法が 異なります。
subnets が指定されている場合: サーバは subnets に指定されたsubnetオブジェクトに順に割り振られます。 サーバの台数のほうがsubnetオブジェクトの数よりも大きい場合は、 先頭に戻ります。 サーバのIPアドレスは subnetオブジェクトに指定されたCIDR から 自動的に割り振ります。サーバはsubnetオブジェクトの available_zone属性で指定された可用性ゾーンに配備されます。
ip_address_list が指定されている場合: サーバのIPアドレスは ip_address_list から順に割り当てられます。 ip_address_listの要素数はサーバの台数と一致しなければなりません。 アベラブルゾーンは自動的にできるだけ分散するように割り振ります。
上記以外の場合: サーバのIPアドレスは cidr 属性から自動的に割り振ります。 アベラブルゾーンは自動的にできるだけ分散するように割り当てます。
コンテナ間通信やコンテナとホスト間通信には docker が必要に応じて作成する仮想ブリッジが使用されます。 このような仮想ブリッジ内でコンテナやホストに割り当てられるIPアドレスは外から見えることはありませんが、 コンテナから外部に通信する際にIPアドレスが重複していると接続することができません。 このため、仮想ブリッジのネットワークのアドレスも外部とかぶらないように割り当てる必要があります。 これらのネットワークのアドレスは、デフォルトではdocker デーモンが適宜 LOCALなIPアドレス領域から割り当てますが、 hive定義の internal_cidr プロパティで変更できます。 以下に swarm クラスタで利用される仮想ブリッジの種別について説明します。
種別 | 説明 | 接続の条件 | 比率 |
---|---|---|---|
Overlay | docker swarm クラスタに分散して配置されるコンテナ間で通信するためのネットワークで、異なるサーバのコンテナと仮想的なネットワークで通信する。管理セグメント内をトンネリングして実装されるVPNである。 | サービスのコンテナはデフォルトで接続される | 1/4 |
Ingress | docker swarm クラスタで内のコンテナが負荷分散モードでサービスを公開するときに利用するネットワークで、サーバ間の仮想的なネットワークで通信する。管理セグメント内をトンネリングして実装されるVPNである。 | サービスのコンテナがポートを公開すると接続される | 1/4 |
docker_gwbridge | サーバ内で動作している swarm モードのコンテナが属するネットワークでサーバ上に設置されたブリッジを経由し外部と接続できる。このとき、コンテナ側のアドレスは NAT により、サーバのアドレスに付け替えられる。 | サービスのコンテナはデフォルトで接続される | 1/8 |
docker0 | swarmモードでないコンテナが属するネットワークでサーバ上に設置されたブリッジを経由し外部と接続できる。このとき、コンテナ側のアドレスは NAT により、サーバのアドレスに付け替えられる。 | 非swarmモードのコンテナのみが接続される | 1/8 |
registry_default | リポジトリサーバ上のリポジトリサービスが使用するネットワークである。コンテナ側のアドレスは NAT により、サーバのアドレスに付け替えられるが、リポジトリサーバ内の別のコンテナへの通信の場合は付け替えられない。 | リポジトリサービスのコンテナのみが接続される | 1/8 |
zabbix_default | リポジトリサーバ上の zabbix が使用するネットワークである。コンテナ側のアドレスは NAT により、サーバのアドレスに付け替えられるが、リポジトリサーバ内の別のコンテナへの通信の場合は付け替えられない。 | zabbixのコンテナのみが接続される | 1/8 |
ここで、比率とは internal_cidr で指定されたネットワークを分割して割り当てる際の比率を示しています。 以下に上記種別の接続関係の例を簡略化して図に示します。
vagrant プロバイダを利用するには、 Vagrant がインストールされていて、 virtualbox か libvirt の Vagrant プロバイダ がセットアップされている必要があります。また、 vagrant-disksize プラグインがインストールされている 必要があります。詳細についてはインストールの章を参照してください。
vagrant プロバイダ固有の属性には以下のものがあります。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
memory_size | 4096 | Vagrant のデフォルト | コンテナ収容サーバに割り当てるメモリのサイズで(MBytes) |
repository_memory_size | 4096 | Vagrant のデフォルト | リポジトリサーバに割り当てるメモリのサイズで(MBytes) |
cpus | 2 | Vagrant のデフォルト | サーバに割り当てる仮想CPUの個数 |
bridge | brHive | '' | 外部のネットワークへブリッジ経由で接続するための仮想ブリッジをこの名前で生成する |
dev | brHive | '' | この名前の既設の仮想ブリッジに接続する(Vagrantプロバイダが libvirt である場合のみ利用できる) |
- disk_size, repository_disk_size を省略した場合、Vagrant のデフォルトのサイズになります。
- subnets 属性は指定できません
- bridge, dev のどちらも指定しない場合、ホストオンリーネットワークに接続されます。
aws プロバイダ固有の属性には以下のものがあります。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
instance_type | t3.medium | 必須 | コンテナ収容サーバのインスタンスタイプ |
repository_instance_type | t3.medium | 必須 | リポジトリサーバのインスタンスタイプ |
region | ap-northeast-1 | 必須 | 構築先のリージョン |
aws プロバイダを使用する場合は、以下のコマンドで hive の環境に AWS EC2 API の鍵を設定する必要があります。
hive set aws_access_key_id アクセスキーID
hive set aws_secret_access_key アクセスキー
gcp プロバイダ固有の属性には以下のものがあります。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
instance_type | n1-standard-2 | 必須 | コンテナ収容サーバのインスタンスタイプ |
repository_instance_type | n1-standard-2 | 必須 | リポジトリサーバのインスタンスタイプ |
region | asia-northeast2 | 必須 | 構築先のリージョン |
gcp プロバイダを使用する場合は、プロジェクトのルートディレクトリに gcp_credential.json という 名前でサービスアカウントキーを保持するファイルを置く必要があります。 サービスアカウントの作成については、 https://cloud.google.com/iam/docs/creating-managing-service-accounts?hl=ja を参照してください。サービスアカウントを作成する際には「Compute 管理者」のロールを割り当ててください。 サービスアカウントキーについては、 https://cloud.google.com/iam/docs/creating-managing-service-account-keys?hl=ja を参照してください。 鍵の形式でJSONを選択して、プロジェクトのルートディレクトリに gcp_credential.json という名前で保存してください。
gcpプロバイダで disk_size 属性を省略した場合、コンテナ収容サーバの起動ディスクのサイズは25Gになります。
azure プロバイダ固有の属性には以下のものがあります。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
instance_type | n1-standard-2 | 必須 | コンテナ収容サーバのインスタンスタイプ |
repository_instance_type | n1-standard-2 | 必須 | リポジトリサーバのインスタンスタイプ |
region | asia-northeast2 | 必須 | リソースグループのロケーション |
azure プロバイダを使用する場合は、 Azure AD アプリケーションを作成し、 仮想マシーンやネットワークの課金先のサブスクリプションに サービスプリンシパルとしてアプリケーションを設定(ロールを割り当てる)していただく必要があります。 Azure ポータルで作成する場合は、Azure のオフィシャルサイト 方法:リソースにアクセスできる Azure AD アプリケーションとサービスプリンシパルをポータルで作成する を参照してください。
作成後、以下のコマンドで、そのクレデンシャルを認証情報として hive 変数に設定してください。
hive set azure_client_id ...
hive set azure_secret ...
hive set azure_subscription_id ...
hive set azure_tenant ...
azure_subscription_id にはポータルの「サブスクリプション」サービスで、表示されるサブスクリプションIDを設定してください。 azure_client_id には、ポータルの「Azure Active Directory」サービスの「アプリの登録」からアプリケーションを選択したときに表示される「アプリケーション(クライアントID)」の値を設定してください。 azure_tenant には、ポータルの「Azure Active Directory」サービスの「アプリの登録」からアプリケーションを選択したときに表示される「ディレクトリ(テナント)」の値を設定してください。 azure_secret には、アプリケーション上に作成したシークレットの値を設定してください。シークレットの値は作成時にしか表示されないため、値が不明の場合はシークレットを作り直してください。
region 属性にはAzure Location をコードで指定してください。 有効な値のリストは Azure Cloud Shell 上で以下のコマンドを実行して取得することができます。
Get-AzureRmLocation |Format-Table
instance_type 属性、repository_instance_type には VM のサイズをコードで指定してください。 有効な値のリストは Azure Cloud Shell 上で以下のコマンドを実行して取得することができます。
Get-AzureRmVMSize -Location region属性の値
kickstart プロバイダは OS のインストール媒体を生成します。 インストール媒体は、USBメモリ、DVD、isoイメージファイルに出力できます。 VirtualBox や iDRAC で OS を最初からインストールする際に このインストール媒体をセカンダリの光学ドライブとしてマウントして利用できます。
kickstart プロバイダを利用するには motherマシンは linux でなければなりません。 また、現在のバージョンではサーバは UEFI ブート可能なものである必要があります。
kickstart プロバイダを利用する場合は、ステージオブジェクトに kickstart_config 属性に サーバのインストールパラメータを指定してください。 kickstart_config 属性には 以下の属性が指定できます。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
iso_src | /var/lib/isos/CentOS-7-x86_64-Minimal-2003.iso | 必須 | 元となるOSのインストール媒体(媒体が挿されているデバイス名かISOイメージのファイル名) |
iso_dest | /dev/sda | 必須 | インストール媒体の出力先(媒体が挿されているデバイス名かISOイメージのファイル名) |
media_usb |
|
False | インストール媒体がUSBであるかいなか |
networks | 未執筆 | 必須 | ネットワーク定義オブジェクトのリスト |
以下にkickstart_configの例を示します。
kickstart_config:
iso_src: /var/lib/isos/CentOS-7-x86_64-Minimal-2003.iso
iso_dest: /dev/sda
media_usb: True
networks:
- interface: bond0
bonding_interfaces:
- eth0
- eth1
ips:
- 192.168.200.20
- 192.168.200.21
- 192.168.200.22
netmask: 255.255.255.0
- interface: bond0
vlanid: 2
- interface: bond0
vlanid: 4
- interface: bond0
vlanid: 1000
- interface: bond0
vlanid: 1001
- interface: bond0
vlanid: 1002
ips:
- 192.168.203.20
- 192.168.203.21
- 192.168.203.22
netmask: 255.255.255.0
gateway: 192.168.203.1
nameservers:
- 192.168.203.1
- interface: bond0
vlanid: 1003
- interface: bond0
vlanid: 1004
prepared プロバイダは OS がインストール済みのホストが 事前に用意されている場合に使用します。 以下に prepared プロバイダの hive 定義の例を示します。
staging:
provider: prepared
separate_repository: False
cidr: 192.168.0.96/27
ip_address_list:
- 192.168.0.98
- 192.168.0.99
- 192.168.0.100
root_password: mzYY3qjdvBiD
root_password が指定された場合は、build-infra フェーズは 鍵認証ではなく root ユーザでパスワードでログインして実行されます。 mother 環境が CentOS の場合、 root_password を使用して build-infra を実行するためには、 sshpass パッケージが必要ですので、以下を実行して事前にインストールしておいてください。
yum install sshpass
build-infra フェーズで ssh 鍵を生成し、 hive_admin で指定された ユーザを作成して、 authorized_keys を設定します。
hiveでは、デフォルトで複製同期用のデバイスを使用し、そのデバイスに drbd の複製同期ディスクを割り当てます。 各プロバイダは自動的に mirrored_disk_size で指定された大きさで複製同期用デバイスを作成しますが、prepared プロバイダの場合は、事前に複製同期用のデバイスを割り当てて、ホストのデバイスとして見えている必要があります。 複製同期用のデバイスは以下のうちのいずれかの名前である必要があります。
- /dev/sdc
- /dev/sdb
- /dev/vdc
- /dev/vdb
- /dev/xvdb
- /dev/nvme1n1
- /dev/sda
また、場合によって、複製同期用デバイスを持たないホストを作成したい場合もあります。その場合、ホストの hive_no_mirrored_device 変数に True を設定することで、当該ホストの複製同期用デバイスが無いものとして扱われます。 たとえば、inventory/host_vars/hive2.pdns.yml に以下のように指定すると hive2.pdns には複製同期用のデバイスは無いものとして扱われます。
hive_no_mirrored_device: True
この変数に True を指定した場合、以下の仕様となります。
- 各プロバイダで複製同期用のディスクを作成しません
- setup-hosts フェーズの drbd のインストール時の複製同期用のディスクの初期化処理をスキップします
- build-volumes フェーズで drbd リソースを作成する際、当該ホスト上では diskless として設定します。
サービス定義には、サービスをどのように構築するかが書かれます。以下の属性を記述できます。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
available_on | ["production"] | ["production", "staging", "private"] | サービスが有効になるステージ |
backup_scripts | 後述 | [] | バックアップ、リストア、夜間バッチのスクリプト(詳細後述) |
command | ["--api=yes", "--api-key={{db_password}}"] | イメージの command の値 | サービス実行時にentrypoint に与えられる引数(entrypoint が [] の場合、1個めが実行コマンドとなる) |
dns | "192.168.1.2" | "" | サービス内で使用するDNSサーバのアドレス(docker service create の --dns オプションと等価) |
endpoint_mode |
|
VIP | エンドポイント・モード(docker service create の --endpoint-mode オプションと等価) |
entrypoint | ["/docker-entrypoint.sh"] | イメージの entorypoint の値 | サービスの起動時に実行されるコマンド |
environment | {"MYSQL_PASSWORD": "{{db_password}}, "MYSQL_HOST": "pdnsdb"} | {} | サービス実行時にプロセスに付与される環境変数(docker service create の --env オプションと等価) |
hosts | {"test.example.com": "192.168.1.2"} | {} | サービス内の /etc/hosts ファイルに追加するホスト名をキーとしたIPアドレスの辞書(docker service create の --hosts オプションと等価) |
monitor_error | ["Error:", "Exception"] | [] | サービスが出力するログからエラーメッセージとして検知するものの正規表現パターンの配列 |
ignore_error | ["(favicon.ico|echo.php)", "^ [^[]"] | [] | サービスが出力するエラーメッセージのうち、無視したいものに対する正規表現パターンの配列。monitor_error属性が定義されている場合のみ有効である。 |
image | 後述 | [] | サービスのもととなるコンテナイメージの取得方法(詳細後述) |
initialize_roles | ["python-aptk", "powerdns"] | [] | サービスのイメージのビルド時に適用される role 名のリスト |
labels | {"published_fqdn": "pdnsadmin.pdns.procube-demo.jp"} | {} | サービスに付与されるラベル(ラベル名と値の dict を指定する。値に文字列以外のものを指定すると JSON 文字列化されるが、 constraint などで使用する場合には文字列としてしか参照できないので注意を要する) |
logging | {"driver": "journald", "options": {"tag": "powerdns"}} | {"driver": "fluentd", "options": {"fluentd-address": リポジトリサーバ:24224}} | サービスのログ出力方法(docker service create の --log-driver("driver"に指定), --log-opt("options"に指定) オプションと等価) |
mode |
|
replicated | サービス・モード(docker service create の --mode オプションと等価) |
placement | {"constraints": "node.hostname!=hive2"} | {} | サービスの配置に関するルールを constraints 属性、 preferences 属性で指定する(docker service create の --constraint ("constraints"に指定), placement-pref("preferences"に指定) オプションと等価) |
ports | "80:8080" | [] | サービス実行時に外部に公開するポート(詳細後述) |
replicas | 3 | -1 | サービスでインスタンス化されたコンテナの複製数。mode 属性が replicated である場合にのみ有効です。(docker service create の --replicas オプションと等価) ・1に設定され、サービスが存在しない場合、複製数は1に設定されます。 ・1に設定され、サービスが存在する場合、複製数は変更されません。 |
restart_config | {"restart_config": {"condition": "on-failure", "delay": "5s", "max_attempts": 3, "window": "120s"}} | [] | 再起動に関する設定(docker service create の --restart-condition("condition", "max_attempts"に指定) --restart-window("window"に指定) --restart-delay("delay"に指定)オプションと等価) |
standalone |
|
False | サービスをスタンドアローン型として実行するか否か(詳細後述) |
user | admin | イメージの user の値 | サービスを実行するプロセスのユーザID(docker service create の --user オプションと等価) |
volumes | 後述 | [] | サービス実行時にコンテナにマウントするボリューム(詳細後述) |
working_dir | /opt/wildfly | 省略 | コンテナのプロセスの working diretory(docker service create の --workdir オプションと等価) |
volumes 属性には、そのサービスが利用するボリュームの内容を記述できます。 また、 必要に応じて build-volumes フェーズでボリュームを作成することができます。 以下の属性を持つボリュームオブジェクトのリストを指定してください。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
target | /var/lib/mysql | 必須 | コンテナ上のマウントポイント |
type | volume | bind | マウントタイプ(drbdの場合は volume を指定、ホストのディレクトリをマウントする場合は bind を指定) |
readonly |
|
False | ボリュームを読み取り専用でマウントするか否か |
driver | local | local | ボリュームを作成する際のドライバ(drbd属性と同時に指定することはできません) |
driver_opts | {device: "/dev/sda2"} | {} | ボリュームを作成する際のドライバのオプション(drbd属性と同時に指定することはできません) |
drbd | {fstype: "xfs", size: "500M"} | omit | drbd のボリュームを作成する場合の作成内容(driver 属性と同時に指定することはできません) |
drbd 属性、driver属性のいずれかを指定すると対応するボリュームが build-volume フェーズで 作成されます。
hive環境ではdocker swarm の機能により、コンテナがサーバ間を移動するため、 ボリュームは原則として drbd によりすべてのコンテナ収容サーバ間で複製同期 しておく必要があります。このためには、volume 属性に drbd 属性を指定してください。 drbd 属性はオブジェクトであり、以下の属性を指定できます。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
fstype |
|
必須 | ファイルシステムのタイプを指定 |
size | 100M | 必須 | ボリュームのサイズを100M, 20G などのように単位を付与した文字列で指定 |
diskless | ['s-hive1.pdns', 'hive1.pdns'] | [] | このボリュームを diskless とするサーバのリスト |
fstype について、小さいボリュームに xfs を指定すると、領域のムダが大きく、また、フォーマットで エラーになる場合があります。100M 以下のボリュームについては ext4 が推奨されます。 大きいボリュームでは xfs が推奨されます。 xfs でフォーマットすると、ボリュームの初期データは docker のコンテナに マウントする際にディレクトリが空っぽであることを契機としてマウント前の データがコピーされます。ext4 でフォーマットすると lost+found ディレクトリが 存在するため、空っぽであると認識されずこの機能は動作しませんので、注意が必要です。
image 属性には、そのサービスを構成する docker コンテナのイメージの取得方法を記載してください。 image 属性には、以下のいずれかを設定できます。 - タグ指定(文字列が指定された場合) - ビルド方法指定(オブジェクトが指定された場合)
image 属性に文字列を指定すると、それはイメージのタグとみなされます。 サービスの起動時には、 docker pull により、タグに対応するイメージを ダウンロードします。
image 属性にオブジェクトを指定すると、イメージのビルド方法の指定とみなされます。 この場合、その内容に従って、 build-images フェーズでコンテナ イメージがビルドされ、リポジトリサーバのプライベートリポジトリに push されます。 ビルド方法指定には以下の属性が指定できます。
パラメータ | 選択肢/例 | デフォルト | 意味 |
---|---|---|---|
from | mariadb:10.4 | 必須 | ビルドのもととなるイメージのタグ |
roles | ['python-aptk', 'powerdns'] | 必須 | ビルド時に適用する role のリスト(対応する role が roles ディレクトリ配下に定義されていなければならない) |
standalone |
|
False | ビルド時にスタンドアローン型としてビルドするか否か |
env | {"HTTPD_USER": "admin"} | {} | イメージの設定:ビルドで追加される環境変数 |
stop_signal | "2" | "15" | イメージの設定:コンテナを終了させる場合にルートプロセスに送られるシグナルの番号 |
user | admin | root | イメージの設定:コンテナでルートプロセスを起動する際のユーザID |
working_dir | /home/admin | / | イメージの設定:コンテナでルートプロセスを起動する際の作業ディレクトリ |
entrypoint | /docker_entrypoint.sh | "[]" | イメージの設定:コンテナの entrypoint |
command | ["--api-port","5000"] | "[]" | イメージの設定:コンテナのデフォルト command |
privileged |
|
False | イメージの設定:コンテナのプロセスに特権を与えるか否か |
pull_on | ["production"] | 省略可能 | 指定されたステージではイメージのビルドを行わず、 pull_from に指定されたイメージを使用する |
pull_from | procube/certbot | 省略可能 | pull_on に指定されたステージでサービスを deploy する際のイメージのタグ。イメージはタグのリポジトリからダウンロードされる。 |
python-aptk はビルトイン role であり、イメージのビルド時に role 定義を行わずに使用できます。 build-images フェーズでは、 ansible で中身を構築するため、 ビルド用に起動したコンテナに python がインストールされていなければなりません。 しかし、 ubuntu や alpine をベースとしたイメージには python がインストールされていないものが 多々あります。このような場合、ビルドの最初の roleとして python-aptk を指定してください。 python-aptk には以下のようにタスクが定義されており、ubuntu や alpine をベースとした コンテナに python をインストールできます。
- name: install python
raw: if [ -x /usr/bin/apt-get ]; then (apt-get update && apt-get -y install python3); else (apk update && apk add python3); fi
changed_when: False
build-images でビルドされたイメージはプライベートリポジトリに push されます。このときのタグは、以下のようになります。
リポジトリサーバ名:5000/image_サービス名
例:separate_repository=True の production ステージの powerdns サービスのイメージの場合
hive3.pdns:5000/image_powerdns
build-images でビルドするイメージを複数のサービスで共有するためには、 最初のサービス定義で image 属性にオブジェクトを指定してビルドし、 二個目以降のサービスではimage 属性にプライベートリポジトリ上のタグを 指定してイメージを参照する必要があります。
staging ステージの build-images でビルドされたイメージを外部リポジトリに push し、これをproduction ステージから参照するように設定できます。 例えば、imgage オブジェクトで以下のように指定すると、production ステージでは、 build-images でのビルドを skip し、代わりに外部リポジトリからイメージをダウンロードします。
pull_on:
- production
pull_from: procube/pdnsadmin_test
staging ステージでテストし、イメージをリリースできる状態になったら、外部リポジトリに push します。 例えば、pdnsadmin サービスのイメージを procube/pdnsadmin_test にリリースする場合、以下のコマンドを実行します。
$ docker tag s-hive2.pdns:5000/image_pdnsadmin:latest procube/pdnsadmin_test:latest
$ docker push procube/pdnsadmin_test:latest
この後、production ステージで pdnsadmin サービスをデプロイすると、外部リポジトリからイメージがダウンロードされます。
docker のコンテナはスタンドアローン型とマイクロサービス型の2種類に分類することができます。
型 説 | 明 |
---|---|
スタンドアローン型 - centos: |
7 などスーパバイザ機能を持った OS のイメージをベースとして構築する - 実行時には /sbin/init を起動する - systemd により内部のプロセスが管理される |
マイクロサービス型 - dockerh |
ub のオフィシャルイメージをベースとして構築する - ベースの OS はUbuntuやalpineなどの軽量 OS を採用する - 実行時にはサービスを提供するプロセス1個を起動する |
コンテナがスタンドアローン型である場合、standalone 属性にTrue を指定してください。 スタンドアローン型かマイクロサービス型かで、イメージのビルド時の entrypoint の値とデフォルトボリュームの値が異なります。
build-images フェーズでスタンドアローン型のコンテナをビルドする場合(standalone属性が True で image 属性にビルド方法が指定されている場合)は、 from に指定されたイメージのデフォルトのentrypoint, command でコンテナを起動します。 これにより、ルートプロセスとして /sbin/init が起動され、ビルドが終了してシャットダウンされるまで仮想マシンとして動作し、 ansible でコンテナにプロビジョニングすることができます。
build-images フェーズでマイクロサービス型のコンテナをビルドする場合(standalone属性が False で image 属性にビルド方法が指定されている場合)は、 ルートプロセスとして、以下のような sleep をし続ける1行のシェルスクリプトが起動されます。
/bin/sh -c 'trap "kill %1" int;sleep 2400 &wait'
このコマンドでルートプロセスが 40分間sleepするため、その間に ansible でコンテナにプロビジョニングできます。 ビルドが終了すると、ルートプロセスに INT シグナルが送られ、コンテナは停止します。
サービスがスタンドアローン型である場合、以下のボリュームが volumes に暗黙的に追加されます。
- source: '/sys/fs/cgroup'
target: /sys/fs/cgroup
readonly: True
- source: ''
target: /run
type: tmpfs
- source: ''
target: /tmp
type: tmpfs
ports 属性にはポート定義のリストを指定できます。ポート定義の属性は以下のとおりです。
Option | Short syntax | Long syntax | Description |
---|---|---|---|
published_port and target_port | "8080:80" | {published_port:8080, target_port: 80} | The target port within the container and the port to map it to on the nodes, using the routing mesh (ingress) or host-level networking. More options are available, later in this table. The key-value syntax is preferred, because it is somewhat self-documenting. |
mode | Not possible to set using short syntax. | {published_port:8080, target_port: 80, mode: "host"} | The mode to use for binding the port, either ingress or host. Defaults to ingress to use the routing mesh. |
protocol | "8080:80/tcp" | {published_port: 8080, target_port: 80, protocol: "tcp"} | The protocol to use, tcp , udp, or sctp. Defaults to tcp. To bind a port for both protocols, specify the -p or --publish flag twice. |
また、サービス定義では published_port を省略できます。Short Syntax で "80" のように1個のポート番号を記載した場合や、Long Syntax で published_port 属性を 省略した場合は、hive-builder が自動的に 61001 から順にポート番号を割り当てます。 これらはサービスのホスト変数で調べることができます。たとえば、外からそのポートに接続するためにポート番号を調べる場合、initialize-services から起動される role で以下のように参照することができます。
pdns_port: "{{ hostvars['powerdns'].hive_ports | selectattr('target_port', 'eq', 8081) | map(attribute='published_port') | first }}"
(サービス定義のbackup_scripts, volumes 属性の詳細については未執筆)