Ansible Content Builder Collection

This repository contains the ansible.content_builder Ansible Collection.

Tested with Ansible

Tested with ansible-core 2.13 releases and the current development version of ansible-core.

Installation

pip install black==22.3.0 autoflake jsonschema jinja2==3.0.3 ansible-core
ansible-galaxy collection install git+https://github.com/ansible-community/ansible.content_builder.git

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml using the format:

collections:
- name: ansible.content_builder

See Ansible Using collections for more details.

Using this collection

build.yaml

---
- hosts: localhost
  gather_facts: yes
  roles:
    - ansible.content_builder.run

MANIFEST.yaml

---
collection:
  path: /path/to/collection
  namespace: test_namespace
  name: test_name
plugins:
  - type: action
    name: custom_action
    docstring: /path/to/docstring.yaml

  - type: cache
    name: custom_cache
    docstring: /path/to/docstring.yaml

  - type: filter
    name: custom_filter
    docstring: /path/to/docstring.yaml

  - type: test
    name: custom_test
    docstring: /path/to/docstring.yaml

  - type: lookup
    name: custom_lookup
    docstring: /path/to/docstring.yaml

  - type: module_openapi
    name: deepsec_intrusion_prevention_rules
    module_version: 1.0.0
    rm_swagger_json: /swagger_tm.json
    api_object_path: /intrusionpreventionrules
    resource: intrusion_prevention_rules
    unique_key: ""
    author: "Ansible Team"

  - type: module_openapi
    name: "amazon_cloud"
    content: cloud
    api_object_path: /path/to/schema_file
    resource: /path/to/modules.yaml
    action: generate_all
    unique_key: ""
    rm_swagger_json: ""
    module_version: "1.0.0"
    author: ""

ansible-playbook build.yaml -e manifest_file=MANIFEST.yaml

Supported plugins

Plugin Type	Description
action	Scaffold a action plugin
cache	Scaffold a cache plugin
filter	Scaffold a filter plugin
test	Scaffold a test plugin
lookup	Scaffold a lookup plugin
module_network_cli	Scaffold a Network Resource Module that support network_cli (doc)
module_network_netconf	Scaffold a Network Resource Module that supports netconf
module_openapi	Scaffold a Resource Module generated using OpenApi swagger JSON file

Resource module scaffolding generated using OpenApi based JSON

Giving module_openapi as an input to Ansible.content builder scaffolding tool helps Ansible content developers scaffold and output Ansible Resource Modules (RM) based out of OPENAPI based swagger JSON file, using HTTPAPI connection plugin for the platform configuration.

Capabilities:

• Use a pre-defined OPENAPI based swagger JSON file or other JSON file to scaffold a resource module in an Ansible Collection.
• Generates working resource module file <vendor>_<resource>.py and relevant action logic file both action/<vendor>_<resource>.py.
• Generates cloud content for amazon.aws and vmware.vmware_rest collections when <content> is set to cloud.

Input Parameters:

• collection:path: Destination folder where the user wants the output of the scaffolding tool to be stored.
• collection:namespace: Ansible collection org name.
• collection:name: Ansible collection name.
• collection:requires_ansible: The Ansible (core) version the collection requires (only used to generate vmware.vmware_rest).
• plugin:rm_swagger_json: Swagger JSON/JSON file where OEMs API with all of its REST operations are defined.
• plugin:content: The content that the builder generates (values: cloud/security default: security).
• plugin:api_object_path: API for which resource module needs to be generated by the tool. When plugin:content is set to cloud this parameter should be set to the path of the schema files.
• plugin:name: Ansible module name against the API. When plugin:content is set to cloud this parameter should be set to amazon_cloud or vmware_rest.
• plugin:action: The action that the builder is expected to perform to generate the cloud content (values: generate_schema, generate_modules, generate_examples, generate_all). Only applicable when plugin:content is set to cloud.
• plugin:resource: API resource. When plugin:content is set to cloud this parameter is set to the path of modules.yaml.
• plugin:unique_key: Unique key for API.
• plugin:author: Author for the resource module.

Builing a new module/collection:

