このエントリーをはてなブックマークに追加

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

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

https://github.com/edx/configuration/wiki/Ansible-Coding-Conventions

このリポジトリは 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 definedwhen: 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_dirgroup_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が大量に公開されていますので、一度目を通してみると、発見があるかもしれません。