{"id":20588816,"url":"https://github.com/ciscodevnet/ftdansible","last_synced_at":"2025-04-14T22:03:26.986Z","repository":{"id":33856573,"uuid":"134294492","full_name":"CiscoDevNet/FTDAnsible","owner":"CiscoDevNet","description":"FTD Ansible module","archived":false,"fork":false,"pushed_at":"2023-01-24T23:22:53.000Z","size":1660,"stargazers_count":40,"open_issues_count":12,"forks_count":21,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-14T22:03:04.973Z","etag":null,"topics":["ansible-modules","ftd","ftd-ansible","playbook","sample-playbooks"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CiscoDevNet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-21T16:19:37.000Z","updated_at":"2025-01-17T09:30:09.000Z","dependencies_parsed_at":"2023-02-14T02:31:09.185Z","dependency_job_id":null,"html_url":"https://github.com/CiscoDevNet/FTDAnsible","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FFTDAnsible","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FFTDAnsible/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FFTDAnsible/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FFTDAnsible/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CiscoDevNet","download_url":"https://codeload.github.com/CiscoDevNet/FTDAnsible/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248968737,"owners_count":21191159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible-modules","ftd","ftd-ansible","playbook","sample-playbooks"],"created_at":"2024-11-16T07:26:32.428Z","updated_at":"2025-04-14T22:03:26.959Z","avatar_url":"https://github.com/CiscoDevNet.png","language":"Python","readme":"# FTD Ansible Modules\n\nA collection of Ansible modules that automate configuration management \nand execution of operational tasks on Cisco Firepower Threat Defense (FTD) devices using FTD REST API.\n\n_This file describes the development and testing aspects. In case you are looking for \nthe user documentation, please check [FTD Ansible docs on DevNet](https://developer.cisco.com/site/ftd-ansible/)._\n\n## Installation Guide\n\nThe project contains four Ansible modules:\n\n* [`ftd_configuration.py`](./library/ftd_configuration.py) - manages device configuration via REST API. The module configures virtual and physical devices by sending HTTPS calls formatted according to the REST API specification;\n* [`ftd_file_download.py`](./library/ftd_file_download.py) - downloads files from FTD devices via HTTPS protocol;\n* [`ftd_file_upload.py`](./library/ftd_file_upload.py) - uploads files to FTD devices via HTTPS protocol;\n* [`ftd_install.py`](./library/ftd_install.py) - installs FTD images on hardware devices. The module performs a complete reimage of the Firepower system by downloading the new software image and installing it. \n\nSample playbooks are located in the [`samples`](./samples) folder.\n\n### Running playbooks in Docker\n\n1. Build the default Docker image:\n    ```\n    docker build -t ftd-ansible .\n    ```\n    **NOTE** The default image is based on the release v0.1.0 of the [`FTD-Ansible`](https://github.com/CiscoDevNet/FTDAnsible) and Python 3.6. \n\n2. You can build the custom Docker image:\n    ```\n    docker build -t ftd-ansible --build-arg PYTHON_VERSION=\u003c2.7|3.5|3.6|3.7\u003e --build-arg FTD_ANSIBLE_VERSION=\u003ctag name | branch name\u003e .\n    ```\n\n3. Create an inventory file that tells Ansible what devices to run the tasks on. [`sample_hosts`](./inventory/sample_hosts) shows an example of inventory file.\n\n4. Run the playbook in Docker mounting playbook folder to `/ftd-ansible/playbooks` and inventory file to `/etc/ansible/hosts`:\n    ```\n    docker run -v $(pwd)/samples:/ftd-ansible/playbooks -v $(pwd)/inventory/sample_hosts:/etc/ansible/hosts ftd-ansible playbooks/network_object.yml\n    ```\n\n### Running playbooks locally \n\n1. Create a virtual environment and activate it:\n```\npython3 -m venv venv\n. venv/bin/activate\n```\n\n2. Install dependencies:\n`pip install -r requirements.txt`\n\n3. Update Python path to include the project's directory:\n```\nexport PYTHONPATH=.:$PYTHONPATH\n```\n  \n4. Run the playbook:\n``` \nansible-playbook samples/network_object.yml\n```\n\n## Unit Tests\n\nThe project contains unit tests for Ansible modules, HTTP API plugin and util files. They can be found in `test/unit` directory. Ansible has many utils for mocking and running tests, so unit tests in this project also rely on them and including Ansible test module to the Python path is required.\n\n### Running unit tests in Docker\n\n1. Build the Docker image: \n```\ndocker build -t ftd-ansible-test -f Dockerfile.tests . \n```\n**NOTE**: Dockerfile uses Ansible version from `requirements.txt`. You can change it by replacing the version in `requirements.txt` and rebuilding the Docker image.\n\n2. Run unit tests with:\n```\ndocker run ftd-ansible-test\n```\nTo run a single test, specify the filename at the end of command:\n```\ndocker run ftd-ansible-test test/unit/test_ftd_configuration.py\n```\n\n**NOTE**: You need to rebuild the Docker image on every change of the code.\n\n#### Troubleshooting\n\n```\nimport file mismatch:\nimported module 'test.unit.module_utils.test_common' has this __file__ attribute: ...\nwhich is not the same as the test file we want to collect:\n  /ftd-ansible/test/unit/module_utils/test_common.py\nHINT: remove __pycache__ / .pyc files and/or use a unique basename for your test file modules\n```\n\nIn case you experience the following error while running the tests in Docker, remove compiled bytecode files files with \n`find . -name \"*.pyc\" -type f -delete` command and try again.\n\n### Running unit tests locally\n\n1. Clone [Ansible repository](https://github.com/ansible/ansible) from GitHub;\n\n2. Install Ansible and test dependencies:\n```\npip install $ANSIBLE_DIR/requirements.txt\npip install test-requirements.txt\n```\n\n3. Add Ansible modules to the Python path:\n```\nexport PYTHONPATH=$PYTHONPATH:$ANSIBLE_DIR/lib:$ANSIBLE_DIR/test\n```\n\n4. Run unit tests:\n```\npytest test/unit\n```\n \n### Running tests with [TOX](https://tox.readthedocs.io/en/latest/) \n**NOTE**: To be able to run tests with the specific version of Python using tox you need to have this version of Python installed locally  \n\nInstall tox locally:\n```\npip install tox\n```\nCheck the list of currently supported environments:\n```\ntox -l\n```\n**NOTE**: environments with _-integration_ postfix preconfigured for integration tests:\n\nSetup `PYTHONPATH` as described in the previous section\nRun unit tests in virtualenvs using tox:\n```\ntox -e py27,py35,py36,py37\n```\nRun integration tests in virtualenvs using tox:\n```\nexport REPORTS_DIR=\u003cpath to the folder where JUnit reports will be stored\u003e\ntox -e py27-integration,py35-integration,py36-integration,py37-integration -- samples/network_object.yml -i inventory/sample_hosts\n```\n### Running style check locally\n1. Install [Flake8](http://flake8.pycqa.org/en/latest/) locally:\n    ```\n    pip install flake8\n    ```\n\n2. Run Flake8 check:\n    ```\n    flake8\n    ```\n\nFlake8 configuration is defined in the [tox config file](./tox.ini) file.\n\n## Integration Tests\n\nIntegration tests are written in a form of playbooks and usually started with `ansible-test` command from Ansible repository. As this project is created outside Ansible, it does not have utils to run the tests. Thus, integration tests are written as sample playbooks with assertion and can be found in the `samples` folder. They start with `test_` prefix and can be run as usual playbooks.\n\n## Debugging\n\n1. Add `log_path` with path to log file in `ansible.cfg`\n\n2. Run `ansible-playbook` with `-vvvv`\n    ```\n    $ ansible-playbook samples/network_object.yml -vvvv\n    ```\n\n3. The log file will contain additional information (REST, etc.)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fciscodevnet%2Fftdansible","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fciscodevnet%2Fftdansible","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fciscodevnet%2Fftdansible/lists"}