Ansible best practices and coding guidelines

Ansible best practices (coding standards)

Why ansible not scripts

Ansible is the preferred way as YAML will allow us to create homogenous environment for different OS platforms with easily defined standards, which will be easy to understand and contribute to. Ansible allows for asset reuse - by leveraging already existing ansible modules and code which can be swiftly integrated into newly created playbooks because they share the same interface which can’t be said about custom written shell scripts.

Variables naming convention

• Ansible code should follow standards defined by YAML coding standard and adhering to standard defined in Ansible docs: variable names and YAML syntax
• Local variable names should be lower case, using underscores when necessary. Dashes, spaces, dots will be frown upon. Example of a valid variable names are:

  foo
  foo2
  foo_address
  user_name
  

• Use human readable variable names with prefixes allowing the reader to easily group them logically:

  http_address
  http_port
  user_name
  user_password
  

• Environment-wide variables, or overridable variables should be named all uppercase, for example: USER_NAME
• Role variables should start with role name prefix for example:

  hardening_user_name
  hardening_user_password
  

  Use built in standard modules instead of shell

  As a general rule – it is always better idea to use dedicated modules to satisfy the goal of Your ansible playbook than executing anything remotely with shell, command, raw or script modules. These run-like commands have little logic to them and no concept of desired state (the base idea of Ansible). That command that succeeded the first time you ran your play, may fail the next time when something already exists.

Additionally a code using them is hard to maintain and future-proof, as users can’t always know what could’ve been changed in the remote binary after new release for example. So a patching on a target system can update the binary executed locally with the Ansible shell module so it no longer works correctly. Therefore ansible modules should be used whenever possible, as they provide a stable coding interface for their creator, and any changes in the modules can be tracked in the ansible code base.

If You have a need that is not covered by an existing module, consider developing your own Ansible module. Modules abstract users away from the complexity of implementation details.

For a great detailed guide on how to write your own Ansible modules please see : https://docs.ansible.com/ansible/latest/dev_guide/developing_modules.html https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html

Naming convention (best practices)

• All the tasks inside the ansible playbook have to be named, this comes in handy especially when debugging.
• Task names should be short but informative, for example: install apache packages, start apache service.
• Playbook names should start uppercase and not contain dashes, spaces or underscores. Exmaple of a valid playbook name: CertificateCleanup.yml

  Roles:

• Use roles to group related tasks - for example when deploying an application, separate activities, default values and other variables can be grouped as a role.
• Role should provide standardized directory structure to keep the code base clean, follow https://docs.ansible.com/ansible/devel/user_guide/playbooks_reuse_roles.html Example:

                    site.yml
                    webservers.yml
                    fooservers.yml
                    roles/
                    common/
                        tasks/
                        handlers/
                        files/
                        templates/
                        vars/
                        defaults/
                        meta/
                    webservers/
                        tasks/
                        defaults/
                        meta/
  

• Following ansible documentation: roles expect files to be in certain directory names. Roles must include at least one of these directories, however it is perfectly fine to exclude any which are not being used. When in use, each directory must contain a main.yml file, which contains the relevant content:

                tasks - contains the main list of tasks to be executed by the role.
                handlers - contains handlers, which may be used by this role or even anywhere outside this role.
                defaults - default variables for the role (see Using Variables for more information).
                vars - other variables for the role (see Using Variables for more information).
                files - contains files which can be deployed via this role.
                templates - contains templates which can be deployed via this role.
                meta - defines some meta data for this role. See below for more details.
  

• K.I.S.S. - tasks in a role should break complicated activities into simple pieces for reusability

Readability

The code should be written in such a way, that when you read it, you feel like you read the automation documentation. Follow the below described best practices to accomplish this goal:

• start your each playbook with the three dashes followed by a blank line; always end your files with a newline
• always quote strings ( prefer single quotes over double ones ); use double quotes only when they are nested within single quotes or when your string requires escaping characters; avoid quoting of Booleans and numbers; make sure to quote filenames in the include statements
• it is always the good idea to add a commented comment at the top, which will describe the purpose of the playbook usage
• ansible is the language which is heavily depending on the indentation, so remember to indent correctly ( 2 spaces ); also child elements should be indented with 2 spaces from their parents
• use snake_case for variable names ( so name your variables in such a way that elements are separated with one underscore character and no spaces )
• comments are strongly recommended ( it’s good to comment it before you forget how it works ); put the single space after hash tag for better readability; put one line of whitespace before you start a comment block; for inline comments, remember to begin after the appropriate indentation, related to the current block indentation
• use the native YAML syntax when assigning values so instead of using this:

  template: src=itim.conf.j2 dest=/etc/itim/itim.conf
  

  you’d better use this:

   template:
    src: telegraf.conf.j2
    dest: /etc/telegraf/telegraf.conf
  

• always name your tasks; remember to use meaningful names, which will wholly describe the task goal but – on the other hand – try to laconic enough
• put the tags to your tasks
• encode your playbooks with UTF-8
• use prefixes and human meaningful names with your variables