hive コマンド

hiveコマンドはいくつかのサブコマンドを指定して利用します。 以下にその形式とオプションを説明します。

support tool to build docker site

usage: hive [-h] [-r ROOT_DIR] [-s {production,staging,private}]
            [-i INVENTORY_PATH] [-c CONTEXT_DIR] [-W TEMP_DIR]
            [-P PLAYBOOKS_DIR] [-v]
            {build-infra,setup-hosts,build-images,build-volumes,build-networks,deploy-services,initialize-services,all,inventory,init,set,ssh,install-collection}
            ...

Named Arguments

-r, --root_dir

directory where hold project inventory/settings(default: current directory)

Default: /home/docs/checkouts/readthedocs.org/user_builds/hive-builder/checkouts/latest/docs

-s, --stage

Possible choices: production, staging, private

stage name which is passed to ansible-playbook with --limit option as inventory group name

-i, --inventory_path

path of inventory

-c, --context_dir

directory where save context(ex. VagrantFile, CA key, password).

-W, --temp_dir

directory where save temporary file(ex. ansible.cfg, vars.yml).

-P, --playbooks_dir

path of hive playbooks(default: where hive.py is installed)

-v, --verbose

output verbose log

Default: False

Sub-commands:

build-infra

build infrastructure, setup networks, global ip, firewall

hive build-infra [-h] [-H] [-D] [-C] [-l LIMIT_TARGET]

Named Arguments

-H, --halt

stop vpc/subnet/host

Default: False

-D, --destroy

destroy vpc/subnet/host

Default: False

-C, --check_mode

check mode of ansible

Default: False

-l, --limit_target

limit target

setup-hosts

setup hosts, install software, configure services, configure cluster

hive setup-hosts [-h] [-T TAGS] [-C] [-l LIMIT_TARGET]

Named Arguments

-T, --tags

select task

-C, --check_mode

check mode of ansible

Default: False

-l, --limit_target

limit target

build-images

build container images

hive build-images [-h] [-C] [-l LIMIT_TARGET]

Named Arguments

-C, --check_mode

check mode of ansible

Default: False

-l, --limit_target

limit target

build-volumes

build volumes on hives

hive build-volumes [-h] [-D] [-l LIMIT_TARGET]

Named Arguments

-D, --destroy

destroy volume

Default: False

-l, --limit_target

limit target

build-networks

build networks for swarm

hive build-networks [-h]

deploy-services

deploy services

hive deploy-services [-h] [-D] [-C] [-l LIMIT_TARGET]

Named Arguments

-D, --destroy

destroy service

Default: False

-C, --check_mode

check mode of ansible

Default: False

-l, --limit_target

limit target

initialize-services

initialize services

hive initialize-services [-h] [-C] [-l LIMIT_TARGET]

Named Arguments

-C, --check_mode

check mode of ansible

Default: False

-l, --limit_target

limit target

all

do all phase

hive all [-h]
         [-S {build-infra,setup-hosts,build-images,build-volumes,build-networks,deploy-services,initialize-services}]

Named Arguments

-S, --start_phase

Possible choices: build-infra, setup-hosts, build-images, build-volumes, build-networks, deploy-services, initialize-services

default start phase. before hive command execute a phase specified by command line, all preceeding phase are executed implicitly from this value. if success to execute the stage, then set persistently (saved into .hive/persistent_values.yml) the next stage to start_phase.

inventory

list ansible inventory

hive inventory [-h]

init

initialize hive environment

hive init [-h]

set

set hive variable persistently

hive set [-h] variable_name value

Positional Arguments

variable_name

variable name

value

variable value

ssh

ssh to hive server

hive ssh [-h] [-t SSH_HOST] [-z] [-Z FOWARD_ZABBIX_PORT] [-L PORT_FORWARDING]

Named Arguments

-t, --ssh_host

target host

-z, --foward_zabbix

if true, forward zabbix web console to localhost on ssh

Default: False

-Z, --foward_zabbix_port

port number for forwarding zabbix port

-L, --port_forwarding

port forwading on ssh

install-collection

install ansible collections

hive install-collection [-h]

変数

