Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/the-pod-shop/netbox_docker_podman_collection
Automatically installs Netbox-Docker for you, creates a superuser and Token for direct usage via ansible.
https://github.com/the-pod-shop/netbox_docker_podman_collection
automatic-superuser automatic-usertoken docker-compose ip-assignment netbox network-automation podman-compose postgresql
Last synced: 11 days ago
JSON representation
Automatically installs Netbox-Docker for you, creates a superuser and Token for direct usage via ansible.
- Host: GitHub
- URL: https://github.com/the-pod-shop/netbox_docker_podman_collection
- Owner: the-pod-shop
- License: gpl-3.0
- Created: 2024-08-24T04:11:21.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-08-30T17:03:35.000Z (5 months ago)
- Last Synced: 2024-11-28T20:14:38.553Z (2 months ago)
- Topics: automatic-superuser, automatic-usertoken, docker-compose, ip-assignment, netbox, network-automation, podman-compose, postgresql
- Homepage:
- Size: 680 KB
- Stars: 0
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Netbox Docker Podman Ansible Collection
| [vars](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#vars) | [usage](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#usage) | [complete example](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#complete-examples) | [all variables](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#all-variables) | [troubleshoot](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#troubleshoot) |
---
Ansible Galaxy Collection
ji_podhead.netbox_docker_podman
Install
ansible-galaxy collection install ji_podhead.netbox_docker_podman
---
### features
Netbox Docker Podman automatically installs Netbox-Docker for you, creates a superuser and Token for direct usage via ansible.
- direct ansible usage! no manual exec needed!
- automatic superuser creation
- automatic usertoken creation
- ip assignment
- multiple networks (can vary per container)
- waits until database migration has finished before config
> uses [Netbox-Docker](https://github.com/netbox-community/netbox-docker), so pls head over there and give them a star!
---
## vars
> ***please see the `all variables` section for a complet list, description and types of all variables used in this collection***
- you dont need to specify any variables other than required
- be aware that this will use default network and credentials
- changing the django / db credentials might be challenging
- you can add networks for some containers only and use default for the rest
- you can have as many networks for each container as you want, but only one static ip in the compose file,
however i left the option to use override to config all of your other networks on the host
- you can add additionally overrides, but be aware of the formation and indent
- make sure the main static ip is in the subnet of at least one of your networks, or at least in the default networks subnet
- use the `use_default_network` parameter if you dont want to define the network manually
---
## usage
### use sudo and import the collection
```yaml
- hosts:
gather_facts: no
become: true
become_method: sudo
become_user: root
collections:
- ji.podhead.netbox_docker_podman
```
### most basic setup
- this is only using the required vars, but i will show more complex and complete manual scenarios in the `complete examples` section
```yaml
- name: setup netbox
vars:
version: "4.0-2.9.1"
cluster_index: 1
platform: "podman"
compose_path: /home/worker/.local/bin/podman-compose
allow_default_network: "yes"
```
- note the the compose path variable!
- you can find your docker/podman-compose path on the host by running:
```bash
which podman/docker-compose
```
### deploy
- note that you dont need to init the folder (also pulls the repo) if you make changes
- ***THIS IS NOT RESTORING YOUR DB***
- be aware that recreating the containers will also delete your postgress db, so you need to back it up before.
- im thinking of implementing this however
- you dont need to pull if you have done so before and your dependencies have not changed
```yaml
block:
- name: init_netbox_folder (not required when updating)
import_role:
name: ji_podhead.netbox_docker_podman.init_netbox_folder
- name: networksetbox-docker_netbox-worker_1
import_role:
name: ji_podhead.netbox_docker_podman.networks
- name: compose
import_role:
name: ji_podhead.netbox_docker_podman.compose
- name: pull
import_role:
name: ji_podhead.netbox_docker_podman.pull
- name: up
import_role:
name: ji_podhead.netbox_docker_podman.up
```
### create usertoken and superuser
- note that for the token you have to have the netbox ip and a network, or use default network .
```yaml
# --------> optional <----------
- name: superuser
import_role:
name: ji_podhead.netbox_docker_podman.superuser
- name: create api token
import_role:
name: ji_podhead.netbox_docker_podman.create_token
vars:
port: 8000
ip: localhost
user: admin
password: admin
register: token_result
- name: debug
debug:
var: token_result.json.key
```
### optional: update vault
- check out the return token_result we registered before. there are other values you may wanna make use of
```yaml
- name: Update Vault secret
delegate_to: localhost
ansible.builtin.uri:
url: "http://127.0.0.1:8200/v1/keyvalue/data/netbox/{{token_result.json.user.display}}/{{token_result.json.id}}"
method: POST
body_format: json
force_basic_auth: true
body:
options:
cas: 0
data:
token: "{{token_result.json.key}}"
url: "{{token_result.json.url}}"
expires: "{{token_result.json.expires}}"
validate_certs: false
status_code: 200
return_content: yes
headers:
X-Vault-Token: "{{vault_token}}"
```
### optional: create an ip in netbox using our token
```yaml
- name: Create IP address within NetBox with only required information
netbox.netbox.netbox_ip_address:
netbox_url: http://192.168.10.1
netbox_token: "{{token_result.json.key}}"
data:
address: 192.168.10.1
state: present
```
---
## complete examples
### overrides, static ips, default- and 2 additional networks
> both postgres and netbox have their own network and ip
> this way we can make postgres ha and fetch the netbox ip
> all the other containers use the default network and get an ip from podman, or docker
> we also override the netbox port
```yaml
- hosts:
gather_facts: no
become: true
become_method: sudo
become_user: root
collections:
- ji.podhead.netbox_docker_podman
- name: setup netbox
vars:
# --------> Required <----------
version: "4.0-2.9.1"
index: 1
platform: "podman"
compose_path: /home/worker/.local/bin/podman-compose
use_default_network: "yes"
# --------> Credentials <----------
user: "admin"
password: "admin"
email: "[email protected]"
# ----------> Network <-----------
networks:
- name: netbox
range: 192.168.10.30/25
subnet: 192.168.10.0/24
gateway: 192.168.10.0
# ------
- name: postgres
range: 2.1.2.30/25
subnet: 2.1.2.0/24
gateway: 2.1.2.0
# -------> Container Values <--------
postgres:
hostname: postgres
ip: 2.1.2.0
networks:
- postgres
- default
netbox:
hostname: netbox
ip: 192.168.10.0
networks:
- netbox
- default
# --------> Overrides <----------
overrides:
services:
netbox:
ports:
- 8000:8880
#-----------------> DEPLOYMENT <-----------------
block:
- name: init_netbox_folder (not required when updating)
import_role:
name: ji_podhead.netbox_docker_podman.init_netbox_folder
- name: networksetbox-docker_netbox-worker_1
import_role:
name: ji_podhead.netbox_docker_podman.networks
- name: compose
import_role:
name: ji_podhead.netbox_docker_podman.compose
- name: up
import_role:
name: ji_podhead.netbox_docker_podman.up
# --------> optional <----------
- name: superuser
import_role:
name: ji_podhead.netbox_docker_podman.superuser
```
---
### no defaults: overwriting all vars
```yaml
- hosts:
gather_facts: no
become: true
become_method: sudo
become_user: root
collections:
- ji.podhead.netbox_docker_podman
- name: setup netbox
- name: setup netbox
vars:
version: "4.0-2.9.1"
index: 1
platform: "podman"
compose_path: /home/worker/.local/bin/podman-compose
allow_default_network: false
user: "ji_podhead"
password: "ji_superpass"
email: "[email protected]"
networks:
- name: rest
range: 192.168.10.30/25
subnet: 192.168.10.0/24
gateway: 192.168.10.0
- name: postgres
range: 2.1.2.30/25
subnet: 2.1.2.0/24
gateway: 2.1.2.0
postgres:
hostname: postgres
ip: 2.1.2.1
networks:
- postgres
- rest
netbox:
hostname: netbox
ip: 192.168.10.0
networks:
- rest
redis:
hostname: redis
ip: 192.168.10.3
networks:
- rest
redis_cache:
hostname: redis_cache
ip: 192.168.10.4
networks:
- rest
- postgres
netbox_housekeeping:
hostname: netbox_housekeeping
ip: 192.168.10.5
networks:
- rest
netbox_worker:
hostname: netbox_worker
ip: 192.168.10.6
networks:
- rest
- postgres
overrides:
services:
netbox:
ports:
- 8000:8880
block:
- name: init_netbox_folder (not required when updating)
import_role:
name: ji_podhead.netbox_docker_podman.init_netbox_folder
- name: networksetbox-docker_netbox-worker_1
import_role:
name: ji_podhead.netbox_docker_podman.networks
- name: compose
import_role:
name: ji_podhead.netbox_docker_podman.compose
- name: up
import_role:
name: ji_podhead.netbox_docker_podman.up
- name: superuser
import_role:
name: ji_podhead.netbox_docker_podman.superuser
```
---
## All Variables
Containers
< Container Values >
< Networks >
< Required >
< credentials >
override
name
name
description
type
name
description
type
name
description
type
name
description
type
info
netbox
ip
the main ip - must be in a subnet
string
name
name of the network
string
index
index of the netbox node
int
user
database and netbox user
string
overrides for the docker-compose.overrides.yaml. needs to be in yaml format.
redis
hostname
the containers hostname
string
subnet
the networks subnet
string
platform
compose platform: docker/podman
string
password
userpassword
string
x
redis_cache
network
all networks this container uses
list(strings)
gateway
the gateway ip of the network
string
compose_path
the path to docker/podman-compose
string
email
useremail
string
x
netbox_housekeeping
x
x
x
iprange
the networks ip range
string
version
postgres version
string
x
x
x
x
netbox_worker
x
x
x
x
x
x
allow_default_network
automatically add default network
bool
x
x
x
x
postgres
x
x
x
x
x
x
x
x
x
x
x
x
x
---
## troubleshoot
- i had issues with the container modules, so you might need to import them like this:
```yaml
- hosts:
gather_facts: no
become: true
become_method: sudo
become_user: root
collections:
- containers.podman.podman_network
- containers.podman.podman_container
- containers.podman.podman_compose
- ji.podhead.netbox_docker_podman
```
- if you have used another postgres version in the past, you might need to pull again
- if you run into issues in the `up` role, check your formation and indents.
you can check the /tmp/netbox-docker/docker-compose.yml in your container,
this is where the `init netbox folder` role clones the repo and overrides the yaml files
---
## contribution and testing
- i have not tested with docker-compose yet, but should be working
- if you find some bugs, or something is not working for you, just let me know and feel free to open an issue
---
## intention thoughts and thanks
### why
someone from the oh so beloved homelab discord channel came up with netbox and i was about to build my own network manager, so i thought: lets give this a try.
- unfortunately the official netbox ansible docs dont explain how to automate the entire process, so its required to manually exec into the deployed container instance to create superuser and therefore also the token.
- i noticed though that its somehow possible, but i ran in a bunch of issues with compose and ansible, so i thought i make this a collection, so others may profit from this
### thanks
- huge thanks goes out to [homelab discord](https://discord.gg/homelab) for helping me out ♥
- huge thanks goes out to [@bvierra](https://github.com/bvierra) for giving me some nice hints and reviewing my codebase ♥
---
## todo and roadmap
- back up and restore postgres
- improve error handling
---
| [vars](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#vars) | [usage](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#usage) | [complete example](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#complete-examples) | [all variables](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#all-variables) | [troubleshoot](https://github.com/the-pod-shop/netbox_docker_podman_collection/tree/main?tab=readme-ov-file#troubleshoot) |