Daemon Lifecycle Handlers

The Daemon Lifecycle Handlers in this project are responsible for managing the state of the Teleport service throughout its operational lifecycle, including installation, configuration updates, and service restarts. These handlers ensure that the Teleport daemon responds correctly to environmental changes, such as updated TLS certificates, modified configuration files, or system-level daemon reloads.

The system supports multiple init systems, primarily focusing on systemd for modern Linux distributions while providing legacy support for SysV init. The lifecycle management is orchestrated through Ansible handlers that are triggered by changes in configuration tasks, ensuring that the service is only interrupted when necessary to apply updates.

Service Orchestration Flow

The service management logic is divided into configuration, system integration, and state enforcement. When a configuration file is modified or a new version of Teleport is installed, specific handlers are notified to synchronize the running process with the disk-level state.

The diagram shows the notification flow from configuration or package changes to the execution of service handlers.
Sources: handlers/main.yml:2-17, tasks/config/main.yml:52-54

Core Lifecycle Handlers

Handlers are defined to manage different levels of service interruption. A "Reload" is generally preferred for configuration changes to maintain connectivity, while a "Restart" is used for binary updates or structural service file changes.

Handler Definitions

The following handlers are central to the daemon lifecycle:

Sources: handlers/main.yml:2-17, tasks/service/systemd.yml:10-18, tasks/config/proxy.yml:78-88

Systemd Integration

For systems utilizing systemd, the role manages the lifecycle through a dedicated service unit file. This includes validating systemctl availability before attempting to manage the unit.

The sequence illustrates the interaction between Ansible, the system init manager, and the resulting process state.
Sources: tasks/service/systemd.yml:1-35, handlers/main.yml:2-10

Service Persistence

To ensure the daemon survives reboots, the role explicitly enables the service. In systemd environments, this is handled via the ansible.builtin.systemd module, while legacy systems use ansible.builtin.service.
Sources: tasks/service/systemd.yml:30-35, tasks/service/daemon_management.yml:22-28

Configuration-Driven Triggers

The lifecycle handlers are not called directly but are "notified" by tasks that detect changes. This idempotency-friendly approach ensures the service is only touched if the underlying configuration has actually changed.

• Config Files: When teleport.yaml is updated via the template or copy modules, it notifies Reload Teleport service.
• ACME/TLS: Updates to Let's Encrypt certificates via certbot trigger a service reload to pick up new credentials.
• Unit Files: Modification of the teleport.service.j2 template notifies Reload systemd daemon followed by Restart Teleport service.

Sources: tasks/config/main.yml:52-54, tasks/config/proxy.yml:88, tasks/service/systemd.yml:15-18

Legacy Init Support

For non-systemd environments (e.g., older RedHat or Debian versions), the project provides a SysV init script. The lifecycle for these systems is managed by ensuring the /etc/init.d/teleport script is present and notifying a service restart upon installation.

Summary

The Daemon Lifecycle Handlers provide a robust framework for managing the Teleport process state. By utilizing Ansible's handler system, the role minimizes service downtime, preferring reloads over restarts where possible, and ensures that the service remains persistent and synchronized with its configuration across both modern systemd and legacy SysV init environments.
Sources: README.md:144-150, handlers/main.yml