cleanup and comments

Author: nickrusso42518

.travis.yml

@@ -1,17 +1,20 @@
 ---
-language: python
+# Define the language and version used. The CI system will create
+# a Python virtualenv for this particular version for the test.
+language: "python"
 python:
   - "2.7"
 
-# Install python packages for ansible and linters.
+# Install python packages for ansible and linters first.
 install:
   - "pip install -r requirements.txt"
 
-# Execute linting and unit tests before running the main playbook.
+# Execute linting to catch minor errors before running the main playbook.
+# If you have a directory hierarchy, use this style instead:
+# "find . -name '*.yml' | xargs yamllint -s"
 before_script:
-  - "find . -name '*.yml' | xargs yamllint -s"
-  - "export ANSIBLE_HOST_KEY_CHECKING=False"
+  - "yamllint -s *.yml"
 
-# Perform playbook testing with mock CI inputs.
+# Perform playbook testing with on a pre-existing virtual router.
 script:
-  - "ansible-playbook test_playbook.yml -i hosts.yml"
+  - "ansible-playbook test.yml"

README.md

@@ -2,5 +2,5 @@
 https://travis-ci.org/nickrusso42518/slt-netdevops.svg?branch=master)](
 https://travis-ci.org/nickrusso42518/slt-netdevops)
 
-# Safari Live Training - Foundations of Network DevOps
+# Safari Live Training - Network DevOps
 Actively in development ... check back soon!

ansible.cfg

@@ -0,0 +1,15 @@
+# This configuration file identifies general settings
+# for the Ansible environment.
+[defaults]
+
+# Where to find the list of hosts
+inventory = hosts.yml
+
+# Disable general-purpose information collection on control machine
+gathering = explicit
+
+# Disable SSH "known_host" key checking; helps with CI
+host_key_checking = False
+
+# Use the "network_cli" transport for default; helps for network devices
+transport = network_cli

hosts.yml

@@ -1,9 +1,23 @@
 ---
+# The "all" group is at the top of the hierarchy and encompasses
+# all other hosts and subgroups. This particular inventory is
+# simplified and contains no subgroups.
 all:
   hosts:
+    # The list of hosts contained in the "all" group. These
+    # can be real DNS hostnames, local host mappings, or IP
+    # addresses.
     csr1.njrusmc.net:
     # csr2.njrusmc.net:
   vars:
+    # These are group-level variables associated with the "all"
+    # group. Ansible gives many options with respect to variable
+    # playment, but for a simple example playbook, embedding them in
+    # the inventory file is acceptable. The "ansible_*" variables
+    # serve as input for the "network_cli" transport method
+    # which allow Ansible to connect to our routers. The "ntp_*"
+    # variables are user-defined and represent that NTP servers we
+    # are configuring in our main playbook.
     ansible_network_os: "ios"
     ansible_user: "ansible"
     ansible_ssh_pass: "ansible"

ntp_config.yml

@@ -0,0 +1,61 @@
+---
+# This is a play, which is an element in the playbook.
+# A playbook is a list of plays, and each play runs on
+# a subset of hosts in the inventory. This specific play
+# runs on all inventory devices. If there was a diverse set
+# of hosts, such as routers, firewalls, and wireless LAN
+# controllers, each one may have different NTP configuration
+# syntax and could use different plays.
+- name: "PLAY 1: Manage NTP configuration"
+  hosts: "all"
+  tasks:
+
+    # This is the first task, and each play generally contains
+    # a list of tasks. The task is a set of actions to execute
+    # against each host specified within the play. This task
+    # checks the data input quality, ensuring that the two
+    # NTP servers are defined and are valid IPv4 addresses.
+    # This task uses the "assert" module as a way of integrating
+    # testing within a playbook.
+    - name: "TASK 1: Validate NTP server IP addresses"
+      assert:
+        that:
+          - "ntp_server1 is defined"
+          - "ntp_server2 is defined"
+          - "ntp_server1 | ipv4 == ntp_server1"
+          - "ntp_server2 | ipv4 == ntp_server2"
+        msg: "Malformed input; please check ntp_server values"
+
+    # This is the second task. It logs into the Cisco IOS or
+    # IOS-XE device using the "ios_config" module. The commands
+    # specified within that module are passed to the router, and
+    # the NTP server values are substituted using {{ }} syntax.
+    # The previous task verified that these servers were valid,
+    # so the router CLI should not report any errors.
+    # The "register" directive tells Ansible to "save" the
+    # feedback from the module, which provides us a list of which
+    # commands needed to be added (between 0 and 4 in this case),
+    # whether there were any failures, and more.
+    - name: "TASK 2: Apply NTP updates"
+      ios_config:
+        commands:
+          - "ntp authenticate"
+          - "ntp logging"
+          - "ntp server {{ ntp_server1 }}"
+          - "ntp server {{ ntp_server2 }}"
+      register: "ntp_updates"
+
+    # This is the third task. If any new changes were configured
+    # on the router (for example, "ntp logging" had been accidentally
+    # disabled before running the playbook), those delta commands
+    # are printed to stdout so the user sees them. This only occurs
+    # if there are changes due to the "when" directive. If the "when"
+    # evaluates to false, the task is skipped. The task will only
+    # be false when the registered variable from the previous task
+    # does not define the "updates" subfield, which indicates no
+    # changes were needed.
+    - name: "TASK 3: Print changes if NTP config changed"
+      debug:
+        var: "ntp_updates.updates"
+      when: "ntp_updates.updates is defined"
+...