Currently, the tool is optimised to parse Trendmicro Deepsecurity, Fortinet and CheckPoint swagger JSON files to output Resource modules for respective platforms. For the amazon.cloud content , the tool can generate and parse REST Schemas generated by the CloudFormation API and uses Cloud Control API to generate the modules. The vmware.vmware_rest modules are generated using VMware vSphere REST API.

Examples:

1. Trendmicro Deepsecurity

MANIFEST.yaml:

---
collection:
  path: /tmp/trendmicro/deepsec
  namespace: trendmicro
  name: deepsec
plugins:
  - type: module_openapi
    name: deepsec_intrusion_prevention_rules
    module_version: 1.0.0
    rm_swagger_json: /swagger_tm.json
    api_object_path: /intrusionpreventionrules
    resource: intrusion_prevention_rules
    unique_key: ""
    author: "Ansible Team"

2. Fortinet

MANIFEST.yaml:

---
collection:
  path: /tmp/fortinet/fortios
  namespace: fortinet
  name: fortios
plugins:
  - type: module_openapi
    name: fortios_firewall_policy
    module_version: 1.0.0
    resource: firewall_policy
    rm_swagger_json: /FortiOS_7.0.3_Configuration_API_firewall.json
    api_object_path: /firewall/policy
    unique_key: policyid
    author: "Ansible Team"

3. CheckPoint

MANIFEST.yaml:

---
collection:
  path: /tmp/checkpoint/mgmt
  namespace: checkpoint
  name: mgmt
plugins:
  - type: module_openapi
    name: cp_mgmt_access_rules_global
    module_version: 1.0.0
    rm_swagger_json: ~/Sumit/ansible_fork/collections/security_collections/doc_generator/apis_ckp.json
    api_object_path: add-access-rule
    resource: access_rules
    unique_key: ""
    author: "Ansible Team"

4. amazon.cloud

MANIFEST.yaml:

---
collection:
  path: /collections/ansible_collections/amazon/cloud
  namespace: amazon
  name: cloud
plugins:
  - type: module_openapi
    name: "amazon_cloud"
    content: cloud
    api_object_path: api_specifications
    resource: config/modules
    action: generate_all
    unique_key: ""
    rm_swagger_json: ""
    module_version: "1.0.0"
    author: "Ansible Cloud Team"

5. vmware.vmware_rest

MANIFEST.yaml:

---
collection:
  path: /collections/ansible_collections/vmware/vmware_rest
  namespace: vmware
  name: vmware_rest
  requires_ansible: 2.14.0
plugins:
  - type: module_openapi
    name: "vmware_rest"
    content: cloud
    api_object_path: api_specifications/7.0.2
    resource: config/modules
    action: generate_all
    unique_key: ""
    rm_swagger_json: ""
    module_version: "1.0.0"
    author: "Ansible Cloud Team"

6. cisco.intersight

MANIFEST.yaml:

---
collection:
  path: /Documents/intersight_ansible_content_builder/intersight
  namespace: cisco
  name: intersight
  requires_ansible: 2.15
plugins:
  - type: module_openapi
    name: "cisco_intersight"
    content: cloud
    api_object_path: /Documents/intersight_schema
    resource: ./
    action: generate_modules
    unique_key: ""
    rm_swagger_json: ""
    module_version: "1.0.0"
    author: "Cisco Intersight Team"

Refresh the RETURN Block of the vmware modules using the test-suite:

    mkdir -p ~/.ansible/collections/ansible_collections/goneri/utils
    git clone https://github.com/goneri/ansible-collection-goneri.utils.git ~/.ansible/collections/ansible_collections/goneri/utils
    cd ~/.ansible/collections/ansible_collections/vmware/vmware_rest/tests/integration/targets/vcenter_vm_scenario1
    ./refresh_RETURN_block.sh
    cd ~/.ansible/collections/ansible_collections/goneri/utils
    ./scripts/inject_RETURN.py ~/.ansible/collections/ansible_collections/vmware/vmware_rest/manual/source/vmware_rest_scenarios/task_outputs ~/.ansible/collections/ansible_collections/vmware/vmware_rest --config-file config/inject_RETURN.yaml

Licensing

GNU General Public License v3.0 or later.

See COPYING to see the full text.