Add the 'debops.netbase' Ansible role

parent 3009dda7
...@@ -781,6 +781,14 @@ stages: ...@@ -781,6 +781,14 @@ stages:
# --- n --- [[[2 # --- n --- [[[2
'netbase role':
<<: *test_role_no_deps
variables:
JANE_TEST_PLAY: '${DEBOPS_PLAYBOOKS}/service/netbase.yml'
JANE_INVENTORY_GROUPS: 'debops_service_netbase'
JANE_DIFF_PATTERN: '.*/debops.netbase/.*'
JANE_LOG_PATTERN: '\[debops\.netbase\]'
'netbox role': 'netbox role':
<<: *test_role_3rd_deps <<: *test_role_3rd_deps
variables: variables:
......
...@@ -23,6 +23,9 @@ Added ...@@ -23,6 +23,9 @@ Added
- New DebOps roles: - New DebOps roles:
- :ref:`debops.netbase`: manage local host and network database in
:file:`/etc/hosts` and :file:`/etc/networks` files.
- :ref:`debops.sudo`: install and manage :command:`sudo` configuration on - :ref:`debops.sudo`: install and manage :command:`sudo` configuration on
a host. The role is included in the ``common.yml`` playbook. a host. The role is included in the ``common.yml`` playbook.
......
---
- name: Manage local host and network database
hosts: [ 'debops_service_netbase' ]
become: True
environment: '{{ inventory__environment | d({})
| combine(inventory__group_environment | d({}))
| combine(inventory__host_environment | d({})) }}'
roles:
- role: debops.netbase
tags: [ 'role::netbase' ]
--- ---
- import_playbook: netbase.yml
- import_playbook: sysnews.yml - import_playbook: sysnews.yml
- import_playbook: kmod.yml - import_playbook: kmod.yml
......
../service/netbase.yml
\ No newline at end of file
debops.netbase - Manage local host and network database using Ansible
Copyright (C) 2018 Maciej Delmanowski <drybjed@gmail.com>
Copyright (C) 2018 DebOps https://debops.org/
This Ansible role is part of DebOps.
DebOps is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3, as
published by the Free Software Foundation.
DebOps is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with DebOps. If not, see https://www.gnu.org/licenses/.
---
# .. vim: foldmarker=[[[,]]]:foldmethod=marker
# debops.netbase default variables
# ================================
# .. contents:: Sections
# :local:
# General configuration, APT packages [[[
# ---------------------------------------
# .. envvar:: netbase__enabled [[[
#
# Enable or disable support for local host and network database management.
netbase__enabled: True
# ]]]
# .. envvar:: netbase__base_packages [[[
#
# List of base APT packages to linstall for netbase support.
netbase__base_packages: [ 'netbase' ]
# ]]]
# .. envvar:: netbase__packages [[[
#
# List of additional APT packages to install for netbase support.
netbase__packages: []
# ]]]
# ]]]
# Host database in :file:`/etc/hosts` [[[
# ---------------------------------------
# These variables define what host entries should be present in the
# :file:`/etc/hosts` database. Each dictionary key is an IP address and value
# should be a string or a YAML list of FQDN addresses or hostnames. Example:
#
# .. code-block:: yaml
#
# netbase__hosts:
# '192.0.2.1': [ 'router.example.org', 'router' ]
# '192.0.2.2': 'db.example.org'
#
# Entries with empty values will be removed from the database.
# See the :man:`hosts(5)` manual page for more details.
# .. envvar:: netbase__hosts [[[
#
# YAML dictionary of host entries which should be present on all hosts in the
# Ansible inventory.
#
# Since the host database is supposed to be the same across all hosts, you
# should most likely stick to using this variable and define it for the ``all``
# inventory group.
netbase__hosts: {}
# ]]]
# .. envvar:: netbase__group_hosts [[[
#
# YAML dictionary of host entries which should be present on hosts in
# a specific Ansible inventory group.
netbase__group_hosts: {}
# ]]]
# .. envvar:: netbase__host_hosts [[[
#
# YAML dictionary of host entries which should be present on specific hosts in
# the Ansible inventory.
netbase__host_hosts: {}
# ]]]
# ]]]
# Network database in :file:`/etc/networks` [[[
# ---------------------------------------------
# These variables define what network entries should be present in the
# :file:`/etc/networks` database. Each dictionary key is a network name and
# value should be a string or a YAML list of a class A, B or C network address
# and optional aliases. Example:
#
# .. code-block:: yaml
#
# netbase__networks:
# 'net.example.org': '192.0.2.0'
#
# Entries with empty values will be removed from the database.
# See the :man:`networks(5)` manual page for more details.
# .. envvar:: netbase__networks [[[
#
# YAML dictionary of network entries which should be present on all hosts in
# the Ansible inventory.
#
# Since the network database is supposed to be the same across all hosts, you
# should most likely stick to using this variable and define it for the ``all``
# inventory group.
netbase__networks: {}
# ]]]
# .. envvar:: netbase__group_networks [[[
#
# YAML dictionary of network entries which should be present on hosts in
# a specific Ansible inventory group.
netbase__group_networks: {}
# ]]]
# .. envvar:: netbase__host_networks [[[
#
# YAML dictionary of network entries which should be present on specific hosts
# in the Ansible inventory.
netbase__host_networks: {}
# ]]]
# ]]]
---
dependencies: []
galaxy_info:
author: 'Maciej Delmanowski'
description: 'Configure local host and network database'
company: 'DebOps'
license: 'GPL-3.0'
min_ansible_version: '2.4.0'
platforms:
- name: Ubuntu
versions:
- precise
- quantal
- raring
- saucy
- trusty
- xenial
- bionic
- name: Debian
versions:
- wheezy
- jessie
- stretch
- buster
galaxy_tags:
- networking
- hosts
- system
- nss
---
- name: Install required packages
package:
name: '{{ item }}'
state: 'present'
with_flattened:
- '{{ netbase__base_packages }}'
- '{{ netbase__packages }}'
when: netbase__enabled|bool
- name: Manage entries in /etc/hosts
lineinfile:
dest: '/etc/hosts'
regexp: '^{{ item.key | replace(".","\.") }}\s+'
line: "{{ item.key }}\t{{ item.value if (item.value is string) else (item.value|d() | join(' ')) }}"
state: '{{ "present" if item.value|d() else "absent" }}'
with_dict: '{{ netbase__hosts | combine(netbase__group_hosts, netbase__host_hosts) }}'
when: netbase__enabled|bool
- name: Manage entries in /etc/networks
lineinfile:
dest: '/etc/networks'
regexp: '^{{ item.key | replace(".","\.") }}\s+'
line: "{{ item.key }}\t{{ item.value if (item.value is string) else (item.value|d() | join(' ')) }}"
state: '{{ "present" if item.value|d() else "absent" }}'
with_dict: '{{ netbase__networks | combine(netbase__group_networks, netbase__host_networks) }}'
when: netbase__enabled|bool
- name: Make sure that Ansible local facts directory exists
file:
path: '/etc/ansible/facts.d'
state: 'directory'
owner: 'root'
group: 'root'
mode: '0755'
- name: Save netbase local facts
template:
src: 'etc/ansible/facts.d/netbase.fact.j2'
dest: '/etc/ansible/facts.d/netbase.fact'
owner: 'root'
group: 'root'
mode: '0755'
register: netbase__register_facts
- name: Update Ansible facts if they were modified
action: setup
when: netbase__register_facts is changed
#!/usr/bin/env python
# {{ ansible_managed }}
from __future__ import print_function
from json import dumps
output = {'configured': True}
print(dumps(output, sort_keys=True, indent=4))
...@@ -196,6 +196,7 @@ Networking ...@@ -196,6 +196,7 @@ Networking
- :ref:`debops.dhcpd` - :ref:`debops.dhcpd`
- :ref:`debops.dnsmasq` - :ref:`debops.dnsmasq`
- :ref:`debops.ifupdown` - :ref:`debops.ifupdown`
- :ref:`debops.netbase`
- :ref:`debops.radvd` - :ref:`debops.radvd`
- :ref:`debops.stunnel` - :ref:`debops.stunnel`
- :ref:`debops.tinc` - :ref:`debops.tinc`
...@@ -247,6 +248,7 @@ System configuration ...@@ -247,6 +248,7 @@ System configuration
- :ref:`debops.locales` - :ref:`debops.locales`
- :ref:`debops.logrotate` - :ref:`debops.logrotate`
- :ref:`debops.machine` - :ref:`debops.machine`
- :ref:`debops.netbase`
- :ref:`debops.nsswitch` - :ref:`debops.nsswitch`
- :ref:`debops.ntp` - :ref:`debops.ntp`
- :ref:`debops.resources` - :ref:`debops.resources`
......
Getting started
===============
.. contents::
:local:
Host and network database bootstrapping
---------------------------------------
Since the role is not included directly in the :file:`common.yml` playbook, if
you need to configure the host database before the common playbook is applied,
you can execute the role before the common or site playbook:
.. code-block:: console
debops service/netbase -l <hosts> && debops common -l <hosts>
Example inventory
-----------------
To enable support for the ``debops.netbase`` role, the host(s) need to be
included in the ``[debops_service_netbase]`` Ansible inventory group:
.. code-block:: none
[debops_service_netbase]
hostname
A common practice is to maintain the same host and network database across
multiple hosts in a cluster. To do that effectively, you can use inventory
parent/children groups to, for example, enable the role on all DebOps-managed
hosts:
.. code-block:: none
[debops_service_netbase:children]
debops_all_hosts
Example playbook
----------------
If you are using this role without DebOps, here's an example Ansible playbook
that uses the ``debops.netbase`` role:
.. literalinclude:: ../../../../ansible/playbooks/service/netbase.yml
:language: yaml
Ansible tags
------------
You can use Ansible ``--tags`` or ``--skip-tags`` parameters to limit what
tasks are performed during Ansible run. This can be used after a host was first
configured to speed up playbook execution, when you are sure that most of the
configuration is already in the desired state.
Available role tags:
``role::netbase``
Main role tag, should be used in the playbook to execute all of the role
tasks as well as role dependencies.
Other resources
---------------
List of other useful resources related to the ``debops.netbase`` Ansible role:
- Manual pages: :man:`hosts(5)`, :man:`networks(5)`
.. _debops.netbase:
debops.netbase
==============
The ``debops.netbase`` Ansible role manages the local host and network database
located in :file:`/etc/hosts` and :file:`/etc/networks` files, respectively.
It can be used as a substitute for a DNS service for small number of hosts;
with bigger network or larger clusters usage of a real DNS server is preferred.
.. toctree::
:maxdepth: 2
getting-started
defaults
Copyright
---------
.. literalinclude:: ../../../../ansible/roles/debops.netbase/COPYRIGHT
..
Local Variables:
mode: rst
ispell-local-dictionary: "american"
End:
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment