This repository contains Ansible Custom Modules and Roles for automating ISDS Appliance tasks. Custom Modules provide the interface to python idempotent functions in ibmsecurity package. Handlers are coded into the roles to ensure changes are committed (deployed) and relevant processes restarted.

Python v2.7.10 and above is required for this package.

The following Python Packages are required (including their dependencies):

1. ibmsecurity
2. ansible

Appliances need to have an ip address defined for their LMI. This may mean that appliances have had their initial setup done with license acceptance.

Use ansible-galaxy to install the roles like so: ansible-galaxy install git+https://github.com/ibm-security/isds-ansible-roles.git --roles-path <dest dir>

Using the --roles-path option allows installation to a desired location. This avoids the need to write to system directory.

Use the following setting in ansible.cfg to set the location of the installed roles:

[defaults]
roles_path = <dest dir>

git tag will be used to indicate version numbers. The version numbers will be based on date. For example: "2017.03.20.0"

It is the date when the package is released with a sequence number at the end to handle when there are multiple releases in one day (expected to be uncommon).

The start_config role is a requirement for every playbok. It contains the custom modules and all handlers. All other roles have a dependency on it and start_config will get automatically invoked as needed.This repository contains a small selection of roles - users are encouraged to add more as needed.

”Modules (also referred to as “task plugins” or “library plugins”) are the ones that do the actual work in ansible, they are what gets executed in each playbook task. But you can also run a single one using the ‘ansible’ command.” http://docs.ansible.com/ansible/modules_intro.html

Ansible custom modules provide the glue to seamless invoke python functions to execute REST API calls against ISDS appliances. There are three custom modules. Each allows a different set of parameters to be passed.

isds - this module is for all calls to ISDS appliances

After a change happens, ansible can be set to execute "handlers" to commit changes and/or restart processes. Handlers are just other tasks. Handlers execute based on the sequence in which they are listed. See start_config role for details.

“Roles in Ansible build on the idea of include files and combine them to form clean, reusable abstractions – they allow you to focus more on the big picture and only dive down into the details when needed.” http://docs.ansible.com/ansible/playbooks_roles.html

Using roles allows one to concentrate on describing the business needs in a playbook. The actual call to the python function and the need to deploy and restart processes is taken care of isnide the role.

Roles start with a verb like "set" or "add" followed by a name that describes either the task or the python function being called. This depends on whether the role contains a single tasks or a combination of tasks.

Preference should be given to using "set" roles versus ones that do an "add" or "update". This allows for the role to either do an add or an update as the situation demands.

The contents of this repository are open-source under the Apache 2.0 licence.

Copyright 2018 Intact Financial Corporation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Ansible is a trademark of Red Hat, Inc.