ntp_playbook.yml

@@ -0,0 +1,87 @@
+---
+# This is the first play, but rather than define a new play
+# and corresponding set of tasks, we import the main NTP
+# playbook and pass in some custom NTP servers instead. Using
+# static inputs is a good way to "stub out" our variables file
+# for the purpose of testing the playbook's logic.
+- name: "PLAY 1: Import original playbook with mock NTP servers"
+  import_playbook: "ntp_config.yml"
+  vars:
+    ntp_server1: "203.0.113.1"
+    ntp_server2: "203.0.113.2"
+
+# This is the second play. Its purpose is to ensure the
+# first play (playbook import) worked correctly. The general
+# flow is to ensure the NTP configuration was correctly applied,
+# remove the NTP configuration, then ensure the NTP configuration
+# was correctly removed. Removal isn't critical, but without it
+- name: "PLAY 2: Log into routers to test playbook"
+  hosts: "all"
+  tasks:
+
+    # This is the first task. It collects information from the
+    # router using the "ios_command" module, which is used for
+    # non-configuration (exec shell) commands. The command issued
+    # returns a table showing each NTP server configured.
+    # The output from this command is registered in the
+    # variable called "ntp_associations".
+    - name: "TASK 1: Gather mock NTP state data after enabling NTP"
+      ios_command:
+        commands: "show ntp associations"
+      register: "ntp_associations"
+
+    # This is the second task. Now that we've registered the router's
+    # feedback, we can test it using basic string membership/containment
+    # operations. We must ensure that our two mock NTP servers are
+    # present in this output. The text output is contained in a subfield
+    # called "stdout", and the 0 index is used to represent that this is
+    # the output associated with the first (and only) command issued.
+    - name: "TASK 2: Check that mock NTP servers are present"
+      assert:
+        that:
+          - "'203.0.113.1' in ntp_associations.stdout[0]"
+          - "'203.0.113.2' in ntp_associations.stdout[0]"
+        msg: "Missing some NTP data:\n{{ ntp_associations.stdout[0] }}"
+
+    # This is the third task. At this point, we've verified that the
+    # original NTP playbook works, but we should clean up after ourselves.
+    # Note that if we wanted to create a more robust and complex CI system,
+    # these steps would be unnecessary, since the disposal nature of
+    # virtual routers would indicate that simply deleting the router
+    # and spinning up a new one for a future CI test would be fine. In our
+    # case, the virtual router is longer living, and we want to prepare it
+    # for future tests by removing the mock servers.
+    - name: "TASK 3: Remove mock NTP servers"
+      ios_config:
+        commands:
+          - "no ntp server 203.0.113.1"
+          - "no ntp server 203.0.113.2"
+
+    # This is the fourth task and inserts a short pause using the
+    # "pause" module. This allows the router to fully disable its
+    # NTP logic for the two recently removed servers. Waiting helps
+    # avoid a false negative in future tasks by ensuring the router
+    # does not incorrectly report that these NTP servers still exist.
+    - name: "TASK 4: Wait 1 seconds"
+      pause:
+        seconds: 1
+
+    # This is the fifth task and is a copy of the second task. We
+    # need to update our ntp_associations variable and test to
+    # ensure NTP was removed in a future task.
+    - name: "TASK 5: Gather mock NTP data after disabling NTP"
+      ios_command:
+        commands: "show ntp associations"
+      register: "ntp_associations"
+
+    # This is the sixth task and checks the registered output from the
+    # previous task to ensure the mock NTP servers were not seen
+    # in the NTP association state data. If they were, then something
+    # went wrong with the NTP configuration removal in task 4.
+    - name: "TASK 6: Check mock NTP data is absent"
+      assert:
+        that:
+          - "'203.0.113.1' not in ntp_associations.stdout[0]"
+          - "'203.0.113.2' not in ntp_associations.stdout[0]"
+        msg: "Saw some NTP data:\n{{ ntp_associations.stdout[0] }}"
+...