Ansible コーディング規約 (の例)

(これは http://tdoc.info/blog/2014/10/09/ansible_coding.html の転載です)

edX
がgithub上でAnsibleのコーディング規約を公開しています。

このリポジトリは GNU
AGPLv3です。翻訳の場合でもおそらく大丈夫だと思いますので、ここで翻訳して公開してみます。

一般

YAMLファイル

すべてのyamlファイルは2スペースのインデントで、 .yml を拡張子に
付けてください。
変数

jinja変数の形式を使ってください。 $var ではなく {{ var }} です。
jinjaの変数名の前後に空白を入れてください。 {{var}} ではなく
{{ var }} です。
環境独自で上書きされる必要がある変数名は全部大文字としてください。
ロール内で完結する変数名は全部小文字としてください。
ロール内で定義する変数名は、先頭にロール名を付けてください。例:
EDXAPP_FOO
ロールを自己完結型にしてください。

ロールは可能な限り他のロールからタスクをincludeしないでください。
Playbookはロールのリストをincludeする以上のことはしないでください。

ただし、pre_tasksとpost_tasksが必要な場合は使ってください。(例えばロー
ドバランサーの管理など)
一般的なコミュニティに適用するPlaybookは configuration/playbooksにお
いてください (訳注: edX独自の話)。
特定の組織(edx-east, edx-west)に適用するPlaybookは
configuration/playbooksの下にサブディレクトリを作り、そこに置いてく
ださい (訳注: edx独自の話)。
テスト

自動化された統合テストは test.yml というplaybookをincludeしてく
ださい。また、 run_tests という変数を使ってテストかどうかを確認
するようにしてください。
デプロイ

アプリケーションの更新には、 service stop で始まり、
service start で終わる一連のタスクを含む deploy.yml
をincludeしてください。 deploy.yml の中の各タスクには deploy
というタグを付けてください。
deploy.yml 内のタスクの他に、アプリケーションの状態に影響するよ
うなタスクは記述しないでください。
deploy.yml 内のすべてのタスクは限定されたsudo権限を持つユーザー
で実行できるようにし、root権限が要求されないようにしてください。
Handlers

各ロールはサービスを再起動する必要があるmain.yml内のタスクのために、一つ以上のhandlerを持つ必要があります。

条件式と返り値

常に when: を使ってください。

変数が設定されているかどうかを調べる場合は when: my_var is defined
か when: my_var is not defined を使います。

返り値を調べるにはこうします。

- command: /bin/false
  register: my_result
  ignore_errors: True
- debug: msg="task failed"
  when: my_result|failed

フォーマット

長い行はYAMLの行継続を利用して改行してください。

- debug: >
    msg={{ test }}

あるいは、ansibleではこうも書けます。

- debug:
    msg: "{{ test }}"

ロール

ロール変数

group_vars/all

すべてのロールに適用される変数を定義してください。
"common" ロール

edX独自のすべてのロールに適用される変数とタスクを定義してください。
ロール変数

ロール独自の変数は /var/main.yml に定義してください。すべての変数名
にはロール名を先頭に付けてください。
ロールdefaults

ロールのデフォルト変数は、単一サーバーですべてのサービスが動くように
設定されているべきです。
環境独自で、上書きされる必要がある変数は全部大文字で定義してください。

すべてのロールはロールが持つ標準的なディレクトリを一通り持ってくださ
い。下記はpythonとrubyのvirtualenvの例です。

edxapp_data_dir: "{{ COMMON_DATA_DIR }}/edxapp"
edxapp_app_dir: "{{ COMMON_APP_DIR }}/edxapp"
edxapp_log_dir: "{{ COMMON_LOG_DIR }}/edxapp"
edxapp_venvs_dir: "{{ edxapp_app_dir }}/venvs"
edxapp_venv_dir: "{{ edxapp_venvs_dir }}/edxapp"
edxapp_venv_bin: "{{ edxapp_venv_dir }}/bin"
edxapp_rbenv_dir: "{{ edxapp_app_dir }}"
edxapp_rbenv_root: "{{ edxapp_rbenv_dir }}/.rbenv"
edxapp_rbenv_shims: "{{ edxapp_rbenv_root }}/shims"
edxapp_rbenv_bin: "{{ edxapp_rbenv_root }}/bin"
edxapp_gem_root: "{{ edxapp_rbenv_dir }}/.gem"
edxapp_gem_bin: "{{ edxapp_gem_root }}/bin"

ロール名の慣習

ロール名

簡潔で、可能な限り一単語にしてください。必要であれば _ を使ってく
ださい。
ロールのタスク名

簡潔で、説明的にしてください。空白はOKです。ロール名を先頭につけてくだ
さい。(訳注:
実行時にロール名も表示されるので、ロール名を付ける必要はないかと思いますが…)
ロールhandler

簡潔で、説明的にしてください。空白はOKです。ロール名を先頭につけてくだ
さい。(訳注: 同上)

セキュア vs セキュアじゃないデータ

基本的なポリシーとして、以下のデータは保護される必要があります。

ユーザー名
公開鍵

鍵そのものは公開OKでも、ユーザー名を推測される可能性があります
ホスト名
パスワード、APIキー

安全なリポジトリのディレクトリ構造です。

ansible
├── files
├── keys
└── vars

secure_dir は group_vars/all に置き、 group_vars内のグループ名
を使う他のファイルが必要に応じて上書きします。

安全である必要がある、テンプレートやファイルには first_available_file
を使います。

- name: install read-only ssh key for the content repo that is required for grading
  copy: src={{ item }} dest=/etc/git-identity force=yes owner=ubuntu group=adm mode=60
  first_available_file:
    - "{{ secure_dir }}/files/git-identity"
    - "git-identity-example"

まとめ

必ずしもこの規約が適しているとは限りませんが、参考になればと思います。

なお、edXのリポジトリにはplaybookが大量に公開されていますので、一度目を
通してみると、発見があるかもしれません。