PCE TLS/proxy settings (#18)

* extend PCE util with TLS and proxy settings vars

* bump illumio lib min version requirement to 1.1.3 for set_tls_settings function

* update changelog to include PCE settings changes

* raise more verbose error messages when PCE connection fails

* update roles to use PCE TLS/proxy vars

* fail gracefully if ven ctl not present on the remote

* update role docs with PCE TLS/proxy vars

* use ansible-lint github action due to inconsistent failures when running w/matrix

.ansible-lint

@@ -2,9 +2,12 @@
 # .ansible-lint
 exclude_paths:
   - ${HOME}/.cache/
+  - .cache/
   - venv/
   - .github/
   - molecule/
+  - local/
+  - demo/
 
 use_default_rules: true
 

.github/workflows/sanity.yml

@@ -8,32 +8,15 @@ on:
 
 jobs:
   ansible-lint:
-    name: ansible-lint ${{ matrix.ansible }}+py${{ matrix.python }}
-    strategy:
-      matrix:
-        ansible:
-          - stable-2.12
-          - stable-2.13
-          - stable-2.14
-          - stable-2.15
-        python:
-          - "3.9"
+    name: Ansible Lint
     runs-on: ubuntu-latest
     steps:
 
       - name: Check out code
         uses: actions/checkout@v3
 
-      - name: Set up Python ${{ matrix.ansible }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python }}
-
-      - name: Install ansible-base ${{ matrix.ansible }}
-        run: pip install ansible-lint yamllint https://github.com/ansible/ansible/archive/${{ matrix.ansible }}.tar.gz --disable-pip-version-check
-
       - name: Run ansible-lint
-        run: ansible-lint --force-color -v
+        uses: ansible/ansible-lint-action@v6
 
   sanity:
     name: Sanity ${{ matrix.ansible }}+py${{ matrix.python }}

.gitignore

@@ -33,3 +33,7 @@ _version.py
 
 # local testing files
 local/
+demo/
+
+# ansible-lint
+.cache/

CHANGELOG.rst

@@ -5,10 +5,21 @@
 Version 0.2.6 (TBD)
 -------------------
 
+* increment `illumio` python library version requirement to 1.1.3
+
 FEATURES:
 
 * Label module - create/update/delete label objects in the PCE
 
+IMPROVEMENTS:
+
+* add the following options to all PCE modules:
+    * `pce_tls_verify` - flag denoting whether TLS verification should be enabled on the PCE connection
+    * `pce_tls_ca` - path to a custom root CA certificate bundle to use for the PCE connection
+    * `pce_tls_client_certs` - paths to client-side certificate files
+    * `pce_http_proxy` - HTTP proxy server to use when connecting to the PCE
+    * `pce_https_proxy` - HTTPS proxy server to use when connecting to the PCE
+
 Version 0.2.5 (June 12, 2023)
 -----------------------------
 

README.md

@@ -46,10 +46,10 @@ Python version **3.8** or higher is required for this collection.
 
 **Python**  
 
-For most components, you will need the `illumio` Python library version **1.1.1** or higher installed on the Ansible controller:  
+For most components, you will need the `illumio` Python library version **1.1.3** or higher installed on the Ansible controller:  
 
 ```sh
-$ pip install illumio>=1.1.1
+$ pip install illumio>=1.1.3
 ```
 
 For Windows hosts, you will also need to install the `pywinrm` library on the Ansible controller:

docs/CVEN_ROLE.md

@@ -30,6 +30,8 @@ PCE Version  | CVEN 19.3.6 | CVEN 21.1 | CVEN 21.2 | CVEN 21.5
 ------------ | :---------: | :-------: | :-------: | :-------:
 21.2         | X           | X         | X         | 
 21.5         | X           | X         | X         | X
+22.2         | X           | X         | X         | X
+22.5         | X           | X         | X         | X
 
 ## Installation  
 
@@ -83,6 +85,11 @@ Variable | Description | Data Type | Environment variable | Default value
 `illumio_pce_org_id` | PCE Organization ID | `int` | `ILLUMIO_PCE_ORG_ID` | `1`
 `illumio_pce_api_key` | PCE API key | `str` | `ILLUMIO_API_KEY_USERNAME` | -
 `illumio_pce_api_secret` | PCE API secret | `str` | `ILLUMIO_API_KEY_SECRET` | -
