Documentation for the collection.
This is still a work in progress. README files in this collection were copied from roles repository and need to be edited.
Support for ISAMProxy will be added in due course of time.
Requirements:
Instructions for installing ibm.isam:
pip install ansible
)pip install ibmsecurity
)ansible-galaxy collection install ibm.isam
ansible-galaxy collection install ibm.isam --force
Python packages can be downloaded from pypi.org as tar.gz files and copied to server for installation.
Ansible collection can also be downloaded as a file and installed:
[primary]
192.168.198.100
[primary:vars]
ansible_host=192.168.198.100
ansible_connection="ibm.isam.isam"
ansible_isam_username="admin@local"
ansible_isam_password="admin"
ansible_isam_port="443"
Using ibmsecurity v2024.4.5+ enables secure TLS connections.
[isam]
validate_certs = True
verify_ca_path = /<path_to_pem>/isamAppliance.pem
You can retrieve the certificate of the LMI and store it to use as verify_ca_path
openssl s_client -connect ${HOSTNAME}:${PORT} </dev/null 2>/dev/null | openssl x509 -outform pem > isamAppliance.pem
The best solution is to get a signed certificate from a Certificate Authority that is trusted within your organization's default ca settings. In that case, simply setting validate_certs to True is sufficient.
[isam]
validate_certs = True
When using an Ansible Execution Environment, the behaviour of the Python Requests module with TLS may become tricky. Where the Python configuration in a virtual environment may use your certificates correctly, that is most likely not the case in a container.
You can check what CA bundle Python will use by default.
Python 3.9.18 (main, Sep 22 2023, 17:58:34)
>>> import certifi
>>> certifi.where()
'/home/tbosmans/venv/lib64/python3.9/site-packages/certifi/cacert.pem'
The default path will probably point to a keystore within site-packages. The problem with that truststore, is that is likely not updated with any trusts you need to add (eg. certificates from you private Certificate Authority)
So you then have a couple of options:
verify_ca_path
in ansible.cfg (through ansible-builder or in ansible.cfg in your project directory)REQUESTS_CA_BUNDLE
) that points to the container's system ca bundle. This is the recommended approach.Prepare a 'san.cnf' file. You could add multiple IP.x addresses in it if you want. You can also use DNS.x hostnames instead.
[req]
default_bits = 2048
distinguished_name = req_distinguished_name
req_extensions = req_ext
x509_extensions = v3_req
prompt = no
[req_distinguished_name]
countryName = US
stateOrProvinceName = N/A
localityName = N/A
organizationName = Self-signed certificate
commonName = ISVA_LMI
[req_ext]
subjectAltName = @alt_names
[v3_req]
subjectAltName = @alt_names
[alt_names]
IP.1 = 192.168.42.2
IP.2 = 192.168.42.3
Using openssl, you can then generate a certificate and public key, and convert it to pkcs12 format .
# generate key & cert
openssl req -x509 -nodes -days 1730 -newkey rsa:2048 -keyout isamlmi_key.pem -out isamlmi_cert.pem -config san.cnf
# extract public key
openssl x509 -pubkey -noout -in isamlmi_cert.pem > isamAppliance.pem
# turn into a pkcs12
openssl pkcs12 -export -in isamlmi_cert.pem -inkey isamlmi_key.pem -out isamlmi.p12 -passout pass:<some password>
You can now use the isamlmi.p12
certificate as your management ssl certificate (for instance , by using Ansible)
ansible-playbook ibm.isam.base.configure_management_ssl.yml -e update_management_ssl_cert_cert="$(pwd)/files/isamlmi.p12" -e update_management_ssl_cert_pwd=<password> -i <your inventory>
To use the ibm.isam collection with execution environments, you may need to create a custom Execution Environment first. However, the collection now includes a playbook that you can use to check if it works in your case with a standard Execution Environment.
Warning This is not a complete documentation on how to configure Ansible Automation Platform!
The idea is that you can use ansible-navigator to run the exact same execution environment as would be used on the Ansible Automation Platform.
pip install ansible-navigator
playbook
directory.Create a new playbook directory.
Create the following directories:
Although not required, you likely want to have an ansible-navigator.yml
file, with the default configuration for ansible-navigator.
Below is an example:
---
ansible-navigator:
ansible:
# cmdline: --extra-vars comment=snapshot
config:
help: false
path: ./ansible.cfg
inventory:
entries:
- "inventories/isam"
ansible-runner:
artifact-dir: ./logs/ansible-artifacts
rotate-artifacts-count: 10
timeout: 3600
color:
enable: true
osc4: false
app: run
execution-environment:
container-engine: podman
enabled: true
environment-variables:
pass: []
# image: yourcustom-ee:latest
pull:
policy: tag
logging:
file: ./logs/ansible-navigator.log
level: critical
mode: stdout
playbook-artifact:
enable: true
replay: ./logs/REPLAY_{playbook_name}.json
save-as: ./logs/ARTIFACT_{playbook_name}-{time_stamp}.json
time-zone: Europe/Brussels
Note that the mode
is set to stdout, so you will see output similar to ansible-playbook
's output.
For the collection to be available in the Execution environment for ansible-navigator, the simplest way is to install it in the collections directory adjacent your playbooks.
For the collection to be available in Ansible Automation Platform (or Ansible Tower), you need to create a requirements.yml
in the collections directory.
collections/requirements.yml:
---
collections:
- ibm.isam
So in AAP, the collection will be installed automatically, for ansible-navigator (or ansible-playbook, for that matter), you need to install the collection manually:
ansible-galaxy collection install -r collections/requirements.yml -p ./collections --force
The command installs the collection adjacent to your playbooks.
You can use the same inventory you used before.
You can define 1 or more default inventories in the ansible-navigator.yml
file (ansible.inventory.entries
),
or you can pass the inventory on the command line (-i or --inventory, the same as for ansible-playbook)
The playbook in the collection connectivity_check.yml
will try to install the ibmsecurity python package in the standard Execution Environment.
So if you defined your default inventory upfront, you can just run this from with your playbook directory:
ansible-navigator run ibm.isam.connectivity_check.yml
You can pass arguments, for instance a different inventory:
ansible-navigator run ibm.isam.connectivity_check.yml -i inventory/test
If this fails with errors indication that the ibmsecurity
module is missing, you must build a custom Execution Environment.
You can build a custom execution environment, that contains the python prerequisites for the ibm.isam collection.
You may also need to add custom CA trusts to the execution environment (eg. from your private Certificate Authority),
and you likely want to set the REQUESTS_CA_BUNDLE
environment variable.
note : adding that environment variable, effectively enables TLS verification in some cases, which may not (yet) be the expected behaviour.
Alternatively, you can override the cacert.pem that comes with the certifi
package in your execution environment.
In Ansible Automation Platform, you need to define the custom execution environment you prepared earlier.
In the Project, you can then reference that Execution Environment.
It is not (yet) possible at the moment to define a Job template to run playbooks from collections directly, so you need to create a small playbook that references the collection's playbook:
your_playbook.yml:
- name: use playbook from collection
import_playbook: ibm.isam.connectivity_check.yml
Then reference that playbook in your Job template, and run it.
To use ansible vaults with ansible-navigator, there's a couple of options. Take a look at the documentation here : https://ansible-navigator.readthedocs.io/faq/#how-can-i-use-a-vault-password-with-ansible-navigator
The playbooks in the collection can be used as examples to create your own specific deployments of IBM Verify Access using Ansible !