Ansible Role: serdigital64.automation.auto_ansible_control

Purpose

Automate the management of Ansible Control Node.

Supported features in the current version:

  • Create directory structure.
  • Create site user and group
  • Setup site configuration files:
    • ansible.cfg: regular operation
    • ansible-debug.cfg: task debugging
  • Create OpenSSH Public/Private key pair for Ansible Managed Nodes
  • Register Ansible Managed Nodes`s OpenSSH server keys in known_hosts file.
  • Create shell environment script for setting Ansible variables.

The auto_ansible_control Ansible-Role is part of the A:Platform64 project and is available in the application Ansible-Collection.

Directory structure

The directory structure is based on the collection structure recommended by Ansible documentation and extended to hold all the assets that the Ansible Control node will require to manage the target environment.

Content is separated into two main groups:

  • root: infrastructure-as-code content that can be added to a GIT repository. Path is defined in the auto_ansible_control_paths.root variable.
  • var: temporary files, not to be added to GIT. Path is defined in the auto_ansible_control_paths.var variable.

Additional directories are create to further organize content. The full list is defined in auto_ansible_control_base variable.

Path Content Ansible Variable
root/bin/ Shell scripts and environment variables
root/etc/cfg Ansible configuration files ANSIBLE_CONFIG
root/etc/keys OpenSSH key pairs ANSIBLE_PRIVATE_KEY_FILE
root/etc/tokens API tokens ANSIBLE_GALAXY_TOKEN_PATH
root/etc/groups Host groups resources
root/inventories/ Ansible inventory files, host_vars and group_vars ANSIBLE_INVENTORY
root/playbooks/ Ansible Playbooks ANSIBLE_PLAYBOOK_DIR
root/collections/ Collections installed from Ansible-Galaxy ANSIBLE_COLLECTIONS_PATHS
root/roles/ Custom site-specific Ansible Roles ANSIBLE_ROLES_PATH
root/files/ Custom site-specific data files
root/templates/ Custom site-specific Ansible Templates
root/vars/ Custom site-specific Ansible variables
root/tests/ Ansible playbooks for testing Custom Ansible Roles and Playbooks
root/docs/ Repository for storing site-specific documentation
var/home Site control user home
var/cache General purpose cache ANSIBLE_CACHE_PLUGIN_CONNECTION, ANSIBLE_GALAXY_CACHE_DIR
var/logs General purpose log store ANSIBLE_LOG_PATH
var/persistence General purpose persistence store ANSIBLE_PERSISTENT_CONTROL_PATH_DIR,ANSIBLE_SSH_CONTROL_PATH_DIR
var/tmp General purpose ephemeral store ANSIBLE_RETRY_FILES_SAVE_PATH

The directory structure incorporates the concept of sites:

  • Sites are used to isolate group of hosts from each other. For example, create separate sites for production, development, testing environments.
  • Each content directory will have additional subdirectories to hold each site. For example:
    • etc/cfg/prod
    • etc/cfg/dev
    • etc/cfg/qa
  • Sites can be activated by using the corresponding environment load script. For example, to set the environment for the prod site: source ansible_control-prod.sh

Usage

The following example is an Ansible Playbook that includes all the supported features:

use this link if viewing the doc on github

---
- name: "Automation / Ansible / Control / Usage example"
  hosts: "localhost"
  gather_facts: true

  tasks:
    - name: "Example: Create directory structure for Ansible and create the site test"
      vars:
        auto_ansible_control:
          resolve_prereq: true
          prepare: true
          setup: true
        auto_ansible_control_site: "test"
      ansible.builtin.include_role:
        name: "serdigital64.automation.auto_ansible_control"
...

The playbook can be run by executing:

# Set ANSIBLE_COLLECTIONS_PATHS to the default location. Change as needed.
ANSIBLE_COLLECTIONS_PATHS="${HOME}/.ansible/collections"
ansible-playbook "${ANSIBLE_COLLECTIONS_PATHS}/ansible_collections/serdigital64/automation/playbooks/auto_ansible_control.yml"

Role Parameters

Actions

  • Use action-parameters to control what tasks are enabled for the role to execute.
  • Parameters should be declared as task level vars as they are intented to be dynamic.
auto_ansible_control:
  resolve_prereq:
  prepare:
  setup:
  provision:
Parameter Required? Type Default Purpose / Value
auto_ansible_control.resolve_prereq no boolean false Enable automatic resolution of prequisites
auto_ansible_control.prepare no boolean false Enable preparation of the runtime environment
auto_ansible_control.setup no boolean false Enable configuration of the runtime environment
auto_ansible_control.provision no boolean false Enable processing of SSH keys

End State

  • Use end-state parameters to define the target state after role execution.
  • Parameters should be declared in host_vars or group_vars as they are intended to be permanent.
auto_ansible_control_site:
auto_ansible_control_node:
auto_ansible_control_python:
auto_ansible_control_owners:
  control:
    user:
    group:
auto_ansible_control_paths:
  root:
  var:
auto_ansible_control_key:
  type:
  size:
auto_ansible_control_managed:
Parameter Required? Type Default Purpose / Value
auto_ansible_control_site no string "site" Short name of the site that will be managed by A:Platform64
auto_ansible_control_node no string "localhost" Ansible Control Node`s hostname. The hostname must resolve to a valid IP address
auto_ansible_control_python no string "/usr/bin/python3" Set the path to the Python 3.9 interpreter
auto_ansible_control_owners yes dictionary Define what users will use the automation platform
auto_ansible_control_owners.control yes dictionary Define the user that will own and run tasks on the Ansible Control Node
auto_ansible_control_owners.control.user yes string "sitectl" User's login name
auto_ansible_control_owners.control.group yes string "sitectl" User's primary group name
auto_ansible_control_paths yes dictionary Define where will A:Platform64 be installed to
auto_ansible_control_paths.root yes string "/opt/sitectl" Base directory for collections, roles, configuration
auto_ansible_control_paths.var yes string "/var/opt/sitectl" Base directory for logs, cache, temporary content
auto_ansible_control_key no dictionary Define OpenSSH key parameters
auto_ansible_control_key.type no string "ed25519" Key type. Valid values: as accepted by ssh-keygen
auto_ansible_control_key.size no string Key size
auto_ansible_control_managed no list List of Ansible Managed Hosts controlled by this Ansible Control node

Deployment

OS Compatibility

The operating system compatibility list is defined in the variable: auto_ansible_control_platforms

Dependencies

  • Ansible Collections:
    • serdigital64.backup
      • bkp_archive
    • serdigital64.system
      • sys_package
      • sys_repository
    • serdigital64.security
      • sec_openssh_client
      • sec_key_ssh

Prerequisites

The Ansible engine must be already installed and configured for privileged access and remote execution.

Installation Procedure

Manually install Ansible Collections from the Ansible Galaxy repository:

ansible-galaxy collection install --upgrade serdigital64.automation

Automatic installation is also available by deploying A:Platform64

Contributing

Help on implementing new features and maintaining the code base is welcomed.

Please see the guidelines for further details.

Author

License

GPL-3.0-or-later