+`illumio_pce_tls_verify` | Enable/disable TLS verification | `bool` | - | `true`
+`illumio_pce_tls_ca` | Custom root CA path. If set, overrides `illumio_pce_tls_verify` | `str` | - | -
+`illumio_pce_tls_client_certs` | TLS client cert paths. Can point to a single PEM file containing public/private pair or two separate files | `list` | - | -
+`illumio_pce_http_proxy` | HTTP proxy server | `str` | `http_proxy` | -
+`illumio_pce_https_proxy` | HTTPS proxy server | `str` | `https_proxy` | -
 
 ### Kubelink  
 

docs/KUBELINK_ROLE.md

@@ -31,6 +31,8 @@ PCE Version  | Kubelink 2.0 | Kubelink 2.1
 ------------ | :----------: | :---------: 
 21.2         | X            | 
 21.5         | X            | X
+22.2         | X            | X
+22.5         | X            | X
 
 ## Installation  
 
@@ -98,6 +100,11 @@ Variable | Description | Data Type | Environment variable | Default value
 `illumio_pce_org_id` | PCE Organization ID | `int` | `ILLUMIO_PCE_ORG_ID` | `1`
 `illumio_pce_api_key` | PCE API key | `str` | `ILLUMIO_API_KEY_USERNAME` | -
 `illumio_pce_api_secret` | PCE API secret | `str` | `ILLUMIO_API_KEY_SECRET` | -
+`illumio_pce_tls_verify` | Enable/disable TLS verification | `bool` | - | `true`
+`illumio_pce_tls_ca` | Custom root CA path. If set, overrides `illumio_pce_tls_verify` | `str` | - | -
+`illumio_pce_tls_client_certs` | TLS client cert paths. Can point to a single PEM file containing public/private pair or two separate files | `list` | - | -
+`illumio_pce_http_proxy` | HTTP proxy server | `str` | `http_proxy` | -
+`illumio_pce_https_proxy` | HTTPS proxy server | `str` | `https_proxy` | -
 
 ### Container Cluster  
 

docs/VEN_ROLE.md

