General

YAML files - All yaml files should use 2 space indents and end with .yml
Variables - Use jinja variable syntax over deprecated variable syntax. {{ var }} not $var
Use spaces around jinja variable names. {{ var }} not {{var}}
Variables that are environment specific and that need to be overridden should be in ALL CAPS.
Variables that are internal to the role should be lowercase.
Prefix all variables defined in a role with the name of the role. Example: EDXAPP_FOO
Keep roles self contained - Roles should avoid including tasks from other roles when possible
Plays should do nothing more than include a list of roles except where pre_tasks and post_tasks are required (to manage a load balancer for example)
Plays/Playbooks that apply to the general community should be copied to configuration/playbooks
Plays/Playbooks that apply only to a specific organization (edx-east, edx-west) should be copied to a sub-directory under configuration/playbooks
Handlers - Do not use handlers. If you need to restart an app when specific tasks run, just add a task to do so at the end of the playbook. If necessary, it can be skipped with tags (see Role Life-cycle Tags)
Separators - Use underscores (e.g. my_role) not dashes (my-role).
Paths - When defining paths, do not include trailing slashes (e.g. my_path: /foo not my_path: /foo/. When concatenating paths, follow the same convention (e.g. {{ my_path }}/bar not {{ my_path }}bar)
Tag tasks using the tags described in Role Life-cycle Tags

Conditionals and Return Status

Always use when: for conditionals - To check if a variable is defined when: my_var is defined or when: my_var is not defined

To verify return status (see conditionals)

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

Formatting

Use yaml-style blocks.
Good:

  - file:
      dest: "{{ test }}"
	  src: "./foo.txt"
	  mode: 0770 
	  state: present
	  user: "root"
	  group: "wheel"

Bad:

- file: >
	dest={{ test }} src=./foo.txt mode=0770
	state=present user=root group=wheel

Break long lines using yaml line continuation.
Reference: http://docs.ansible.com/playbooks_intro.html

- shell: >
	python a very long command --with=very --long-options=foo
	--and-even=more_options --like-these

Roles

Role Variables

"common" role - Contains tasks that apply to all roles that are edX specific.
"common_vars" role - Contains vars that apply to all roles that are edX specific.
Roles variables - Variables specific to a role should be defined in /vars/main.yml. All variables should be prefixed with the role name.
Role defaults - Default variables should configure a role to install edx in such away that all services can run on a single server
Variables that are environment specific and that need to be overridden should be in all caps.

Every role should have a standard set of role directories, example that includes a python and 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"

Role Naming Conventions

Role names - Terse, one word if possible, use underscores if necessary.
Role task names - Terse, descriptive, spaces are OK and should be prefixed with the role name.

Secure vs. Insecure data

As a general policy we want to protect the following data:

Usernames
Public keys (keys are OK to be public, but can be used to figure out usernames)
Hostnames
Passwords, API keys

Directory structure for the secure repository:


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

Secure vars are set in files under the 'ansible/vars' directory. These files will be passed in when the relevant ansible-playbook commands are run. If you need a secure variable defined, give it a name and use it in your playbooks like any other variable. The value should be set in the secure vars files of the relevant deployment(edx, edge, etc.). If you don't have access to this repository, you'll need to submit a ticket to the devops team to make the secure change.

Browser not supported