hiveコマンドは様々な変数を参照しながら動作します。変数の値は以下の順序で決定します。

  • root_dir にカレントディレクトリをセット

  • install_dir にhive がインストールされているディレクトリをセット

  • local_python_path に python コマンドの絶対パスをセット

  • コマンドラインで --root-dir が指定されている場合は、 root_dir にセット

  • context_dir に {root_dir}/.hive' をセット

  • 永続変数を {context_dir}/persistent_values.yml からロード

  • 変数stageの値が設定されていなければデフォルト値をセット

  • 永続変数でglobal値を持つものをセット

  • 永続変数でstage固有値を持つものをセット

  • コマンドラインの root_dir 以外の変数値をセット

  • デフォルト値のうちまだ設定されていないものをセット

  • フェーズを実行するサブコマンドの場合は phase 変数にサブコマンド名をセット

ログレベル

--verbose を指定するか set サブコマンドで verbose 変数に True を設定することでデバッグログを出力することができます。

.hive ディレクトリ

hive コマンドを実行するとカレントディレクトリの下に .hive ディレクトリが生成され、様々なコンテキストを保存します。 - .hive/persistent_values.yml にはhiveの永続変数が保存されます。

作業ディレクトリ

hive コマンドを実行すると/var/tmp/hiveディレクトリが生成され、hive の作業ディレクトリとして利用されます。

マザーマシンからサーバへのアクセス

マザーマシンからは各サーバの ssh にアクセスします。 build-infra の playbook では、処理の最後に ssh_config をコンテキストディレクトリに出力します。 以降の ansible からのssh アクセスはこのファイルに基づいて行われるため、サーバ名がDNSやhostsファイルで解決できる必要はありません。 build-images のフェーズでは、イメージ構築用の playbook をリポジトリサーバに転送してコンテナイメージを構築します。

ステージング

ステージングはインベントリ内でステージごとのグループを定義し、そのグループ名で対象となるホストを切り替えます。 ステージ名は hive コマンドの -s オプションでにより指定できます。 有効なステージの値は production, staging, private であり、ステージのデフォルト値は private です。

hive set stage ステージ名

を実行することで、以降のhiveコマンド実行時のステージを指定できます。 このコマンドにより、ステージ名が .hive/persistent_values.yml に保存されます

ステージングの切り替え

グループ名でインベントリ内のどのホストを対象とするかを切り替えるので、 同一の役割のホストでもステージが異なる場合はその名前が異なる必要があり、 staging ステージのホスト名には s-、 privaite ステージのホスト名には p- のプリフィックスを付与されます。 サービス、ボリューム、イメージ、ネットワークなどのリソースはデフォルトですべてのステージで有効です。available_on を指定して、 有効なステージを指定することができます。 プロジェクトのロール内でステージ固有の挙動を行う場合は、hive_stage 変数の値で挙動を切り替える必要があります。

hive コマンドを使わずに playbook を実行

hive コマンドを使わずに playbook を実行する場合は、ANSIBLE_CONFIG環境変数に/var/tmp/hive/ansible.cfgを 指定し、ansibleの変数を/var/tmp/hive/vars.ymlから読み込んでください。また、 -l オプションにステージ名を 指定し対象を絞り込んでください。 例えば、private ステージで test.yml を実行する場合は、 以下のように指定してください。

ANSIBLE_CONFIG=/var/tmp/hive/ansible.cfg ansible-playbook -e @/var/tmp/hive/vars.yml -l private test.yml

ただし、この場合、hiveの組み込み変数のいくつかが使えません。hive の組み込み変数を 参照したい場合は、playbook で以下のように変数の定義を読み込んでください。

vars_files:
- "{{ hive_playbooks_dir }}/group_vars/hosts.yml"

hive コマンドを使わずに ssh/scp を実行

hive コマンドを使わずに ssh/scp を実行する場合は、コンテキストディレクトリの ssh_config ファイルを 使用してください。例えば、hive0.pdns の /etc/hosts ファイルをカレントディレクトリにコピーする場合は、 以下のコマンドを実行してください。

scp -F .hive/production/ssh_config hive0.pdns:/etc/hosts .