@@ -39,10 +39,12 @@ This role will work with the following operating systems (see the compatibility
 
 ### VEN Compatibility  
 
-PCE Version  | VEN 21.2.5 | VEN 21.5.20
------------- | :--------: | :---------: 
-21.2         | X          | 
-21.5         | X          | X
+PCE Version  | VEN 21.2.x | VEN 21.5.x | VEN 22.2.x | VEN 22.5.22
+------------ | :--------: | :--------: | :--------: | :---------:
+21.2         | X          |            |            | 
+21.5         | X          | X          |            | 
+22.2         | X          | X          | X          | 
+22.5         | X          | X          | X          | X
 
 See the [Illumio Support dependencies page](https://support.illumio.com/software/os-support-package-dependencies/ven.html) for specific VEN OS compatibility details.  
 
@@ -112,6 +114,11 @@ Variable | Description | Data Type | Environment variable | Default value
 `illumio_pce_org_id` | PCE Organization ID | `int` | `ILLUMIO_PCE_ORG_ID` | `1`
 `illumio_pce_api_key` | PCE API key | `str` | `ILLUMIO_API_KEY_USERNAME` | -
 `illumio_pce_api_secret` | PCE API secret | `str` | `ILLUMIO_API_KEY_SECRET` | -
+`illumio_pce_tls_verify` | Enable/disable TLS verification | `bool` | - | `true`
+`illumio_pce_tls_ca` | Custom root CA path. If set, overrides `illumio_pce_tls_verify` | `str` | - | -
+`illumio_pce_tls_client_certs` | TLS client cert paths. Can point to a single PEM file containing public/private pair or two separate files | `list` | - | -
+`illumio_pce_http_proxy` | HTTP proxy server | `str` | `http_proxy` | -
+`illumio_pce_https_proxy` | HTTPS proxy server | `str` | `https_proxy` | -
 
 ### Pairing profile  
 

galaxy.yml

@@ -18,6 +18,9 @@ dependencies:
   community.general: '*'
   kubernetes.core: '*'
 repository: https://github.com/illumio/illumio.core
+documentation: https://github.com/illumio/illumio.core
+homepage: https://github.com/illumio/illumio.core
+issues: https://github.com/illumio/illumio.core/issues
 build_ignore:
   - '.github'
   - '.gitignore'
@@ -28,6 +31,7 @@ build_ignore:
   - 'build'
   - 'dist'
   - 'local'
+  - 'demo'
   - 'venv'
   - 'molecule'
   - '**/integration_config.yml'

plugins/doc_fragments/pce.py

@@ -42,4 +42,30 @@ class ModuleDocFragment(object):
       - Can be set with the environment variable C(ILLUMIO_API_KEY_SECRET).
     type: str
     required: true
+  pce_tls_verify:
+    description:
+      - Flag denoting whether TLS verification should be enabled on the PCE connection.
+    type: bool
+    default: true
+  pce_tls_ca:
+    description:
+      - Path to a custom root CA certificate bundle to use for the PCE connection.
+      - If set, overrides C(pce_tls_verify).
+    type: str
+  pce_tls_client_certs:
+    description:
+      - Optional paths to client-side certificate files.
+      - May point to separate cert and private key files or a PEM bundle containing both.
+    type: list
+    elements: str
+  pce_http_proxy:
+    description:
+      - HTTP proxy server to use when connecting to the PCE.
+      - If not set, it will use the default C(http_proxy) environment variable.
+    type: str
+  pce_https_proxy:
+    description:
+      - HTTPS proxy server to use when connecting to the PCE.
+      - If not set, it will use the default C(https_proxy) environment variable.
+    type: str
 '''

plugins/module_utils/pce.py

@@ -40,11 +40,37 @@ def __init__(self, module: AnsibleModule):
         api_key_username = module.params.get('api_key_username')
         api_key_secret = module.params.get('api_key_secret')
 
+        pce_tls_verify = module.params.get('pce_tls_verify')
+        pce_tls_ca = module.params.get('pce_tls_ca')
+        pce_tls_client_certs = module.params.get('pce_tls_client_certs')
+        pce_http_proxy = module.params.get('pce_http_proxy')
+        pce_https_proxy = module.params.get('pce_https_proxy')
+
+        if pce_tls_client_certs:
+            # per requests cert formatting, use the str if only one
+            # path is given, otherwise bundle paths as a tuple
+            if len(pce_tls_client_certs) == 1:
+                pce_tls_client_certs = pce_tls_client_certs[0]
+            else:
+                pce_tls_client_certs = tuple(pce_tls_client_certs)
+
         self._pce = PolicyComputeEngine(hostname, port=port, org_id=org_id)
         self._pce.set_credentials(api_key_username, api_key_secret)
+        self._pce.set_tls_settings(
+            verify=pce_tls_ca or pce_tls_verify,
+            cert=pce_tls_client_certs
+        )
 
-        if not self._pce.check_connection():
-            module.fail_json("Failed to establish a connection to the PCE.")
+        if pce_http_proxy or pce_https_proxy:
+            self._pce.set_proxies(
+                http_proxy=pce_http_proxy,
+                https_proxy=pce_https_proxy
+            )
+
+        try:
+            self._pce.must_connect()
+        except Exception as e:
+            module.fail_json("Failed to establish a connection to the PCE: %s" % (str(e)))
 
 
 class PceObjectApi(PceApiBase, metaclass=ABCMeta):
@@ -146,5 +172,10 @@ def pce_connection_spec() -> dict:
             required=True,
             no_log=True,
             fallback=(env_fallback, ['ILLUMIO_API_KEY_SECRET'])
-        )
+        ),
+        pce_tls_verify=dict(type='bool', default=True),
+        pce_tls_ca=dict(type='str'),
+        pce_tls_client_certs=dict(type='list', elements='str'),
+        pce_http_proxy=dict(type='str'),
+        pce_https_proxy=dict(type='str'),
     )

plugins/modules/container_cluster.py

@@ -20,7 +20,7 @@
   - Duncan Sommerville (@dsommerville-illumio)
 requirements:
   - "python>=3.8"
-  - "illumio>=1.1.1"
+  - "illumio>=1.1.3"
 version_added: "0.2.0"
 
 options:

plugins/modules/label.py

@@ -18,7 +18,7 @@
   - Duncan Sommerville (@dsommerville-illumio)
 requirements:
   - "python>=3.8"
-  - "illumio>=1.1.1"
+  - "illumio>=1.1.3"
 version_added: "0.3.0"
 
 options:

plugins/modules/pairing_key.py

@@ -19,7 +19,7 @@
   - Duncan Sommerville (@dsommerville-illumio)
 requirements:
   - "python>=3.8"
-  - "illumio>=1.1.1"
+  - "illumio>=1.1.3"
 version_added: "0.2.0"
 
 options:

plugins/modules/pairing_profile.py

@@ -18,7 +18,7 @@
   - Duncan Sommerville (@dsommerville-illumio)
 requirements:
   - "python>=3.8"
-  - "illumio>=1.1.1"
+  - "illumio>=1.1.3"
 version_added: "0.2.0"
 
 options:

requirements.txt

@@ -1 +1 @@
-illumio>=1.1.1
+illumio>=1.1.3

roles/cven/tasks/main.yml

@@ -6,6 +6,11 @@
     pce_org_id: "{{ illumio_pce_org_id }}"
     api_key_username: "{{ illumio_pce_api_key }}"
     api_key_secret: "{{ illumio_pce_api_secret }}"
+    pce_tls_verify: "{{ illumio_pce_tls_verify | default(omit) }}"
+    pce_tls_ca: "{{ illumio_pce_tls_ca | default(omit) }}"
+    pce_tls_client_certs: "{{ illumio_pce_tls_client_certs | default(omit) }}"
+    pce_http_proxy: "{{ illumio_pce_http_proxy | default(omit) }}"
+    pce_https_proxy: "{{ illumio_pce_https_proxy | default(omit) }}"
     name: "{{ illumio_cven_profile_name }}"
     description: "{{ illumio_cven_profile_description }}"
     enabled: true
@@ -24,6 +29,11 @@
     pce_org_id: "{{ illumio_pce_org_id }}"
     api_key_username: "{{ illumio_pce_api_key }}"
     api_key_secret: "{{ illumio_pce_api_secret }}"
+    pce_tls_verify: "{{ illumio_pce_tls_verify | default(omit) }}"
+    pce_tls_ca: "{{ illumio_pce_tls_ca | default(omit) }}"
+    pce_tls_client_certs: "{{ illumio_pce_tls_client_certs | default(omit) }}"
+    pce_http_proxy: "{{ illumio_pce_http_proxy | default(omit) }}"
+    pce_https_proxy: "{{ illumio_pce_https_proxy | default(omit) }}"
     pairing_profile_href: "{{ cven_pairing_profile_result.pairing_profile['href'] }}"
   delegate_to: '127.0.0.1'
   register: cven_pairing_key_result

roles/kubelink/tasks/container_cluster.yml

@@ -11,6 +11,11 @@
     pce_org_id: "{{ illumio_pce_org_id }}"
     api_key_username: "{{ illumio_pce_api_key }}"
     api_key_secret: "{{ illumio_pce_api_secret }}"
+    pce_tls_verify: "{{ illumio_pce_tls_verify | default(omit) }}"
+    pce_tls_ca: "{{ illumio_pce_tls_ca | default(omit) }}"
+    pce_tls_client_certs: "{{ illumio_pce_tls_client_certs | default(omit) }}"
+    pce_http_proxy: "{{ illumio_pce_http_proxy | default(omit) }}"
+    pce_https_proxy: "{{ illumio_pce_https_proxy | default(omit) }}"
     name: "{{ kubelink_cluster_name }}"
     description: Container cluster created by Ansible
     state: present

roles/ven/tasks/manage_ven_linux.yml

@@ -5,6 +5,21 @@
   tags:
     - always
 
+- name: "Stat VEN control tool"
+  become: true
+  ansible.builtin.stat:
+    path: "{{ ven_ctl }}"
+  register: ven_cli
+  tags:
+    - always
+
+- name: "Fail on missing VEN control tool"
+  ansible.builtin.fail:
+    msg: "Missing VEN control tool at {{ ven_ctl }}"
+  when: not ven_cli.stat.exists
+  tags:
+    - always
+
 - name: "Start VEN"
   become: true
   ansible.builtin.command: "{{ ven_ctl }} start"
@@ -68,17 +83,8 @@
     - never
     - ven_unpair
 
-- name: "Stat VEN control tool"
-  become: true
-  ansible.builtin.stat:
-    path: "{{ ven_ctl }}"
-  register: ven_cli
-  tags:
-    - always
-    - ven_status
-
 - name: "Check VEN status"
-  when: ven_cli.stat.exists
+  when: "'ven_unpair' not in ansible_run_tags"
   tags:
     - always
     - ven_status