How to be an Ansible Contributor

Step-by-Step
John McDonough
Cisco DevNet – Developer Advocate
My automation story

1. How did you get started with Ansible?

I signed up to teach a workshop for Cisco UCS and Ansible so I had
to learn it.

2. How long have you been using it?

Almost Three years

3. What's your favorite thing to do when you Ansible?

Eat a sandwich and provision a server.
John McDonough
Cisco DevNet - Developer Advocate

John Works for Cisco DevNet

John Writes Code
John Talks about Code
John Talks about Writing Code
John Writes OK Code and Talks Pretty Good Well
John Contributes to Ansible
How to be an Ansible Contributor
• What Do I Know About Ansible?
• Read Some Docs
• Fork Ansible on Github
• Setup Your Development Environment
• Read Some Docs… again
• Create an Ansible Module
• Read Some Docs… again
• Read Some Docs… again and again!
• Submit a Pull Request
• Read Some Docs… again
• Sync Your Fork
• Delete Your Branch
What Do I Know About Ansible?
What Do I know About Ansible?

• Not that Much … but it's Enough!

• I know how to
– Install Ansible
– Create/Run Ansible playbooks
– Run Ansible in very very very verbose mode
– Write Python Code (can be other languages, python is best)
– Use github.com and git
– Google Stuff
 Read Some Docs

https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html
 Read Some Docs

Someone wrote these Docs for you!

Don't make them Ugly Cry!
https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html
 Read Some Docs

Someone wrote these Docs for you! Don't make them Ugly Cry!
https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html
Fork Ansible on Github
 Fork Ansible (docs say clone – I say fork)

• Forking a Github repository is

– Making a copy of that repository on github under YOUR account
– At that point in time
– Awareness of the original but not updated by the original
• https://github.com/ansible/ansible
– Fork is not a git command and is done in the github.com interface
• hub – git from the command line - https://hub.github.com/
• hub is an extension to command-line git do everyday GitHub tasks without ever leaving the terminal.
 Fork Ansible (docs say clone – I say fork)

Their Code Your Fork

• Forking a Github repository is

– Making a copy of that repository on github under YOUR account
– At that point in time
– Awareness of the original but not updated by the original
• https://github.com/ansible/ansible
– Fork is not a git command and is done in the github.com interface
• hub – git from the command line - https://hub.github.com/
• hub is an extension to command-line git do everyday GitHub tasks without ever leaving the terminal.
Setup Your Development
Environment
Setup Your Development Environment
• Clone YOUR Forked Code NOT the Ansible Code!
– $ git clone https://github.com/johnamcdonough/ansible.git
• Setup a Python Virtual Environment in the ansible Directory
– $ cd ansible
– Python 3 $ python3 -m venv venv
– Python 2 $ virtualenv venv
• Requires virtualenv $ pip install virtualenv

• Activate the Virtual Environment

– $ . venv/bin/activate
• Install the Development Requirements
– $ pip install -r requirements.txt
• Run the Development Environment Setup Script
– $ . hacking/env-setup
Setup Your Development Environment
Setup Your Development Environment
Setup Your Development Environment
Setup Your Development Environment
Setup Your Development Environment
 Read Some Docs … again

https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general.html#common-environment-setup
 Read Some Docs … again

https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general.html#common-environment-setup
Create an Ansible Module
Create an Ansible Module
• Be concise – "Do One Thing Well"
• A user does not need to know all the options
• Encompass much of the logic for a resource
• Think CRUD (Create / Read / Update / Delete)
– Or DRUC, CURD, URCD, DURC, RUCD, etc.
– Whatever seems to work best!
Create an Ansible Module
• 'cd' to the desired directory or create a new directory
• Create a new file
• Use the "New module development" Template
• Test the Module
– Locally – JSON formatted ANSIBLE_MODULE_ARGS file
– Playbook – YAML formatted playbook
• Run Sanity Tests
• Create/Run Unit Tests
Read Some Docs … again

https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#starting-a-new-module
 Read Some Docs … again and again

https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#contributing-back-to-ansible
 Read Some Docs … again and again

https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html#contributing-back-to-ansible
Submit a Pull Request
Create an Ansible Module – Revised
• Create feature branch
• 'cd' to the desired directory or create a new directory
• Create a new file
• Use the "New module development" Template
• Test the Module
– Locally
– Playbook
• Run Sanity Tests
• Create Unit Tests
• Commit and Push YOUR Code to YOUR feature branch
• Create Pull Request
Submit a Pull Request

• Pull Requests can only be submitted against one

module
• One feature branch per Pull Request
– git checkout -b <feature branch name> 🡨 Create
– git branch 🡨 List branches
Read Some Docs … again

https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/index.html
Submit a Pull Request
Submit a Pull Request
Submit a Pull Request – After the Click
• Automated testing happens

• Your code will probably fail

– Fix it
– Commit it
– Push it
• Automated Testing Happens
– You do not need to submit a new Pull Request!!!!
Submit a Pull Request – Reviewers
• When your code is "Good" it will be merged… maybe.
• There are reviewers and maintainers that need to approve your code
– They will recommend changes
– They will hurt your feelings
– They will break you!
– They will help you be better!
• Make the changes that are requested
– Commit it
– Push it
• Automated Testing Happens
– You do not need to submit a new Pull Request!!!!
Submit a Pull Request

• Your Code Passes Tests!

• Your Code is marked shipit!
• Your Code is Merged!
Submit a Pull Request

• Your Code Passes Tests!

• Your Code is marked shipit!
• Your Code is Merged!

• Wait you're not done yet!

Sync Your Fork
Sync Your Fork
git remote add upstream https://github.com/ansible/ansible.git
git remote –v 🡨 what are your remotes
Only need to add the upstream once

git fetch upstream 🡨 fetch the current ansible/devel

git checkout devel 🡨 checkout YOUR devel
git merge upstream/devel 🡨 merge ansible/devel to YOUR devel
git push origin devel 🡨 push YOUR devel to YOUR Ansible fork

https://help.github.com/articles/syncing-a-fork/
Delete Your Branch
• git branch -d branch1 <--- locally
• git push origin :branch1 <--- remote

• Do it all over again for your next module

Links
• Red Hat
– How to Make Your Mark: Ansible Community Contributions -
https://www.ansible.com/resources/webinars-training/how-to-make-ansible-community-contributions
– Ansible Module Development video - https://github.com/nitzmahone/ansible-modules-101
– Ansible Module Development 101 github - https://www.ansible.com/ansible-module-development-101

• Ansible Links:
– Ansible on Github - https://github.com/ansible/ansible
– Ansible module development: getting started -
https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general.html
– Testing Ansible - https://docs.ansible.com/ansible/devel/dev_guide/testing.html

• Learning
– DevNet Learning Labs an introduction - https://developer.cisco.com/learning/modules/sdx-ansible-intro
– DevNet Learning Labs a bunch of labs - https://developer.cisco.com/learning/modules?keywords=ansible
Got Questions? This is where I'm at!
jomcdono@cisco.com
@johnamcdonough
http://github.com/movinalot

@CiscoDevNet
facebook.com/ciscodevnet
http://github.com/CiscoDevNet
https://developer.cisco.com/join/ansiblefest20