|
| 1 | +## Debugging Ansible Automation for AEM |
| 2 | + |
| 3 | +Hints for debugging the [Automation for AEM][ansible-aem]. |
| 4 | + |
| 5 | + |
| 6 | +### Ansible verbose mode |
| 7 | + |
| 8 | +Ansible Commands support the verbose flag |
| 9 | + |
| 10 | +``` |
| 11 | +-v # simple verbose output |
| 12 | +-vv # more verbose |
| 13 | +-vvv # even more verbose |
| 14 | +-vvvv # connection debugging |
| 15 | +-vvvvv # even more verbose, and so on |
| 16 | +``` |
| 17 | + |
| 18 | +Which each added "v" the verbosity increases (and the readability decreases). |
| 19 | + |
| 20 | +It is recommened to write the output to a file like: |
| 21 | + |
| 22 | +``` |
| 23 | +ansible-playbook playbook-setup-prod.yml | tee ansible.log |
| 24 | +``` |
| 25 | + |
| 26 | +### Use \-\-skip-tags |
| 27 | + |
| 28 | +If you want to speed up debugging and want to skip the tasks/roles that are working use the parameter |
| 29 | + |
| 30 | +``` |
| 31 | +--skip-tags aem-cms,aem-dispatcher |
| 32 | +``` |
| 33 | + |
| 34 | +When working with the Conga Ansible IT Automation it is recommended to skip the compile process of the wcm_io_devops.conga_maven role to save time |
| 35 | + |
| 36 | +``` |
| 37 | +--skip-tags conga-maven-compile |
| 38 | +``` |
| 39 | + |
| 40 | +For more information refer to: https://docs.ansible.com/ansible/2.6/user_guide/playbooks_tags.html |
| 41 | + |
| 42 | +### Use \-\-start-at-task |
| 43 | + |
| 44 | +If you want to start the playbook at a particula task you can use the --start-at-task option: |
| 45 | + |
| 46 | +``` |
| 47 | +ansible-playbook playbook-setup-prod.yml --start-at-task="Download AEM quickstart." |
| 48 | +``` |
| 49 | + |
| 50 | +### Execute interactively |
| 51 | + |
| 52 | +If you want to inspect the result of each task you can run the playbook with the --step option: |
| 53 | + |
| 54 | +``` |
| 55 | +ansible-playbook playbook-setup-prod.yml --step |
| 56 | +``` |
| 57 | + |
| 58 | +This will cause Ansible to stop on each task if it should execute that task. |
| 59 | + |
| 60 | +### Enable debug logs |
| 61 | + |
| 62 | +Ansible is for example hiding the Maven log output. When an error occurs the log-output will be shown. |
| 63 | + |
| 64 | +#### wcm_io_devops.conga_aem_packages |
| 65 | + |
| 66 | +This role supports the logging of the current maven output to a file which then can be "tailed". |
| 67 | + |
| 68 | +Refer to: |
| 69 | + |
| 70 | +* https://github.com/wcm-io-devops/ansible-conga-aem-packages and |
| 71 | +* https://github.com/wcm-io-devops/ansible-conga-aem-packages/blob/master/defaults/main.yml#L27-L31 |
| 72 | + |
| 73 | +For more information. |
| 74 | + |
| 75 | +## Advanced Debugging |
| 76 | + |
| 77 | +### Manipulating Roles |
| 78 | + |
| 79 | +Ansible looks per default in the following pathes to search for roles |
| 80 | + |
| 81 | +* `roles` directory, relative to the playbook file. |
| 82 | +* By default, in `/etc/ansible/roles` |
| 83 | + |
| 84 | +This behavior becomes handy when you want to debug a role in your current project. |
| 85 | + |
| 86 | +#### Example for wcm_io_devops.conga_aem_packages role |
| 87 | + |
| 88 | +_Prepare role for local manipulation_ |
| 89 | +``` |
| 90 | +# switch into the ansible playbook dir |
| 91 | +mkdir roles && cd roles |
| 92 | +git clone https://github.com/wcm-io-devops/ansible-conga-aem-packages.git && git checkout 1.0.0 |
| 93 | +``` |
| 94 | + |
| 95 | +With this setup the role "wcm_io_devops.conga_aem_packages" will be loaded from the roles directory. |
| 96 | + |
| 97 | +You can then start manipulating the role e.g. by adding debug statements, manual inputs and fail statements to avoid continuing of the play. |
| 98 | + |
| 99 | +_Example: Output content of conga_config and continue_ |
| 100 | + |
| 101 | +```yaml |
| 102 | +- name: Debug conga_config |
| 103 | + debug: |
| 104 | + msg: |
| 105 | + - conga_config |
| 106 | + - "{{ conga_config }}" |
| 107 | + |
| 108 | +- fail: |
| 109 | + msg: do not continue |
| 110 | +``` |
| 111 | +
|
| 112 | +_Example: Wait for user input_ |
| 113 | +
|
| 114 | +```yaml |
| 115 | +- name: "Wait for user input" |
| 116 | + prompt: "Continue?" |
| 117 | +``` |
| 118 | +
|
| 119 | +Links: |
| 120 | +
|
| 121 | +* https://docs.ansible.com/ansible/2.6/modules/fail_module.html |
| 122 | +* https://docs.ansible.com/ansible/2.6/modules/debug_module.html |
| 123 | +* https://docs.ansible.com/ansible/2.6/user_guide/playbooks_prompts.html |
| 124 | +
|
| 125 | +
|
| 126 | +### Playbook Debugger |
| 127 | +
|
| 128 | +When you are using Ansible 2.5+ you can use the Playbook Debugger<br/> |
| 129 | +https://docs.ansible.com/ansible/2.5/user_guide/playbooks_debugger.html |
| 130 | +
|
| 131 | +
|
| 132 | +[ansible-aem]: http://devops.wcm.io/ansible-aem/ |
0 commit comments