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
- serdigital64.backup
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.