Skip to content

Commit 123cb02

Browse files
jeffgdotorgjeffgdotorg
authored
Updates to top-level README.md to align collection with Ansible best practices (#1239)
1 parent 1f8791c commit 123cb02

File tree

1 file changed

+154
-18
lines changed

1 file changed

+154
-18
lines changed

‎README.md

Lines changed: 154 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,165 @@
1-
![Devel CI Status](https://github.com/netbox-community/ansible_modules/workflows/All%20CI%20related%20tasks/badge.svg?branch=devel)
2-
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
3-
![Release](https://img.shields.io/github/v/release/netbox-community/ansible_modules)
4-
[![Talk to us: Slack](https://img.shields.io/badge/Slack-blue.svg)](https://netdev-community.slack.com/join/shared_invite/zt-mtts8g0n-Sm6Wutn62q_M4OdsaIycrQ#/shared-invite/email)
1+
# Ansible Modules for NetBox
52

6-
# NetBox modules for Ansible using Ansible Collections
3+
## Description
4+
The NetBox Ansible project provides an Ansible collection for interacting with NetBox, the leading solution for modeling and documenting modern networks. By combining the traditional disciplines of IP address management (IPAM) and datacenter infrastructure management (DCIM) with powerful APIs and extensions, NetBox provides the ideal "source of truth" to power network automation.
75

8-
We have moved this collection to a different namespace and collection name on Ansible Galaxy. The new versions will be at `netbox.netbox`.
9-
10-
To keep the code simple, we only officially support the two latest releases of NetBox and don't guarantee backwards compatibility beyond that. We do try and keep these breaking changes to a minimum, but sometimes changes to NetBox's API cause us to have to make breaking changes.
6+
This Ansible collection consists of a set of modules to define the intended network state in NetBox, along with plugins to drive automation of the network using data from NetBox.
117

128
## Requirements
139

14-
- The two latest NetBox releases
10+
- You must be running one of the two most recent releases of NetBox
11+
- A NetBox write-enabled API token when using modules or a read-only token for the `nb_lookup ` and `nb_inventory` plugins.
1512
- Python 3.8+
1613
- Python modules:
17-
- `pytz`
18-
- `pynetbox`
19-
- `packaging` if using Ansible < 2.10, as it's included in Ansible 2.10+
20-
- Ansible 2.12+
21-
- NetBox write-enabled token when using modules or read-only token for `nb_lookup/nb_inventory`
14+
- pytz
15+
- pynetbox
16+
- Ansible 2.12+
17+
18+
## Installation
19+
20+
### Python Modules and Ansible
21+
```
22+
pip install pytz
23+
pip install pynetbox
24+
pip install ansible
25+
```
26+
27+
### NetBox Ansible Collection
28+
Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
29+
30+
```
31+
ansible-galaxy collection install netbox.netbox
32+
```
33+
34+
You can also include it in a `requirements.yml` file and install it with `ansible-galaxy collection install -r requirements.yml`, using the format:
35+
```
36+
collections:
37+
- name: netbox.netbox
38+
```
39+
40+
To upgrade the collection to the latest available version, run the following command:
41+
```
42+
ansible-galaxy collection install netbox.netbox --upgrade
43+
```
44+
You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax to install version 3.17.0:
45+
46+
```
47+
ansible-galaxy collection install netbox.netbox:==3.17.0
48+
```
49+
See using [Ansible collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#installing-collections) for more details.
50+
51+
### Other Installation Options
52+
53+
#### Build From Source
54+
55+
Follow these steps to install from source:
56+
57+
1. ``git clone git@github.com:netbox-community/ansible_modules.git``
58+
2. ``cd ansible_modules``
59+
3. ``ansible-galaxy collection build .``
60+
4. ``ansible-galaxy collection install netbox-netbox*.tar.gz``
61+
62+
#### Build From Source (Pull Request)
63+
64+
This is useful to test code within PRs.
65+
66+
1. ``git clone git@github.com:netbox-community/ansible_modules.git``
67+
2. ``cd ansible_modules``
68+
3. ``git fetch origin pull/<pr #>/head:<whatever-name-you-want>``
69+
4. ``git checkout <whatever-name-you-want>``
70+
5. ``ansible-galaxy collection build .``
71+
6. ``ansible-galaxy collection install netbox-netbox*.tar.gz``
72+
73+
**_Note:_** This [GitHub link](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally) provides detailed information on checking out pull requests locally.
74+
75+
## Use Cases
76+
77+
### Use Case 1 - Define Intended Network State in NetBox
78+
Define the intended state of your network in NetBox, by interacting with the NetBox database to define objects and their associated state in the following ways:
79+
80+
- Make sure objects exit
81+
- Update objects if they do exist
82+
- Remove objects if they do not not exist
83+
84+
For example, to make sure a new aggregate network prefix exists:
85+
```
86+
tasks:
87+
- name: Create aggregate within NetBox with only required information
88+
netbox.netbox.netbox_aggregate:
89+
netbox_url: http://netbox.local
90+
netbox_token: thisIsMyToken
91+
data:
92+
prefix: 192.168.0.0/16
93+
rir: Test RIR
94+
state: present
95+
```
96+
97+
### Use Case 2 - NetBox as a Dynamic Inventory Source for Ansible
98+
Use the Inventory Plugin to dynamically generate Ansible inventory from device data in NetBox. Use query filters, groups and mappings to tailor the generated inventory to your specific needs.
99+
100+
The following example builds an Ansible inventory that groups devices by `role`, and filters for only devices that have the `network-edge-router` role, have a primary IP address and belong to the `internal` tenant:
101+
```
102+
# netbox_inventory.yml file in YAML format
103+
# Example command line: ansible-inventory -v --list -i netbox_inventory.yml
104+
105+
plugin: netbox.netbox.nb_inventory
106+
api_endpoint: http://localhost:8000
107+
validate_certs: True
108+
config_context: False
109+
group_by:
110+
- device_roles
111+
query_filters:
112+
- role: network-edge-router
113+
device_query_filters:
114+
- has_primary_ip: 'true'
115+
- tenant__n: internal
116+
```
117+
118+
### Use Case 3 - Query and Return Elements from NetBox
119+
Use the Lookup plugin to query NetBox and return data to drive network automation, such as lists of devices, device configurations, prefixes and IP addresses etc.
120+
121+
The following example returns a list of devices and their manufacturers, using an API filter to only return devices with the `management` role and the NetBox tag of `Dell`:
122+
```
123+
tasks:
124+
# query a list of devices
125+
- name: Obtain list of devices from NetBox
126+
debug:
127+
msg: >
128+
"Device {{ item.value.display_name }} (ID: {{ item.key }}) was
129+
manufactured by {{ item.value.device_type.manufacturer.name }}"
130+
loop: "{{ query('netbox.netbox.nb_lookup', 'devices',
131+
api_endpoint='http://localhost/',
132+
api_filter='role=management tag=Dell'),
133+
token='<redacted>') }}"
134+
135+
```
136+
## Testing
137+
Tested with Ansible Core v2.15.9. Ansible Core versions prior to 2.15.9 are not supported.
138+
139+
## Contributing
140+
If you would to contribute to the project then you can find out how to get started [here](https://github.com/netbox-community/ansible_modules/blob/devel/CONTRIBUTING.md).
141+
142+
## Support
143+
There are various options to get support for the collection:
144+
- Search through previous [GitHub Discussions](https://github.com/netbox-community/ansible_modules/discussions) or start a new one.
145+
- Raise a [GitHub Issue](https://github.com/netbox-community/ansible_modules/issues)
146+
- Read the module [documentation](https://netbox-ansible-collection.readthedocs.io/en/latest/)
147+
- Join the discussion on the dedicated `#ansible` Slack Channel on [netdev-community.slack.com](https://netdev-community.slack.com/join/shared_invite/zt-mtts8g0n-Sm6Wutn62q_M4OdsaIycrQ#/shared-invite/email)
148+
149+
Customers of NetBox Labs and Ansible using the officially certified version of the collection can get support via the usual Ansible channels. Escalation to the NetBox Labs support team will be provided as needed.
150+
151+
## Release Notes
152+
The collection release notes and changelog can be found [here](https://github.com/netbox-community/ansible_modules/releases).
22153

23-
## Docs
154+
## Related Information
155+
Some extra resources you might find useful for both the Anisble collection and for NetBox itself:
156+
- [NetBox Zero to Hero](https://netboxlabs.com/zero-to-hero/) - free 12 part course that takes you from an empty NetBox through to a fully deployed branch site, using the Ansible collection extensively along the way.
157+
- [Network Configuration Assurance with NetBox and Ansible](https://netboxlabs.com/blog/network-configuration-assurance-with-netbox-and-ansible/) - blog post featuring the Inventory plugin being used in a simple network automation use case to compare actual network state Vs intended state as defined in NetBox.
158+
- Official NetBox [documentation](https://docs.netbox.dev/en/stable/).
24159

25-
Module documentation exists on [netbox-ansible-collection.readthedocs.io](https://netbox-ansible-collection.readthedocs.io/en/latest/).
160+
## License Information
161+
GNU General Public License v3.0 or later.
26162

27-
## Join the discussion
163+
See [LICENSE](https://github.com/netbox-community/ansible_modules/blob/devel/LICENSE) for the full text of the license.
28164

29-
We have a dedicated Slack channel `#ansible` on [netdev-community.slack.com](https://netdev-community.slack.com/join/shared_invite/zt-mtts8g0n-Sm6Wutn62q_M4OdsaIycrQ#/shared-invite/email)
165+
Link to the license that the collection is published under.

0 commit comments

Comments
 (0)