Switch to fenced code blocks
This commit is contained in:
parent
838d9a41cd
commit
dcd50fdbcf
119
CONVENTIONS.md
119
CONVENTIONS.md
|
@ -4,26 +4,29 @@
|
||||||
|
|
||||||
We can use the `ansible-galaxy init` command to bootstrap a new role :
|
We can use the `ansible-galaxy init` command to bootstrap a new role :
|
||||||
|
|
||||||
$ ansible-galaxy init foo
|
```
|
||||||
- foo was created successfully
|
$ ansible-galaxy init foo
|
||||||
$ tree foo
|
- foo was created successfully
|
||||||
foo
|
|
||||||
├── defaults
|
$ tree foo
|
||||||
│ └── main.yml
|
foo
|
||||||
├── files
|
├── defaults
|
||||||
├── handlers
|
│ └── main.yml
|
||||||
│ └── main.yml
|
├── files
|
||||||
├── meta
|
├── handlers
|
||||||
│ └── main.yml
|
│ └── main.yml
|
||||||
├── README.md
|
├── meta
|
||||||
├── tasks
|
│ └── main.yml
|
||||||
│ └── main.yml
|
├── README.md
|
||||||
├── templates
|
├── tasks
|
||||||
├── tests
|
│ └── main.yml
|
||||||
│ ├── inventory
|
├── templates
|
||||||
│ └── test.yml
|
├── tests
|
||||||
└── vars
|
│ ├── inventory
|
||||||
└── main.yml
|
│ └── test.yml
|
||||||
|
└── vars
|
||||||
|
└── main.yml
|
||||||
|
```
|
||||||
|
|
||||||
All `main.yml` file will be picked up by Ansible automatically, with respect to their own responsibility.
|
All `main.yml` file will be picked up by Ansible automatically, with respect to their own responsibility.
|
||||||
|
|
||||||
|
@ -35,9 +38,12 @@ The main directory is `tasks`. It will contains tasks, either all in the `main.y
|
||||||
|
|
||||||
`files` is the directory where we'll put files to copy on hosts. They will be copied "as-is". When a role has multiple logical groups of tasks, it's best to create a sub-directory for each group that needs files. The name of files in these directories doesn't have to be the same as the destination name. Example :
|
`files` is the directory where we'll put files to copy on hosts. They will be copied "as-is". When a role has multiple logical groups of tasks, it's best to create a sub-directory for each group that needs files. The name of files in these directories doesn't have to be the same as the destination name. Example :
|
||||||
|
|
||||||
copy:
|
```
|
||||||
src: apt/jessie_backports_preferences
|
copy:
|
||||||
dest: /etc/apt/apt.conf.d/backports
|
src: apt/jessie_backports_preferences
|
||||||
|
dest: /etc/apt/apt.conf.d/backports
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
`templates` is the twin brother of `files`, but differs in that it contains files that can be pre-processed by the Jinja2 templating language. It can contain variables that will be extrapolated before copying the file to its destination.
|
`templates` is the twin brother of `files`, but differs in that it contains files that can be pre-processed by the Jinja2 templating language. It can contain variables that will be extrapolated before copying the file to its destination.
|
||||||
|
|
||||||
|
@ -59,19 +65,23 @@ We create roles (instead of a plain tasks files) when it makes sense as a whole,
|
||||||
|
|
||||||
It's possible to use a compact (Ansible specific) syntax,
|
It's possible to use a compact (Ansible specific) syntax,
|
||||||
|
|
||||||
- name: Add evomaintenance trap for '{{ user.name }}'
|
```
|
||||||
lineinfile: state=present dest='/home/{{ user.name }}/.profile' insertafter=EOF line='trap "sudo /usr/share/scripts/evomaintenance.sh" 0'
|
- name: Add evomaintenance trap for '{{ user.name }}'
|
||||||
when: evomaintenance_script.stat.exists
|
lineinfile: state=present dest='/home/{{ user.name }}/.profile' insertafter=EOF line='trap "sudo /usr/share/scripts/evomaintenance.sh" 0'
|
||||||
|
when: evomaintenance_script.stat.exists
|
||||||
|
```
|
||||||
|
|
||||||
but we prefer the pure-YAML syntax
|
but we prefer the pure-YAML syntax
|
||||||
|
|
||||||
- name: Add evomaintenance trap for '{{ user.name }}'
|
```
|
||||||
lineinfile:
|
- name: Add evomaintenance trap for '{{ user.name }}'
|
||||||
state: present
|
lineinfile:
|
||||||
dest: '/home/{{ user.name }}/.profile'
|
state: present
|
||||||
insertafter: EOF
|
dest: '/home/{{ user.name }}/.profile'
|
||||||
line: 'trap "sudo /usr/share/scripts/evomaintenance.sh" 0'
|
insertafter: EOF
|
||||||
when: evomaintenance_script.stat.exists
|
line: 'trap "sudo /usr/share/scripts/evomaintenance.sh" 0'
|
||||||
|
when: evomaintenance_script.stat.exists
|
||||||
|
```
|
||||||
|
|
||||||
Here are some reasons :
|
Here are some reasons :
|
||||||
|
|
||||||
|
@ -86,6 +96,14 @@ Here are some reasons :
|
||||||
|
|
||||||
When a role is using variables, they must be defined (for example in the `defaults/main.yml`) with a default value (possibly Null). That way, there will never be a "foo is undefined" situation.
|
When a role is using variables, they must be defined (for example in the `defaults/main.yml`) with a default value (possibly Null). That way, there will never be a "foo is undefined" situation.
|
||||||
|
|
||||||
|
If a variable can't have a default value, it must be marked as [mandatory](http://docs.ansible.com/ansible/playbooks_filters.html#forcing-variables-to-be-defined). Example :
|
||||||
|
|
||||||
|
```
|
||||||
|
- name: Setting default timezone
|
||||||
|
lineinfile:
|
||||||
|
line: "{{ evolinux_system_timezone | mandatory }}"
|
||||||
|
```
|
||||||
|
|
||||||
### progressive specificity
|
### progressive specificity
|
||||||
|
|
||||||
In many roles, we use a *progressive specificity* pattern for some variables.
|
In many roles, we use a *progressive specificity* pattern for some variables.
|
||||||
|
@ -93,14 +111,18 @@ The most common is for "alert_email" ; we want to have a default email address w
|
||||||
|
|
||||||
For the *evolinux-base* role we have those defaults :
|
For the *evolinux-base* role we have those defaults :
|
||||||
|
|
||||||
general_alert_email: "root@localhost"
|
```
|
||||||
reboot_alert_email: Null
|
general_alert_email: "root@localhost"
|
||||||
log2mail_alert_email: Null
|
reboot_alert_email: Null
|
||||||
raid_alert_email: Null
|
log2mail_alert_email: Null
|
||||||
|
raid_alert_email: Null
|
||||||
|
```
|
||||||
|
|
||||||
In the *log2mail* template, we set the email address like this :
|
In the *log2mail* template, we set the email address like this :
|
||||||
|
|
||||||
mailto = {{ log2mail_alert_email or general_alert_email | mandatory }}
|
```
|
||||||
|
mailto = {{ log2mail_alert_email or general_alert_email | mandatory }}
|
||||||
|
```
|
||||||
|
|
||||||
If nothing is customized, the mail will be sent to root@localhost, if general_alert_email is changed, it will be used, but if log2mail_alert_email is set to a non-null value, it will have precedence.
|
If nothing is customized, the mail will be sent to root@localhost, if general_alert_email is changed, it will be used, but if log2mail_alert_email is set to a non-null value, it will have precedence.
|
||||||
|
|
||||||
|
@ -142,18 +164,21 @@ We try not to alter configuration files managed by packages. It makes upgrading
|
||||||
|
|
||||||
We usually put a `z-evolinux-defaults` with our core configuration. This file can be changed later via Ansible and must not be edited by hand. Example :
|
We usually put a `z-evolinux-defaults` with our core configuration. This file can be changed later via Ansible and must not be edited by hand. Example :
|
||||||
|
|
||||||
copy:
|
```
|
||||||
src: evolinux-defaults.cnf
|
copy:
|
||||||
dest: /etc/mysql/conf.d/z-evolinux-defaults.cnf
|
src: evolinux-defaults.cnf
|
||||||
force: yes
|
dest: /etc/mysql/conf.d/z-evolinux-defaults.cnf
|
||||||
|
force: yes
|
||||||
|
```
|
||||||
|
|
||||||
We also create a blank `zzz-evolinux-custom` file, with commented examples, to allow custom configuration that will never be reverted by Ansible. Example :
|
We also create a blank `zzz-evolinux-custom` file, with commented examples, to allow custom configuration that will never be reverted by Ansible. Example :
|
||||||
|
|
||||||
copy:
|
```
|
||||||
src: evolinux-custom.cnf
|
copy:
|
||||||
dest: /etc/mysql/conf.d/zzz-evolinux-custom.cnf
|
src: evolinux-custom.cnf
|
||||||
force: no
|
dest: /etc/mysql/conf.d/zzz-evolinux-custom.cnf
|
||||||
|
force: no
|
||||||
|
```
|
||||||
|
|
||||||
The source file or template shouldn't to be prefixed for ordering (eg. `z-` or `zzz-`). It's the task's responsibility to choose how destination files must be ordered.
|
The source file or template shouldn't to be prefixed for ordering (eg. `z-` or `zzz-`). It's the task's responsibility to choose how destination files must be ordered.
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue