{"id":20155254,"url":"https://github.com/redhat-cop/network.telemetry","last_synced_at":"2025-04-09T22:01:57.300Z","repository":{"id":159927959,"uuid":"634943791","full_name":"redhat-cop/network.telemetry","owner":"redhat-cop","description":"An Ansible Collection for managing telemetry configuration on network devices and integrating with Event-Driven Ansible (EDA).","archived":false,"fork":false,"pushed_at":"2025-01-16T16:28:44.000Z","size":91,"stargazers_count":5,"open_issues_count":0,"forks_count":7,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-04-09T22:01:20.283Z","etag":null,"topics":["ansible","event-driven-automation","network","telemetry","validated-content"],"latest_commit_sha":null,"homepage":"","language":"Jinja","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/redhat-cop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-01T15:55:07.000Z","updated_at":"2025-01-27T13:39:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"917116ef-3088-4a8c-92c7-8ad01dee1b45","html_url":"https://github.com/redhat-cop/network.telemetry","commit_stats":{"total_commits":56,"total_committers":4,"mean_commits":14.0,"dds":0.1071428571428571,"last_synced_commit":"0f1587b4b16c714096728001a5a02ba2621bf7e9"},"previous_names":["redhat-cop/network.telemetry"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fnetwork.telemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fnetwork.telemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fnetwork.telemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-cop%2Fnetwork.telemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhat-cop","download_url":"https://codeload.github.com/redhat-cop/network.telemetry/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119303,"owners_count":21050755,"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","event-driven-automation","network","telemetry","validated-content"],"created_at":"2024-11-13T23:30:59.909Z","updated_at":"2025-04-09T22:01:57.290Z","avatar_url":"https://github.com/redhat-cop.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Network Telemetry Validated Content\n[![CI](https://github.com/redhat-cop/network.telemetry/actions/workflows/tests.yml/badge.svg?event=schedule)](https://github.com/redhat-cop/network.telemetry/actions/workflows/tests.yml)\n[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/7404/badge)](https://bestpractices.coreinfrastructure.org/projects/7404)\n\nThis repository contains the `network.telemetry` Ansible Collection.\n\n## Description\n\nThe `network.telemetry` enables user to manage the Telemetry configuration on networking devices and\nalso setup a Telegraf - Kafka stack to seemlessly integrate with [Event-Driven Ansible](https://www.ansible.com/use-cases/event-driven-automation).\n\n## Tested with Ansible\n\nTested with ansible-core \u003e=2.15 releases.\n\n## Installation\n\nTo consume this Validated Content from Automation Hub, the following needs to be added to `ansible.cfg`:\n\n```ini\n[galaxy]\nserver_list = automation_hub\n\n[galaxy_server.automation_hub]\nurl=https://cloud.redhat.com/api/automation-hub/\nauth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token\ntoken=\u003cSuperSecretToken\u003e\n```\nGet the required token from the [Automation Hub Web UI](https://console.redhat.com/ansible/automation-hub/token).\n\nWith this configured, simply run the following commands:\n\n```bash\nansible-galaxy collection install network.base\nansible-galaxy collection install network.telemetry\n```\n\n## Capabilities\n\n- `Gather Telemetry Facts`: Gather telemetry facts from network devices and store it as host_vars (locally or remote), enabling the creation of a telemetry source-of-truth on a per target host basis.\n\n- `Manage Telemetry Configuration`: Configure telemetry as a discrete resource on target hosts. Use locally or remotely stored source-of-truth to push (or update) configuration and also detect/remediate drifts.\n\n- `Perform Telemetry Health Checks`: Run health checks to validate the telemetry process running on target hosts. Check for transport connection status, verify data collection statistics for sensor paths, and more.\n\n## Usage\n\n### Gather Telemetry Facts with `action: gather`\n\n- This action \"gathers\" telemetry configuration from the target host and displays it.\n\n```yaml\n- name: Gather telemetry configuration\n  hosts: nxos-9k\n  gather_facts: false\n  tasks:\n  - name: Run Telemetry Manager\n    ansible.builtin.include_role:\n      name: network.telemetry.run\n    vars:\n      ansible_network_os: cisco.nxos.nxos\n      operations:\n        - name: gather\n```\n\n### Build Brownfield Inventory with `action: persist`\n\n- Gather telemetry configuration (as structured data) from the target host and build a source-of-truth.\n- This action \"persists\" the gathered telemetry configuration into a flat-file (`telemetry.yaml`) in YAML format.\n- By default, this file will be created under `host_vars/{{ inventory_hostname }}/` directory.\n- To persist this data in a remote scm, specify details in the `scm` option under `data_store` key.\n- Or, to persist this data locally, please specify the path in the `local` option under the `data_store` key.\n\n```yaml\n- name: Persist telemetry configuration as host_vars\n  hosts: nxos-9k\n  gather_facts: false\n  tasks:\n  - name: Run Telemetry Manager\n    ansible.builtin.include_role:\n      name: network.telemetry.run\n    vars:\n      ansible_network_os: cisco.nxos.nxos\n      operations:\n        - name: persist\n      data_store:\n        scm:\n          origin:\n            url: \"/path/to/remote/scm\"\n            token: \"superSecretToken\"\n            user:\n              name: scm_user_name\n        local: ./telemetry_backup # optional\n\n```\n\n### Deploy Telemetry Configuration with `action: deploy`\n\n- This action \"deploys\" (pushes) telemetry configuration defined in the host_vars (SoT) to the target hosts.\n\n```yaml\n- name: Deploy telemetry configuration from host_vars\n  hosts: nxos-9k\n  gather_facts: false\n  tasks:\n  - name: Run Telemetry Manager\n    include_role:\n      name: network.telemetry.run\n    vars:\n      ansible_network_os: cisco.nxos.nxos\n      operations:\n        - name: deploy\n      data_store:\n        scm:\n          origin:\n            url: \"/path/to/remote/scm\"\n            token: \"superSecretToken\"\n            user:\n              name: scm_user_name\n```\n\n### Perform Telemetry Health Checks with `action: health_check`\n\n```yaml\n---\n- name: Perform telemetry health checks\n  hosts: nxos-9k\n  gather_facts: false\n  tasks:\n  - name: Run Telemetry Manager\n    ansible.builtin.include_role:\n      name: network.telemetry.run\n    vars:\n      ansible_network_os: cisco.nxos.nxos\n      operations:\n        - name: health_check\n          vars:\n            checks:\n              - name: transport_connected\n```\n\n### Supported Health Checks\n\n|     Health Check    |        Supported For       |\n|:-------------------:|:--------------------------:|\n| transport_connected |         cisco.nxos         |\n\n### Deploy a telemetry collector for use with Event-Driven Ansible\n\n- This action builds a containerized Telegraf - Kafka that collects telemetry from network devices.\n- The Telegraf container is configured to receive the data on port 57000 and write it to the Kafka topic `eda`.\n- The Kafka container is configured to listen for reads/writes on port `9092`.\n- An EDA rulebook can then read the telemetry data from this Kafka topic by leveraging the Kafka source plugin\n  and take operations.\n- Optionally, you can set the `kafka_external_listener` variable to the IP address of the host where these containers\n  are deployed. This is required when EDA is running on a different host.\n\n```yaml\n- name: Deploy telemetry collector\n  hosts: collector01\n  gather_facts: true\n  tasks:\n  - name: Run Telemetry Manager\n    include_role:\n      name: network.telemetry.run\n    vars:\n      operations:\n        - name: deploy_collector\n          kafka_external_listener: 203.0.113.100 # optional\n```\n\n### Example Rulebook\n\n```yaml\n- name: Report incident to ServiceNow\n  hosts: nxos\n  sources:\n    - ansible.eda.kafka:\n        host: 203.0.113.100\n        topic: eda\n        port: 9092\n  rules:\n    - name: Check route count drops\n      condition:\n        all:\n          - event.fields.routeCount \u003c 100\n          - event.tags.vrfName == \"prod\"\n      actions:\n        - run_playbook:\n            name: report_event.yaml\n```\n\n### Support Matrix\n\n|      Action      |               Platform              |\n|:----------------:|:-----------------------------------:|\n|      deploy      |             Cisco NX-OS             |\n|      gather      |             Cisco NX-OS             |\n|      persist     |             Cisco NX-OS             |\n| deploy_collector | RHEL \u003cbr/\u003e CentOS \u003cbr/\u003e Fedora\u003cbr/\u003e |\n\n### Code of Conduct\n\nThis collection follows the Ansible project's\n[Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html).\nPlease read and familiarize yourself with this document.\n\n## Release notes\n\nRelease notes are available [here](https://github.com/redhat-cop/network.telemetry/blob/main/CHANGELOG.rst).\n\n## Contributing to this collection\n\nWe welcome community contributions to this collection. If you find problems, please open an issue or create a PR against this repository.\n\n### Testing and Development\n\nTo test with a different IP address:\n Update the `inventory.ini` file with your target machine's IP address:\n   ```ini\n   [collectors]\n   collector ansible_host=your_target_ip ansible_user=your_username\n\nThe project uses tox to run `ansible-lint` and `ansible-test sanity`.\nAssuming this repository is checked out in the proper structure,\ne.g. `collections_root/ansible_collections/network/telemetry`, run:\n\n```shell\n  tox -e ansible-lint\n  tox -e py39-sanity\n```\n\nTo run integration tests, ensure that your inventory has a `network_telemetry` group.\nDepending on what test target you are running, comment out the host(s).\n\n```shell\n[network_telemetry]\nnxos\ncollector01\n\n[nxos_9k]\nnxos\n\n[collectors]\ncollector01\n\n[nxos_9k:vars]\n\u003c enter inventory details for this group \u003e\n\n[collectors:vars]\n\u003c enter inventory details for this group \u003e\n```\n\n```shell\n  ansible-test network-integration -i /path/to/inventory --python 3.9 [target]\n```\n\n## Licensing\n\nGNU General Public License v3.0 or later.\n\nSee [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-cop%2Fnetwork.telemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredhat-cop%2Fnetwork.telemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-cop%2Fnetwork.telemetry/lists"}