prepare-host.yaml

Overview

The prepare-host.yaml file is an automation playbook that configures system resource limits and Docker service settings on a host machine. Its primary purpose is to adjust kernel and user-level limits to optimize system performance and stability, particularly for applications that require high file descriptor counts, memory lock capabilities, and process limits. It also configures Docker daemon resource restrictions to support these enhanced limits and ensures that changes take effect by restarting the Docker service if necessary.

This playbook utilizes system configuration files such as /etc/security/limits.conf and /etc/sysctl.conf, and modifies systemd service unit files for Docker. It is structured as a sequence of tasks, each performing a specific configuration step.

Tasks and Their Functionalities

1. Adjust Limits

Purpose:
Modify /etc/security/limits.conf to set hard and soft limits for file descriptors (nofile), memory locking (memlock), and number of processes (nproc) to high or unlimited values.

Implementation Details:

• Uses the lineinfile module to ensure specific configuration lines are present in the file.

• Iterates over a list of limit settings via with_items.

• Each item specifies a regular expression (r) to find the relevant line and a line (l) to insert or replace.

• Sets both hard and soft limits:

  • nofile limits set to 1048576.

  • memlock and nproc limits set to unlimited.

Parameters:

• dest: Path to the configuration file (/etc/security/limits.conf).

• state: Ensures the line is present.

• regexp: Regular expression to match the target line.

• line: The exact line to be inserted or replaced.

• with_items: List of limit settings.

Example Usage:
No direct invocation parameters; this task runs as part of the playbook.

2. Sysctl Limits

Purpose:
Set the kernel parameter vm.max_map_count to 512000 in /etc/sysctl.conf, which controls the maximum number of memory map areas a process may have. This is critical for applications like Elasticsearch that require large numbers of memory mappings.

Implementation Details:

• Uses the lineinfile module to insert or update the vm.max_map_count setting.

• Ensures the line is present in /etc/sysctl.conf.

Parameters:

• dest: /etc/sysctl.conf

• state: Ensures the line is present.

• regexp: Matches the line containing vm.max_map_count.

• line: Sets the line to vm.max_map_count = 512000.

3. Docker Memlock Limit

Purpose:
Modify the Docker systemd service file to set the LimitMEMLOCK parameter to infinity, allowing Docker containers to lock unlimited amounts of memory, which is necessary for some high-performance or security-sensitive workloads.

Implementation Details:

• Uses the ini_file module to edit the /lib/systemd/system/docker.service file.

• Changes are made in the [Service] section.

• Sets LimitMEMLOCK to infinity.

• Uses become: yes to ensure elevated privileges for modifying system files.

• Registers the result in docker_changed to detect if changes were applied.

Parameters:

• path: Path to Docker's systemd service file.

• section: [Service] section.

• option: LimitMEMLOCK.

• value: infinity.

• no_extra_spaces: Ensures minimal formatting changes.

• backup: Disabled to avoid creating backup files.

4. Restart Docker

Purpose:
Restart the Docker service to apply changes made to its systemd service configuration.

Implementation Details:

• Uses the ansible.builtin.systemd module.

• Restarts the Docker daemon only if the previous task (docker memlock limit) resulted in changes (docker_changed.changed).

• Uses daemon_reexec: yes to reload the systemd manager configuration before restarting.

Parameters:

• daemon_reexec: Reloads systemd manager configuration.

• state: restarted to restart the service.

• name: docker service.

Implementation Details and Algorithms

• The playbook leverages the lineinfile and ini_file Ansible modules to safely and idempotently edit configuration files.

• Regular expressions (regexp) are used to precisely identify lines to be replaced or inserted to avoid duplication or conflicts.

• The use of with_items in the first task provides a concise way to apply multiple similar configurations efficiently.

• Conditional execution (when) ensures Docker is restarted only if its configuration was modified, minimizing unnecessary service interruptions.

Interaction with Other System Components

• System Configuration Files:

  • /etc/security/limits.conf: Controls user resource limits applied at login or process creation.

  • /etc/sysctl.conf: Controls kernel parameters that can be applied system-wide.

• Systemd and Docker:

  • Modifies /lib/systemd/system/docker.service to adjust Docker service resource limits.

  • Restarts Docker service to apply new systemd settings.

• System Resources:

  • Adjusted limits affect how applications run on the host, particularly those requiring high resource usage such as databases, search engines, or containerized workloads.

Visual Diagram

flowchart TD
A[Start prepare-host.yaml] --> B[Adjust /etc/security/limits.conf]
B --> C[Set vm.max_map_count in /etc/sysctl.conf]
C --> D[Modify Docker systemd service: LimitMEMLOCK=infinity]
D --> E{Docker config changed?}
E -- Yes --> F[Restart Docker service]
E -- No --> G[End]
F --> G[End]

This flowchart illustrates the sequential execution of tasks and the conditional restart of the Docker service based on configuration changes.